Headings in MDX

Headings are the backbone of any well-structured document. They create the hierarchy that readers use to navigate your content, that screen readers use to help visually impaired users find information, and that search engines use to understand what your page is about. In MDX, headings work exactly like regular Markdown — use # symbols followed by a space. More hashes means a smaller heading level.

Which Level to Use Where

Understanding when to use each level is more important than knowing the syntax. Here is the practical breakdown:

H1 — Page Title (Use Only ONE Per Page)

Every page should have exactly one H1. It is your page title — the main subject of the entire page. Using two H1 elements on one page confuses both search engines and screen readers. Think of H1 as the book title — a book only has one.

In many MDX-powered sites, the H1 is automatically generated from frontmatter metadata, so you may not even write it manually in the content body. Check your framework's documentation to understand how your site handles this.

H2 — Major Sections

These break your page into logical chapters. If your page were a book, H2 elements would be the chapter titles.

H2 headings are what appear in automatically generated tables of contents. They should clearly describe the major topic of each section and be scannable — a reader should understand your page structure just by reading the H2 headings.

H3 — Subsections

When a major section needs to be broken into smaller parts, use H3:

H3 elements subdivide your H2 sections. They represent one level deeper in the content hierarchy.

H4 to H6 — Deep Nesting (Use Sparingly)

If you find yourself regularly using H5 or H6, that is a signal your page is too long or too deeply nested. Consider splitting the content into separate pages instead of nesting deeper.

Rules for Proper Heading Hierarchy

1. Never Skip Levels

Go in order. Do not jump from H2 to H4 without an H3 in between.

Skipping levels creates accessibility problems. Screen readers announce heading levels, and a jump from level 2 to level 4 confuses users who rely on this hierarchy to navigate. It also signals to search engines that your content structure is broken.

2. Keep Headings Short and Descriptive

Headings should be scannable. A reader skimming your page should understand what each section covers just from the heading text alone, without reading the content beneath it.

3. Pick One Capitalization Style

Either Title Case or Sentence case — be consistent across your entire site.

Both are fine. Title Case looks more formal, Sentence case looks more conversational. The important thing is consistency — mixing styles looks unprofessional and confusing.

4. Do Not Use Headings for Visual Styling

If you want bigger or bolder text, use CSS classes or bold formatting. Headings have semantic meaning — they tell machines and assistive technologies about your document structure. Using them for visual purposes breaks that meaning.

Why Heading Order Matters for Accessibility

Screen readers provide navigation features that let users jump between headings. A person using a screen reader can press a key to hear a list of all headings on the page, then jump directly to the section they need. This is like a spoken table of contents.

If your heading order is broken (H2 → H4 → H2 → H6), it is like a book where chapter numbers are random. Users cannot build a mental model of your content structure. This particularly impacts:

• Blind users who rely entirely on heading navigation
• Users with cognitive disabilities who need clear structure to process information
• Users with motor impairments who use headings to minimize scrolling and navigation effort

Approximately 15% of the world's population has some form of disability. Proper heading structure is not optional — it is a fundamental accessibility requirement.

How Headings Affect SEO

Search engines use heading hierarchy to understand your content:

1. H1 tells Google what the page is about — it carries the most weight for the page's main topic
2. H2 elements define subtopics — they help search engines understand the breadth of your content
3. Heading keywords matter — including relevant terms in headings helps with ranking for those terms
4. Proper hierarchy signals quality — well-structured content tends to rank higher than disorganized content
5. Featured snippets often use H2/H3 text — Google may pull your heading and the paragraph below it into search results

Auto-Generated IDs and Anchor Links

Most MDX frameworks automatically generate an id attribute for each heading based on the heading text:

Becomes:

This enables anchor links (jump-to-section links) like #installation-guide. Tables of contents are built by collecting these heading IDs. If you change a heading's text, the ID changes, which can break existing links to that section.

Common Mistakes

Quick Reference

Keep it simple: most pages only need H1, H2, and H3. If you are regularly using H4 or deeper, consider restructuring your content into multiple pages instead.