Versionized Docs design - #144
Open
guanzhousongmicrosoft wants to merge 5 commits into
Open
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.
…project page Points the content pipeline at the docs fork (which carries the v0.114-0 snapshot tag and release-notes section), compiles the v0.114-0 archived version, and deploys to GitHub Pages under /documentdb.github.io/ with the package-repository build steps omitted. This commit is demo-only and is not intended for the upstream repository.
…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
2 participants
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.
No description provided.