Frontmatter is the YAML block at the top of every MDX page. It controls the URL, the sidebar tree, the SEO metadata, and per-page settings.
MDX
---
title: "Page title"
description: "A short SEO description."
slug: section/page-slug
parent: section
order: 0
---Required fields#
| Field | Type | Description |
|---|---|---|
title | string | The page title. Used in the sidebar, the <title> tag, and the H1. |
slug | string | URL path. Lowercase, hyphenated, slashes allowed for nesting. index = homepage. |
The editor will refuse to save without these.
Common optional fields#
| Field | Type | Default | Description |
|---|---|---|---|
description | string | empty | SEO description and sidebar subtitle |
parent | string (slug) | null | Parent page slug for sidebar nesting |
order | number | inferred | Position within siblings (lower = higher in sidebar) |
published | boolean | true | If false, page is a draft (hidden from live site) |
SEO fields#
| Field | Type | Default | Description |
|---|---|---|---|
seoTitle | string | derived from title | Override the <title> tag |
seoDescription | string | derived from description | Override the meta description |
ogImage | string (URL or path) | auto-generated | Custom Open Graph image (1200×630) |
noindex | boolean | false | Add <meta name="robots" content="noindex"> |
canonical | string (URL) | derived from slug | Override the canonical URL (rare) |
Display fields#
| Field | Type | Default | Description |
|---|---|---|---|
sidebarTitle | string | derived from title | Override how the page is shown in the sidebar |
hideFromSidebar | boolean | false | Page exists at its URL but doesn't appear in the sidebar |
hideFromSearch | boolean | false | Excluded from the search index |
collapsedByDefault | boolean | false | Group is collapsed when readers first land |
Example: a typical page#
MDX
---
title: "Custom domain"
description: "Move from acme.dokly.co to docs.acme.com."
slug: customization/custom-domain
parent: customization
order: 2
---
By default, every project lives at `<your-subdomain>.dokly.co`...Example: a draft#
MDX
---
title: "Webhooks (work in progress)"
description: "Sending and receiving webhooks."
slug: api-reference/webhooks
parent: api-reference
order: 5
published: false
---
I'm still drafting this page...When you're ready, flip published: true (or use the toggle in the editor).
Example: an indexed but hidden page#
MDX
---
title: "Legal: Terms of Service"
slug: legal/terms
parent: legal
hideFromSidebar: true
---The page is published at /legal/terms and indexed by Google, but doesn't show in the in-app sidebar. Useful for footer links.
Example: a noindex page#
MDX
---
title: "Internal architecture notes"
description: "Implementation details for the engineering team."
slug: internal/architecture
noindex: true
hideFromSearch: true
---Page is live at the URL (sharable), but search engines won't index it and your in-product search won't return it.
Slug rules#
- Lowercase letters, numbers, hyphens, slashes
- No leading or trailing slashes
- No spaces, underscores, or special characters
- Slashes create URL hierarchy (e.g.,
editor/writing→/editor/writing) - The slug
indexis special — it's the homepage at/
The editor enforces these on input and rejects invalid characters.