fix(docs): repair broken "SEE ALSO" links on CLI reference pages#49
Merged
Conversation
The link handler passed to cobra/doc was the identity function, so each command page's "SEE ALSO" section kept cobra's default "<command>.md" targets (e.g. frames_auth_login.md). Starlight serves those pages at extensionless, trailing-slash routes (/reference/cli/frames_auth_login/), and the site's remark-base-links plugin only rewrites root-absolute links, so the relative ".md" links resolved against the current page and 404'd. Replace the identity handler with one that maps "<command>.md" to the root-absolute route "/reference/cli/<command>/". remark-base-links then prepends the deployment base path, matching every other content link. Regenerate the pages and add a table-driven test pinning the mapping. Verified with a production-base build: the SEE ALSO links now render as /nebari-frames/reference/cli/<command>/ with no ".md" hrefs remaining.
|
📄 Docs preview for |
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
The bug
Every CLI reference page's SEE ALSO section linked to sibling/parent commands using cobra's default
<command>.mdtargets, e.g.:Starlight serves those pages at extensionless, trailing-slash routes (
/reference/cli/frames_auth_login/). A relativeframes_auth_login.mdon the page at/reference/cli/frames_auth/resolves to/reference/cli/frames_auth/frames_auth_login.md-> 404. So every "See also" link was dead. (The left sidebar was fine - Starlight builds those from slugs; only the in-content cobra links were broken.)Root cause
tools/docs-gen/main.gopassed the identity function as cobra/doc'slinkHandler, so the.mdtargets were emitted verbatim. The site'sremark-base-linksplugin only rewrites root-absolute links (/...), so it left these relative.mdlinks untouched.This is pre-existing and independent of the theme/runtime work in the other open PRs.
The fix
Replace the identity handler with one that maps
<command>.md->/reference/cli/<command>/(root-absolute).remark-base-linksthen prepends the deployment base path, exactly like every other content link on the site. The URL prefix is derived fromoutDirso it can't drift.<command>.md-> route mapping.Verification
go test ./...passes (incl. the newdocs-gentest);go vetclean; generator output is still byte-for-byte deterministic (the "CLI reference is up to date" CI check stays green).BASE=/nebari-frames/): SEE ALSO links now render as/nebari-frames/reference/cli/<command>/, with zero.mdhrefs remaining in any built CLI page, and they match the actual page routes.Before -> after (rendered):