Skip to main content

Working on these docs

The docs are a Docusaurus site in a git repo. Everyone edits Markdown in docs/, previews locally with Docker, and merges to main to publish.

Prerequisites​

  • Git
  • Docker with Compose v2

You don't need Node.js installed; everything runs in containers.

Preview locally​

docker compose --profile dev up docs-dev

Open http://localhost:3000. Pages reload as you save.

Add or edit a page​

  1. Create a branch: git switch -c docs/<topic>.
  2. Add or edit a .md file in the right folder under docs/. The sidebar updates automatically.
  3. Follow the conventions in .claude/skills/write-docs/SKILL.md.
  4. Open a pull request. Merge once someone reviews it.

:::tip Using Claude Code The repo includes a write-docs skill. Ask Claude Code something like "document the export API from ../veloxiq/src/api/export.ts", and it follows the house structure and style. :::

Check the production build​

The production build fails on broken links and MDX errors, so run it before you push:

docker compose build docs

Publish​

Merging to main publishes automatically. The Build and deploy docs GitHub Action builds the site, then deploys it to the docs server, which takes about a minute. Pull requests run the build only, so a broken link shows up as a failed check before you merge.

Track deploys in the repo's Actions tab. To redeploy without a new commit, open Build and deploy docs there and click Run workflow.

Traefik serves the site at the domain set in .env (DOCS_DOMAIN), with HTTPS from Let's Encrypt.