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

Use the Node.js version pinned in website/.nvmrc and the committed lockfile:

cd website
npm ci
npx playwright install chromium
npm start

Before committing:

npm run check

Format

Write a titled callout as :::note[Title], with the title in brackets. Docusaurus 2 accepted :::note Title, but the site enables Docusaurus v4 behavior, where that form prints as plain text; the website test suite rejects it. Prefer a table for reference facts and prose for procedures, and check a page in both the light and dark themes and at phone width before publishing.

Structure a task guide

Give each recurring user task one canonical guide, then link to it from the relevant overview and adjacent workflows. Keep setup instructions in installation or configuration pages and exact fields in References. A household member should be able to start from a task without reading the operator's deployment procedure.

Use this order where it fits the task:

1. State the outcome and who the guide is for.
2. List the account, permissions, tools, and sample data needed before starting.
3. Give numbered steps using the application's exact labels.
4. Explain the result and any consequential boundary beside the action it affects.
5. Map common visible failures to a concrete next action.
6. End with an observable verification and links to the next tasks.

Keep copyable examples complete for their stated prerequisites. Distinguish live results from snapshots, a stored original from completed processing, and a dismissed notice from a resolved failure. Check every UI claim against the implementation, including whether a task is available in the browser, through the API, or only to an operator.

Add new guides to website/sidebars.ts and the section overview. The build includes hand-authored Markdown in local search, Markdown alternatives, and the full documentation index; update the featured groups in scripts/build-discovery-artifacts.mjs when a new guide should be a primary entry point. Keep existing page paths and headings stable when other pages link to them.

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. A tag is eligible only when it contains website/docs plus the matching OpenAPI contract, configuration schema, default configuration, and example configuration. The build creates a temporary 2.x Docusaurus version, copies those contracts under /versioned-contracts/2.x/, and rewrites the snapshot's API and configuration links to them. It skips an incomplete tag rather than combining old prose with Latest contracts. Generated version directories and contracts are ignored; never edit them by hand.