Maintain a Docusaurus Manual
Treat the running product and source code as authoritative. Keep documentation,
translations, navigation, screenshots, inventories, and generated site behavior
consistent in the same change.
Discover the project contract
- Read the repository instructions and the manual's own contributor guide.
- Locate the Docusaurus config, source docs, localized docs, sidebar, package
scripts, validation scripts, screenshot registry, coverage inventory, and CI.
- Identify the canonical locale, supported locales, URL/version scheme, and
whether localized pages may fall back or must have exact path parity.
- Locate app strings or another terminology source before translating UI names.
- Read references/discovery-and-review.md
when the repository has custom inventories, generated screenshots, or
versioned publishing.
Do not assume conventional paths when the repository declares its own.
Update the manual
- Verify the current product behavior from implementation and focused tests.
- Update the canonical page with concrete, task-oriented prose. Describe only
controls, states, limitations, and workflows that exist.
- Preserve stable frontmatter identifiers, component calls, links, anchors,
admonitions, and code unless the change intentionally modifies them.
- Add new pages to navigation and every repository-owned coverage or surface
inventory.
- Update every published locale required by the project. Translate meaning,
not sentence shape; preserve product terminology from the localized app.
- Record questionable product wording separately unless changing UI copy is
explicitly in scope.
Handle screenshots as evidence
- Prefer the repository's deterministic screenshot harness and registry.
- Capture the real production widget or route with representative state.
- Keep required locale, viewport, and theme variants complete.
- Reference screenshots through the site's component or registry rather than
hard-coded media URLs when such an abstraction exists.
- Keep generated media outside the source repository when that is the declared
architecture.
If the task is only a one-off application screenshot, use the repository's
screenshot skill instead of extending the manual pipeline.
Validate in increasing scope
Run the bundled parity audit when the site uses standard Docusaurus locale
trees:
python3 <skill-dir>/scripts/audit_docusaurus_locales.py \
--site-root path/to/site
Pass --fail-identical only when identical localized page bodies are
forbidden. Treat its default identical-page output as a review warning.
Run focused repository validators and tests for touched metadata or helpers.
Run type checking, link/content validation, unit tests, and the production
Docusaurus build through repository scripts.
Smoke-test built routes, locale switching, assets, search, and base URLs.
Review the rendered page at representative widths and in every changed
locale. A successful build does not prove prose accuracy or layout quality.
Do not claim completion while required checks fail. Report any validation that
could not run and why.
1---2name: maintain-docusaurus-manual3description: Maintain a Docusaurus product manual whose prose, navigation, localized page trees, screenshots, coverage metadata, and release build must stay aligned with the application. Use when adding or revising manual pages, documenting a product change, updating translated MDX, repairing locale parity, adding registered screenshots, auditing stale documentation, or validating a multilingual Docusaurus site before publication.4---56# Maintain a Docusaurus Manual78Treat the running product and source code as authoritative. Keep documentation,9translations, navigation, screenshots, inventories, and generated site behavior10consistent in the same change.1112## Discover the project contract13141. Read the repository instructions and the manual's own contributor guide.152. Locate the Docusaurus config, source docs, localized docs, sidebar, package16 scripts, validation scripts, screenshot registry, coverage inventory, and CI.173. Identify the canonical locale, supported locales, URL/version scheme, and18 whether localized pages may fall back or must have exact path parity.194. Locate app strings or another terminology source before translating UI names.205. Read [references/discovery-and-review.md](references/discovery-and-review.md)21 when the repository has custom inventories, generated screenshots, or22 versioned publishing.2324Do not assume conventional paths when the repository declares its own.2526## Update the manual27281. Verify the current product behavior from implementation and focused tests.292. Update the canonical page with concrete, task-oriented prose. Describe only30 controls, states, limitations, and workflows that exist.313. Preserve stable frontmatter identifiers, component calls, links, anchors,32 admonitions, and code unless the change intentionally modifies them.334. Add new pages to navigation and every repository-owned coverage or surface34 inventory.355. Update every published locale required by the project. Translate meaning,36 not sentence shape; preserve product terminology from the localized app.376. Record questionable product wording separately unless changing UI copy is38 explicitly in scope.3940## Handle screenshots as evidence4142- Prefer the repository's deterministic screenshot harness and registry.43- Capture the real production widget or route with representative state.44- Keep required locale, viewport, and theme variants complete.45- Reference screenshots through the site's component or registry rather than46 hard-coded media URLs when such an abstraction exists.47- Keep generated media outside the source repository when that is the declared48 architecture.4950If the task is only a one-off application screenshot, use the repository's51screenshot skill instead of extending the manual pipeline.5253## Validate in increasing scope54551. Run the bundled parity audit when the site uses standard Docusaurus locale56 trees:5758 ```bash59 python3 <skill-dir>/scripts/audit_docusaurus_locales.py \60 --site-root path/to/site61 ```6263 Pass `--fail-identical` only when identical localized page bodies are64 forbidden. Treat its default identical-page output as a review warning.65662. Run focused repository validators and tests for touched metadata or helpers.673. Run type checking, link/content validation, unit tests, and the production68 Docusaurus build through repository scripts.694. Smoke-test built routes, locale switching, assets, search, and base URLs.705. Review the rendered page at representative widths and in every changed71 locale. A successful build does not prove prose accuracy or layout quality.7273Do not claim completion while required checks fail. Report any validation that74could not run and why.
matthiasn