Page-level settings | Fern Documentation

You can optionally use frontmatter to set each page’s title, slug override, meta description, a URL to suggest edits to the page, and its OpenGraph image. You can also use frontmatter to disable certain page elements like the table of contents, on-page feedback, and page actions.

For advanced styling and functionality customizations beyond frontmatter options, see custom CSS and JavaScript.

Frontmatter syntax

Frontmatter must be added to the top of a .md or .mdx file, before the rest of the content. Use sets of three dashes to indicate the beginning and end of your frontmatter, as shown:

Example frontmatter

1 ---
2 title: Customize content using frontmatter
3 subtitle: Set titles, add meta descriptions, and more 
4 slug: frontmatter
5 description: Use frontmatter to set the page title, subtitle, slug, meta description, its OpenGraph image, and a URL to suggest edits.
6 keywords: frontmatter, seo, customization, metadata
7 og:site_name: Your Company Inc.
8 og:title: SEO Metadata Title
9 ---

Special characters

Frontmatter uses YAML syntax, but values are also processed as MDX. Some characters need quoting, while others need backslash escaping.

Characters	Solution	Example
`:` `#` `&` `*` `!` `%`	Wrap in quotes	`title: "OAuth: A guide"`
`{` `}` `<` `>`	Escape with `\`	`title: "Using \<Callout\>"`
`"` `'`	Opposite style or `\`	`title: 'The "best" practices'`

Title

title

stringDefaults to Page name from docs.yml

Sets the page’s <title> element. This appears in browser tabs, bookmarks, and search results.

The page title can be set in two ways:

In the page’s frontmatter:

welcome.mdx

1 ---
2 title: Welcome to our docs
3 ---

From the page name in docs.yml (used if no frontmatter title is set):

docs.yml

1 title: Fern | Documentation  # Site-wide title suffix
2 navigation:
3   - page: Welcome          # This becomes the page title
4     path: ./pages/welcome.mdx

The final title will include the site-wide suffix. For example:

With frontmatter: “Welcome to our docs - Fern | Documentation”
Without frontmatter: “Welcome - Fern | Documentation”

sidebar-title

stringDefaults to Page name from docs.yml

Sets the title displayed in the sidebar navigation. This takes precedence over sidebar titles defined in docs.yml. Use this when you want a shorter navigation label while keeping a descriptive page title.

The sidebar title can be set in two ways:

In the page’s frontmatter:

authentication.mdx

1 ---
2 title: Getting started with authentication # Browser tab and page header
3 sidebar-title: Authentication # Shorter version for sidebar only
4 ---

From the page name in docs.yml (used if no frontmatter sidebar-title is set):

docs.yml

1 navigation:
2   - page: Authentication guide # Displays in sidebar if no frontmatter override
3     path: ./pages/authentication.mdx

Subtitle and description

subtitle and description are closely related but serve different purposes: subtitle is visible on the page, while description is metadata for search engines and social previews. When description is missing, Fern falls back to subtitle for the metadata; a missing subtitle simply renders nothing.

MDX

Rendered

Example subtitle and description

1 ---
2 title: Page-level settings
3 subtitle: Set titles, descriptions, slugs, layout, and visibility using frontmatter
4 description: Use frontmatter to set a variety of page properties and metadata.
5 ---

subtitle

string

Renders as visible text below the page title — readers see it directly on the page. When description is not set, subtitle is also used as the HTML meta description and in llms.txt.

description

string

Sets the HTML meta description for SEO. This text appears in search engine result snippets and in llms.txt. Unlike subtitle, description is not visible on the page itself.

When description is not set, Fern uses subtitle as the meta description. When og:description is not set, Fern uses description as the OpenGraph description for social sharing previews.

Last updated

last-updated

string

Displays a “Last updated” timestamp in the page footer. Use this to show readers when the content was last modified. The value is displayed as-is, so you can use any date format you prefer.

This field is separate from the timestamps in your sitemap, which are managed automatically and used exclusively by search engines.

Example last-updated

1 ---
2 title: API Reference
3 last-updated: December 9, 2025
4 ---

Want to automatically update the last-updated field when MDX files change? See Auto-update last updated dates to set up a GitHub Action workflow.

Slug

slug

string

Overrides the page’s URL path, replacing the section and folder hierarchy while preserving any product or version prefix. Takes precedence over a slug set in docs.yml. See configuring slugs for detailed examples, including behavior within products and versions.

Edit this page

edit-this-page-url

string

