# FluffOS Documentation

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

The site is built with **[Docusaurus 3](https://docusaurus.io/)** (`@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).

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

Other scripts:

```bash
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`](https://github.com/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`](CLAUDE.md) for detailed documentation templates (applies, efuns, CLI
tools) and the full contribution workflow.