> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontmatter

Complete reference for all YAML frontmatter fields available on HolyDocs MDX pages.

## Overview

Every MDX page in HolyDocs starts with a YAML frontmatter block enclosed in `---` delimiters. Frontmatter defines metadata about the page: its title, description, layout, SEO properties, and behavior. The only required field is `title` — everything else is optional.

```mdx
---
title: Getting Started
description: Set up your first documentation project in under 5 minutes.
icon: rocket
---

Your page content starts here.
```

## Field Reference

### title

**Type:** `string` — **Required**

The page title displayed as the `<h1>` heading, the browser tab title, and the default sidebar label.

```yaml
---
title: Authentication Guide
---
```

The `title` field is the only required frontmatter field. Every page must have one. It is used for the page heading, the `<title>` tag, and as the default label in sidebar navigation.

### description

**Type:** `string`

A short summary of the page content. Used as the `<meta name="description">` tag for SEO, displayed in search results, and shown as preview text in the AI search feature.

```yaml
---
title: Authentication Guide
description: Learn how to authenticate API requests using bearer tokens, API keys, and OAuth 2.0.
---
```

Keep descriptions between 50 and 160 characters. Search engines truncate longer descriptions, and shorter ones may not provide enough context to earn clicks.

### icon

**Type:** `string`

A [Lucide](https://lucide.dev/icons/) icon name displayed next to the page title in the sidebar navigation.

```yaml
---
title: API Reference
icon: code
---
```

Common icon values include `book`, `rocket`, `code`, `settings`, `shield`, `database`, `globe`, `terminal`, `lock`, `zap`, and `file-text`. Browse the full set at [lucide.dev/icons](https://lucide.dev/icons/).

### sidebarTitle

**Type:** `string`

Override the text displayed in the sidebar navigation. Useful when the full page title is too long for the sidebar or when you want a shorter label.

```yaml
---
title: Migrating from Mintlify to HolyDocs
sidebarTitle: From Mintlify
---
```

Without `sidebarTitle`, the sidebar uses the `title` value.

### mode

**Type:** `"wide"`

Set to `"wide"` to use a full-width layout that removes the right-hand table of contents sidebar and expands the content area. Useful for pages with wide tables, diagrams, or comparison layouts.

```yaml
---
title: Theme Comparison
mode: wide
---
```

Wide mode only removes the right sidebar (table of contents). The left navigation sidebar remains visible. The content area expands to fill the available space.

### api

**Type:** `string`

Marks the page as an API endpoint reference. The value should be the HTTP method and path. When set, HolyDocs renders the API playground, request/response panels, and auto-generated code samples.

```yaml
---
title: Create User
api: "POST /api/v1/users"
---
```

The `api` field is used for manually authored API pages. For auto-generated API docs from a specification, use `openapi` instead.

### openapi

**Type:** `string`

Links the page to a specific operation in your OpenAPI specification. HolyDocs generates the full endpoint documentation — parameters, request body, responses, and code samples — from the spec.

```yaml
---
title: List Pets
openapi: "GET /pets"
---
```

The value must match an operation defined in the OpenAPI spec connected to your project. You can add custom content below the frontmatter that renders alongside the generated documentation.

### noindex

**Type:** `boolean` — **Default:** `false`

When `true`, adds a `<meta name="robots" content="noindex">` tag to the page. Search engines will not index the page, and it will not appear in external search results.

```yaml
---
title: Internal Testing Guide
noindex: true
---
```

Use `noindex` sparingly. Common use cases include internal-only pages, draft content, and deprecated pages that you plan to remove. Overusing `noindex` can hurt your documentation's search visibility.

### Open Graph Overrides

Override the default Open Graph tags for social media previews. These control how the page appears when shared on Twitter, LinkedIn, Slack, Discord, and other platforms.

#### og:title

**Type:** `string`

Override the Open Graph title. Defaults to the `title` field.

```yaml
---
title: Authentication
og:title: "HolyDocs Authentication — Bearer Tokens, API Keys & OAuth"
---
```

#### og:description

**Type:** `string`

Override the Open Graph description. Defaults to the `description` field.

```yaml
---
title: Authentication
description: Learn how to authenticate API requests.
og:description: "Complete guide to authenticating with HolyDocs — supports bearer tokens, API keys, and OAuth 2.0 flows."
---
```

#### og:image

**Type:** `string`

Set a custom image for social media previews. Provide an absolute URL or a path relative to the docs root.

```yaml
---
title: Getting Started
og:image: /images/og/getting-started.png
---
```

Open Graph images should be 1200x630 pixels for optimal display across platforms. Use PNG or JPG format. If no `og:image` is set, HolyDocs generates a default card using your site name and page title.

## Complete Example

Here is a frontmatter block using all available fields:

```yaml
---
title: Create a New Project
description: Step-by-step guide to creating and configuring a HolyDocs documentation project.
icon: folder-plus
sidebarTitle: Create Project
mode: wide
noindex: false
og:title: "Create a HolyDocs Project — Full Setup Guide"
og:description: "Everything you need to create, configure, and deploy your first HolyDocs documentation project."
og:image: /images/og/create-project.png
---
```

## API Page Example

```yaml
---
title: Create User
description: Create a new user account with the specified role and permissions.
api: "POST /api/v1/users"
---
```

## OpenAPI Page Example

```yaml
---
title: List All Pets
description: Retrieve a paginated list of pets from the store.
openapi: "GET /pets"
---
```

## Best Practices

**Always include a description**

The `description` field directly impacts SEO and search result quality. Every page should have a unique, specific description that summarizes the page content.
  **Use icons consistently**

Pick icons from a cohesive set for your sidebar. Using related icons within a navigation group (e.g., all API pages use `code`, all guide pages use `book`) creates visual consistency.
  **Keep titles concise**

Aim for titles under 60 characters. Longer titles get truncated in browser tabs, search results, and the sidebar. Use `sidebarTitle` if you need a short sidebar label but want a descriptive page heading.
  **Set og:image for key pages**

Landing pages, getting started guides, and API overviews benefit most from custom Open Graph images. These are the pages most likely to be shared on social media.
  **Use noindex for internal content**

Draft pages, internal testing guides, and deprecated content that still needs to be accessible by URL should use `noindex: true` to avoid polluting search results.