Headings

↑ Docs content model

Headings define the structure of a page through heading levels and the hierarchy they form.

When to use

Use headings to break a page into named, scannable sections. Each heading becomes an anchor and an entry in the on-page table of contents, so headings are how a reader jumps to the part they need. Most page sections begin with a heading.

Technical details

Headings are Markdown ATX headings — one to six # characters followed by a space:

• # — H1, the page title. Exactly one per page, and it must be the first heading.
• ## — H2, a top-level section.
• ### — H3, a subsection.

Docusaurus generates a slug (anchor) from each heading's text, which is what links target with #anchor. Only ## and ### appear in the on-page table of contents.

Rules

• Exactly one H1 per page, and it comes first.
• Don't go deeper than H3. If content seems to need an H4, that's a signal to restructure — not to demote the heading to bold text, which keeps the same depth while reading worse.
• Don't skip levels (no H3 directly under an H1).
• Keep the H1 under 60 characters and SEO-focused.

Style

• Use sentence case: capitalize only the first word and any proper nouns.
• Write descriptive, parallel headings. For a set of task sections, lead each with a verb ("Create a pipeline", "Run the pipeline").
• Don't end a heading with punctuation, and keep it to a phrase rather than a full sentence.

Template

Markdown

# Page title

## Section

### Subsection

Examples

Example:

Markdown

# Monitor Lakeflow Jobs

## View job runs

### Filter the runs list

## Export run results

Used in

Content atoms appear in any page section. Headings are structural: every page has one H1, and each section is introduced by an H2 or H3. The allowed heading depth is set by each page type.