Overview

Frontmatter is the YAML metadata block at the top of every MDX file. It controls how pages are displayed, organized, and processed by Docs Kit.

---
title: "Page Title"
description: "Page description"
published: true
order: 1
---

Your content starts here...

Required Fields

title: "Getting Started Guide"

description: "Learn how to set up and configure your first project"

published: true

Optional Fields

order: 1 # This page appears first in its group

openapi: "POST /api/users"

Field Details

Title

The title appears in multiple locations:

• Browser tab - As the page title
• Navigation sidebar - As the link text (if not specified in config)
• Page header - As the main heading
• Search results - As the result title

Best Practices:

• Keep it under 60 characters
• Use sentence case: "Getting started" not "Getting Started"
• Be specific: "API Authentication" not "Auth"
• Avoid special characters that might break URLs

Examples:

# Good
title: "Configuring Webhooks"
title: "Authentication with API Keys"
title: "Quick Start Guide"

# Avoid
title: "Configuration"  # Too vague
title: "GETTING STARTED!!!"  # Excessive caps and punctuation
title: "Everything You Need to Know About Authentication"  # Too long

Description

The description is used for:

• SEO meta tags - <meta name="description">
• Social media cards - Open Graph and Twitter cards
• Search previews - Google search results
• Internal search - Docs Kit search results

Best Practices:

• Keep it between 120-160 characters
• Include relevant keywords naturally
• Make it compelling - it's often the first thing users read
• End with a period

Examples:

# Good
description: "Learn how to authenticate API requests using API keys, OAuth 2.0, or JWT tokens."

description: "Step-by-step guide to configuring webhook endpoints and handling event notifications."

# Avoid
description: "This page is about webhooks"  # Too short, not compelling

description: "This comprehensive guide will walk you through everything you need to know about webhooks including setup, configuration, testing, debugging, and best practices."  # Too long (180+ chars)

Published

Controls page visibility throughout the site:

published: true   # Page is visible everywhere
published: false  # Page is hidden (draft mode)

When published: false:

• ❌ Not shown in navigation sidebar
• ❌ Not included in search results
• ❌ Not indexed by search engines (via robots.txt)
• ✅ Still accessible via direct URL (for preview/review)
• ✅ Works in development and production

Use Cases:

---
title: "Advanced Features"
description: "Coming soon"
published: false
---

This content is still being written...

during holidays" published: false # Publish only during holidays --- ```
</Tab>

<Tab title="Beta Features">
  ```yaml
  ---
  title: "Beta: Real-time Sync"
  description: "Preview of upcoming sync feature"
  published: false  # Share URL with beta testers only
  ---

Order

Controls the position of pages within navigation groups:

order: 1   # Appears first
order: 10  # Appears tenth
order: 99  # Appears near the end

How It Works:

1. Pages are sorted by order value (ascending)
2. Pages without order are sorted alphabetically
3. Ordered pages always appear before unordered pages
4. Ties are broken alphabetically by title

Example Navigation Setup:

content/docs/
├── introduction.mdx      (order: 1)
├── installation.mdx      (order: 2)
├── quick-start.mdx       (order: 3)
├── advanced-config.mdx   (order: 10)
└── troubleshooting.mdx   (no order, appears last alphabetically)

OpenAPI

References an OpenAPI endpoint for automatic API documentation:

openapi: "POST /otp/request_token"

Format:

METHOD /path/to/endpoint

• METHOD - HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
• Path - Endpoint path matching your OpenAPI spec

What It Generates:

When you include openapi in frontmatter, Docs Kit automatically displays:

• 📋 Request parameters (path, query, header)
• 📝 Request body schema with examples
• ✅ Response schemas for all status codes
• 🔐 Authentication requirements
• 🧪 Interactive "Try It" button
• 💻 Code examples in multiple languages

Example:

---
title: "Create User"
description: "Create a new user account"
openapi: "POST /api/users"
published: true
---

Additional context about creating users...

The endpoint supports bulk user creation by passing an array.

Learn more in Creating API Pages.

Page Types

Documentation Page

Standard documentation with explanations and guides:

---
title: "Understanding Webhooks"
description: "Learn how webhooks work and how to use them"
published: true
order: 5
---

API Reference Page

Auto-generated API documentation:

---
title: "Get User"
description: "Retrieve user information by ID"
openapi: "GET /api/users/{id}"
published: true
---

Changelog Page

Release notes and version history:

---
title: "API Changelog"
description: "Latest updates to the API"
published: true
order: 1
---

Landing Page

Homepage or section introduction:

---
title: "Welcome to Docs"
description: "Comprehensive documentation for our platform"
published: true
order: 1
---

Complete Examples

Tutorial Page

---
title: "Building Your First Integration"
description: "Step-by-step guide to creating your first API integration in 5 minutes"
published: true
order: 1
---

Reference Page

---
title: "Configuration Options"
description: "Complete reference of all configuration options and environment variables"
published: true
order: 10
---

API Endpoint

---
title: "Send SMS"
description: "Send a text message to a phone number"
openapi: "POST /api/sms/send"
published: true
---

Draft Page

---
title: "Advanced Rate Limiting"
description: "Advanced techniques for handling rate limits"
published: false
order: 99
---

Validation

Docs Kit validates frontmatter at build time. Common errors:

Missing Required Field

---
title: "My Page"
# ❌ Error: Missing required field 'description'
published: true
---

Fix: Add all required fields:

---
title: "My Page"
description: "Page description"
published: true
---

Invalid Type

---
title: "My Page"
description: "Page description"
published: "yes" # ❌ Error: Expected boolean, got string
---

Fix: Use correct type:

---
published: true # ✅ Boolean value
---

Invalid YAML Syntax

---
title: My Page Without Quotes: Will Fail
description: "Valid description"
published: true
---

Fix: Quote strings with special characters:

---
title: "My Page Without Quotes: Works Now"
description: "Valid description"
published: true
---

Best Practices

Be Consistent

Use consistent formatting across all pages:

# Good - Consistent style
title: "Getting started"
title: "API reference"
title: "Configuration"

# Avoid - Inconsistent capitalization
title: "Getting Started"
title: "API Reference"
title: "configuration"

Use Descriptive Values

Make titles and descriptions helpful:

# Good
title: "Webhook Event Types"
description: "Complete list of webhook events and their payloads"

# Avoid
title: "Events"
description: "Webhook stuff"

Plan Your Order

Use spacing between order values for flexibility:

order: 10  # Leave room to insert pages later
order: 20
order: 30
# Can easily add order: 25 between these

Next, learn about Theming to customize your site's appearance.