---
title: Frontmatter
description: Page-level configuration with YAML frontmatter.
icon: file-text
---

# 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`:

```yaml
---
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

```yaml
---
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:

```yaml
---
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:

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

### Solid Color

```yaml
---
background: "#050510"
---
```

### Gradient

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

### Background Image

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

## SEO Fields

Optimize for search engines and social sharing:

```yaml
---
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:

```yaml
---
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

```yaml
---
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

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

### GraphQL

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

### gRPC

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

### Event-Driven

```yaml
---
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:

```yaml
---
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:

```yaml
---
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

```yaml
---
# 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
---
```