Frontmatter

Every MDX file starts with a YAML block between --- markers. This metadata controls your page title, sidebar appearance, and how the page looks when shared on social media or in search results.

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 next to the page title in sidebar navigation
`sidebarTitle`	string	`title`	Shorter title for sidebar navigation
`mode`	string	-	Set to `"wide"` for full-width layout
`hideFooter`	boolean	`false`	Hide the social footer on this page
`rss`	boolean	`false`	Enable RSS feed generation from Update components on this page
`private`	boolean	`false`	Require the site password to view this page. Setting this on any page activates specific-pages mode on the next build.
`public`	boolean	`false`	Exempt this page from password protection (used when the whole site is gated via `auth.password.enabled`). Wins over `private: true` if both are set.

Control how the page appears in search results and social previews. Set these as flat top-level keys or under a nested seo: block. Both work, and per-page values override your docs.json seo.metatags defaults.

Field	Type	Default	Description
`keywords`	string[]	-	Search keywords, emitted as a `<meta name="keywords">` tag
`canonical`	string	auto	Canonical URL for this page, overriding the auto-generated one
`noindex`	boolean	`false`	Exclude this page from search engines and the sitemap
`og:` / `twitter:`	string	-	Open Graph and Twitter/X social-preview tags (e.g. `og:title`, `og:image`, `twitter:card`)
`seo`	object	-	Nested block holding any of the above plus arbitrary custom meta tags

---
title: API Reference
description: REST endpoints and authentication
"og:image": /images/api-card.png
"twitter:card": summary_large_image
canonical: https://docs.acme.com/api-reference
---

See SEO Optimization for the full list of supported tags and examples.

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.

Hide Footer

---
title: Custom Landing
description: A focused landing page experience
hideFooter: true
---

Use hideFooter for landing pages, changelog pages, or any page where you want a cleaner bottom section without social links.

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?

SEO Optimization

Optimize your documentation for search engines

MDX Basics

Learn the fundamentals of MDX