Skip to main content

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
  • The documentation rules available in lumie-document/AGENTS.md, .codex/knowledge/document/DOC_GEN_RULES.md, and .codex/knowledge/document/DOC_GEN_SIDEBAR_MAP.md

Where Product Docs Live​

PathPurpose
docusaurus/docs/**English source-of-truth pages
docusaurus/i18n/ko/**Korean localized pages
docusaurus/sidebars.jsNavbar-level sidebar roots and doc sidebar wiring
docusaurus/docs/**/_category_.jsonCategory 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/knowledge/document/DOC_GEN_RULES.md
sed -n '1,260p' .codex/knowledge/document/DOC_GEN_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.

Required Authoring Rules​

Every page must begin with frontmatter containing:

---
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/knowledge/document/DOC_GEN_SIDEBAR_MAP.md are useful for choosing the right existing page, but they are not the canonical sidebar structure themselves.

Step 3: 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​

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

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.

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​

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