Docs maintenance guide
Use this handbook when you need to add a repository to docs_ui, refresh an existing project section, or clean up stale documentation before other teams rely on it.
This section is about operating the docs site itself. It focuses on where the content lives, which files to touch, which commands to run, and how to verify the rendered result before handoff.
What good maintenance looks like
When a docs update is done well:
- the repo has a clear home under
docs/<project>/... - project metadata and Bitbucket links point to the right place
- imported reference pages come from real repo files
- navigation and search surface the important pages quickly
- the local build, tests, and smoke checks pass before handoff
Common maintainer flow
1. Collect source material
2. Add or update pages
3. Run make sync
4. Preview locally on http://localhost:8877
5. Run make verify
6. Run make smoke for route, search, and rendering confidence
7. Hand off with the touched files and checks performed
Key files inside docs_ui
docs/<project>/...: curated product docs that belong to the hosted sitesidebars.ts: the main product-doc navigationsrc/data/projects.ts: project chip labels, default routes, and Bitbucket linksscripts/doc-metadata.mjs: the imported-doc manifest and slug mappingscripts/sync-doc-sources.mjs: the sync script that copies imported repo docs intodocs_uiintegrations/docs/manual/...: this maintainer handbook
Choose the path you need
- Adding a repo for the first time: continue to Add a new repo
- Refreshing a repo that already exists in the site: continue to Update an existing repo
- Unsure what evidence to gather before editing: open Collect source material