Documentation site

The documentation in /docs is rendered by a Docusaurus site in /docs-site and served at /docs/ by the root nginx.

Why Docusaurus

The docs are already Markdown with relative links, and the rest of the frontend stack is Node/React. Docusaurus renders that Markdown as-is (markdown.format: 'detect' parses .md as CommonMark, so the existing files' literal {/< never hit the MDX compiler), supports two independent doc sets, and fails the build on broken links — which doubles as a link checker for the whole tree. DocFX's strengths (.NET API reference generation) are not something these docs need.

Structure

Route	Source	Sidebar
/docs/	docs/user-guide/**	autogenerated from folders, _category_.json and sidebar_position
/docs/developer/	docs/*.md (excluding user-guide/, archive/, design/, marketing/, screenshots/, README.md)	docs-site/sidebars-developer.js

src/plugins/remark-repo-links.js rewrites relative links that leave the docs tree (e.g. ../inference/src/Foo.cs) into GitHub URLs, so the same file reads correctly on GitHub and on the site.

Running locally

cd docs-site
npm ci
npm start        # dev server with hot reload, http://localhost:3000/docs/
npm run build    # production build; fails on broken links

Container

docs-site/Dockerfile builds the static site and serves it from nginx:alpine under /docs/. Its build context is ./docs-site; the Markdown arrives through a named build context docs=./docs (additional_contexts in docker-compose.yml, build-contexts in CI). The root nginx routes location ^~ /docs/ to http://docs:80 with the URI unchanged; the docs are public and unauthenticated.

docker compose up --build -d docs nginx

CI

The docs-site job runs npm ci && npm run build whenever docs/** or docs-site/** changes, and the docker job builds the docs-site image. See ci.md.