Provide the absolute link to the source .md or .mdx file in GitHub. Fern uses it to add an Edit this page link to the page, which users of your documentation can use to suggest corrections or additions. You can also configure this globally instead of page-by-page - see global configuration.

This URL works with both launch modes. With launch: github, it’s the primary link for the edit button. With launch: dashboard, it’s passed as a fallback so users can also navigate to the source on GitHub from the dashboard screen.

Example edit-this-page-url

1 ---
2 title: API Reference
3 edit-this-page-url: https://github.com/your-org/docs/blob/main/content/api-reference.mdx
4 ---

Meta image

image

string

Configure the OpenGraph image metadata for a page using an absolute URL to an image hosted online. This image appears when your documentation links are shared on social media platforms, using the OpenGraph metadata protocol. For more information, see the web.dev explanation of OpenGraph.

Hide table of contents

hide-toc

boolean

Controls the conditional rendering of the table of contents feature on the right-side of the page. Set to true to disable this feature.

Example hide-toc

1 ---
2 title: Landing Page
3 hide-toc: true
4 ---

When the table of contents is hidden, Fern will center the contents of the page by default. To control the layout of the page, see the layout documentation.

Max depth

max-toc-depth

number

Sets the maximum depth of the table of contents. For example, a value of 3 will only show <h1>, <h2>, and <h3> headings in the table of contents.

Example max-toc-depth

1 ---
2 title: Sample Page
3 max-toc-depth: 3
4 ---

hide-nav-links

boolean

Controls the conditional rendering of the navigation links (previous, next) at the bottom of the page. Set to true to disable this feature.

This can be set globally in the global configuration.

Example hide-nav-links

1 ---
2 title: Standalone Guide
3 hide-nav-links: true
4 ---

On-page feedback

hide-feedback

boolean

Controls the conditional rendering of the on-page feedback form at the bottom of the page. Set to true to disable this feature.

This can be set globally in the global configuration.

Example hide-feedback

1 ---
2 title: API Status Page
3 hide-feedback: true
4 ---

Page actions

hide-page-actions

boolean

Controls the conditional rendering of page action buttons (Copy Page, View as Markdown, Ask AI, ChatGPT, Claude, Claude Code, Cursor). Set to true to turn off page actions for an individual page.

Alternatively, configure page actions for your entire site in your docs.yml file.

docs/getting-started/overview.mdx

1 ---
2 title: Overview
3 hide-page-actions: true
4 ---

Page logo

logo

object

Override the site-wide logo for a page. Specify different logos for light and dark modes using absolute URLs.

index.mdx logo example

1 ---
2 logo:
3   light: https://link-to-image.com/image-light-mode.png
4   dark: https://link-to-image.com/image-dark-mode.png
5 ---

Currently, relative paths are not supported for this field.

Layout

layout

stringDefaults to guide

Sets the page layout. Available options:

guide: The default documentation layout featuring a table of contents on the right side. Ideal for tutorials, how-to guides, and any content that benefits from easy navigation through sections.
overview: A wider layout (50% wider than guide) with a table of contents and navigation sidebar. Perfect for landing pages and section overviews that need more horizontal space while maintaining navigation.
reference: A full-width layout optimized for API or SDK reference. Always hides the table of contents so you can add another column, such as code examples. Navigation sidebar remains visible.
page: A distraction-free, full-screen layout that hides both the table of contents and navigation sidebar. Best for standalone content that benefits from focused reading experiences.
custom: A blank canvas layout that removes all default styling constraints. Hides both the table of contents and navigation sidebar, allowing complete control over the page layout.

SEO metadata

These fields set SEO metadata for a single page from its frontmatter. You can alternatively set the same metadata site-wide in docs.yml.

Only the documented SEO fields are added to the HTML <head> as meta tags. Custom frontmatter fields won’t automatically appear in your page metadata. To add custom metadata, use custom JavaScript.

plantstore-quickstart.mdx

1 ---
2 title: PlantStore API Quick Start
3 headline: "Get Started with PlantStore API | Developer Documentation"
4 keywords: plants, garden, nursery
5 canonical-url: https://docs.plantstore.dev/welcome
6 og:site_name: PlantStore Developer Documentation
7 og:title: "PlantStore API Quick Start Guide"
8 og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
9 og:image: https://plantstore.dev/images/api-docs-banner.png
10 og:image:width: 1200
11 og:image:height: 630
12 twitter:card: summary_large_image
13 twitter:site: "@PlantStoreAPI"
14 noindex: false
15 nofollow: false
16 ---

Document properties

headline

stringDefaults to Page title with site name

