Frontmatter

A page starts with frontmatter: YAML between two --- lines, describing the page.

---
title: Webhooks
description: Get an HTTP request when something changes in your account.
sidebarTitle: Webhooks
icon: webhook
tag: New
---

Webhooks send ...

Every field is optional. A page in the navigation doesn’t need frontmatter at all; one outside it needs at least the --- lines to be a page - see Project structure.

The page

title

The page’s main heading, its name in the sidebar and in previous/next links, and the browser tab’s title. Without it, the title comes from the file name: getting-started.mdx is “Getting started”, and an index.mdx takes its folder’s name.

Don’t repeat the title as a # heading in the page - it’s already shown.

description

A one-sentence summary of the page. It’s the page’s <meta name="description"> - what search engines show under the link, and the text of link previews. It’s also the page’s summary in llms.txt, and in the MCP server’s page list. Without it, the page uses the site’s description from writedocs.json.

slug

A different address for the page, without moving the file:

---
title: Authentication
slug: guides/auth
---

docs/security/authentication.mdx with this slug is served at /guides/auth/. The navigation still lists it by its file: docs/security/authentication. Slashes at either end don’t matter - guides/auth and /guides/auth/ are the same - and slug: / makes the page the home page.

When you change a published page’s address, add a redirect from the old one.

mode

The page’s layout - how much of the site’s frame (topbar, sidebar, table of contents) is around it: default, wide, frame, custom or blank. See Page modes.

How the page appears in the sidebar

sidebarTitle

A shorter name for the sidebar and menus, when the title is long:

---
title: Authenticating requests with OAuth 2.0
sidebarTitle: OAuth 2.0
---

The page’s heading and previous/next links still use title.

icon

An icon before the page’s name in the sidebar: an icon name, an emoji, or an image - see Icons.

tag

A small label after the page’s name in the sidebar, like New or Beta.

deprecated

deprecated: true shows a Deprecated label next to the page’s title, and in the sidebar.

hidden

hidden: true leaves the page out of the sidebar, menus and previous/next links, even when the navigation lists it. The page is still published at its address, and links to it work.

A hidden page is also noindex - out of search engines, sitemap.xml and llms.txt - unless it sets seo.noindex: false. To hide a whole tab, version or product, see Hidden sections.

url

Makes the page a link to another site:

---
title: Status page
url: https://status.example.com
---

Its sidebar entry opens url in a new tab, and its own address redirects there. The page’s content isn’t shown anywhere, and the page is left out of sitemap.xml, llms.txt and previous/next links.

hideFooterPagination

hideFooterPagination: true removes the Previous and Next links at the bottom of the page.

API pages

openapi

Makes the page an API reference page for one endpoint: your text, then the endpoint’s parameters, responses and Try it playground, from the spec.

---
title: Create a refund
openapi: POST /refunds
---

See Your own page for an endpoint.

hideApiMarker

On an API page, hideApiMarker: true removes the method label (GET, POST, …) from its sidebar entry.

seo

Meta tags for this page. Each field replaces the site’s default from writedocs.json’s seo; the rest still apply.

---
title: Enterprise SSO
seo:
  ogImage: /images/social/sso.png
  ogType: article
  twitterCard: summary_large_image
  keywords:
    - sso
    - saml
  noindex: false
  title: "Single sign-on (SSO) with SAML - Acme"
  description: Connect Acme to Okta, Entra ID or any SAML identity provider.
  canonical: /docs/security/sso/
  metatags:
    "og:locale": en_GB
---

Mistakes

A field with the wrong type, or a mode that doesn’t exist, is an error in writedocs validate, with the file and line. Frontmatter that isn’t valid YAML is too - a common cause is a value with a colon in it, which needs quotes: title: "Step 2: Configure".