website-metalsmith
website-metalsmith copied to clipboard
fastify
Feature: switching docs version should retain the current page (if exists)
🚀 Feature Proposal
As proposed by @Eomm in #160:
When you switch version in a page (like decorators for ex), the user is sent to the TOC, could we maintain the path changing only the version-path-param?
Motivation + Example
The user might be reading a page, for instance Request, and suddenly realises they are reading the doc for the wrong version. They might switch to the desired version but the switch will bring them to the ToC for that version rather than to the Request page for that version. So they have to navigate manually to the Request page, which requires extra effort.
Potential issue: pages might not exist in all versions
When a page does not exist in a given version, what do we do?
- Option 1: we don't show the version itself in the dropdown
- Option 2: we show the version but we point it to the Table of Contents for that version
Any preference @Eomm, @mcollina, @jsumners ?
Possible implementation
- In the
process-releasesscript, build a data file with an array of all the docs paths available. - In the template, where we render the dropdown boxes, we can easily check if a given page exists or not by accessing the data from the file above.
@jsumners are you thinking about a generic error page (generic 404) or a more specific one like the following?
~~~
Sorry the page `Request` does not exist in v.X.Y.Z
[Go somewhere else]
~~~
Where do we go from there? ToC for vX.Y.Z ?
Maybe at that point it could make more sense to just print the entire ToC for vX.Y.Z under the error... 🤔
Maybe at that point it could make more sense to just print the entire ToC for vX.Y.Z under the error... 🤔
Yes, this seems about right!
Where do we go from there? ToC for vX.Y.Z ?
Maybe at that point it could make more sense to just print the entire ToC for vX.Y.Z under the error... 🤔
Agree!
In my opinion, the common use case scenario will be to first select the version if you are not working with latest. Realizing you are targeting the wrong version I think will hardly ever happen. So just redirecting to the main docs page (as it's done now) I think is the correct solution. Having two different behaviours without signaling the user somehow could mislead them
