문서화

Lumie의 제품 문서는 lumie-document에 있으며 Docusaurus 3로 빌드됩니다. 이 페이지는 영문 기준 원본 문서를 업데이트하고, 결과를 로컬에서 검증하며, 가장 흔한 Docusaurus 및 워크플로 실수를 피하기 위한 how-to 가이드입니다.

준비 사항

• lumie-document/docusaurus/가 포함된 워크스페이스 체크아웃
• Docusaurus 앱용 Node 의존성 설치
• lumie-document/AGENTS.md, .codex/knowledge/document/DOC_GEN_RULES.md, .codex/knowledge/document/DOC_GEN_SIDEBAR_MAP.md에서 제공하는 문서화 규칙

제품 문서 위치

경로	용도
docusaurus/docs/**	영문 기준 원본 페이지
docusaurus/i18n/ko/**	한국어 현지화 페이지
docusaurus/sidebars.js	navbar 수준의 sidebar 루트와 문서 sidebar 연결
docusaurus/docs/**/_category_.json	카테고리 라벨 및 정렬 메타데이터
docusaurus/static/img/	정적 이미지와 에셋

일반적인 페이지 업데이트라면 새 섹션을 만들기보다 docs/** 아래 기존 영문 페이지를 수정하는 편을 우선하세요.

1단계: 문서화 규칙 불러오기

cd /path/to/Lumie
sed -n '1,220p' lumie-document/AGENTS.md
sed -n '1,260p' .codex/knowledge/document/DOC_GEN_RULES.md
sed -n '1,260p' .codex/knowledge/document/DOC_GEN_SIDEBAR_MAP.md

예상 성공 신호: 편집 전에 페이지 유형, frontmatter 계약, 대상 문서 경로를 확인할 수 있습니다.

2단계: 영문 원본 페이지 업데이트

lumie-document/docusaurus/docs/** 아래의 대상 페이지를 편집합니다. 일반적인 변경이라면 새로운 카테고리나 sidebar 구조를 발명하기보다 가장 가까운 기존 페이지를 업데이트하세요.

필수 작성 규칙

모든 페이지는 다음 frontmatter로 시작해야 합니다.

---
sidebar_position: 1
title: "Page Title"
description: "One-line description"
---

그 외에도 Lumie는 Docusaurus가 항상 크게 실패하지 않기 때문에 몇 가지 규칙을 엄격하게 유지합니다.

• frontmatter title을 페이지 제목으로 사용하고, 본문에 두 번째 H1을 추가하지 않습니다.
• 내부 문서에는 상대 Markdown 링크를 사용합니다.
• 바이너리 에셋은 docs/가 아니라 static/img/에 둡니다.
• 기술적 주장은 실제 코드, 설정, 배포된 동작에 근거하도록 유지합니다.
• onBrokenLinks와 onBrokenMarkdownLinks는 hard failure가 아니라 경고로 설정되어 있으므로 링크를 수동으로 검증합니다.

인라인 Mermaid 다이어그램은 허용되며, 다이어그램이 실제로 흐름을 명확하게 해줄 때 가벼운 아키텍처 시각화를 추가하는 선호 방식입니다.

Lumie가 문서 구조를 매핑하는 방식

문서 구조는 세 가지 파일이 정의합니다.

• sidebars.js는 navbar 수준의 sidebar 루트를 제어합니다.
• _category_.json 파일은 카테고리 라벨과 정렬을 제어합니다.
• frontmatter는 페이지 순서, 제목, 설명을 제어합니다.

.codex/knowledge/document/DOC_GEN_SIDEBAR_MAP.md 같은 라우팅 참고 문서는 올바른 기존 페이지를 고르는 데 유용하지만, 그것 자체가 canonical sidebar 구조는 아닙니다.

3단계: 문서 미리 보기 또는 빌드

로컬 검증에는 Docusaurus 앱 디렉터리를 사용하세요.

cd /path/to/Lumie/lumie-document/docusaurus
npm run start:en

예상 성공 신호: 영문 문서 개발 서버가 시작되고, 편집한 페이지가 로컬에서 렌더링됩니다.

cd /path/to/Lumie/lumie-document/docusaurus
npm run build

예상 성공 신호: Docusaurus가 정적 빌드를 성공적으로 완료하고 결과를 build/ 에 기록합니다.

npm run serve는 실시간 markdown 편집본이 아니라 정적 출력물을 제공하므로, 반드시 새 빌드 이후에만 사용하세요.

유용한 로컬 명령

cd /path/to/Lumie/lumie-document/docusaurus
npm run start:en
npm run build
npm run serve

흔한 실패

• frontmatter의 sidebar_position, title, description이 빠지면 페이지 정렬이 예측 불가능해지거나 기대한 sidebar에서 사라질 수 있습니다.
• 본문에 # H1을 추가하면 Docusaurus가 이미 frontmatter title을 사용하므로 제목이 중복됩니다.
• 내부 문서에 절대 링크를 쓰면 이식성이 깨지므로 상대 markdown 링크를 사용하세요.
• 제목이나 일반 MDX 텍스트에서 escape되지 않은 중괄호는 페이지 파서를 깨뜨릴 수 있습니다.
• onBrokenLinks와 onBrokenMarkdownLinks가 docusaurus.config.js에서 경고로 설정되어 있으므로 깨진 링크가 경고로만 보일 수 있습니다.
• 현지화 문서를 미러 페이지를 완성하지 않은 채 편집하면 locale 트리가 일관성을 잃습니다. 영문 원본 문서를 먼저 업데이트해야 합니다.

이 페이지가 다루지 않는 것

이 페이지는 lumie-document의 제품 문서에 초점을 맞춥니다. .codex/ 아래의 내부 워크플로 markdown은 다른 라우팅 경로를 따르며, 공개 Docusaurus 콘텐츠 트리의 일부로 취급해서는 안 됩니다.

다음에 볼 문서

• Codex에서 문서 작업 뒤의 공용 워크플로와 라우팅 규칙을 확인하세요.