Building and publishing documentation

The documentation site renders the repository's Markdown using pinned Python-Markdown. Markdown files remain the source of truth. The build includes all pages under docs/, root overview/contribution/changelog pages, and locally linked Markdown references. Every page links to its exact Markdown snapshot included in the site. Other repository-file links point to GitHub source.

Build and validate

Use Python 3.10 or newer. Create the virtual environment and output outside the checkout; these commands work on macOS and Linux:

python3 -m venv /tmp/mori-docs-venv
/tmp/mori-docs-venv/bin/python -m pip install -r scripts/docs-requirements.txt
/tmp/mori-docs-venv/bin/python scripts/test-build-docs.py
site_output=$(mktemp -d /tmp/mori-docs-site.XXXXXX)
/tmp/mori-docs-venv/bin/python scripts/build-docs.py --output "$site_output" --source-ref main

The builder refuses to overwrite a nonempty directory or place output inside the checkout. It verifies every local page, image, stylesheet link and heading fragment, and writes build-report.json with page/link counts and the renderer version. Missing links fail the build. External source and release links are not fetched by this check; validate the chosen source ref separately.

For a reproducible published snapshot, pass the exact source commit to --source-ref instead of main, and build from that commit's clean checkout. A development worktree build can preview uncommitted documentation. Each page includes its exact Markdown source locally; GitHub code links use the chosen ref and cannot represent uncommitted implementation changes. The builder adds no timestamps to generated pages.

Preview with a local HTTP server:

/tmp/mori-docs-venv/bin/python -m http.server 8765 --directory "$site_output"

Check the overview, first-review guide, a wide reference table, and navigation at desktop and phone widths. Confirm keyboard navigation, code scrolling, images, anchors and the minimum-version banner. Stop the server after review.

Publish deliberately

Publish only the validated output to an isolated gh-pages branch or equivalent static hosting artifact. Configure GitHub Pages to serve that branch's root. Keep source checkout changes, private files, research evidence and credentials out of the publication tree. Review the artifact and obtain the normal project publication authorization before pushing it. Do not mix publication history with main or use deployment as evidence that a release was published.

The current template labels the site Mori v0.34.0 documentation. Publish it only after that release is available, and retain the minimum-version notice. Preserve that banner while the site describes unreleased behavior. Update it only when the corresponding release is verified, and make the documentation version explicit. There is intentionally no automatic main-branch or release-triggered publishing workflow.

To change presentation, edit the stylesheet and the HTML template in the builder. Keep renderer updates pinned in the requirements file and rerun the tests and visual checks after any update.

The build tests exercise real documentation, source snapshots, Unicode headings, broken anchors and output-directory safety.