You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Per-product version selector, sidebar topics and breadcrumbs - #1272
Our docs follow package versions (IdentityServer 5.x to 8.x, BFF, Access Token Management, IdentityModel). With this PR, readers can now pick the version they're on. Pages, nav folders, cards and sections that don't apply are hidden client-side. It's still a single build and everything stays in the HTML, so search and agents see it all.
The default is the latest stable version plus the preview ("what's next") content, so we can advertise upcoming features in the docs people already read. Preview and unsupported versions get a notice. I also added topics in the sidebar and breadcrumbs to make navigating easier.
Topics in the sidebar with the version dropdown below.
Version 7.3: green chip, 8.0-only nav items and cards hidden.
Breadcrumbs, preview notice and the preview badge in the nav.
Notice for an unsupported version (6.3).
How to use it (for editors)
Version-specific content is declared in the content files. Use quoted "major.minor" values; since is inclusive, until is exclusive.
Pages and folders: add a versions block to page frontmatter or a folder's _meta.yml. Pages inherit the folder's value unless they set their own.
versions:
since: "8.0"until: "9.0"
Sections: wrap a heading and its content in <Version>. Use literal values only. The full label (e.g. "IdentityServer 8.0 and later") always stays in the page text (visually hidden) for exports, agents and screen readers. Blocks with only since get a quiet "Added in 8.0" tag after the section heading, a small "8.0+" tag after each top-level list item, or a muted caption above other content; blocks with until show nothing visible.
importVersionfrom"~/components/Version.astro";
<Versionsince="8.0">
## SAML Events
Content for 8.0 and later.
</Version>
Cards: wrap a LinkCard/Card in <Version since="8.1" inline> to hide it (never shows a caption or badge) when its target page does not apply to the selected version; the label stays as screen-reader/export text. Only use it for targets within the same product. A inline wrapper also works around a whole list of links (including its lead-in sentence).
Unsupported versions: set unsupported: true on a declared version (e.g. { version: "6.3", unsupported: true }) to show "(unsupported)" in the dropdown and a notice on every page while it is selected. It cannot be combined with preview: true (the build fails). A product may also set an upgrades URL (e.g. /identityserver/upgrades/), which adds an upgrade guide link to the notice. Use sparingly.
Preview pages: set preview: true in frontmatter for an automatic sidebar badge and preview banner.
Each product declares its versions (newest first) in products in astro/astro.config.mjs, e.g. { version: "8.1", preview: true }, { version: "8.0" }. The latest stable version is the first non-preview entry. Every since/until must be a declared version or the build fails. Declared versions with no content are still selectable. Pages whose since is a preview version automatically get the preview badge and banner; remove preview: true from the version entry when it ships (the page-level preview: true flag remains for pages not tied to a version). general/, release notes, and upgrade guides are never filtered.
The version chip lists the declared versions and preselects the latest stable one. That default view also shows preview content and hides only content valid solely for older versions (until at or before the latest stable). Pick an older version (or the preview) for strict filtering. The new sidebar badge shows only in the default view.
Sets the banner offset with a synchronous inline script so it is applied
before first paint, keeps it updated with a ResizeObserver (resize and
web-font swaps), and adds a CSS fallback height for the first paint.
Products and their declared versions live in astro.config.mjs (with
`preview` and `unsupported` flags and an upgrades link). Pages and folders
(_meta.yml) take a `versions` frontmatter block (since inclusive, until
exclusive) and `preview: true`; sections use the <Version> component, which
shows a visible label (also in llms.txt and markdown exports), with an
`inline` variant for cards. The latest stable version is the default and
preview content is shown only for the preview version, with a notice and a
switch link. A route middleware derives sidebar `new`/`preview` badges,
hoists them, and adds version metadata and Pagefind filter tags. A chip in
the product sidebar group heading filters pages, folders and blocks
client-side (?version= and localStorage supported), pushes browser history
entries and shows unsupported/preview notices. Headings in hidden <Version>
blocks are dropped from "On this page", and labels are kept quiet (muted
captions, no pills on cards). Undeclared versions fail the build.
Documents the authoring rules in README and the review instructions.
Switches the sidebar to starlight-sidebar-topics with four topics (General
Information, IdentityServer, BFF Security Framework, Open Source containing
Access Token Management, IdentityModel, IdentityModel.OidcClient and
Introspection). The version selector moves from the product group heading
to a "Version" dropdown rendered below the topic list by a Sidebar override,
for the current page's product; the Sidebar override only renders it when the
page has a version chip (hasVersionChip), and sidebar badges are hoisted at
the root. Adds a General Information overview page and topic icons on the
root index cards. Version logic is unchanged.
Uses astro-breadcrumbs via a Starlight PageTitle override. The first crumb is
the topic (product label), then folder labels from _meta.yml or the folder
index page, then the current page. Hidden when there is only one crumb, and
excluded from search and the markdown exports.
Replaces manual version badges, "Added in" notes, inline version badges and
BFF/ATM V3/V4 tabs with `versions` frontmatter, folder-level `_meta.yml`
versions and <Version since|until> blocks (including inline cards that point
at version-specific pages). Preview pages use `preview: true` instead of
hand-written asides. Pages that now use <Version> are renamed from .md to
.mdx and links to them are updated.
The client-rendered unsupported and out-of-range notices fell back to the
default blue link color. Their links and titles now use the notice's aside
accent (orange for caution, green for the out-of-range notice), matching the
links inside Starlight's own aside used for the preview notice.
…main
Restores main's condensed rules and keeps our version-badge guidance in tighter wording.
maartenba
added
preview
Spins up a preview of the Pull Request for review
and removed
preview
Spins up a preview of the Pull Request for review
labels
Oct 20, 2026
The version middleware emitted `version` filter tags that nothing used, and
Pagefind's default search UI rendered them as a long "Version" facet panel.
Search stays global (latest and greatest) for now. A comment notes the next
step for version-aware search.
Tighter topic rows (smaller icons and row pitch), a one-row "Version" picker
with a single divider, and a tighter vertical rhythm for the nav items on
desktop. The nav list now starts about 180px higher on pages with a version
picker. The version select gets an aria-label.
…scale
Gives the active topic the same sand highlight as the active nav item, uses
an ink icon box for topics in the light theme (also on hover and focus),
removes the visible "Version" label in favor of a tag icon inside the select,
adds a bit of air back around the topics and the version select, makes the
topic labels as large as the top-level nav items, and introduces a
three-step type scale for nested groups and leaves.
maartenba
added
preview
Spins up a preview of the Pull Request for review
and removed
preview
Spins up a preview of the Pull Request for review
labels
Oct 20, 2026
…ns borderless
The version select now reads "Version 8.0" with the label drawn inside the
control instead of a tag icon. Inactive topic icons in the left nav lose their
border and use a muted glyph, so only the current topic (and hovered or focused
ones) shows a filled icon box.
maartenba
added
preview
Spins up a preview of the Pull Request for review
and removed
preview
Spins up a preview of the Pull Request for review
labels
Oct 21, 2026
Selecting IdentityServer 5.x or 6.x now hides the compatibility note explaining that those versions require IdentityServerTools, while the example above still injects IIdentityServerTools. Older-version readers lose the explanation needed to adapt that example. Keep this compatibility note visible across versions, or provide a separate pre-7.0 example.
This range includes every selectable Access Token Management 3.x version, but the new sample uses Scheme.Parse, Scope.Parse, and Resource.Parse, introduced with strongly typed configuration in 4.0 (upgrading/atm-v3-to-v4.md:56–65). Those readers receive code that does not compile against their version. Restrict this sample to 4.0–4.2; any separate 3.x sample should use string-valued options.
JSX version bounds with spaced equals bypass validation
astro/src/utils/versions.ts:82
Valid literal JSX such as <Version since = "99.0"> is skipped by this regex, so an undeclared bound bypasses build-time validation. That section is then hidden for every selectable version. Whitespace around = also bypasses validation for until. Allow whitespace around the assignment so these values reach the existing checks.
The preview notice now reads "This page applies to <product> <version> and
later (preview) ..." (rendered on the server) and the version script adds a
"You're viewing <product> <version>." line, with the "View the ... documentation"
link below it. Pages flagged preview without a version range keep the generic
sentence.
Validate <Version since = "x"> written with spaces around "=", keep the
IdentityServerTools compatibility note visible for all versions, and give ATM
3.x readers a string-valued options sample while limiting the strongly typed
sample (Scheme.Parse etc.) to 4.0-4.2.
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
documentationImprovements or additions to documentation
3 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.
Our docs follow package versions (IdentityServer 5.x to 8.x, BFF, Access Token Management, IdentityModel). With this PR, readers can now pick the version they're on. Pages, nav folders, cards and sections that don't apply are hidden client-side. It's still a single build and everything stays in the HTML, so search and agents see it all.
The default is the latest stable version plus the preview ("what's next") content, so we can advertise upcoming features in the docs people already read. Preview and unsupported versions get a notice. I also added topics in the sidebar and breadcrumbs to make navigating easier.
Fixes https://github.com/DuendeSoftware/customer-success/issues/990
Screenshots
Topics in the sidebar with the version dropdown below.
Version 7.3: green chip, 8.0-only nav items and cards hidden.
Breadcrumbs, preview notice and the preview badge in the nav.
Notice for an unsupported version (6.3).
How to use it (for editors)
Version-specific content is declared in the content files. Use quoted
"major.minor"values;sinceis inclusive,untilis exclusive.Pages and folders: add a
versionsblock to page frontmatter or a folder's_meta.yml. Pages inherit the folder's value unless they set their own.Sections: wrap a heading and its content in
<Version>. Use literal values only. The full label (e.g. "IdentityServer 8.0 and later") always stays in the page text (visually hidden) for exports, agents and screen readers. Blocks with onlysinceget a quiet "Added in 8.0" tag after the section heading, a small "8.0+" tag after each top-level list item, or a muted caption above other content; blocks withuntilshow nothing visible.Cards: wrap a
LinkCard/Cardin<Version since="8.1" inline>to hide it (never shows a caption or badge) when its target page does not apply to the selected version; the label stays as screen-reader/export text. Only use it for targets within the same product. Ainlinewrapper also works around a whole list of links (including its lead-in sentence).Unsupported versions: set
unsupported: trueon a declared version (e.g.{ version: "6.3", unsupported: true }) to show "(unsupported)" in the dropdown and a notice on every page while it is selected. It cannot be combined withpreview: true(the build fails). A product may also set anupgradesURL (e.g./identityserver/upgrades/), which adds an upgrade guide link to the notice. Use sparingly.Preview pages: set
preview: truein frontmatter for an automatic sidebar badge and preview banner.Each product declares its versions (newest first) in
productsinastro/astro.config.mjs, e.g.{ version: "8.1", preview: true },{ version: "8.0" }. The latest stable version is the first non-preview entry. Everysince/untilmust be a declared version or the build fails. Declared versions with no content are still selectable. Pages whosesinceis a preview version automatically get the preview badge and banner; removepreview: truefrom the version entry when it ships (the page-levelpreview: trueflag remains for pages not tied to a version).general/, release notes, and upgrade guides are never filtered.The version chip lists the declared versions and preselects the latest stable one. That default view also shows preview content and hides only content valid solely for older versions (
untilat or before the latest stable). Pick an older version (or the preview) for strict filtering. Thenewsidebar badge shows only in the default view.