feat(ci): check that every synced man page has a docs.json nav entry#41
Merged
Conversation
man/*.mdx is synced from flox/flox, but sidebar entries in docs.json are curated by hand, so a new command's page can ship reachable-by-URL but invisible in the nav (this happened with flox-run and flox-deactivate, fixed in #40). scripts/check-man-nav.sh fails when a man page has no nav entry, with an ALLOWLIST for deliberate exclusions (the auto-activation pages, per c2f6538) and stale-allowlist warnings. It runs as a non-fatal warning at the end of sync-man-pages.sh and as a required-to-pass workflow on PRs that touch man/, docs.json, or the script itself. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
djsauble
marked this pull request as draft
July 15, 2026 18:41
djsauble
force-pushed
the
add-man-nav-check
branch
from
July 15, 2026 18:45
6c2e613 to
e4f4888
Compare
djsauble
marked this pull request as ready for review
July 15, 2026 18:46
stephenyeargin
approved these changes
Jul 15, 2026
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
2 participants
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.
Summary
Follow-up to #40, where
flox runandflox deactivateshipped reachable-by-URL but missing from the sidebar:man/*.mdxis synced from flox/flox, whiledocs.jsonnav entries are curated by hand, and nothing caught the gap.This adds
scripts/check-man-nav.sh, which fails when a page underman/is not referenced in thedocs.jsonnavigation tree:ALLOWLISTin the script covers deliberate exclusions — currently the auto-activation pages (flox-activate-allow,flox-activate-deny) removed from the nav in c2f6538. Stale allowlist entries (file deleted upstream, or page added back to the nav) produce warnings.sync-man-pages.shnow runs the check at the end as a non-fatal warning, so both local syncs and the daily sync workflow surface missing entries in their output.check-man-navworkflow runs the check as a hard gate on PRs touchingman/**,docs.json, or the script — so the daily sync PR goes red when a new command needs a sidebar entry.Verified against a scratch copy: removing
man/flox-runfrom the nav fails with the page listed; deleting an allowlisted page's file warns without failing.🤖 Generated with Claude Code