When set, the <title /> tag in the document head will use this value rather than the title property. For example, your title might be “Quickstart” (shown in the sidebar and as the H1), while headline could be “Quickstart | PlantStore API Docs” to give search engines more context. If not set, Fern uses title with your site name appended.

canonical-url

stringDefaults to Page URL

Overrides the canonical URL for this page. Must be a full URL including the protocol (e.g., https://buildwithfern.com/learn/docs/content/frontmatter). Defaults to the page’s resolved URL when unset.

keywords

string

Comma-separated keywords relevant to the page (e.g., plants, garden, nursery). Accepts only comma-separated strings, not arrays. No default; the tag is omitted when unset.

OpenGraph properties

og:site_name

stringDefaults to metadata.og:site_name

The name of your website as it should appear when your content is shared. Falls back to the site-wide metadata.og:site_name from docs.yml.

og:title

stringDefaults to Page title

The title of your page as it should appear when your content is shared. Falls back to the page’s title when unset.

og:description

stringDefaults to Page description

The description of your page as it should appear when your content is shared. Falls back to the page’s description, subtitle, or excerpt when unset.

og:url

stringDefaults to Page URL

The URL of your page. Falls back to the page’s resolved URL when unset.

og:image

stringDefaults to metadata.og:image

The URL of the image displayed when your content is shared. Falls back to the site-wide metadata.og:image from docs.yml.

og:image:width

number

The width of the image in pixels. No default; only used when og:image is set.

og:image:height

number

The height of the image in pixels. No default; only used when og:image is set.

og:locale

stringDefaults to metadata.og:locale

The locale of the page, typically in the format language_TERRITORY (e.g., en_US). Falls back to the site-wide metadata.og:locale from docs.yml.

og:logo

stringDefaults to metadata.og:logo

The URL of your logo image displayed when your content is shared. Falls back to the site-wide metadata.og:logo from docs.yml.

Twitter properties

twitter:title

stringDefaults to og:title

The title of your page as it should appear in a tweet. Falls back to og:title (and then to the page title) when unset.

twitter:description

stringDefaults to og:description

The description of your page as it should appear in a tweet. Falls back to og:description (and then to the page description) when unset.

twitter:handle

stringDefaults to metadata.twitter:handle

The Twitter handle of the page creator or site. Falls back to the site-wide metadata.twitter:handle from docs.yml.

twitter:image

stringDefaults to og:image

The URL of the image displayed in a tweet. Falls back to og:image when unset.

twitter:site

stringDefaults to metadata.twitter:site

The Twitter handle for your website. Falls back to the site-wide metadata.twitter:site from docs.yml.

twitter:url

stringDefaults to og:url

The URL of your page. Falls back to og:url (and then to the page URL) when unset.

twitter:card

stringDefaults to summary_large_image

The type of card used for sharing on Twitter. Options: summary, summary_large_image, app, player.

Indexing properties

noindex

boolean

If true, the page won’t be indexed by search engines and will be excluded from llms.txt endpoints.

nofollow

boolean

If true, search engines won’t follow any links on the page.

Availability

availability

string

Displays an availability badge on the page. When set in frontmatter, it overrides any availability defined in the navigation (docs.yml). Valid values are: stable, generally-available, in-development, pre-release, deprecated, or beta.

fern/docs/pages/getting-started/feature.mdx

1 ---
2 title: New feature
3 availability: beta
4 ---

This is useful when you want to set availability for individual pages without modifying your docs.yml navigation configuration, or when you need to override the availability inherited from a parent section or folder.

1	---
2	tags: ["plants-api", "breaking-change", "inventory-management"]
3	---
4
5	## Summary
6
7	In the latest release, we've added endpoints to create a new Plant.
8
9	### What's new?
10
11	New endpoints:
12
13	- `POST /plant` add a new plant to inventory.
14
15	New object schemas:
16
17	- `CreatePlantRequest`
18
19	<Note> Have questions? Reach out to your local botanist. </Note>

Frontmatter syntax

Special characters

Title

Sidebar title

Subtitle and description

MDX

Rendered

Last updated

Slug

Edit this page

Meta image

Table of contents

Hide table of contents

Max depth

Navigation links

On-page feedback

Page actions

Page logo

Layout

SEO metadata

Document properties

headline

canonical-url

keywords

OpenGraph properties

og:site_name

og:title

og:description

og:url

og:image

og:image:width

og:image:height

og:locale

og:logo

Twitter properties

twitter:title

twitter:description

twitter:handle

twitter:image

twitter:site

twitter:url

twitter:card

Indexing properties

noindex

nofollow

Availability

Changelog tags