From 301e062316fe709eb801aca54f8cf7bb9d791bfb Mon Sep 17 00:00:00 2001
From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com>
Date: Fri, 15 May 2026 13:11:56 -0500
Subject: [PATCH] Update style guide: body H1 + wiki-URL internal links

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.
---
 STYLE_GUIDE.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
index 8f0c9c9f25..0578a5068a 100644
--- a/STYLE_GUIDE.md
+++ b/STYLE_GUIDE.md
@@ -159,8 +159,10 @@ Avoid:
 
 ### Headings
 
-Every page has exactly one H1, which is taken from the page's front
-matter `title`. Markdown body content starts at H2.
+Every page has exactly one H1, written as the first line of the body
+(`# Adding the button module`). mkdocs-material renders this as the
+page heading. The front matter `title:` is used by the nav, browser
+tab, and search snippets, and should match the H1.
 
 All headings use sentence case. The first word is capitalised, and
 proper nouns are capitalised. Everything else is lowercase.
@@ -177,8 +179,8 @@ mkdocs-material integrates each page's TOC into the left sidebar, and
 `toc_depth` is set to `3` in `mkdocs.yml`. That means **only H2 and H3
 headings appear in the sidebar**. Plan your headings with that in mind:
 
-- **H1**: the page title, taken from the front matter `title`. Exactly
-  one per page, and the body never starts with another H1.
+- **H1**: the page title, written as the first line of the body and
+  mirrored in the front matter `title:`. Exactly one per page.
 - **H2**: major sections. Each H2 becomes a sidebar entry, so use them
   for things a reader might jump to ("Connecting through hotspot",
   "Troubleshooting").
@@ -304,16 +306,16 @@ homeassistant:
 
 ### Internal links
 
-Internal links use site-relative paths, not absolute
+Internal links use site-relative paths in wiki-URL form (trailing
+slash, no `.md` extension), not absolute
 `https://wiki.apolloautomation.com/...` URLs:
 
 ```markdown
-See [getting started](../setup/getting-started.md) for first-boot setup.
+See [getting started](../setup/getting-started/) for first-boot setup.
 ```
 
-Relative links work in PR previews, survive a future domain change, and
-let mkdocs catch broken targets at build time. Links to external sites
-(home-assistant.io, esphome.io) stay absolute.
+Relative links work in PR previews and survive a future domain change.
+Links to external sites (home-assistant.io, esphome.io) stay absolute.
 
 ---