Documentation

This repo's documentation has two layers:

1. docs/user/ and docs/contributor/ — the actual markdown content, and the single source of truth. Both are plain files, readable directly on GitHub.

2. website/ — a self-contained Docusaurus 3 site (its own package.json/package-lock.json; it doesn't touch the Go module) that renders those two folders as two independent, separately-sidebared "modes":

   Mode	Source	Site route	Sidebar file
   User Guide	docs/user/	/docs/	website/sidebars.user.js
   Contributor Guide	docs/contributor/	/contributing/	website/sidebars.contributor.js

   This is Docusaurus's supported multi-instance plugin-content-docs pattern: the User Guide is the classic preset's default docs instance, and the Contributor Guide is a second, explicit @docusaurus/plugin-content-docs entry in website/docusaurus.config.js's plugins array, with its own id, path, routeBasePath, and sidebarPath. The navbar's two "User Guide"/"Contributor Guide" links are type: 'docSidebar' items pointing at each instance by docsPluginId, so the correct sidebar stays active as you browse each mode.

This site does not reproduce the generated Go API reference (2,700+ schemas under openapi//models/) — both modes link out to pkg.go.dev for that instead.

Adding a page

Add a markdown file under docs/user/ or docs/contributor/ (whichever mode it belongs to) with front matter setting sidebar_position:

---
sidebar_position: 6
---

# Page Title

Both sidebars are {type: 'autogenerated', dirName: '.'} — no sidebar file needs editing; the new page shows up automatically, ordered by sidebar_position. Relative markdown links between docs work as normal relative file paths; a link from one mode into the other needs an extra ../ (e.g. docs/user/usage.md linking to ../contributor/testing.md).

Running the site locally

cd website
npm install
npm start        # dev server with hot reload, http://localhost:3000
npm run build     # production build into website/build/; also what CI runs to
                   # validate PRs touching docs/**Or website/**
npm run serve      # serve the production build locally

Deployment

.github/workflows/docs.yml builds the site on every PR touching docs/** or website/** (catching broken links — onBrokenLinks: 'throw' in docusaurus.config.js fails the build on any dangling internal link — before merge), and deploys it to GitHub Pages via actions/upload-pages-artifact + actions/deploy-pages on push to main. See CI & Release for how this fits alongside the Go-focused workflows.

A known gap in the current npm install

npm audit currently reports high-severity advisories in Docusaurus 3.10.2's own build-time dependency tree (image-size, serialize-javascript via webpack-dev-server/copy-webpack-plugin) with no fix released upstream yet. These affect the build tooling (npm start/npm run build), not the static site that gets shipped — but worth tracking, since the rest of this repo's CI is otherwise strict about dependency vulnerabilities (govulncheck, gosec, dependency-review.yml). Re-run npm audit after bumping the @docusaurus/* packages to see if upstream has resolved them; there's no Go-side equivalent tool covering the website/ npm tree today, so this needs to be checked by hand until/unless a dependency-review.yml-style job is added for website/package-lock.json.