Update "Syntax docs" link in Brim app's query bar drop-down menu

[garrisonhess]

Hi Brim team,

I was playing with the toy data in Brim yesterday and noticed that the "Syntax docs" link sent me to GitHub, but the new Zed website docs seemed more helpful. This may not be a bug, so please feel free to close this if it's intended! The description below details things.

Describe the bug
Brim app's "Syntax docs" link directs to older GitHub documentation but the new Zed docs are more directly helpful.

Here is the current link: https://github.com/brimdata/zed/blob/v1.1.0/docs/language/README.md

To Reproduce
Open the Brim app and click the query bar's settings drop-down icon.

Expected behavior
Link to: https://zed.brimdata.io/docs/commands/zq/ (or something else on the new Zed website).

Screenshots

Desktop Info

• OS: MacOS
• v0.30.0 downloaded via: https://www.brimdata.io/download/

[philrz]

Thanks @garrisonhess. The new Zed docs site would indeed be a better destination to link to from the app. While doing some research on migrating the docs site to another hosting provider other reasons (brimdata/zed-docs-site#26) I bumped into a Docusaurus limitation that concerned me, but I think I see the fix.

We ideally want the app to point to the docs that match the tag of the bundled Zed release, and this is possible today with the docs in GitHub. However, as can be seen in the first table at https://docusaurus.io/docs/versioning, whichever Version is "latest" ends up being served at a URL that lacks the tag. Using the versions on the current Zed docs site as an example, we can find the Zed v1.1.0-tagged zq doc at https://zed.brimdata.io/docs/v1.1.0/tutorials/zq/, but if you then select the Zed v1.2.0 tag from the drop-down, the URL changes to https://zed.brimdata.io/docs/tutorials/zq/. If you try to go directly to a URL like https://zed.brimdata.io/docs/v1.2.0/tutorials/zq/, it's a 404. Going through the Docusaurus docs and open issues, I couldn't find a way to fix this at the Docusaurus level.

Thankfully I do think I see a fix if we end up deploying on Netlify, which looks to be the current likely choice. Their redirects config includes a splat option that seems to do the trick in my quick test. So if I put this _redirects file in the base of the build/ directory before pushing to Netlify, I was able to go directly to v1.2.0-tagged URLs in my test site.

$ cat _redirects 
/docs/v1.2.0/*	/docs/:splat

I'll leave this comment here as a note-to-self to circle back and test/deploy this config change once the base work to migrate to Netlify is finished.

[philrz]

Verified in Brim commit ef478a4.

In current Brim code (which will soon be GA'ed under the new "Zui" name) the link to the language docs is no longer present at the location shown in the screenshot at the top of this issue. However, we've always linked to it from Help > Zed Syntax Docs in the pull-down menu. As shown in the attached video, that link now goes to the new docs site.

Verify.mp4

As the notes in #2511 get into it in more detail, since I'm running a Dev release of Brim here that's pointing to a commit hash for a non-GA Zed, here we end up at the "next" version of the Zed docs (i.e., the tip of Zed main). As #2511 shows, when Zed is of a release tagged starting with v (e.g., the upcoming Zui v1.0) then that version tag is used to link to a specific version of the docs that corresponds to a GA Zed tag. And of course once they land on the new docs site, the reader is always free to pick any version they like from the pull-down.

Thanks again @garrisonhess for pointing this one out to us!