This module connects user-facing syntax with exact parse behavior.
Headings as document structure
Headings are one of the most important Markdown constructs because they define document hierarchy. Search engines, screen readers, table of contents generators, static site builders, and documentation tools all rely on headings to understand page structure. A Markdown heading is therefore not just visual text. It is a semantic boundary.
CommonMark supports ATX headings and setext headings. ATX headings use one to six leading # characters. The number of markers determines the heading level. Setext headings use an underline of = for level one or - for level two. ATX headings are more common in technical documentation because they support all six levels and are visually explicit.
The space after the opening # sequence matters. CommonMark requires a space or tab after the opening sequence unless the heading is empty. This avoids accidental headings such as hashtags or issue references. For compatibility, always write # Heading, not #Heading.
ATX heading details
An ATX heading may have an optional closing sequence of # characters. For example, ## Title ## is a level two heading. The closing sequence is mostly cosmetic. The heading level is determined only by the opening sequence. Closing markers must be preceded by whitespace, otherwise they are treated as part of the heading text.
Indentation also matters. Up to three spaces before an ATX heading are allowed. Four spaces usually makes the line an indented code block instead. This is a recurring Markdown principle: three spaces may still be structural markup, but four spaces often means code.
Because headings can interrupt paragraphs in CommonMark, a line beginning with # can create a heading even without a blank line before it. That said, authoring guidelines should still require blank lines around headings. It improves source readability and helps portability across tools that may not follow CommonMark exactly.
Setext headings and ambiguity
Setext headings are elegant for short documents but can be ambiguous. A line of dashes below text may become a level two heading underline rather than a thematic break. This is one of the classic Markdown edge cases. The parser uses context to decide whether the underline belongs to a heading.
Setext headings only support levels one and two. They can span multiple text lines in CommonMark, which may surprise users familiar with simpler Markdown guides. Because of their ambiguity and limited depth, many technical writing teams prefer ATX headings for consistency.
If you choose to use setext headings, be deliberate. Keep them for top-level titles or avoid them entirely in large documentation systems. Consistency matters more than personal preference when many contributors edit the same source.
Paragraphs and soft line breaks
A Markdown paragraph is one or more consecutive lines of text separated from other blocks by blank lines or structural boundaries. Source line breaks inside a paragraph are usually soft line breaks. They do not necessarily produce HTML <br> elements. Many renderers treat them as spaces in normal flow.
This behavior supports hard-wrapped source text. Writers can wrap prose at 80 or 100 columns without forcing visual line breaks in the rendered output. That is useful for version control because diffs remain readable. It also preserves Markdown’s plain-text heritage.
If you need a hard line break, CommonMark supports a backslash at the end of a line or two trailing spaces. The trailing-space method is historically common but hard to see in editors. The backslash method is visible, but not supported by every older Markdown dialect. In production style guides, prefer explicit constructs and avoid relying on invisible whitespace.
Thematic breaks
Thematic breaks are created with three or more matching -, _, or * characters, with optional spaces depending on the exact rules. They render as section breaks, usually HTML <hr>. Thematic breaks are block-level elements, not inline decoration.
The important edge case is that dashes can conflict with setext headings. If a line of dashes follows paragraph text, the parser may produce a heading instead of a thematic break. To avoid this, put blank lines around thematic breaks and consider using *** when the surrounding text might be ambiguous.
Thematic breaks can be useful in long tutorials, but they should not replace headings. Headings carry semantic structure; thematic breaks only indicate a separation. Use headings to divide topics and thematic breaks sparingly.
Heading semantics and outline stability
Headings should describe the actual section that follows them. A document with one clear top-level heading and logically nested subheadings is easier for renderers, table-of-contents generators, and readers to understand. The source should not rely on visual spacing alone to communicate hierarchy.
Heading syntax also interacts with links. Many documentation systems generate heading anchors from rendered heading text. If a heading changes level or fails to parse, internal links can break. That is why heading practice connects directly to Markdown links and reference definitions.
Paragraphs should be substantial enough to answer questions directly. Short fragments can be useful, but long-form tutorial content needs explanatory prose, examples, and edge-case discussion. Markdown makes this easy as long as the source structure is clean.
FAQ
What is the best Markdown heading style?
ATX headings are usually best for technical documentation because they support all six levels and are less ambiguous than setext headings.
Why is #Heading not reliable?
CommonMark requires whitespace after the opening heading marker. Without the space, many parsers treat the text as a paragraph.
How do Markdown soft line breaks work?
Soft line breaks are source line endings inside a paragraph. They usually render as spaces or normal line wrapping, not explicit HTML breaks.
How do I force a line break in Markdown?
Use a trailing backslash or two trailing spaces, depending on your supported dialect and style guide.
Why did my horizontal rule become a heading?
A dash line after text can become a setext heading underline. Add blank lines or use asterisks for a clearer thematic break.
Related tutorials
- Understand precedence in Markdown Block Parsing and Precedence Rules.
- Continue with containers in Markdown Lists, Blockquotes, and Container Blocks.
- Link headings safely with Markdown Links, Images, and Reference Definitions.
- Inspect rendered structure using Markdown AST with mdast.
- Enforce outline rules in Designing Production Markdown Systems.
Continue with Lists, Blockquotes, and Containers.