Docs versioning

The docs site hosts a separate tree for every release plus a bleeding-edge next/ view of main. Pick the one that matches your installed binary with the Version dropdown in the top nav — or URL-pin it directly:

URL prefix	What you get
/	Redirects to the latest released version
/next/	The bleeding-edge docs on main, may describe unreleased features
/v1.0.3/	Frozen docs as they shipped with the v1.0.3 release
/v1.0.2/	…and so on for every past release

Run rite --version to see what your binary reports, and visit the matching /v<VERSION>/ path.

Schema URLs

The JSON schema for Ritefiles is published at three URL shapes that mirror the docs convention above:

URL	Mutability	When to use
https://clintmod.github.io/rite/schema.json	Mutable (latest)	Editor / IDE defaults — always tracks the newest release
https://clintmod.github.io/rite/v<X.Y.Z>/schema.json	Frozen at the tag	Pin in CI when you pin a rite binary version, so the schema matches what the binary accepts
https://clintmod.github.io/rite/next/schema.json	Mutable	Bleeding-edge, tracks main

The format-versioned variants (schema/v3.json) live alongside each shape — e.g. clintmod.github.io/rite/v1.0.4/schema/v3.json.

Example yaml-language-server directive pinned to a specific binary:

# yaml-language-server: $schema=https://clintmod.github.io/rite/v1.0.4/schema.json

Why per-version docs?

The install examples in the docs embed concrete version pins (brew install rite, ubi:clintmod/rite@vX.Y.Z). When those get bumped on main but you're running an older binary, the docs start describing flags and syntax you don't have yet. Per-version docs mean the page you land on matches the code you're running.

Fixing a typo in an old version

Old-version dirs are not frozen — they're just files in main. Find the file under website/src/v<VERSION>/, open a PR, ship. Next merge to main re-deploys that version's path with the fix. No re-release needed.

Reporting docs bugs

Open an issue at https://github.com/clintmod/rite/issues/new and paste the full URL (including the /v<VERSION>/ prefix) so we know which version's docs you're reading.

How it's wired

• Each release, rite release:prepare VERSION=X.Y.Z runs release:snapshot-docs which copies website/src/next/ into website/src/v<X.Y.Z>/. The snapshot lands in the staging PR.
• VitePress discovers version dirs at build time by scanning website/src/ for vX.Y.Z/ subdirs; sidebars and the version dropdown are generated from that list.
• The Pages workflow runs a hoist step after vitepress build that copies website/src/v*/public/ into dist/v*/, exposing each frozen schema at /v<X.Y.Z>/schema.json. (VitePress only auto-publishes the root srcDir/public/ dir, not nested per-version public/ dirs.)
• SPEC.md and CHANGELOG.md aren't inlined into versioned dirs (the site's Vue toolchain chokes on Go-template syntax in fenced blocks) — each version's Spec / Changelog pages are thin stubs that link out to the tag-pinned blobs on GitHub.