MkDocs Headers and Headings

When migrating from MkDocs, the word "header" can mean two different things:

The YAML block at the top of a Markdown file
The visible Markdown headings inside the page body

Nexus Docs handles both, but they feed different parts of the system.

MkDocs Material supports page-level metadata at the top of a Markdown file:

YAML

---
title: Installation
description: Install and configure the project.
tags:
  - setup
  - docker
---

Nexus Docs uses the same YAML-frontmatter pattern, but with a stricter schema:

YAML

---
title: "Installation"
summary: "Install and configure the project."
access_tier: public
product: platform
status: published
owner: maintainer
tags: [setup, docker]
nav_order: 10
---

How frontmatter is used

Frontmatter field	Used for
`title`	Navigation label, browser metadata, OpenGraph title source, section card title.
`summary`	Meta description, search result text, cards, generated previews.
`access_tier`	Page-level access control.
`product`	Product or platform grouping, and client-tier permission checks.
`status`	Draft, published, or deprecated behavior.
`tags`	Tag pages, SEO keywords, search facets, generated OG image tags.
`nav_order`	Sort order inside a menu section.
`nav_hidden`	Keeps the page routable while hiding it from navigation.
`redirect_from`	Build-time redirects from old MkDocs URLs.

Visible Markdown headings

Markdown headings stay in the body:

Markdown

# Installation

## Requirements

## Docker Compose

### Environment file

The renderer processes headings with:

rehype-slug, which adds stable id attributes
rehype-autolink-headings, which wraps headings with anchor links
The right-side TableOfContents, which scans rendered h2 and h3 elements

Heading behavior

Heading	Behavior
`# H1`	Rendered in the article body, but not included in the right-side table of contents.
`## H2`	Included in the right-side table of contents.
`### H3`	Included in the right-side table of contents and indented under H2-level items.
`#### H4` and deeper	Rendered normally, but not included in the current table of contents.

The table of contents is generated in the browser from the rendered article. It is not read from MkDocs toc settings.

Slug and anchor examples

Headings become URL fragments:

Heading	Fragment
`## Docker Compose`	`#docker-compose`
`### Environment file`	`#environment-file`
`## Access Grant API`	`#access-grant-api`

Use normal Markdown links for same-page references:

Markdown

See [Docker Compose](#docker-compose).

Title versus H1

Frontmatter title and the page # H1 should usually match, but they are not the same value.

Source	Controls
Frontmatter `title`	Nav label, metadata, breadcrumbs title lookup, cards, search title.
Markdown `# H1`	Visible article heading in the page body.

If they differ, the UI can feel inconsistent. Prefer this pattern:

YAML

---
title: "GitLab Automatic Integration"
summary: "Trigger content sync, cache invalidation, and search reindexing from GitLab events."
---

# GitLab Automatic Integration

MkDocs migration pattern

MkDocs projects often keep menu labels in mkdocs.yml:

YAML

nav:
  - Install: install.md

Nexus Docs keeps the label in the document:

YAML

---
title: "Install"
summary: "Install the application locally or in production."
nav_order: 1
---

The file path creates the URL, title creates the menu label, and nav_order creates the menu order.

Practical rules

Use one # H1 per page.
Keep frontmatter title close to the H1.
Use ## and ### for sections you want in the right-side table of contents.
Avoid skipping from ## straight to ####.
Add redirect_from when replacing old MkDocs URLs.
Keep headings human-readable; the renderer generates the anchor IDs for you.