Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix Links for Hugo #5531

Closed
wants to merge 5 commits into from
Closed

Fix Links for Hugo #5531

wants to merge 5 commits into from

Conversation

jameskerr
Copy link
Member

@jameskerr jameskerr commented Dec 12, 2024

I've removed the .md suffixes from the links in the docs.

I've removed the _index from the end of section pages.

We should run the link checker on this soon to see if there are any broken straggler links.

@jameskerr jameskerr requested a review from philrz December 12, 2024 18:57
@philrz
Copy link
Contributor

philrz commented Dec 12, 2024

Hmm. I don't think that matches how I'd expected we might go about addressing that. The way things are now on this branch, when trying to browse within GitHub below docs/, pretty much all the links are now broken. For instance if you go to https://github.com/brimdata/super/blob/fix-links-for-hugo/docs/commands/_index.md and click that first link under "The super command is..." it's a 404 since the underlying file still ends in .md. Now, I'm mindful of the fact that the top priority here is how things look & feel in their final home within the docs site. But in addition to it being convenient that users could still do some light docs browsing within GitHub itself, having working links within the super repo itself is also helpful since it allows for running a markdown-based link checker while PRs are still under development or right after they're merged. And actually renaming the files themselves in the super repo to not have an .md extension would lose us a couple things, such as GitHub would no longer render the markdown (once again handy for quick browsing within the repo), as well as it being a self-documenting extension.

Maybe there's other ways to go about this, but my first instincts were to just see how Docusaurus was doing what it was doing and somehow mimic that. I don't know exactly how they accomplished it at the code level, but we always were able to keep things as they have been on the GitHub side and then when building the docs site contents they'd just morph things to drop the .md extensions while keeping the hyperlinks between pages working to match that, have things that started on the super repo as README.md files become top-level links (e.g., https://github.com/brimdata/super/blob/main/docs/commands/README.md becomes https://zed.brimdata.io/docs/next/commands) etc.

@jameskerr jameskerr closed this Dec 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants