Add _redirect config file as last build step #40
Merged
Conversation
This file contains 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
nwt
reviewed
Aug 29, 2022
Co-authored-by: Noah Treuhaft <noah.treuhaft@gmail.com>
nwt
approved these changes
Aug 30, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
tl;dr
We can't currently link explicitly link to the "latest" Zed docs on zed.brimdata.io by using URLs that contain a GItHub tag. This PR adds a Netlify "redirects" config that fixes that.
Background
Before we can address brimdata/zui#2360, we need to work around a Docusaurus limitation. The table below from the Docusaurus docs sets the scene.
Let's translate that to an example in our world
For starters, the links in the original GitHub repo can always be referenced by explicit tag. These both work fine:
https://github.com/brimdata/zed/blob/v1.1.0/docs/tutorials/zed.md
https://github.com/brimdata/zed/blob/v1.2.0/docs/tutorials/zed.md
But due to what's described in that table, this link exists:
https://zed.brimdata.io/docs/v1.1.0/tutorials/zed
...but this one is a 404:
https://zed.brimdata.io/docs/v1.2.0/tutorials/zed
The page that corresponds to the
v1.2.0tag would be found at https://zed.brimdata.io/docs/tutorials/zed. But we'd not want to ship a version of the app with that non-tagged URL baked into it, since the "latest" is going to keep changing as we release new Zed versions.The Fix
I tried to find a solution at the Docusaurus layer but was unsuccessful. For instance, there's this unanswered StackOverflow question. I also asked on their Discord server and nobody responded.
Thankfully, now that we're on Netlify, it looks like it can be addressed pretty well at that layer via their redirects config. In this PR I've taken the approach of dynamically adding the
_redirectsconfig file to the completedbuilddirectory based on whatever the highest version number is in theversions.json. That way as long as the new version number is added toversions.jsonlike was done in the most recent time we froze a tagged version (#21), the redirect for the new version will happen automatically.Testing
I have a test version of the site deployed in my personal Netlify where you can see for yourself that it's effective. For the link variations without/with trailing slash as well as anchor link, these all land in the correct place when clicked.
https://spiffy-gnome-8f2834.netlify.app/docs/v1.2.0/tutorials/zed
https://spiffy-gnome-8f2834.netlify.app/docs/v1.2.0/tutorials/zed/
https://spiffy-gnome-8f2834.netlify.app/docs/v1.2.0/tutorials/zed#time-travel
As for asset links to downloadable files, these never had version tags in the first place, hence are not affected by this change, e.g.:
https://spiffy-gnome-8f2834.netlify.app/assets/files/github1-2496d524ce44f4cb9f32cfeb70fa669e.zng