fluffos/docs

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 (zh-CN/) pages are indexed (language: ['en', 'zh']).
• Search options live in the themes section of docusaurus.config.ts.

Layout

Path	Contents
docusaurus.config.ts	Site config: navbar, footer, docs plugin, search theme
sidebars.ts	Sidebar navigation tree (Docusaurus SidebarsConfig format)
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
zh-CN/	Chinese documentation
archive/	Historical MudOS-era documents (not published)

Maintenance scripts

Script	Purpose
update_index.sh	Regenerates all generated index.md listing pages (calls gen_index.py)
gen_index.py	Writes an index.md for one doc tree (e.g. ./gen_index.py efun EFUN)
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.
• Generated index.md listing pages (efun/apply/stdlib/cli/concepts/driver/zh-CN) are rewritten by ./update_index.sh — regenerate rather than hand-edit them. lpc/index.md is hand-written and deliberately not regenerated.
• 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.