website: Keep versioned docs links inside their version - #3243
Merged
Merged
Conversation
- Link documentation pages with relative `.md` paths; the build also moves
site-root links from released snapshots into the version being built.
- Keep redirects and the zh-CN → en language switch below the version base.
- On a 404, offer the same page from another version, and style the page.
- Write the GPUI snapshot version as `{{gpui_pre_version}}`, resolved from
the workspace `Cargo.toml` of the documented revision.
- Add `maturity` frontmatter (Stable, Preview, Experimental,
Platform-dependent) with labels under the title and definitions on the
documentation home.
- Check sources (`test:docs`) and built links (`test:links`) in CI.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… target Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
huacnlee
enabled auto-merge (squash)
September 25, 2026 16:47
huacnlee
disabled auto-merge
September 25, 2026 16:48
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.
Documentation pages read under
/versions/mainor/versions/<tag>linked back to the default version through site-root links (/docs/entity,/component/...), which often 404 there because the default is the latest release.Links stay in their version
docs,component,base,shell(en and zh-CN) now link the.mdfile relatively. zh-CN pages that linked English Base pages now link the Chinese ones.remarkDocLinksprefixes any remaining site-root docs link with the build's base, so released snapshots (v0.6.6 still has such links) stay inside/versions/<tag>too./docs/dock→/component/dock, …) and the zh-CN → en language switch kept dropping the version base; both are fixed.GPUI snapshot version in one place
Pages write
{{gpui_pre_version}}in prose, code and docs.rs links. It resolves from thegpuientry of the workspaceCargo.toml;script/build-website-versionspasses each revision's own value. The.mdendpoints andllms-full.txtexpand it as well.Maturity labels
maturity: [preview | experimental | showcase-only | platform-dependent | stable]in frontmatter renders mono labels under the title, linking to a new Maturity section on the docs home. Marked: Mobile and WebView (Experimental, Platform-dependent), WebAssembly (Showcase only: it currently serves the component showcases, not shipped applications), all GPUI Shell pages (Preview), Native Extensions, SystemNotification and TitleBar (Platform-dependent). Unmarked pages are Stable.Checks
bun run test:docs(sources, no build): no site-root docs links; relative links resolve, in the same locale when possible; no hand-written pinnedgpui-preversion or versioned docs.rs gpui-pre URL; known variables only; en/zh-CN maturity match.bun run test:links: every<a>and redirect in a build reaches a built page;test:versioned-examplesrepeats it at/versions/test/, where leaving the version fails.Cargo.tomlchanges.Verified locally with a production-shaped build (v0.6.6 at
/, this branch at/versions/main): all website tests pass, the v0.6.6 snapshot passes the link check at/versions/v0.6.6/, and the 404 fallback works for/docs/entityand/zh-CN/docs/entity.Publishing a release that contains the new GPUI guides is what makes
/docs/show them; this PR does not change which version is the default.🤖 Generated with Claude Code