> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Page settings

> Use frontmatter to set a variety of page properties and metadata.

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](/learn/docs/customization/custom-css-js).

## 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

```mdx
---
title: Customize content using frontmatter
subtitle: Set titles, add meta descriptions, and more 
slug: frontmatter
description: Use frontmatter to set the page title, subtitle, slug, meta description, its OpenGraph image, and a URL to suggest edits.
keywords: frontmatter, seo, customization, metadata
og:site_name: Your Company Inc.
og:title: SEO Metadata Title
---
```

### 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'` |

### Common errors

#### Failed to parse frontmatter

If `fern check` reports `Failed to parse frontmatter`, the [YAML](#frontmatter-syntax) between the `---` markers is invalid. The most common cause is an unquoted value containing one of the [special characters](#special-characters). Wrap the value in quotes or escape the character and re-run `fern check`.

## Title

**`title`** `string` — default: Page name from docs.yml

Sets the page's [`<title>` element](https://web.dev/learn/html/document-structure#document_title). This appears in browser tabs, bookmarks, and search results.

---

The page title can be set in two ways:

1. In the page's frontmatter:

**`welcome.mdx`**

```mdx title="welcome.mdx"
---
title: Welcome to our docs
---
```

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

**`docs.yml`**

```yaml title="docs.yml"
title: Fern | Documentation  # Site-wide title suffix
navigation:
  - page: Welcome          # This becomes the page title
    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

**`sidebar-title`** `string` — default: 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:

1. In the page's frontmatter:

**`authentication.mdx`**

```mdx title="authentication.mdx"
---
title: Getting started with authentication # Browser tab and page header
sidebar-title: Authentication # Shorter version for sidebar only
---
```

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

**`docs.yml`**

```yaml title="docs.yml" 
navigation:
  - page: Authentication guide # Displays in sidebar if no frontmatter override
    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.

| Field            | Visible on page | HTML meta description                 | OpenGraph description                                            | llms.txt                              |
| ---------------- | --------------- | ------------------------------------- | ---------------------------------------------------------------- | ------------------------------------- |
| `subtitle`       | Yes             | Fallback when `description` is absent | Fallback when both `description` and `og:description` are absent | Fallback when `description` is absent |
| `description`    | No              | Yes                                   | Fallback when `og:description` is absent                         | Yes                                   |
| `og:description` | No              | No                                    | Yes                                                              | No                                    |

#### MDX

#### Example subtitle and description

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

#### Rendered

![Subtitle and description](/learn/_fern-img/070e066a5b63140e535d772042c3b32d6913ac4c8bf9f59e8137bc0727b56c9d.webp)

**`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`](/learn/docs/ai-features/llms-txt#page-descriptions).

---

**`description`** `string`

Sets the HTML [meta description](https://web.dev/learn/html/metadata#description) for [SEO](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions). This text appears in search engine result snippets and in [`llms.txt`](/learn/docs/ai-features/llms-txt#page-descriptions). 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`](#seo-metadata) 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](/learn/docs/seo/overview#what-fern-handles-automatically), which are managed automatically and used exclusively by search engines.

---

#### Example last-updated

```mdx
---
title: API Reference
last-updated: December 9, 2025
---
```

Want to automatically update the `last-updated` field when MDX files change? See [Auto-update last updated dates](/learn/docs/developer-tools/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](/learn/docs/seo/configuring-slugs#override-with-a-frontmatter-slug) 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](/learn/docs/configuration/site-level-settings#edit-this-page-configuration).

This URL works with both [launch modes](/learn/docs/user-feedback#edit-this-page). 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

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

![Edit this page feature](/learn/_fern-img/7ad2b2c03552e0e1c18247a9569589cc1a5c1254681fd68acd0378509aed7afd.webp)

## 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](https://ogp.me/) metadata protocol. For more information, see the [web.dev explanation of OpenGraph](https://web.dev/learn/html/metadata#open_graph).

---

## Table of contents

### 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

```mdx
---
title: Landing Page
hide-toc: true
---
```

![Table of contents feature](/learn/_fern-img/c8c8f24d5d058f1e496ae36cf193dd65e83e0193413e3107c0e35d3cc2cfb354.webp)

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](#layout).

### 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

```mdx
---
title: Sample Page
max-toc-depth: 3
---
```

![Table of contents max depth](/learn/_fern-img/147bd164a594901141798a2293e8c280012a0a5ae7e39d6bc125b9ead426f81a.webp)

## Navigation links

**`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](/learn/docs/configuration/site-level-settings#layout-configuration).

---

#### Example hide-nav-links

```mdx
---
title: Standalone Guide
hide-nav-links: true
---
```

![Navigation links feature](/learn/_fern-img/589f6bff88be20aeecd2dfcaa48bbbaf455df2b1eb822fc6ee287187c7f74dc9.webp)

## 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](/learn/docs/configuration/site-level-settings#layout-configuration).

---

#### Example hide-feedback

```mdx
---
title: API Status Page
hide-feedback: true
---
```

![Leave feedback feature](/learn/_fern-img/6773a2db4328b6a14cbabee0d512d8d5c798b74a1b5e3a51d8517a38b6786d30.webp)

## 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](/learn/docs/configuration/site-level-settings#page-actions-configuration) in your `docs.yml` file.

---

#### docs/getting-started/overview\.mdx

```mdx
---
title: Overview
hide-page-actions: true
---
```

## 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

```mdx
---
logo:
  light: https://link-to-image.com/image-light-mode.png
  dark: https://link-to-image.com/image-dark-mode.png
---
```

Currently, relative paths are *not* supported for this field.

## Layout

**`layout`** `string` — default: 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`](/learn/docs/configuration/site-level-settings#seo-metadata-configuration).

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](/learn/docs/customization/custom-css-js#custom-javascript).

#### plantstore-quickstart.mdx

```mdx
---
title: PlantStore API Quick Start
headline: "Get Started with PlantStore API | Developer Documentation"
keywords: plants, garden, nursery
canonical-url: https://docs.plantstore.dev/welcome
og:site_name: PlantStore Developer Documentation
og:title: "PlantStore API Quick Start Guide"
og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
og:image: https://plantstore.dev/images/api-docs-banner.png
og:image:width: 1200
og:image:height: 630
twitter:card: summary_large_image
twitter:site: "@PlantStoreAPI"
noindex: false
nofollow: false
---
```

#### Document properties

**`headline`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: Page URL

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

---

**`og:image`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: og:image

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

---

**`twitter:site`** `string` — default: metadata.twitter:site

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

---

**`twitter:url`** `string` — default: og:url

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

---

**`twitter:card`** `string` — default: 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`](/learn/docs/ai-features/llms-txt) endpoints.

---

**`nofollow`** `boolean`

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

---

#### Structured data properties

Fern emits [JSON-LD structured data](/learn/docs/seo/setting-seo-metadata#structured-data-json-ld) on every indexable page. This field overrides the generated breadcrumb trail.

**`jsonld:breadcrumb`** `object`

A complete [schema.org `BreadcrumbList`](https://schema.org/BreadcrumbList) that replaces the breadcrumb trail Fern generates from the page's position in your navigation. Emitted in the page's `application/ld+json` script alongside the `TechArticle` node.

---

## Availability

**`availability`** `string`

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

---

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

```mdx
---
title: New feature
availability: beta
---
```

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.

## Search metadata

**`search-metadata`** `object`

Custom key-value metadata copied onto the page's Algolia records and declared for [faceting](/learn/docs/customization/search#facet-on-custom-page-metadata). Values can be strings, numbers, booleans, dates (indexed as ISO 8601 strings), arrays, or nested objects.

---

## Changelog tags

**`tags`** `array of strings`

For [changelog pages](/learn/docs/configuration/changelogs) only. Tags allow users to filter changelog entries by specific categories. Define tags as an array of strings in the frontmatter.

---

#### fern/changelog/2024-07-31.mdx

```mdx
---
tags: ["plants-api", "breaking-change", "inventory-management"]
---

## Summary

In the latest release, we've added endpoints to create a new Plant.

### What's new?

New endpoints:

- `POST /plant` add a new plant to inventory.

New object schemas:

- `CreatePlantRequest`

<Note> Have questions? Reach out to your local botanist. </Note>
```

> Set titles, descriptions, slugs, layout, and visibility using frontmatter