Versioned documentation: per-release snapshots, switcher, and version-sticky navigation - #1
Open
GuanzhouSong wants to merge 4 commits into
Open
Versioned documentation: per-release snapshots, switcher, and version-sticky navigation#1GuanzhouSong wants to merge 4 commits into
GuanzhouSong wants to merge 4 commits into
Conversation
Content pipeline: content.config.json sources accept a 'versions' list
({label, ref}); compile-content clones each ref and compiles the same
mappings into versioned/<label>/, cleaned by compile-clean.
Routes: /docs/v/[version]/[section]/[[...slug]] renders archived article
snapshots with an old-version banner, noindex metadata, and a link back to
the current page; /docs/v/[version] is the snapshot landing; /docs/versions
lists current and archived versions. Current article pages get a version
switcher when archived copies of the page exist.
SEO: archived pages are noindex and excluded from the sitemap; only the
current docs are advertised to crawlers. Markdown internal links now honor
the configured base path (needed for project-page deployments).
Also maps the docs repo's release-notes section into the articles tree.
…switcher Fixes version-context leaks: on archived pages the back link now goes to the version home (not current docs) and all sidebar links stay inside the version. Current and versioned article pages share one sidebar shell showing the section's pages, every other section in the same version context, an always-present version switcher (current + each archived version, targeting the same page where it exists), and release-notes/versions footer links. Adds Docs / version / section / page breadcrumbs on article, version-home, and versions pages, and moves Release Notes and Documentation Versions into a secondary row on the docs landing.
Moves archived snapshots from /docs/v/<version>/ to /docs/versions/<version>/ so the versions index and the versions themselves share one hackable namespace (trimming URL segments walks up the hierarchy) and the v/v stutter is gone. Names the current version in the switcher and on the versions index (readers could not tell what 'current' was). Keeps the API Reference visible from archived context, labeled as an exit to current docs. Roots the reference breadcrumb at Docs for consistency, and fixes the sitemap exclusion to skip only version subdirectories while keeping the /docs/versions index listed.
The landing page gained a secondary meta-link row (release notes, documentation versions); the YAML schema validation in CI rejects unknown properties, so declare the new optional field.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds versioned-documentation support to the site, dark-launched behind configuration:
content.config.jsonsources acceptversions: [{label, ref}]; the compile step clones each ref and compiles the same mappings intoversioned/<label>/. Ships withversions: []— zero behavior change until a version is listed./docs/versions/<version>/<section>/…render archived snapshots with a frozen-version banner, noindex metadata, and version-sticky navigation (back link, section list, and sidebar all stay inside the version)./docs/versionslists current + archived versions.Docs / <version> / Section / Page) across article, reference, and version pages.release-notessection into the articles tree (depends on the docs-repo PR adding that folder — merge order matters, the compile fails on missing mapped folders).Live demo
Running with
versions: [v0.114-0]against a docs fork: https://guanzhousong.github.io/documentdb.github.io/docs/ — try the switcher on Configuration vs its frozen v0.114-0 snapshot.Review notes
mainonly); the same code builds, validates, and deploys on the fork'smain. The org CI will run when this is opened upstream.Part 3 of 3 — depends on GuanzhouSong/docs#2 and GuanzhouSong/docs#3 merging upstream first.
🤖 Generated with Claude Code
https://claude.ai/code/session_017M2Wqc6hMjT2AZQ3ULi5wa