Markdown Titles and Headings: H1, Numbering, Page Titles, and Syntax
Table of Contents
The quick answer How to make a title in Markdown H1, H2, and H3 heading levels Markdown heading numbers and auto numbering Markdown page title vs visible document title Horizontal rules and the--- trap Check a heading outline locally Frequently asked questions “Markdown title” can mean several different things. It may mean the visible heading at the top of a README, the browser tab title of a documentation page, a YAML front matter field, or the first item in a generated table of contents. Those are related publishing concepts, but they are not one piece of Markdown syntax.
This guide separates the terms, gives you portable code snippets, and explains where Markdown ends and your site generator or publishing platform begins. The goal is not to force every document into one outline; it is to make the structure visible enough for readers, contributors, and future you to understand.
# Title. Use ## for main sections and ### for subsections. Plain Markdown does not define one portable automatic-heading-number feature or a browser-page <title>; those are usually handled by the author, a table-of-contents tool, or a site generator.
How to make a title in Markdown
The most widely recognized form is an ATX heading: one to six number signs, followed by a space and the heading text. CommonMark defines the level by the number of opening # characters and supports levels one through six.[1]
# Project release notes
## Added
## Fixed
### Known limitationFor an ordinary README, note, or standalone guide, the first visible title is usually an H1. A document does not become invalid if it has more than one H1, but a single primary title is easier to scan and produces a clearer outline for readers and assistive technologies. Use the words in that H1 to describe the document itself, not merely the repository or navigation label.
Recommended ATX style
# Setup the CLI
## Install
## ConfigureThis is easy to scan in source and works across common Markdown renderers.
Setext style, with a limitation
Setup the CLI
=============
Install
-------Setext syntax is valid for level 1 and 2 headings, but is less convenient for deeper sections and can be confused with a divider.
H1, H2, and H3: choose levels by structure, not size
A heading level communicates containment. An H3 belongs inside the preceding H2; it is not simply a smaller-looking heading. A useful mental model is an outline: title, sections, then subsections. If a heading looks visually right only at H4 but has no H3 parent, change the stylesheet or reconsider the structure rather than using a level to obtain a font size.
# Project release notes
## Installation
### Prerequisites
### Install the package
## Configuration
## Troubleshooting| Term people search for | Practical meaning | Portable answer |
|---|---|---|
| Markdown title | The visible main document name. | Use # Your title for the primary visible heading. |
| Markdown heading | A structural section label. | Use ## through ###### according to nesting. |
| Markdown header | A common informal synonym for heading. | In documentation, prefer “heading” when describing document structure. |
| Markdown subheading | A subsection within a section. | Use the next level, such as ### after ##. |
| Sections in Markdown | A set of logically grouped headings and content. | Use H2s for peer sections and H3s only inside their H2. |
If you inherit a long file, do not mechanically promote or demote every heading. First identify the intended top-level sections. Then fix one skipped level at a time, checking the rendered page after each structural change. A skipped level can be a mistake, but it can also show that a short fragment was copied from a larger document.
Markdown heading numbers and automatic numbering
CommonMark defines heading syntax, but it does not define a portable automatic-numbering marker for headings.[1] If a guide must show numbers in every renderer, write them as visible text:
# Migration guide
## 1. Prepare
### 1.1 Back up the database
### 1.2 Check the runtime version
## 2. Run the migration
## 3. Verify the resultThis works in plain Markdown because the numbers are part of the heading text. The trade-off is maintenance: moving a section means updating the visible numbers. Some documentation systems can generate a numbered table of contents or add numbers during rendering, but that behavior is platform-specific. Treat it as a publishing feature and test it in the same renderer where readers will see the document.
Markdown page title vs visible document title vs YAML front matter
A browser’s page title is an HTML concern. A visible H1 is document content. YAML front matter is metadata recognized by some static-site tools, but it is not a CommonMark heading. Keeping those roles distinct avoids a common source of confusing documentation pages.
---
title: "Install the CLI"
description: "Install and configure the command-line tool."
---
# Install the CLI
Use this guide to set up the command-line tool.For example, Astro can read YAML front matter from Markdown and expose fields such as title and description to a page layout; it also gives rendered headings anchor IDs for section links.[2] Another generator may use different names or no front matter at all. Keep the H1 because it is what readers see in the document, then configure metadata in the system that creates your HTML page.
Markdown separator lines: when --- is a divider and when it is a heading
Three hyphens can be a horizontal rule, but they can also underline the preceding line as a Setext H2. In CommonMark, the heading interpretation takes precedence when the preceding text can form a Setext heading.[1]
This becomes an H2
Install
---The dashes underline Install, so this is a level-2 heading.
Use this for a clear divider
Install the package.
***
Configure the client.A blank line and *** make the thematic break intention obvious.
Do not add separators only to make a document look longer. Use a heading when the next content begins a new section; use a thematic break for a meaningful change of topic inside the same broader section.
Check the outline before you publish
Paste a real README, guide, or release note into the editor, then open Outline. The browser-local sidebar lists H1–H3 headings, flags level jumps, and lets you navigate to a line without uploading the document. Use the Formatter & Linter afterward when you want to review heading spacing and hierarchy findings.
Open the Markdown Editor Review heading rules locally Read the syntax referenceFrequently asked questions
Should a Markdown file have one H1?
For a standalone document, one clear H1 is usually the most understandable pattern. Fragments, included files, and generated pages can have different needs. What matters most is that headings represent a sensible hierarchy and that the publishing environment renders the result as intended.
How do I make a Markdown page title?
Use an H1 for the visible document title. To set the browser tab title or search metadata, configure your static-site generator, CMS, or HTML layout. Many tools use YAML front matter for this, but front matter is not standard Markdown.
Can Markdown number headings automatically?
Not in one portable CommonMark syntax. Put numbers in the heading text when they must render everywhere, or use a documented renderer feature to generate them and verify the generated page.
What is the difference between a Markdown header and a heading?
In everyday usage they often mean the same thing. “Heading” is the clearer term for structural H1–H6 elements. “Header” can also mean a webpage header, a table header row, or an HTTP header, so it is more ambiguous in documentation.
Why does a line of dashes turn my text into a heading?
A line of dashes immediately after text can be parsed as a Setext H2. Use an ATX heading such as ## Install, or separate a thematic break with blank lines and use *** when you want a divider.
Next steps
Use headings to describe the real structure of the document, not to imitate a visual style. If the source is hard to scan, open the local Markdown Editor and inspect its outline. If the structure needs a final review, use the Formatter & Linter to distinguish safe syntax cleanup from author decisions.
References
- CommonMark Specification 0.30 — ATX headings, Setext headings, and thematic breaks.
- Astro: Markdown content guide — front matter, Markdown pages, and generated heading IDs.
- MarkdownMaster Docs: Document titles and headings