Frontmatter

Frontmatter is the YAML block at the top of every MDX file. It controls how your page appears in navigation, search results, and social media previews.

Basic Frontmatter

Every page needs at least a title:

---
title: Getting Started
description: Learn the basics in 5 minutes
---

Available Fields

Required

Field	Type	Description
`title`	string	Page title shown in navigation and browser tab

Field	Type	Description
`description`	string	Brief summary for SEO and search results (50-160 chars)

Optional

Field	Type	Default	Description
`icon`	string	-	Font Awesome icon shown in navigation
`sidebarTitle`	string	`title`	Shorter title for sidebar navigation
`mode`	string	-	Set to `"wide"` for full-width layout

Examples

Standard Documentation Page

---
title: Authentication
description: Secure your API with OAuth 2.0 and API keys
icon: lock
---

Long Title with Sidebar Override

---
title: Configuring Single Sign-On with SAML 2.0
sidebarTitle: SSO Setup
description: Set up enterprise SSO for your organization
---

The full title appears on the page, while the shorter sidebarTitle keeps navigation clean.

Wide Layout

---
title: API Reference
description: Complete API documentation
mode: wide
---

Wide mode removes the table of contents and expands content to full width. Useful for API reference pages or content with wide tables.

SEO Best Practices

Your title appears in:

Browser tabs
Search engine results
Navigation sidebar
Social media shares

Keep titles under 60 characters. Front-load important keywords.

# Good - clear and keyword-rich
title: Deploy to Production

# Avoid - vague or too long
title: How to Deploy Your Application to Production Servers

Descriptions appear in search results and social previews. Aim for 50-160 characters that:

Summarize the page content
Include relevant keywords
Entice users to click

# Good - actionable and specific
description: Deploy your docs to production in under 2 minutes with zero configuration

# Avoid - generic or missing
description: Documentation page

Icons help users scan navigation quickly. Use the same icon for related pages:

Topic	Suggested Icon
Getting started	`rocket`
Authentication	`lock`
API reference	`code`
Settings	`gear`
Billing	`credit-card`

Browse icons at Font Awesome.

Validation

Jamdesk validates frontmatter when building. Common errors:

Error: Page "api/auth.mdx" is missing required field: title

Fix: Add the title field to your frontmatter.

Error: Invalid frontmatter in "guide.mdx": unexpected token

Fix: Check for:

Missing quotes around strings with special characters
Incorrect indentation
Missing colons after keys

What's Next?

Navigation

Organize pages in your sidebar

docs.json Reference

Complete configuration options