Versioning and generated reference
The published Alpha documentation is a reviewed prerelease snapshot. It is the default at /docs/. Next · development follows the working Markdown at /docs/next/. The version dropdown switches between them while retaining the current guide when that guide exists in both versions.
Sources and routes
| Documentation | Source | Public route |
|---|---|---|
| Alpha snapshot | versioned_docs/version-alpha/ | /docs/ |
| Working development | docs/ | /docs/next/ |
| Older retained snapshot | Its versioned directory | /docs/<version>/ |
versions.json lists snapshots from newest to oldest. Each snapshot has its own sidebar in versioned_sidebars/. Alpha versions the documentation; it does not declare a stable product release, production readiness or a new API contract.
Maintain Alpha
Edit working guides in docs/. Apply corrections that also affect Alpha to versioned_docs/version-alpha/ and run the checks below. Preserve the snapshot’s capability limits and source receipts. New product functionality belongs in the development guides until it has been reviewed for the applicable version.
npm run check
npm run build
npm run check:build
Inspect Alpha and Next, their introduction/API/CLI/install routes, the desktop dropdown and mobile navigation. Verify that switching versions retains the current document, internal links resolve, Mermaid renders and both themes remain readable. No repository CI workflow or automatic release deployment is configured.
Create a later snapshot
After reviewing the applicable product revision and documentation, use the actual agreed documentation version. The command below is an example; it does not declare that release:
npm run docs:version -- 0.1.0
npm run clear
npm run check
npm run build
npm run check:build
Docusaurus creates a versioned directory, sidebar and versions.json entry. The latest snapshot becomes the default /docs/ route; retained older snapshots receive their named paths. Record the exact product revision and documentation source revision. Do not rename an older snapshot to simulate a release or treat a successful documentation build as product acceptance.
Keep supported snapshots accessible. Before removing one, review inbound links and provide an archive or deliberate redirect. Removing an entry from versions.json removes that version from the generated site.
Generated references and AI-readable content
The product’s api/golf/v1/golf.proto remains the API authority. Human guides explain the generated contract and retain their named source receipts. A documentation snapshot does not change the golf.v1 package or golf.cli.v1 envelope.
npm run llms generates /llms.txt with links to the published snapshot and development guides. /llms-full.txt contains the default published snapshot; /llms-next.txt contains the working development guides. Each full export names its source directory and a content SHA-256 that includes uncommitted edits. Regenerate with every build and keep private deployment material out of published source.
See Docusaurus versioning for the snapshot and route behavior.