SideDoc

Appearance

ADR 0006: Documentation is one VitePress site, partly generated ​

  • Status: accepted
  • Date: 2026-10-23
  • Evidence: commit 6384336 (VitePress site skeleton in the docs workspace), docs/.vitepress/config.mts, docs/typedoc.json

Context ​

Documentation was spread over READMEs in each package, ACTIVE_ENTITY_ARCHITECTURE.md, notes in app/sidedoc-frontend/doc/ (some outdated), the docker README and help texts in the schemas repository. Users, operators, schema authors and developers each had to find their part. Field references and API descriptions written by hand go stale as soon as the schema or code changes.

Decision ​

  • One documentation site, published at docs.sidedoc.app, built with VitePress from the docs npm workspace in the monorepo.
  • Four sections: user guide, deployment, profiles and schemas, developer guide (with ADRs and API reference).
  • Generate what can be generated: the backend API reference with TypeDoc and typedoc-plugin-markdown from TSDoc comments, the profile reference pages from the schemas. Generated pages are rebuilt on every docs build and are not edited by hand.
  • Sidebars are built from the files on disk (frontmatter title and order), so adding a page or a profile version needs no config change.
  • Package READMEs are reduced to a short summary with links into the site.

Consequences ​

  • There is one place to look and one place to update.
  • Code comments become user-visible documentation, so exported backend symbols need TSDoc comments (Contributing).
  • The docs build depends on the backend sources (TypeDoc) and, for profile pages, on the schemas.
  • VitePress treats Markdown as Vue templates; generated and hand-written pages must escape template syntax.