use friendly "semi-stable" urls for key versions #256
Conversation
Currently all of the versioned docs have the explicit version in the url. This has the virtue of being [cool](https://www.w3.org/Provider/Style/URI) but has some awkwardness in practice. For example if one links to https://www.pantsbuild.org/2.18/docs/using-pants/using-pants-in-ci from another webpage it will eventualy end up with the 'no longer maintained' banner. It isn't super fun to update every internal/wiki link every 6 weeks for a release. This change introduces some "semi-stable" urls for key versions: * `prerelease`: The latest prerelease * `dev`: aka `main` aka "trunk" * `stable`: The most recent stable release Redirects ensure that the versioned urls also work. As an example, right now: `/stable/docs/using-pants/using-pants-in-ci` is the doc for `2.21` and `/2.21//docs/using-pants/using-pants-in-ci` redirects to there. After the next release, `/stable/docs/using-pants/using-pants-in-ci` will be for `2.22` and `/2.21/docs/using-pants/using-pants-in-ci` will keep pointing to the `2.21` content. I think this is reasonable compromise of easy of use with permanence. FWIW the Offical Docusaurus position seems to be to prefer server side redirects facebook/docusaurus#9049 but as far as I can tell that isn't an option for GitHub Pages. ref #221
|
To fully test locally: Which takes ~half an hour on my poor old laptop. |
|
cc @thejcannon |
docusaurus.config.js
Outdated
| redirects, | ||
| redirects: old_site_redirects, | ||
| createRedirects(existingPath) { | ||
| if (existingPath.includes("/dev/")) { |
There was a problem hiding this comment.
Is there ever a chance of /dev/ showing up elsewhere in a URL? Can .startsWith be used here?
docusaurus.config.js
Outdated
| createRedirects(existingPath) { | ||
| if (existingPath.includes("/dev/")) { | ||
| return [existingPath.replace("/dev/", `/${currentVersion}/`)]; | ||
| } else if (existingPath.includes("/prerelease/")) { |
There was a problem hiding this comment.
same comment re string matching
docusaurus.config.js
Outdated
| `/${mostRecentPreReleaseVersion.shortVersion}/` | ||
| ), | ||
| ]; | ||
| } else if (existingPath.includes("/stable/")) { |
There was a problem hiding this comment.
same comment re string matching
|
I like it.
This does sound like a reasonable compromise. Brainstorming another idea: have the versioned links remained version, rather than redirect:
(Bonus points: support pressing Example: https://doc.rust-lang.org/stable/std/ and https://doc.rust-lang.org/1.80.1/std/ are the same content, where the first is evergreen while the second is a permalink. Thoughts? Maybe too much effort with how docusaurus works? |
I also like that more. My understanding of the linked docusaurus issue is that it is asking for more or less that. I think to do that today we would need to either:
|
|
(not thinking too hard about it) I do think this is a good change and an improvement 🙂 |
| @@ -52,8 +52,8 @@ jobs: | |||
| - run: yarn install --frozen-lockfile | |||
| - run: npm run build | |||
| env: | |||
| NODE_ENV: "production" | |||
There was a problem hiding this comment.
Not doubting this, but what was the reason to add this?
There was a problem hiding this comment.
I think the various nested ?: operators happen to work either way right now, but being explicit about building everything for the public site.
https://github.com/pantsbuild/pantsbuild.org/blob/main/docusaurus.config.js#L20
Currently all of the versioned docs have the explicit version in the url. This has the virtue of being
cool but has some awkwardness in practice. For example if one links to
https://www.pantsbuild.org/2.18/docs/using-pants/using-pants-in-ci from another webpage it will eventualy end up with the 'no longer maintained' banner. It isn't super fun to update every internal/wiki link every 6 weeks for a release.
This change introduces some "semi-stable" urls for key versions:
prerelease: The latest prereleasedev: akamainaka "trunk"stable: The most recent stable releaseRedirects ensure that the versioned urls also work.
As an example, right now:
/stable/docs/using-pants/using-pants-in-ciis the doc for2.21and/2.21//docs/using-pants/using-pants-in-ciredirects to there. After the next release,/stable/docs/using-pants/using-pants-in-ciwill be for2.22and/2.21/docs/using-pants/using-pants-in-ciwill keep pointing to the2.21content.I think this is reasonable compromise of easy of use with permanence.
FWIW the Offical Docusaurus position seems to be to prefer server side redirects facebook/docusaurus#9049 but as far as I can tell that isn't an option for GitHub Pages.
ref #221