---
title: Frontmatter
description: Configure page titles, descriptions, icons, sidebar overrides, and SEO metadata with the YAML frontmatter block at the top of every MDX file.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

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:

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

### Recommended

| 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/update) components on this page |
| `private` | boolean | `false` | Require the [site password](/setup/password-protection) 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. |

### SEO & Social

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 |

```yaml
---
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](/content/seo) for the full list of supported tags and examples.

## Examples

### Standard Documentation Page

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

### Long Title with Sidebar Override

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

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

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

<AccordionGroup>
  <Accordion title="Write compelling titles" icon="heading" defaultOpen>
    Your title appears in:
    - Browser tabs
    - Search engine results
    - Navigation sidebar
    - Social media shares

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

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

    # Avoid - vague or too long
    title: How to Deploy Your Application to Production Servers
    ```
  </Accordion>

  <Accordion title="Craft useful descriptions" icon="align-left">
    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

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

    # Avoid - generic or missing
    description: Documentation page
    ```
  </Accordion>

  <Accordion title="Use consistent icons" icon="icons">
    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](https://fontawesome.com/icons).
  </Accordion>
</AccordionGroup>

## Validation

Jamdesk validates frontmatter when building. Common errors:

<Accordion title="Missing required fields">
```text
Error: Page "api/auth.mdx" is missing required field: title
```

**Fix:** Add the `title` field to your frontmatter.
</Accordion>

<Accordion title="Invalid YAML syntax">
```text
Error: Invalid frontmatter in "guide.mdx": unexpected token
```

**Fix:** Check for:
- Missing quotes around strings with special characters
- Incorrect indentation
- Missing colons after keys
</Accordion>

## What's Next?

<Columns cols={2}>
  <Card title="SEO Optimization" icon="magnifying-glass-chart" href="/content/seo">
    Optimize your documentation for search engines
  </Card>
  <Card title="MDX Basics" icon="file-code" href="/content/mdx-basics">
    Learn the fundamentals of MDX
  </Card>
</Columns>