Markdown Headings: Syntax and Best Practices

Markdown headings use the hash symbol (#) to create hierarchical titles from H1 through H6. One hash creates the largest heading, and six hashes create the smallest. Headings structure your document for readers and search engines, and they work identically across GitHub, Obsidian, VS Code, and every CommonMark-compatible parser. This guide covers the syntax, alternative styles, best practices, and auto-generated IDs.

How to Create Headings in Markdown

Place one or more # characters at the start of a line, followed by a space and your heading text:

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

The space between # and the text is required by CommonMark 0.31. Without the space, spec-compliant parsers treat the line as plain text, not a heading. GitHub follows the spec here, so #Heading renders as literal text on GitHub too; only older Markdown.pl-style parsers accept it.

Each heading level corresponds to an HTML tag: # becomes <h1>, ## becomes <h2>, and so on. Use H1 for the page title, H2 for major sections, and H3 through H6 for subsections.

Alternative Heading Syntax (Underline Style)

Markdown also supports an underline style for H1 and H2:

Heading 1
=========

Heading 2
---------

Use at least one = for H1 or one - for H2. Multiple characters work too and can make the source more readable. This syntax is called "Setext headings" in the CommonMark spec.

We prefer the # (ATX) style because it supports all six levels and is easier to scan in source files. The underline style only works for H1 and H2, and it takes up two lines instead of one.

How Many Heading Levels Should You Use?

Most markdown documents work best with 2 to 4 heading levels. Here are practical guidelines from our experience writing hundreds of markdown documents:

Blog posts and articles: Use H1 for the title, H2 for main sections (3 to 8 sections), and H3 for subsections within those. Rarely go beyond H3 for web content.

Technical documentation: Use H1 through H4. Deep nesting up to H4 helps organize API references, configuration guides, and specification documents.

GitHub README files: Use H1 for the project name (see the README markdown guide), H2 for major sections like Installation, Usage, and Contributing. Use H3 for sub-steps.

Going beyond H4 makes documents harder to navigate. If you need H5 or H6, consider restructuring your content into separate pages or sections instead.

Heading IDs and Anchor Links

Most markdown renderers automatically generate an ID attribute for each heading. This ID lets you link directly to a specific section of the page.

How IDs are generated:

## How to Create a Table

Becomes: <h2 id="how-to-create-a-table">How to Create a Table</h2>

The algorithm converts the heading text to lowercase, replaces spaces with hyphens, and removes special characters. GitHub, Obsidian, and most static site generators follow this pattern.

Linking to a heading:

See the [installation section](#installation) for setup instructions.

This creates a clickable link that jumps to the heading with id="installation". The same syntax works for creating a manual table of contents. Check our markdown table of contents guide for detailed instructions on building navigation from headings.

Heading Best Practices for SEO and Readability

Proper heading hierarchy matters for search engine optimization and accessibility. Search engines use headings to understand page structure, and screen readers use them for navigation.

Rule 1: One H1 per page. The H1 should be the page title and contain your primary keyword. Multiple H1 tags confuse search engines about the topic of your page.

Rule 2: Do not skip heading levels. Go from H2 to H3, not from H2 to H4. Skipping levels breaks the logical outline and causes accessibility warnings in tools like Lighthouse.

Rule 3: Keep headings descriptive. "Configuration" is vague. "How to Configure the Database Connection" tells readers exactly what the section covers. Descriptive headings improve scannability and SEO.

Rule 4: Front-load keywords. Place important words at the beginning of headings. "Markdown Headings: Syntax Guide" is better than "A Guide to the Syntax of Headings in Markdown" because readers scanning the page, and search snippets that truncate long titles, see the first words first.

Rule 5: Use headings every 200 to 300 words. Long blocks of text without subheadings are harder to read. Break content into sections with clear headings to improve the reading experience.

Formatting Inside Markdown Headings

You can use inline formatting inside headings:

## Using **Bold** in a Heading
## The `config.yml` File
## Links in Headings [Are Possible](https://example.com)

Bold and inline code work well in headings. Links work but are uncommon and can affect the auto-generated ID. Italic text in headings is valid but rarely necessary.

Avoid using images inside headings. While technically possible, it creates accessibility issues and breaks the heading ID generation on some platforms.

Common Mistakes with Markdown Headings

Mistake 1: Missing the space after #.

##This is not a heading (no space after the hashes)
## This is a heading

Mistake 2: Using headings for visual styling.

Do not use #### just because you want smaller text. Headings define document structure, not font size. Use bold or CSS for visual emphasis.

Mistake 3: Too many H1 headings.

Each document should have exactly one H1. Using multiple H1 tags tells search engines your page has multiple main topics, which dilutes your SEO.

Try Markdown Headings in Our Editor

Experiment with heading levels and see the rendered output in real time:

Frequently Asked Questions

Summary

Markdown headings give your documents structure with a simple # syntax. Use one H1 for the title, H2 for sections, and H3 for subsections. Keep headings descriptive, do not skip levels, and add them every 200 to 300 words for readability. Auto-generated heading IDs let you link directly to sections, which is useful for navigation and sharing. Try building your document structure in the editor or reference the markdown cheat sheet for all formatting syntax.

Written by the Markdown Editor Online team. Last updated September 2026.