Frontmatter

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 Starteddescription: 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 Guidedescription: 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 icon name displayed next to the page title in the sidebar navigation.

yaml
---title: API Referenceicon: 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.

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 HolyDocssidebarTitle: 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 Comparisonmode: 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 Userapi: "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 Petsopenapi: "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 Guidenoindex: 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: Authenticationog:title: "HolyDocs Authentication — Bearer Tokens, API Keys & OAuth"---

og:description

Type: string

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

yaml
---title: Authenticationdescription: 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 Startedog: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 Projectdescription: Step-by-step guide to creating and configuring a HolyDocs documentation project.icon: folder-plussidebarTitle: Create Projectmode: widenoindex: falseog: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 Userdescription: Create a new user account with the specified role and permissions.api: "POST /api/v1/users"---

OpenAPI Page Example

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

Best Practices