Docs Site — Developer Guide

Overview

The documentation site at docs.vexlyx.atlantiqs.org is a VitePress app that lives in docs/ of this repository, so docs and code are edited, reviewed and released together. It is a standalone pnpm project (own package.json and pnpm-lock.yaml), deliberately not part of the root pnpm workspace, so installing or building the panel never touches VitePress.

Where content lives

Site section	Source	Notes
Reference (/reference/...)	docs/dev/**/*.md	One page per feature. This is where CLAUDE.md says to write feature docs.
Contributing, Security (/project/...)	CONTRIBUTING.md, SECURITY.md at the repo root
Guide (/guide/...), home page	docs/guide/, docs/index.md	Written for the site, edited in place.
Reference overview	docs/reference/index.md	The only committed file in docs/reference/.
Site config, sidebar, theme	docs/.vitepress/	New docs/dev pages show up under "More" until you place them in sidebar.mts.

docs/reference/ (except index.md) and docs/project/ are generated by docs/scripts/sync-docs.mjs on every pnpm dev and pnpm build, and are git-ignored. Never edit them; every page's "Edit this page" link goes to the real source. The script rewrites links so the build has no dead ones: links between docs become site links, links to source files become GitHub links, and links to files that do not exist are turned into plain text and printed as warnings. It also strips the internal status blockquote that follows the H1 in most docs/dev pages.

Working on the docs

cd docs
pnpm install
pnpm dev      # regenerates the reference pages, then serves http://localhost:5173
pnpm build    # same, then builds to docs/.vitepress/dist (fails on dead links)

Markdown rules for the site: raw HTML is shown as text and {{ }} is not interpreted, so use Markdown only (containers such as ::: tip work).

CI and deployment

• .github/workflows/docs.yml builds the site on pull requests and pushes that touch docs/, CONTRIBUTING.md or SECURITY.md.
• Vercel deploys main from this repository. Project settings: Root Directory docs, Include source files outside of the Root Directory enabled (the build reads ../docs/dev and the root markdown files), framework preset VitePress, Install Command pnpm install, Build Command pnpm build, Output Directory .vitepress/dist, and an Ignored Build Step so unrelated commits do not redeploy: git diff --quiet HEAD^ HEAD -- . ../docs ../CONTRIBUTING.md ../SECURITY.md.

History

The site used to live in a separate private repository (vexlyx-docs) that copied docs/dev with a manual pnpm sync-docs, which let the published reference drift behind the code. It was merged into this repository so there is a single source of truth.