feat: version the website docs#179
Open
V3RON wants to merge 7 commits into
Open
Conversation
Split the docs into latest and v2 versioned trees and enable Rspress multi-version routing with latest as the default.
Add a short note in the rspress config explaining why sidebar and nav are built by hand for versioned docs.
#189) ## Summary - Sets `v2` as the default version in `rspress.config.ts` so the latest docs live at the bare URL path - Generates sidebar and nav dynamically in `rspress.config.ts` by reading the `_meta.json` files at config time -adding a new page only requires updating the relevant `_meta.json`, no changes to `rspress.config.ts` needed ## Root cause Rspress's `multiVersion` feature routes the default version without a URL prefix. When both `_meta.json` and `_nav.json` exist at the version root, rspress uses "global sidebar" mode and collapses the entire sidebar into a single `'/'` key meaning all versions share the same sidebar and switching versions in the header has no effect on the sidebar content. AFAIK, there is currently no documented way to use the global sidebar with `multiVersion`. This is being tracked in a discussion with the rspress maintainers: web-infra-dev/rspress#3452 https://github.com/user-attachments/assets/e59d3d23-8c9b-416c-86f6-9db5a6d0e2cd --------- Co-authored-by: Hristo Totov <hristo.totov@callstack.com> Co-authored-by: Szymon Chmal <szymon@chmal.it>
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.
What is this?
This PR splits the website docs into two versions:
latestfor the current release snapshot andv2for the existing docs content. The site now defaults tolatestwhile still allowing readers to switch back tov2.How does it work?
The docs are moved into versioned directories under
website/docs, and Rspress is configured with multi-version support solatestis served at the root URL. The versioned search index is enabled, and both versions stay available through the shared version switcher.Why is this useful?
latestthe default experience without hidingv2.