From 6da4e1437b9975f1ff41c4a8fde03cfd6f7fee9c Mon Sep 17 00:00:00 2001
From: Julius Volz <julius.volz@gmail.com>
Date: Sat, 24 May 2025 12:54:40 +0200
Subject: [PATCH] Correct heading instructions for blog posts vs. docs pages

Signed-off-by: Julius Volz <julius.volz@gmail.com>
---
 markdown-guide.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/markdown-guide.md b/markdown-guide.md
index c6515bb5..31b9559c 100644
--- a/markdown-guide.md
+++ b/markdown-guide.md
@@ -13,10 +13,17 @@ Generally, we use [GitHub Flavored Markdown](https://github.github.com/gfm/) for
 
 ## Heading levels
 
-For both blog posts and documentation pages, please use headings in the following ways:
+For blog posts and documentation pages, please use headings in the following ways:
+
+### For documentation pages
+
+* Start the Markdown content with a single top-level heading (`# Heading`, `<h1>`) that reflects the page title (should usually be the same as the `title` frontmatter field).
+* Use second-level headings (`## Heading`, `<h2>`) for the main sections of the page and use lower-level headings for subsections as appropriate.
+
+### For blog posts
 
 * **DO NOT use any top-level headings (`# Heading`, `<h1>`) in the Markdown content itself.** The final rendered page will include an automatic H1 heading based on the `title` frontmatter field.
-* Use second-level headings (`## Heading`, `<h2>`) for the main sections of a page and use lower-level headings for subsections as appropriate.
+* Use second-level headings (`## Heading`, `<h2>`) for the main sections of the blog post and use lower-level headings for subsections as appropriate.
 
 ## Frontmatter fields