Writing HubSpot Knowledge Base Articles (Table of Contents Best Practice)

Because HubSpot already reserves:

• H1 for the article title, and

• H2 for the article subtitle

all headings in the article body must start at H3.

---

How the Table of Contents Works

The TOC is generated automatically from:

• H3 – Main sections

• H4 – Sub-sections

Headings outside the article body, or headings created with formatting (bold, font size, colour), are not included.

---

Required Heading Structure

Use H3 for Main Sections

All primary headings in sections in the article body must use H3.

Examples:

Overview

• Before you start

• Configuration steps

• Common issues

---

Use H4 for Sub-Sections

Use H4 only under an H3 to break sections into steps or sub-topics.

Examples:

• Step-by-step instructions

• Troubleshooting scenarios

• Optional settings

---

What Not to Do

Do Not Use H1 or H2 in the Article Body

Do not manually insert:

• H1 headings

• H2 headings

These are already used by HubSpot for the article title and subtitle.

---

Do Not Skip Heading Levels

Incorrect structures:

• H3 → H4 → H3 (without returning logically)

• H3 → H5

Always move down one level at a time.

---

Do Not Fake Headings

Do not use:

• Bold text

• Larger font sizes

• Underlining

• Coloured text

These will not appear in the TOC.

---

Recommended Article Structure

A well-structured article looks like this:

• H3 – Overview

• H3 – Before you start

• H3 – Configuration steps

  • H4 – Step 1: Create the record

  • H4 – Step 2: Set properties

  • H4 – Step 3: Test your setup

• H3 – Common issues

  • H4 – Record not updating

  • H4 – Missing permissions

• H3 – Related articles