Guides
View as Markdown Open in ChatGPT Open in Claude

Frontmatter

Frontmatter is YAML metadata at the top of each MDX file. It controls page settings, SEO, layout, and protocol-specific rendering.

Basic Frontmatter

Every page should have at minimum a title:

---
title: Getting Started
---

Common Fields

Field Type Description
title string Page title (required)
description string Meta description for SEO
icon string Icon in navigation sidebar
draft boolean Hide from production
sidebar boolean Show/hide sidebar
toc boolean Show/hide table of contents

Example

---
title: Authentication Guide
description: Learn how to authenticate with the API using API keys or OAuth.
icon: key
---

How title and description Render

Beyond metadata, title and description can render as visible page content:

  • If the page body contains no <h1> (no # Heading), the build synthesizes one from the frontmatter title, and renders description as a lead paragraph directly below it.
  • If the body already has an <h1>, nothing is synthesized — the frontmatter values are used only for metadata (browser tab, sidebar, SEO).
  • The lead paragraph is skipped when the body's first paragraph already starts with the same text as description, so you won't see it twice.

This means both authoring styles work:

---
title: Authentication Guide
description: Learn how to authenticate with the API.
---

Syntext supports two authentication methods...

---
title: Authentication Guide
---

# Authentication Guide

Syntext supports two authentication methods...

Pick one style per page: either rely on the frontmatter title or write an explicit # Heading — not both. If your body starts with # Authentication Guide, no heading is synthesized, so there's no double render; but mixing styles across pages makes headings inconsistent.

Layout Options

Control page structure with the layout field:

---
title: Welcome
layout: centered
---
Layout Description
default Three-column: sidebar + content + TOC
centered Single column, centered content — no sidebars; ideal for landing pages
full-width Single column, full width

Hiding the right column

Set hideRightSidebar: true to drop the right-hand column and let the content span to the right edge while keeping the left navigation sidebar:

---
title: API Reference
hideRightSidebar: true
---

This works on guide pages (hides the "On this page" TOC) and on prose pages inside the API Reference section (overview and hand-written pages), where it removes the reserved code-example column. Endpoint pages ignore it — the request/response column always stays.

Background Customization

For landing pages or special sections:

---
title: Welcome
layout: centered
background: "#0a0a1a"
---

Solid Color

---
background: "#050510"
---

Gradient

---
background: "linear-gradient(135deg, #0a0a1a 0%, #1a0a2e 100%)"
---

Background Image

---
backgroundImage: "/assets/hero-bg.png"
backgroundSize: cover
backgroundPosition: center
---

SEO Fields

Optimize for search engines and social sharing:

---
title: API Reference
description: Complete API reference for all endpoints.
ogImage: /images/api-og.png
noIndex: false
canonical: https://docs.example.com/api
---
Field Description
description Meta description (150-160 chars ideal)
ogImage Open Graph image for social sharing
noIndex Exclude from search engine indexing
canonical Canonical URL for duplicate content

Control how the page appears in navigation:

---
title: Advanced Configuration
sidebarTitle: Advanced
sidebarPosition: 5
hidden: false
---
Field Description
sidebarTitle Override title in sidebar
sidebarPosition Manual sort order (lower = higher)
hidden Hide from sidebar but keep accessible

Protocol Frontmatter

For API documentation, specify the protocol to get specialized rendering.

REST / HTTP

---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
description: Create a new user account.
---

Renders a colored method badge (POST = green) and endpoint path.

WebSocket

---
title: Order Created Event
protocol: websocket
event: order.created
direction: server-to-client
description: Fired when a new order is placed.
---

GraphQL

---
title: Create Order Mutation
protocol: graphql
operation: mutation
name: createOrder
description: Create a new order.
---

gRPC

---
title: Create Payment
protocol: grpc
service: PaymentService
rpc: CreatePayment
description: Create a new payment via gRPC.
---

Event-Driven

---
title: Order Confirmed
protocol: event
channel: orders.confirmed
broker: kafka
description: Published when an order is confirmed.
---

Page Types

The type field enables specialized templates:

---
title: v2.0 Release
type: changelog
date: 2024-01-15
---
Type Description
guide Standard documentation (default)
api-reference API endpoint page
changelog Changelog entry with date
landing Marketing-style landing page
sdk SDK documentation with language tabs

Feature Toggles

Enable or disable page features:

---
title: Quick Reference
toc: false
sidebar: false
feedback: true
editUrl: https://github.com/org/repo/edit/main/docs/quick-ref.mdx
---
Field Default Description
toc true Table of contents
sidebar true Navigation sidebar
feedback true "Was this helpful?" widget
editUrl auto "Edit on GitHub" link

Complete Example

---
# Core metadata
title: Create User
description: Create a new user account via the REST API.

# Protocol (for API pages)
protocol: rest
method: POST
endpoint: /v1/users

# Layout
layout: default
toc: true
sidebar: true

# SEO
ogImage: /images/api/create-user-og.png

# Features
feedback: true
editUrl: https://github.com/acme/docs/edit/main/docs/api/create-user.mdx
---
Was this page helpful?