Build and publish documentation

The public site is authored under docs/, with navigation in mkdocs.yml. Nexus Forge entry points live at the repository root:

Recipe	Result
Nexus.Docs.Forge.nxscript	Strict local site build
Nexus.Docs.Publish.nxscript	Strict build and GitHub Pages publication

These use the installed MkDocs CLI directly through Nexus Forge's existing Run task. No PowerShell deployment helper or Nexus Forge implementation change is involved.

Install documentation tools

Use Python with pip and install the pinned requirements from the Nexus root. A virtual environment outside the source tree is recommended:

python -m venv ../../toolchain/docs-venv
../../toolchain/docs-venv/Scripts/python.exe -m pip install -r docs-requirements.txt
$env:PATH = (Resolve-Path ../../toolchain/docs-venv/Scripts).Path + ";" + $env:PATH

On Ubuntu, install python3-venv if needed, then:

python3 -m venv ../../toolchain/docs-venv-linux
../../toolchain/docs-venv-linux/bin/python -m pip install -r docs-requirements.txt
export PATH="$(realpath ../../toolchain/docs-venv-linux/bin):$PATH"

Activate the environment or place its Scripts/bin directory on PATH in each documentation shell. mkdocs --version should report the pinned version. Nexus Forge and Git must also be available.

Build and preview

From the Nexus root:

nxforge /input=Nexus.Docs.Forge.nxscript
mkdocs serve --strict

The default build output is ../../worktree/nexus/docs/site relative to the checkout, as configured by site_dir. Change that MkDocs setting if your workspace layout differs. MkDocs cleans this generated output directory on build.

The preview follows the configured site prefix, normally http://127.0.0.1:8000/nexus/. Stop it with Ctrl+C. Check navigation, examples, search, and narrow-screen readability before publishing.

Internal agent instructions, documentation-writing notes, and historical migration artifacts are excluded from the site.

Publish to GitHub Pages

The repository's GitHub Pages source must be the gh-pages branch at /(root). Git credentials and permission to push are prerequisites. The recipe uses the repository's origin remote and gh-pages branch.

Review the local site and the source changes first, then run:

nxforge /input=Nexus.Docs.Publish.nxscript

This invokes MkDocs gh-deploy with strict validation. MkDocs builds the site, creates a deployment commit, and pushes the publication branch. It preserves deployment history and does not request a forced push. The recipe does not commit or push the source branch.

MkDocs deploys the current files on disk, including uncommitted documentation changes. Commit reviewed source changes before publishing when the deployment must correspond to a source commit. Use normal Git credentials; do not put tokens in a recipe.

If a push is rejected, resolve the remote/history/permission issue explicitly. The recipe does not erase branch history to make publication succeed.

See MkDocs' deployment guide and CLI reference.

Targeted updates

Update documentation for the requested topic. Do not create automatic upkeep or implementation histories. Verify command flags against the owning CLI, Nexus Script properties against the dialect, and examples by running the actual tools.

Keep implementation history in Git. Public pages describe current usage, contracts, and meaningful limitations; they should not accumulate task diaries or old test-count reports. Keep a single maintained explanation and link to it instead of repeating tool settings across pages.