Update style guide: body H1 + wiki-URL internal links#812
Conversation
Two adjustments based on how pages are actually authored: - Headings: the H1 lives at the top of the body (rendered by mkdocs-material as the page heading), with the front matter title mirroring it for nav, browser tab, and search snippets. Previously the guide said body content started at H2 and the H1 came from front matter. - Internal links: use wiki-URL form (trailing slash, no .md) instead of .md paths. Removes the build-time validation claim since that no longer applies.
WalkthroughThis PR updates documentation style guide conventions in a single file. H1 heading placement is clarified to require the first body line mirrored in front matter ChangesHeading and Link Conventions
🎯 2 (Simple) | ⏱️ ~10 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
STYLE_GUIDE.md (1)
241-241: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winInconsistency with the new H1 guidance.
Line 241 states that
title"shows in the browser tab, the nav, and the H1," which implies the H1 is derived from the front matter. This contradicts the new guidance introduced in lines 162-165 and 182-183, where the H1 is explicitly written as the first line of the body and the front mattertitle:mirrors it.📝 Proposed fix to align with new H1 conventions
-- `title` shows in the browser tab, the nav, and the H1. +- `title` shows in the browser tab and nav, and should mirror the H1 written as the first line of the body.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@STYLE_GUIDE.md` at line 241, The sentence claiming that the front-matter `title` "shows in the browser tab, the nav, and the H1" conflicts with the newer guidance that the H1 is explicitly written as the first line of the body and `title:` should mirror it; update the wording to state that the front-matter `title` controls the browser tab and nav, while the H1 must be the first line of the document body and should match the `title:` value (i.e., remove the claim that `title` directly produces the H1 and add a brief note that authors must keep them in sync).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@STYLE_GUIDE.md`:
- Line 241: The sentence claiming that the front-matter `title` "shows in the
browser tab, the nav, and the H1" conflicts with the newer guidance that the H1
is explicitly written as the first line of the body and `title:` should mirror
it; update the wording to state that the front-matter `title` controls the
browser tab and nav, while the H1 must be the first line of the document body
and should match the `title:` value (i.e., remove the claim that `title`
directly produces the H1 and add a brief note that authors must keep them in
sync).
1 participant
What does this implement/fix?
Two style-guide adjustments that bring the written rules in line with how pages are actually authored in this repo.
Headings (§6.2, §6.3). The guide previously said the H1 came from the front matter
title:and the body started at H2. In practice, every page has its H1 at the top of the body, which is what mkdocs-material renders as the page heading. The front mattertitle:mirrors it and feeds the nav, browser tab, and search snippets.Internal links (§7.5). The guide previously prescribed
.mdpaths. Pages on the wiki use the wiki-URL form (trailing slash, no extension), and that's what we want to keep. Updated the example accordingly and dropped the "let mkdocs catch broken targets at build time" line since it no longer applies to this link form.No published pages are modified; this is a contributor-facing rules update only. Once merged, a follow-up PR will align
casita-module.md,motion-module.md, andtemperature-humidity-module.mdto matchbutton-module.md's style.Types of changes
mkdocs.yml)Checklist:
devbranch (notmain)mkdocs servemkdocs.ymlmkdocs.ymlSummary by CodeRabbit
titlefield.mdextensions