fluffos/docs/README.md

FluffOS Documentation

This directory contains the source for the FluffOS documentation site, published at https://www.fluffos.info.

The site is built with Docusaurus 3 (@docusaurus/preset-classic). Markdown files live directly in this directory (the docs plugin is configured with path: '.' and routeBasePath: '/'), so docs/efun/strings/explode.md becomes /efun/strings/explode on the site.

This README is for contributors and is excluded from the published site (see exclude in docusaurus.config.ts).

Local Development

Requires Node.js 18+ (Node 22 recommended).

cd docs
npm install
npm run dev       # dev server on http://localhost:3000

Other scripts:

npm run build     # production build → docs/build/
npm run preview   # serve the production build locally
npm run clear     # clear the Docusaurus cache

Search

Full-text search is provided by @easyops-cn/docusaurus-search-local, an offline/local search theme — the index is generated at build time and shipped with the site, so no external search service (e.g. Algolia) is needed.

Notes:

• The search index is only generated by npm run build. In the dev server (npm run dev) the search bar shows a hint instead of results; use npm run build && npm run preview to test search locally.
• Both English and Chinese pages are indexed (language: ['en', 'zh']).
• Search options live in the themes section of docusaurus.config.ts.

Chinese docs (i18n)

The Chinese corpus lives under i18n/zh-CN/docusaurus-plugin-content-docs/current/, mirroring the English tree layout (a translation of docs/efun/arrays/allocate.md goes at i18n/zh-CN/docusaurus-plugin-content-docs/current/efun/arrays/allocate.md). The site serves it at /zh-CN/ with a locale dropdown in the navbar; untranslated pages automatically fall back to the English content.

• Sidebar/navbar/footer label translations: i18n/zh-CN/docusaurus-plugin-content-docs/current.json and i18n/zh-CN/docusaurus-theme-classic/*.json. Rescaffold new keys with npx docusaurus write-translations --locale zh-CN after sidebar changes, then translate them.
• The dev server runs one locale at a time: npm run dev -- --locale zh-CN.
• npm run build builds both locales.

Layout

Path	Contents
docusaurus.config.ts	Site config: navbar, footer, docs plugin, search theme
sidebars.ts	Sidebar skeleton; splices in the generated reference trees
sidebars.generated.json	Generated sidebar trees for the reference docs (do not hand-edit)
sidebar_meta.json	Curated sidebar labels, descriptions and ordering for the generated trees
src/css/custom.css	Infima CSS variable overrides
static/	Files copied verbatim to the site root (CNAME, Google site verification)
apply/	Driver-to-LPC callback (apply) reference
efun/	Built-in function (efun) reference, by category
stdlib/	LPC standard-library reference
driver/	Driver internals & configuration
lpc/	LPC language reference
concepts/	High-level LPC / MUD concepts
cli/	Command-line tool docs
i18n/zh-CN/	Chinese translations (Docusaurus i18n; mirrors the English tree layout)
archive/	Historical MudOS-era documents (not published)

Maintenance scripts

Script	Purpose
gen_sidebar.py	Regenerates sidebars.generated.json from the reference doc trees + sidebar_meta.json (--check verifies freshness, used by CI)
gen_config_docs.py	Regenerates driver/config.md from src/base/internal/rc.cc
add_missing_efuns.py	Creates stub pages under efun/general/ for undocumented efuns (needs a keywords.json from the generate_keywords tool)

Conventions & Gotchas

• driver/config.md is auto-generated from src/base/internal/rc.cc — never edit it by hand. Regenerate with python3 docs/gen_config_docs.py; CI fails if it is stale.
• .md files are treated as standard CommonMark (markdown.format: 'detect'), but bare {...} in prose is still parsed as a JSX expression and breaks the build — escape it as \{...\} outside fenced code blocks.
• Sidebar entries in sidebars.ts use doc IDs (relative path without extension), not URLs.
• The reference trees (efun/apply/stdlib/cli/concepts/driver) have no index.md files: their sidebar trees live in sidebars.generated.json and their landing pages are Docusaurus generated-index card pages. After adding, removing, or moving a page in those trees, run ./gen_sidebar.py and commit the result — CI fails if it is stale. Category labels/descriptions/ordering are curated in sidebar_meta.json. lpc/index.md is hand-written and its sidebar is hand-authored in sidebars.ts.
• The sidebar is shared by both locales; Chinese category labels come from i18n/zh-CN/docusaurus-plugin-content-docs/current.json, not from sidebar_meta.json.
• onBrokenLinks is set to 'throw': a broken internal link fails the build (and the Pages deploy) instead of shipping a 404.

See CLAUDE.md for detailed documentation templates (applies, efuns, CLI tools) and the full contribution workflow.