How to Create Headings in Markdown

The hash-based style is called ATX headings, and it is what you should use almost everywhere. Markdown also supports setext headings, where you underline text with equals signs (for H1) or dashes (for H2). Setext only covers two levels, is easy to break accidentally — a stray line of dashes under a paragraph turns it into an H2 — and confuses diff tools because the heading spans two lines. ATX headings are unambiguous, support all six levels, and are the convention in virtually every modern codebase.

Headings define your document outline, so use them hierarchically: one H1 per document (usually the title), H2 for major sections, H3 for subsections. Skipping levels (jumping from H2 to H4) hurts accessibility because screen reader users navigate by heading level, and it breaks automatically generated tables of contents. On GitHub, every heading automatically gets an anchor ID derived from its text (lowercased, spaces to hyphens, punctuation stripped), so ## Getting Started becomes linkable as #getting-started.

Two formatting rules prevent most heading bugs. First, headings need a blank line before and after them in many renderers — text jammed directly against a heading line can merge into one paragraph. Second, the heading must start at the beginning of the line (up to three leading spaces are tolerated; four turns it into an indented code block). Trailing hashes are optional and ignored: ## Title ## renders the same as ## Title.

Avoid using headings purely for visual size. If you want big bold text without adding a section to the document outline, use bold text or platform-specific features instead. Search engines and accessibility tools treat headings as structure, and a document whose outline is a series of decorative H3s is harder to navigate for everyone.