Markdown Headings: Syntax, Levels & Best Practices

# Heading 1
## Heading 2
### Heading 3

Headings are the structural backbone of written documents. In Markdown, headings establish a clean hierarchical outline that allows readers to scan sections effortlessly, enables screen readers to navigate content accessibly, and powers automated tables of contents and document outlines.

Markdown provides two distinct syntaxes for creating headings: ATX headings (the standard prefix method using # characters) and Setext headings (the traditional underline method). Understanding both formats, along with their edge cases, ensures your notes remain clean, portable, and correctly parsed across all Markdown engines.

ATX heading syntax (Recommended)

ATX headings are the universal standard across modern Markdown implementations. Named after the ATX address system by Aaron Swartz, ATX headings prefix the line with between one and six hash (#) symbols corresponding to HTML heading levels <h1> through <h6>.

The six standard levels

# Heading Level 1 (Document Title)
## Heading Level 2 (Major Section)
### Heading Level 3 (Sub-section)
#### Heading Level 4 (Minor Sub-section)
##### Heading Level 5 (Paragraph Group)
###### Heading Level 6 (Deep Label)

Essential syntax rules for ATX headings

1. Mandatory whitespace: In CommonMark and GitHub Flavored Markdown (GFM), you must include at least one space between the final # and your heading text. Writing #Heading is treated as plain text or a social tag, not a heading.
2. Closing hashes are optional: You can optionally close an ATX heading with matching # symbols (## Section Title ##). Modern Markdown parsers strip the trailing hashes automatically.
3. No multi-line headings: ATX headings cannot span multiple lines. Pressing return terminates the heading block.

Setext heading syntax

Setext (Structure Enhanced Text) is the legacy heading format derived from plain-text email conventions of the 1990s. Setext headings are defined by underlining text with equal signs or hyphens:

First-Level Heading
===================

Second-Level Heading
-------------------

Limitations of Setext headings

• Limited depth: Setext only supports Level 1 (=) and Level 2 (-) headings. Level 3 through Level 6 headings cannot be created with Setext.
• Accidental list collisions: A single hyphen (-) directly beneath a line can accidentally trigger a Setext H2 if blank lines are omitted.
• Industry obsolescence: Modern writing tools and knowledge bases overwhelmingly prefer ATX headings for consistency and predictability.

Specification differences across dialects

While heading syntax appears straightforward, subtle parsing differences exist across specifications:

Heading anchors and internal linking

In modern knowledge management, headings serve as precise navigation targets. In Oyma and Obsidian, you can link directly to a specific heading inside any note using the hash anchor syntax:

See the details in [[Project Plan#Architecture Overview]].

When you rename a heading in Oyma, the application automatically updates incoming links across your entire vault, preventing broken cross-references.

Common pitfalls and authoring best practices

1. Maintain a strict hierarchy: Avoid skipping levels (e.g., jumping directly from H1 to H3 without an intervening H2). Screen readers rely on sequential heading ranks to help visually impaired users build a mental model of your document.
2. Reserve H1 for the page title: Maintain a single H1 at the top of your document. Use H2 for major chapters and H3 for supporting subsections.
3. Avoid inline formatting in headings: While bolding and italics inside headings are valid Markdown (## Key **Findings**), they often produce cluttered document outlines and unpredictable anchor slugs in web generators.
4. Beware of missing blank lines: Always separate headings from preceding and succeeding paragraphs with a blank line to prevent ambiguous block parsing.

Writing headings in Oyma

In Oyma, typing # instantly formats the line into a beautifully scaled heading with native Apple typography. Our live-preview engine gracefully hides the markdown tokens when your cursor leaves the line, maintaining the visual elegance of a polished document while keeping raw CommonMark plain text on disk.

Frequently asked questions

What is the difference between ATX headings and Setext headings?

ATX headings use one to six hash symbols (`#`) preceding the title text. Setext headings use underline markers (`=` for H1, `-` for H2) beneath the line. ATX headings are universal, cleaner, and support all six heading levels (H1 through H6).

Why is a space required between the hash (#) and heading text in CommonMark?

The CommonMark standard mandates a space after the leading `#` characters to prevent accidental heading conversion when writing hashtags like `#productivity` or hex color codes like `#ff0000`.

Can I use multiple H1 headings on a single Markdown page?

While technically valid CommonMark, HTML accessibility standards and SEO best practices recommend having exactly one H1 per page as the primary document title, using H2 and H3 for sub-sections.

How does Oyma handle headings in live-preview mode?

Oyma formats headings with native macOS typography, increasing font weight and size while concealing the leading `#` symbols when your cursor is positioned elsewhere in the document.