Docs Guide: Mintlify Rules, Link Conventions, and i18n Policy

Docs Guide

This directory governs documentation authoring, Mintlify link rules, and documentation i18n policy.

Mintlify Rules

• Documentation is hosted on Mintlify (https://docs.openclaw.ai).
• Internal documentation links in docs/**/*.md must be root-relative and must not include a .md or .mdx suffix (example: [Config](/ai-agents/integrations/open-claw/docs/gateway/configuration)).
• Cross-references between sections should use anchors on root-relative paths (example: [Hooks](/ai-agents/integrations/open-claw/docs/gateway/configuration-reference#hooks)).
• Doc headings should avoid em dashes and apostrophes because Mintlify anchor generation is unreliable there.
• README and other GitHub-rendered docs should use absolute documentation URLs so links function outside Mintlify.
• Documentation content must stay generic: no personal device names, hostnames, or local paths; use placeholders like user@gateway-host.

Docs Content Rules

• For documentation, UI copy, and picker lists, order services and providers alphabetically unless the section explicitly describes runtime order or auto-detection order.
• Keep bundled plugin naming consistent with the repo-wide plugin terminology rules in the root AGENTS.md.
• Generated documentation should never be hand-edited: docs/plugins/reference/**, docs/plugins/reference.md, and docs/plugins/plugin-inventory.md come from pnpm plugins:inventory:gen; docs/docs_map.md from pnpm docs:map:gen; docs/maturity/** from pnpm maturity:render.

Internal Docs

• Long-lived private operator documentation belongs in ~/Projects/manager/docs/.
• Repo-local internal scratch or mirror documentation may live under ignored docs/internal/.
• Never add docs/internal/** pages to docs/docs.json navigation or link them from public documentation.
• scripts/docs-sync-publish.mjs excludes and removes docs/internal/** from the public openclaw/docs publish repo if a page is force-added later.
• Internal documentation may mention repo paths, private app names, 1Password item names, and runbooks, but must never include secret values.

Maturity Scorecard Editing

taxonomy.yaml and qa/maturity-scores.yaml are the source inputs; generated maturity documentation under docs/maturity/ are projections and should not be hand-edited for score, LTS, taxonomy, QA profile, or evidence tables. scripts/qa/render-maturity-docs.ts owns generation; use pnpm maturity:render to refresh committed documentation and pnpm maturity:check to verify it. .github/workflows/maturity-scorecard.yml renders artifact previews and can open generated-doc PRs; .github/workflows/openclaw-release-checks.yml dispatches it for release QA. Keep deterministic qa-evidence.json.scorecard data in GitHub Actions artifacts unless a maintainer explicitly requests a sanitized committed projection. Human overrides must change source state in a PR and explain the reason plus public or redacted evidence.

Docs i18n

• Foreign-language documentation is not maintained in this repo. The generated publish output lives in the separate openclaw/docs repo (often cloned locally as ../openclaw-docs).
• Do not add or edit localized documentation under docs/<locale>/** here.
• Treat English documentation in this repo plus glossary files as the source of truth.
• Pipeline: update English documentation here, update docs/.i18n/glossary.<locale>.json as needed, then let the publish-repo sync and scripts/docs-i18n run in openclaw/docs.
• Before rerunning scripts/docs-i18n, add glossary entries for any new technical terms, page titles, or short nav labels that must stay in English or use a fixed translation.
• pnpm docs:check-i18n-glossary is the guard for changed English doc titles and short internal doc labels.
• Translation memory lives in generated docs/.i18n/*.tm.jsonl files in the publish repo.
• See docs/.i18n/README.md.