Documentation

Lumie's product documentation lives in lumie-document and is built with Docusaurus 3. This page is a how-to guide for updating the English source-of-truth docs, verifying the result locally, and avoiding the most common Docusaurus and workflow mistakes.

Prerequisites

• A workspace checkout with lumie-document/docusaurus/
• Node dependencies installed for the Docusaurus app
• Access to the workspace documentation rule sources

Where Product Docs Live

Path	Purpose
docusaurus/docs/**	English source-of-truth pages
docusaurus/i18n/ko/**	Korean localized pages
docusaurus/sidebars.js	Navbar-level sidebar roots and doc sidebar wiring
docusaurus/docs/**/_category_.json	Category labels and ordering metadata
docusaurus/static/img/	Static images and assets

For ordinary page updates, prefer editing an existing English page in docs/** rather than creating a new section.

Step 1: Load The Documentation Rules

cd /path/to/Lumie
sed -n '1,220p' lumie-document/AGENTS.md
sed -n '1,260p' .codex/routing/document-sidebar-map.md

Expected success signal: you can confirm the page type, frontmatter contract, and target doc path before editing.

Step 2: Update The English Source Page

Edit the target page under lumie-document/docusaurus/docs/**. For ordinary changes, update the closest existing page instead of inventing a new category or sidebar shape.

Step 3: Update Korean Localization

After the English source page is correct, update the matching Korean page under lumie-document/docusaurus/i18n/ko/docusaurus-plugin-content-docs/current/**. Use lumie-doc-translator for full-page localization and lumie-doc-i18n-reviewer for read-only review when the locale tree changes.

Korean localization must preserve the technical surface exactly:

• Keep frontmatter keys, relative links, code fences, command literals, paths, URLs, package names, import paths, and identifiers unchanged unless the English source changed them.
• Translate prose into natural Korean technical writing instead of literal machine-style phrasing.
• Do not translate executable commands such as git remote -v, shell directory names, language labels such as bash, or code identifiers.

Required Authoring Rules

Every page must begin with frontmatter containing:

Representative shape from lumie-document/AGENTS.md:

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

Beyond that, Lumie keeps a few rules strict because Docusaurus will not always fail loudly:

• Use the frontmatter title as the page title and do not add a second body H1.
• Use relative Markdown links for internal docs.
• Put binary assets in static/img/ instead of docs/.
• Keep technical claims anchored to real code, config, or deployed behavior.
• Verify links manually because onBrokenLinks and onBrokenMarkdownLinks are configured as warnings, not hard failures.

Inline Mermaid diagrams are allowed and are the preferred way to add lightweight architecture visuals when a diagram genuinely clarifies a flow.

How Lumie Maps Documentation Structure

Three files define the documentation shape:

• sidebars.js controls navbar-level sidebar roots.
• _category_.json files control category labels and ordering.
• Frontmatter controls page order, title, and description.

Routing references such as .codex/routing/document-sidebar-map.md are useful for choosing the right existing page, but they are not the canonical sidebar structure themselves.

Step 4: Preview Or Build The Docs

Use the Docusaurus app directory for local verification:

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

Expected success signal: the English docs dev server starts and the edited page renders locally.

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

Expected success signal: Docusaurus completes the static build successfully and writes the output into build/.

Use npm run serve only after a fresh build, because it serves the static output rather than live markdown edits.

Useful Local Commands

These commands are the Docusaurus scripts declared in lumie-document/docusaurus/package.json:

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

Expected success signal: start:en starts the English dev server, build prints successful English and Korean static build output, and serve serves the latest static build.

Common Failures

• Missing sidebar_position, title, or description in frontmatter causes the page to sort unpredictably or disappear from the expected sidebar.
• Adding a body # H1 creates a duplicate title because Docusaurus already uses the frontmatter title.
• Absolute links to internal docs break portability; use relative markdown links instead.
• Unescaped braces in headings or plain MDX text can break the page parser.
• Broken links may only show as warnings because onBrokenLinks and onBrokenMarkdownLinks are configured as warnings in docusaurus.config.js.
• Editing localized docs without completing the mirror page leaves the locale tree inconsistent. English source docs should be updated first.
• Localizing code fences, command literals, import paths, or relative link targets can publish a Korean page that builds but is operationally wrong.

What This Page Does Not Cover

This page focuses on product docs in lumie-document. Internal workflow markdown under .codex/ follows a different routing path and should not be treated as part of the public Docusaurus content tree.

Where To Go Next

• Agent Engineering for the shared workflow and routing rules behind doc work.