Documentation Structure
Capell documentation is split by ownership. Source repositories own product and extension docs; this repository owns the public docs shell, navigation, generated index pages, and operational notes for publishing.
Use this page when you need to decide where a doc belongs before opening a pull request.
Where docs live
Section titled “Where docs live”| Documentation | Source of truth | Published path |
|---|---|---|
| Core CMS concepts, install, admin, frontend, operations, performance, and reference docs | capell-app/capell/docs/** | /core/** and selected top-level routes |
Core extension docs for core, admin, frontend, installer, and marketplace | capell-app/capell/packages/<package>/README.md and docs/** | /packages/<package>/** |
| Add-on extension docs | capell-app/packages/packages/<package>/README.md and docs/** | /packages/<package>/** |
| Docs site shell, homepage, Capell Extensions explorer, docs source page, navigation, styles, and sync logic | capell-app/capell-docs | Site-wide |
The sync intentionally excludes internal, specs, and superpowers directories from every public docs level. Keep agent plans, implementation notes, and draft specs out of published docs.
Add or change a doc
Section titled “Add or change a doc”- Add product or package docs beside the code they describe.
- Use
README.mdfor the package landing page anddocs/**for deeper guides. - Keep package metadata current in
capell.json; the Capell Extensions explorer reads product group, tier, runtime contexts, source path, and package name from it. - Run the local sync before reviewing navigation or generated pages:
npm run sync:localFor docs-only changes in this repository, run the normal build check:
npm run buildLocal sync paths
Section titled “Local sync paths”Local package documentation work expects sibling source checkouts:
| Command | Source refreshed |
|---|---|
npm run sync:local | Core and package source docs |
npm run sync:local:core | ../capell-4 |
npm run sync:local:packages | ../capell-4/packages |
Generated files under src/content/docs/** can change after a sync. Review those diffs, but make durable source-doc edits in the source repository unless the page is owned by capell-docs.
Publishing model
Section titled “Publishing model”Documentation publication is a deliberate local action from a machine with SSH access to web2. This repository has no hosted CI/CD pipeline; pushing source or docs changes does not publish them.
Set CAPELL_CORE_PATH and CAPELL_PACKAGES_PATH to clean checkouts of the reviewed source revisions on origin/main. The local deployment script syncs their public docs, builds the static site into dist/, then uses SSH and rsync to copy the finished build to the live docs directory. Building or syncing locally does not change the live site.
Review the planned commands before publishing:
scripts/deploy-local.sh --dry-runFor an authorised publication, run scripts/deploy-local.sh and confirm its rsync prompt. Search indexing runs after the static files are published; use --skip-search-index only when Docker or Typesense credentials are unavailable. A sync or build failure stops before rsync. The rsync step updates the live directory directly and can leave a partial update if interrupted, so verify the deployed site and resolve any transfer or indexing failure before reporting publication complete.