docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) - #28030
Draft
nickvigilante wants to merge 2 commits into
Draft
docs: add front-matter titles to mechanical and no-H1 pages (Phase 3)#28030nickvigilante wants to merge 2 commits into
nickvigilante wants to merge 2 commits into
Conversation
Batch A of the Phase 3 H1 to front-matter migration (DOCS-484, parent DOCS-477). Adds a front-matter title to the 138 pages whose leading body H1 already equals the manifest nav label (dropping that now-duplicate H1) and to the 4 pages that render under a manifest label with no body H1. Rendered no-op: the renderers already prefer the manifest title and hide the body H1 (Phase 1), so no page changes visually. Reference pages (already front-matter-aware via Phase 2 generators) and the 126 pages whose body H1 differs from the manifest label (editorial reconciliation) are out of scope for this batch.
prometheus.md, platform-controls/index.md, and feature-stages.md are make gen outputs whose generators do not yet emit front matter, so a hand-added title would be reverted on the next generation. Excluded here and tracked separately (update the generators, Phase 2 pattern).
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
Batch A of Phase 3 of the H1 → front-matter migration (
DOCS-484; parentDOCS-477). Adds a front-mattertitleto every navigable docs page whose title can be migrated mechanically, with no editorial judgment.This is the content step that Phase 1 (renderers prefer front-matter title,
DOCS-482) and Phase 2 (tooling + generators front-matter-aware,DOCS-483) unblocked. Both are merged; coder.com #964/#974 are merged and live.Rendered no-op. The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it.
What's in this batch
Dry-run on
main(464 navigable pages) splits into:title, drop the duplicate H1titleonly142 files changed, all under
docs/.Deliberately out of scope: the 126 mismatches
Pages where the body H1 is richer than the short sidebar label (e.g. label Modules / H1 Contributing modules, label Install / H1 Installing Coder) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (
install/cli.mdandinstall/index.mdboth carry the H1 Installing Coder). These will land in follow-up batches by nav section once the policy is set, so each gets real review.Verification
AI was the primary author of this PR (see disclosure below); per the AI Contribution Guidelines here is the manual verification.
titleround-trips to the manifest label (checked programmatically across all 142 files).# H1that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing<!-- markdownlint-disable -->comments on the two pages that had them.pnpm check-docs(markdownlint-cli2 + table formatter) passes on the changed set:Summary: 0 error(s).MD041stays off (re-enabled in Phase 4);MD025is not tripped because the duplicate body H1s are removed.Linear: DOCS-484