Writing & publishing docs

This site uses VitePress. Markdown is the authoring format; readers get a website with navigation, full-text local search, a page outline, syntax highlighting, mobile navigation, and light/dark themes.

Add or edit a page

1. Add a .md file inside docs/, or edit an existing page.
2. Add its navigation entry to docs/.vitepress/config.mts.
3. Run pnpm docs:dev and review it in the browser.
4. Run pnpm docs:build to validate rendering and internal page links.

Use relative Markdown links between source pages, such as [Architecture](./architecture.md). Put code examples inside fenced code blocks with a language identifier. Vue code examples are displayed as source; this docs site does not automatically import Nuxt application components.

Existing component, feature, API, and review documents remain at their original paths and are included in the site. Review documents describe the state recorded at their review date.

Build and preview

pnpm docs:build
pnpm docs:preview

Open http://localhost:4173/docs/. The static output is in docs/.vitepress/dist. This directory is generated and should not be committed.

Hosting with the application

Documentation is served at /docs/ on the same domain as the KPZ application. No extra DNS record, webroot, Nginx configuration, or documentation server is needed for the existing Nuxt deployment.

pnpm build
pnpm preview

Open /docs/ on the application preview server. Both pnpm build and npm run build build VitePress first, then build Nuxt. Nitro bundles docs/.vitepress/dist into .output/public/docs and serves the static pages before the application page renderer. pnpm generate also builds documentation first.

The existing staging workflow runs npm run build, uploads the application output, and restarts the application. Documentation changes ship in that same deployment. CI checks the combined build and runs pnpm test:docs against the built Nuxt server to verify documentation routes, assets, missing-page responses, and the application homepage. Run this check locally after pnpm build.

The VitePress base path is fixed at /docs/ so navigation, search, and asset URLs use the same prefix. HTML file extensions are retained. Link to documentation from application components with an ordinary HTML link, such as <a href="/docs/">Documentation</a>, so navigation loads the documentation site instead of the Nuxt client router.

For live documentation editing, use pnpm docs:dev at http://localhost:5173/docs/. To view a documentation snapshot through the Nuxt development server, run pnpm docs:build before starting pnpm dev, then visit http://localhost:3000/docs/.

Access

The generated documentation is public static content; application login does not protect /docs/. This includes developer guides and pages removed from the sidebar. Every deployment using the combined build includes these pages. Sidebar visibility is not an access control.