Skip to main content

Writing documentation

Public docs live under website/docs/. Repository-internal design records and deep operational evidence remain under the root docs/ directory.

Audience contract​

Assume the reader knows basic self-hosting but not how Jiandu components fit together. Lead with a successful task, give copy/paste-safe commands, explain what the reader should observe, and place advanced choices later.

Outside Development:

  • describe supported behavior rather than modules, traits, tables, or internal control flow;
  • introduce one trust boundary at a time;
  • use the exact user-visible error message in troubleshooting pages;
  • link to source only with a commit permalink and only when it improves understanding;
  • do not promise unmeasured performance, OCR quality, or production readiness.

Local workflow​

cd website
npm install
npm start

Before committing:

npm run check

Version lifecycle​

The working docs/ tree is Latest (main). During a site build, scripts/prepare-versions.mjs finds exact major release tags such as v2.0.0, reads that tag's website/docs tree, and creates a temporary 2.x Docusaurus version. Generated version directories are ignored; never edit them by hand.