docs: reconcile H1/label mismatches into front-matter titles (Phase 3) - #28036
Draft
nickvigilante wants to merge 2 commits into
Draft
docs: reconcile H1/label mismatches into front-matter titles (Phase 3)#28036nickvigilante wants to merge 2 commits into
nickvigilante wants to merge 2 commits into
Conversation
Batch B of the Phase 3 H1 to front-matter migration (DOCS-484, parent DOCS-477). For the 124 hand-authored pages whose body H1 differed from the manifest nav label, promote the richer body H1 to the front-matter page title and drop the duplicate H1, keeping the short manifest label as the sidebar entry (policy agreed with the docs owner). Page-title collisions are resolved by renaming the non-generated page: - install/cli.md -> "Install the Coder CLI" (vs install landing "Installing Coder") - ai-gateway/clients/jetbrains.md -> "JetBrains" - extending-templates/web-ides.md -> "Web IDEs in templates" - workspace-management.md -> "Manage workspaces" (vs generated api/workspaces.md) Duplicate sidebar labels are acceptable; identical page titles are not. Generated pages (audit-logs, configuration-reference) are excluded; their generators must emit front matter first (tracked separately). Also drops a now-dangling in-page #mcp fragment in ai-gateway/mcp.md.
There was a problem hiding this comment.
🚫 [linkspector] reported by reviewdog 🐶
Cannot reach ../provisioners/index.md#external-provisioners Status: 404 Cannot find section: #external-provisioners in file: /home/runner/work/coder/coder/docs/admin/provisioners/index.md.
coder/docs/admin/monitoring/health-check.md
Line 318 in a80f3ed
Set the install landing page title to "Install Coder in your infrastructure" (sidebar label unchanged).
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 B of Phase 3 of the H1 → front-matter migration (
DOCS-484; parentDOCS-477), the editorial follow-up to Batch A (#28030). For the 124 hand-authored pages whose leading body H1 differed from the manifest nav label, this promotes the richer body H1 to the front-matter page title and drops the duplicate H1, while keeping the short manifest label as the sidebar entry.Policy agreed with the docs owner:
Page-title collisions resolved
Promoting the H1 created 4 page-title collisions; each is disambiguated by renaming the non-generated / secondary page (sidebar labels left unchanged):
install/index.mdinstall/cli.mdai-gateway/clients/jetbrains.mdworkspace-access/web-ides.mdextending-templates/web-ides.mdworkspace-management.mdapi/workspaces.md)These titles are the only non-mechanical editorial calls in this PR.
Deliberately excluded: generated pages
admin/security/audit-logs.mdandadmin/setup/configuration-reference.mdaremake genoutputs (auditdocgen/configdocgen) that Phase 2 did not update, so a hand-added title would be reverted on the next generation. They're excluded here and need their generators taught to emit front matter first (Phase 2 pattern), tracked asDOCS-631. Batch A (#28030) had the same issue for three other generated pages; it has been corrected there too.Verification
AI was the primary author of this PR (see disclosure below); per the AI Contribution Guidelines here is the manual verification.
titleto the body H1 (or the disambiguated title above) and remove that one duplicate H1. No other body prose is reflowed.pnpm check-docs(markdownlint-cli2 + table formatter):Summary: 0 error(s).[MCP](#mcp)inai-gateway/mcp.md), now repointed. A cross-file fragment audit into the retitled pages found no real breakage.Anchor-change note
Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each page's effective title from the manifest label to the body H1, so the rendered H1 anchor slug changes. An audit of cross-file
.md#fragmentlinks into these pages surfaced no links that break as a result (the only hits were false positives against a still-present## TLS & Reverse Proxyheading). Same-file fragments are enforced by markdownlint MD051, which is green.Linear: DOCS-484