Build this documentation

The site is built with MkDocs Material. The C++ API reference is generated from the headers by Doxide.

Preview the site

python3 -m venv .venv
.venv/bin/pip install -r docs/requirements.txt
.venv/bin/mkdocs serve

Open http://127.0.0.1:8000/forge/. The page reloads as you edit files in docs/.

Regenerate the API reference

Install Doxide by following its documentation, then run it from the top of the repository before building:

doxide build
mkdocs build

Doxide reads doxide.yaml and writes Markdown into docs/api/. Those files are not committed, apart from docs/api/index.md. Without them, links into the API reference are reported as missing when you build locally.

Where pages go

The site follows Diátaxis. Put a new page in the section that matches what the reader is doing:

Directory	For a reader who wants to	Example
docs/tutorials/	learn by following a complete lesson	Your first reconstruction
docs/how-to/	get a specific task done	Run a reconstruction with MPI
docs/reference/	look up a fact	Command-line programs
docs/explanation/	understand how and why FORGE works	Field correction

Add the page to nav in mkdocs.yml and to its section's index.md. Internal planning notes under docs/superpowers/ are kept out of the site by exclude_docs.

Deployment

Pushes to main run .github/workflows/docs.yml, which builds the API reference and the site and deploys it to Cloudflare Pages. The site is served at forge-mri.dev/forge.