Add advisory CI check for docs pages orphaned from sidebars.js - #5011
Draft
Duncanma wants to merge 1 commit into
Draft
Add advisory CI check for docs pages orphaned from sidebars.js#5011Duncanma wants to merge 1 commit into
Duncanma wants to merge 1 commit into
Conversation
sidebars.js is hand-authored here, so a moved or newly added page never gets wired into navigation automatically. bin/check-orphan-pages.js walks every sidebar entry and every docs/ file to find pages that will build and get a real URL but aren't reachable from any sidebar, with automatic exemptions for draft/unlisted frontmatter and a bin/orphan-pages-baseline.json for tracked exceptions. Running it against the current tree found 14 real orphans (seeded into the baseline with notes), including a CLI command-reference page added by the codegen bot in #5002 without a matching sidebar entry. Wired into CI as a warning only (check-orphan-pages.yml): posts a PR comment and file annotations, never fails the job. Replaces the old, unwired, buggy bin/audit-stray-pages script that this supersedes.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview linksThis PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here. |
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.
Summary
sidebars.jsis hand-authored in this repo (no_category_.jsonautogeneration), so a moved or newly added docs page never gets wired into navigation automatically. This adds a check for that gap:bin/check-orphan-pages.js— requiressidebars.jsdirectly (rather than regex-scraping it) and walks every sidebar entry (documentationandtctl), then walks every.md/.mdxfile underdocs/to find pages that will build and get a real URL but aren't reachable from any sidebar.docusaurus.config.js's owndocs.exclude), frontmatterdraft: true(never builds in production), and frontmatterunlisted: true(Docusaurus's own mechanism for a page that renders without navigation — the right choice overdraftfor a page that must stay linkable from prose elsewhere).bin/orphan-pages-baseline.json— tracked exceptions, same shape/convention as the existingbin/metrics-baseline.json. Regenerate with--update-baseline; stale entries (no longer orphaned) are flagged for removal.docs/cli/command-reference/cloud/project.mdx, added by the CLI-docs codegen bot in Update CLI docs for release v1.8.2 #5002 without a matching sidebar entry, anddocs/develop/typescript/install-typescript-sdk.mdx, which has zero inbound links anywhere and looks like dead leftover from the 2023 SDK reorg..github/workflows/check-orphan-pages.yml— wired into CI as a warning only, not a merge gate. Posts a PR comment (marker-based create/update, same pattern asbuild-check.yml) plus::warning::file annotations. No step ever fails the job, so it can't block merging regardless of findings.bin/audit-stray-pages, an old, unwired, buggy version of the same idea (it didn't combine a custom frontmatterid:with the file's directory, so it misflagged pages likecloud/rto-rpo.mdx). UpdatedUTILITIES.mdandAGENTS.mdaccordingly.Test plan
node --test bin/check-orphan-pages.test.js— 17 new unit tests, all passingyarn test— full suite passes except one pre-existing, unrelated failure already onmain(ReleaseNoteHeader featureName overrides explicit type when mapped)yarn check:orphans— clean against the current tree with the seeded baselineyarn build(via the pre-commit hook) — passes::warning::annotation formatsidebars.js, markunlisted: true, or deleteOpening as a draft — parking this for a few days before moving it forward.
┆Attachments: EDU-6865 Add advisory CI check for docs pages orphaned from sidebars.js