Frontmatter

Frontmatter is YAML metadata at the top of each MDX file. It controls page settings, SEO, layout, and protocol-specific rendering.

Basic Frontmatter

Every page should have at minimum a title:

---
title: Getting Started
---

Common Fields

Field	Type	Description
title	string	Page title (required)
description	string	Meta description for SEO
icon	string	Icon in navigation sidebar
draft	boolean	Hide from production
sidebar	boolean	Show/hide sidebar
toc	boolean	Show/hide table of contents

Example

---
title: Authentication Guide
description: Learn how to authenticate with the API using API keys or OAuth.
icon: key
---

Layout Options

Control page structure with the layout field:

---
title: Welcome
layout: centered
---

Layout	Description
default	Three-column: sidebar + content + TOC
centered	Single column, centered content
full-width	Single column, full width

Background Customization

For landing pages or special sections:

---
title: Welcome
layout: centered
background: "#0a0a1a"
---

Solid Color

---
background: "#050510"
---

Gradient

---
background: "linear-gradient(135deg, #0a0a1a 0%, #1a0a2e 100%)"
---

Background Image

---
backgroundImage: "/assets/hero-bg.png"
backgroundSize: cover
backgroundPosition: center
---

SEO Fields

Optimize for search engines and social sharing:

---
title: API Reference
description: Complete API reference for all endpoints.
ogImage: /images/api-og.png
noIndex: false
canonical: https://docs.example.com/api
---

Field	Description
description	Meta description (150-160 chars ideal)
ogImage	Open Graph image for social sharing
noIndex	Exclude from search engine indexing
canonical	Canonical URL for duplicate content

Navigation Fields

Control how the page appears in navigation:

---
title: Advanced Configuration
sidebarTitle: Advanced
sidebarPosition: 5
hidden: false
---

Field	Description
sidebarTitle	Override title in sidebar
sidebarPosition	Manual sort order (lower = higher)
hidden	Hide from sidebar but keep accessible

Protocol Frontmatter

For API documentation, specify the protocol to get specialized rendering.

REST / HTTP

---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
description: Create a new user account.
---

Renders a colored method badge (POST = green) and endpoint path.

WebSocket

---
title: Order Created Event
protocol: websocket
event: order.created
direction: server-to-client
description: Fired when a new order is placed.
---

GraphQL

---
title: Create Order Mutation
protocol: graphql
operation: mutation
name: createOrder
description: Create a new order.
---

gRPC

---
title: Create Payment
protocol: grpc
service: PaymentService
rpc: CreatePayment
description: Create a new payment via gRPC.
---

Event-Driven

---
title: Order Confirmed
protocol: event
channel: orders.confirmed
broker: kafka
description: Published when an order is confirmed.
---

Page Types

The type field enables specialized templates:

---
title: v2.0 Release
type: changelog
date: 2024-01-15
---

Type	Description
guide	Standard documentation (default)
api-reference	API endpoint page
changelog	Changelog entry with date
landing	Marketing-style landing page
sdk	SDK documentation with language tabs

Feature Toggles

Enable or disable page features:

---
title: Quick Reference
toc: false
sidebar: false
feedback: true
editUrl: https://github.com/org/repo/edit/main/docs/quick-ref.mdx
---

Field	Default	Description
toc	true	Table of contents
sidebar	true	Navigation sidebar
feedback	true	"Was this helpful?" widget
editUrl	auto	"Edit on GitHub" link

Complete Example

---
# Core metadata
title: Create User
description: Create a new user account via the REST API.

# Protocol (for API pages)
protocol: rest
method: POST
endpoint: /v1/users

# Layout
layout: default
toc: true
sidebar: true

# SEO
ogImage: /images/api/create-user-og.png

# Features
feedback: true
editUrl: https://github.com/acme/docs/edit/main/docs/api/create-user.mdx
---