Markdown headings are not just “big bold lines.” They are the structure that drives navigation, table of contents generation, internal links, and Word/PDF outline quality.
If you only remember one rule, remember this:
headings are structure first, styling second.
Use this guide when you want heading levels that stay useful across GitHub, docs sites, editor preview, and exported documents.
ATX vs Setext Headings
Markdown has two heading styles.
ATX headings
ATX uses # markers:
# H1
## H2
### H3
#### H4
This is the most portable and maintainable style for real documentation because it scales cleanly from level 1 to level 6.
Setext headings
Setext uses underline markers:
Heading level 1
===============
Heading level 2
---------------
Setext only covers the top two levels. It is fine for short prose documents, but it becomes awkward once the document has more structure.
For most technical and export-focused workflows, ATX is the safer default.
Heading Levels Define Structure
Headings tell the renderer, the reader, and the export pipeline how sections relate to each other.
Good:
# API Guide
## Authentication
### Access Tokens
### Refresh Tokens
## Errors
Weak structure:
# API Guide
#### Authentication
## Errors
Skipping levels is not automatically invalid Markdown, but it often makes the document harder to scan and can produce a weaker outline in TOC-oriented workflows.
Should a Document Have Only One H1?
Markdown syntax itself does not forbid multiple top-level headings. But in most documentation workflows, a single H1 is clearer.
Why one H1 usually wins:
- the page or document has one obvious top-level topic
- the rest of the outline becomes easier to follow
- Word/PDF outlines and navigation structures are usually cleaner
- internal links and exported TOCs are easier to reason about
So this is best treated as a strong authoring convention, not as a syntax law.
Closing Hashes Are Optional
These are equivalent in CommonMark:
## Export Tips
## Export Tips ##
Most authors omit the closing hashes because they add noise without adding structure.
If you inherit content that uses them, that is not automatically wrong. It is just less clean to edit.
Headings and Section Links
Once headings exist, many platforms generate section links from them automatically.
That is useful, but it creates a non-obvious maintenance rule:
if the heading text changes, the generated anchor may change too.
For example, a link to:
# Export Tips
may stop matching after the heading becomes:
# Export Tips for Large Documents
This matters in:
- long README files
- documentation hubs with deep section links
- exported docs where you manually reference sections
If you rely on heading links, test them after renaming headings.
If section links are important to the document, pair this section with the Markdown Hyperlink guide. Heading structure and section-link strategy should be designed together, not treated as separate cleanup steps.
Anchor IDs Are Not Universal
This is where many Markdown answers become misleading.
Different platforms often auto-generate heading IDs, but the exact slugging rules can differ:
- punctuation may be stripped differently
- duplicate headings may get different suffixes
- non-Latin text can be handled differently
- HTML-based renderers and Pandoc-style pipelines may not produce identical identifiers
That means this kind of link:
[Jump to export tips](#export-tips)
is only safe if you know how the target renderer generates heading IDs.
Do not assume GitHub, your local preview, and your export pipeline all use the same algorithm.
In md2word, this matters even more because different surfaces do not rely on one single slugging path. The published page, preview parser, and TOC fallback logic can each participate in heading-id generation, so internal section links should be verified in the actual target surface instead of trusted by analogy.
Pandoc Heading Identifiers
Pandoc can auto-generate identifiers for headings, and it also supports manually assigned identifiers.
Example:
## Export Tips {#export-tips}
That is useful when:
- you need stable internal links
- the heading text may change over time
- the document will generate a TOC or section references downstream
But this is not universal Markdown syntax. Treat it as a Pandoc-oriented or extension-oriented feature.
Practical md2word Advice
This section reflects the current md2word workflow rather than generic Markdown folklore.
1. Use headings as document structure, not as visual styling
If you just want larger text, do not abuse heading levels. In export workflows, heading levels often feed TOC, navigation, and outline logic.
2. Prefer one clear H1, then H2/H3 for real sections
This is the safest structure for documents that may become DOCX or PDF.
3. Keep heading text stable if other sections link to it
md2word preview and page rendering both generate heading IDs for navigation, but they do not all depend on exactly the same implementation path. Stable heading text helps, but it is still worth checking the actual target environment before you rely on section links in a published or exported workflow.
4. Do not assume anchor IDs are portable across platforms
If you are building internal section links, test them in the actual target environment instead of trusting one preview.
5. Avoid decorative headings that break hierarchy
Moving from H1 to H4 because it “looks better” is a common structure mistake. Keep levels meaningful.
Common Mistakes
1. Using multiple H1s because they look visually prominent
That often weakens the structure.
2. Using headings for styling instead of hierarchy
That makes TOC and export outlines noisier.
3. Renaming headings without checking section links
That silently breaks anchor-based navigation.
4. Assuming heading IDs are generated the same way everywhere
They are not.
5. Treating Setext as a full replacement for all heading levels
It only covers the top two levels.
FAQ
Is multiple H1 usage invalid Markdown?
No. It is usually a structure decision, not a syntax error. But one H1 is often the cleaner authoring choice.
Should I use ATX or Setext headings?
Use ATX by default. Use Setext only when you intentionally want a simpler prose style with just the top one or two heading levels.
Why did my heading link stop working?
The most common reason is that the heading text changed and the auto-generated anchor changed with it.
Can I manually assign heading IDs?
Yes in Pandoc-oriented workflows and some Markdown extensions, but not as a universal Markdown rule.
What is the safest heading strategy for Word/PDF export?
One clear H1, meaningful H2/H3 nesting, stable section names, and minimal reliance on renderer-specific anchor behavior.
Further Reading
- CommonMark Spec: ATX headings
- CommonMark Spec: Setext headings
- GitHub Docs: Basic writing and formatting syntax
- Pandoc Manual: Headings and sections
- Pandoc Manual: auto_identifiers
Changelog
- 2026-03-18: Initial high-value release with verified guidance on ATX vs Setext, heading hierarchy, anchor behavior, Pandoc identifiers, and export structure.
- 2026-03-19: Added stronger guidance on duplicate-heading anchor drift and the fact that md2word surfaces do not all share the exact same heading-id path.
Next steps: Explore Markdown Hyperlink, Markdown Export Tips, Markdown List Guide, Markdown Footnote Guide, Markdown Quote Guide, and Markdown Cheat Sheet.