From 88ca87db46c4c0de10ea63956e1d5f2543929b43 Mon Sep 17 00:00:00 2001
From: loganlipscomb <logan.lipscomb@netfoundry.io>
Date: Thu, 12 Nov 2026 15:03:48 -0700
Subject: [PATCH 1/2] Style guide: add numbered steps guidance for headings and
 sidebar labels

---
 nf-style-guide.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/nf-style-guide.md b/nf-style-guide.md
index 1f2534c1..5ceb01fc 100644
--- a/nf-style-guide.md
+++ b/nf-style-guide.md
@@ -30,7 +30,7 @@ scan, and they build user trust.
 - Sidebar category/bucket labels use noun phrases, not verb phrases: "Deployments", "Identity providers",
   "Topologies". Reserve imperative phrases for leaf how-to pages that actually walk through a task.
 - Don't end headings with punctuation (`.`, `,`, `;`, `:`, `!`). Question marks are fine.
-- If a heading has a colon, capitalize the first word after it: "Step 1: Install the agent".
+- If a heading has a colon, capitalize the first word after it: "Optional: Configure a custom domain".
 - Don't skip heading levels. An H3 goes under an H2, not straight under the H1.
 
 ### Sentence-style casing
@@ -52,6 +52,32 @@ References:
 - [Writing readable content](https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read)
 - [Readability Guidelines: Capitals](https://readabilityguidelines.co.uk/grammar-points/capital-letters/#2-use-sentence-case-in-headlines-and-subheads)
 
+### Numbered steps
+
+Show a step number once, and don't use the word "Step". The number alone tells the reader where they are.
+
+**Multi-page procedures** (a sidebar category where each page is one step):
+
+- Put the number in the `sidebar_label`, not the H1. The sidebar already shows the sequence, and an H1 like
+  "Step 2: Register the DNS server identity" reads oddly in search results and browser tabs, where readers often land
+  without the surrounding context.
+- Write the H1 as an imperative verb phrase that makes sense on its own.
+- Keep the sidebar label a shortened version of the H1, prefixed with the number.
+
+| Field           | Use                                                 | Not                                                         |
+| --------------- | --------------------------------------------------- | ----------------------------------------------------------- |
+| `title` (H1)    | `Register the DNS server identity on the overlay`   | `Step 2: Register the DNS server identity on the overlay`   |
+| `sidebar_label` | `2. Register DNS server`                            | `2. DNS server identity`, `Step 2: Register DNS server`     |
+
+**Multiple step sections on one page:**
+
+- When a page uses headings as steps, number them with the number and a period. Don't add "Step":
+  `## 1. Install the agent`, not `## Step 1: Install the agent`.
+- Only number headings when each step is substantial enough to need its own section. For short procedures, use a
+  numbered list instead.
+- Numbered headings change their anchor links (`#1-install-the-agent`). If you reorder or insert steps, check for
+  links to the old anchors.
+
 ## Structure and organization
 
 We use a Diátaxis framework. When creating content, think in terms of these four categories:

From c62c070ccb9c0dbee436eeb89fb2ac6db4e49282 Mon Sep 17 00:00:00 2001
From: loganlipscomb <logan.lipscomb@netfoundry.io>
Date: Thu, 12 Nov 2026 15:05:43 -0700
Subject: [PATCH 2/2] Style guide: rename to 'Numbered steps in headers' and
 clarify scope

---
 nf-style-guide.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/nf-style-guide.md b/nf-style-guide.md
index 5ceb01fc..78c7674f 100644
--- a/nf-style-guide.md
+++ b/nf-style-guide.md
@@ -52,9 +52,10 @@ References:
 - [Writing readable content](https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read)
 - [Readability Guidelines: Capitals](https://readabilityguidelines.co.uk/grammar-points/capital-letters/#2-use-sentence-case-in-headlines-and-subheads)
 
-### Numbered steps
+#### Numbered steps in headers
 
-Show a step number once, and don't use the word "Step". The number alone tells the reader where they are.
+This covers how to style step numbers in headings: page titles (H1) and section headings in the page body. Show a
+step number once, and don't use the word "Step". The number alone tells the reader where they are.
 
 **Multi-page procedures** (a sidebar category where each page is one step):
 
@@ -69,9 +70,9 @@ Show a step number once, and don't use the word "Step". The number alone tells t
 | `title` (H1)    | `Register the DNS server identity on the overlay`   | `Step 2: Register the DNS server identity on the overlay`   |
 | `sidebar_label` | `2. Register DNS server`                            | `2. DNS server identity`, `Step 2: Register DNS server`     |
 
-**Multiple step sections on one page:**
+**Step headings in the page body** (multiple step sections on one page):
 
-- When a page uses headings as steps, number them with the number and a period. Don't add "Step":
+- When a page uses H2 or H3 headings as steps, number them with the number and a period. Don't add "Step":
   `## 1. Install the agent`, not `## Step 1: Install the agent`.
 - Only number headings when each step is substantial enough to need its own section. For short procedures, use a
   numbered list instead.