문서화

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

준비 사항

• lumie-document/docusaurus/가 포함된 워크스페이스 체크아웃
• Docusaurus 앱용 Node 의존성 설치
• 워크스페이스 문서화 규칙 소스 접근 권한

제품 문서 위치

경로	용도
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/routing/document-sidebar-map.md

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

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

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

3단계: 한국어 현지화 업데이트

영문 원본 페이지가 올바른 상태가 된 뒤, lumie-document/docusaurus/i18n/ko/docusaurus-plugin-content-docs/current/** 아래의 대응 한국어 페이지를 업데이트합니다. locale 트리가 바뀌면 전체 페이지 현지화에는 lumie-doc-translator를 사용하고, 읽기 전용 검토에는 lumie-doc-i18n-reviewer를 사용하세요.

한국어 현지화는 기술 표면을 그대로 보존해야 합니다.

• frontmatter key, 상대 링크, code fence, 명령 literal, 경로, URL, package 이름, import path, identifier는 영문 원본이 바뀐 경우가 아니면 그대로 유지합니다.
• 본문 설명은 직역투가 아니라 자연스러운 한국어 기술 문서 문장으로 번역합니다.
• git remote -v 같은 실행 명령, shell 디렉터리 이름, bash 같은 언어 label, code identifier는 번역하지 않습니다.

필수 작성 규칙

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

lumie-document/AGENTS.md의 대표 형식:

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

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

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

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

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

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

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

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

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

로컬 검증에는 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 편집본이 아니라 정적 출력물을 제공하므로, 반드시 새 빌드 이후에만 사용하세요.

유용한 로컬 명령

다음 명령은 lumie-document/docusaurus/package.json에 선언된 Docusaurus 스크립트입니다.

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

예상 성공 신호: start:en은 영문 개발 서버를 시작하고, build는 영문과 한국어 정적 빌드 성공 출력을 보여주며, serve는 최신 정적 빌드를 제공합니다.

흔한 실패

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

이 페이지가 다루지 않는 것

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

다음에 볼 문서

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