Customize content using frontmatter

Set titles, add meta descriptions, and more

You can optionally use frontmatter to set each page’s title, full 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 element like the table of contents and on-page feedback.

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

2title: Customize content using frontmatter

3subtitle: Set titles, add meta descriptions, and more 

4slug: frontmatter

5description: Use frontmatter to set the page title, subtitle, slug, meta description, its OpenGraph image, and a URL to suggest edits.

6og:sitename: Your Company Inc.

7og:title: SEO Metadata Title

8---

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:

  1. In the page’s frontmatter:
welcome.mdx
1---

2title: Welcome to our docs

3---
  1. From the page name in docs.yml (used if no frontmatter title is set):
docs.yml
1title: Fern | Documentation  # Site-wide title suffix

2navigation:

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”

Subtitle

subtitle
string

Renders as a subtitle on the page. If description is not set, subtitle is also used as the meta description tag.

For example, scroll to the top of this page you’re visiting now and you’ll see the subtitle “Set titles, add meta descriptions, and more”.

Slug

slug
string

Overrides the full URL path for the page, starting from the root of your docs site. This takes precedence over any slug defined in docs.yml.

For example, if you set slug: email in frontmatter, the page will be available at /email regardless of its location in the navigation structure.

There are two ways to set a page’s URL slug:

  1. Using slug in docs.yml, which is relative to the page’s location in the navigation:
docs.yml
1navigation:

2  - tab: overview

3    layout:

4      - section: Support

5        contents:

6          - page: Email Us

7            path: ./pages/email-us.mdx

8            slug: email  # Results in /overview/support/email
  1. Using slug in frontmatter, which overrides everything and sets the absolute path from the root:
email-us.mdx
1---

2slug: email  # Results in /email (ignores navigation structure)

3---

The key difference is:

  • A slug in docs.yml is relative to the page’s location in the navigation structure
  • A slug in frontmatter is absolute and ignores the navigation structure completely

Meta description

description
string

Set the meta description for a page. Like the page title, the meta description is important for SEO. It impacts the text that search engines display about your page in search results snippets. It can also influence search engine indexing and ranking. For more information, see Google’s guidelines for meta descriptions.

Example meta description
1---

2title: API Authentication

3description: Learn how to authenticate your API requests using API keys, OAuth 2.0, or JWT tokens. Includes code examples in multiple languages and security best practices.

4---

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.

Example edit-this-page-url
1---

2title: API Reference

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

4---
Edit this page feature

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.

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

2title: Landing Page

3hide-toc: true

4---
Table of contents feature

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.

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.

Example hide-nav-links
1---

2title: Standalone Guide

3hide-nav-links: true

4---
Navigation links feature

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.

Example hide-feedback
1---

2title: API Status Page

3hide-feedback: true

4---
Navigation links feature
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---

2logo:

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:

  • overview: A spacious, full-width layout without a table of contents. Perfect for landing pages, section overviews, and content that benefits from maximum horizontal space. Navigation sidebar remains visible.

  • 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.

  • reference: A full-width layout optimized for an API or SDK reference. Removes 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

SEO Best Practices

When configuring SEO metadata, ensure your titles and descriptions are unique, descriptive, and relevant to the page content. Keep descriptions between 150-160 characters for optimal display in search results.

Example SEO metadata
1---

2title: PlantStore API Quick Start

3headline: "Gett Started with PlantStore API | Developer Documentation"

4canonical-url: https://docs.plantstore.dev/welcome

5og:site_name: PlantStore Developer Documentation

6og:title: "PlantStore API Quick Start Guide"

7og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."

8og:image: https://plantstore.dev/images/api-docs-banner.png

9og:image:width: 1200

10og:image:height: 630

11twitter:card: summary_large_image

12twitter:site: "@PlantStoreAPI"

13noindex: false

14nofollow: false

15---

Document Properties

headline
string

When set, the <title /> tag in the document head will use this value rather than the title property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.

canonical-url
string

Overrides the canonical url for this page. Must be a full URL including the protocol (i.e. https://buildwithfern.com/learn/docs/content/frontmatter)

OpenGraph Properties

og:site_name
string

The name of your website as it should appear when your content is shared.

og:title
string

The title of your page as it should appear when your content is shared.

og:description
string

The description of your page as it should appear when your content is shared.

og:url
string

The URL of your page.

og:image
string

The URL or identifier of the image that will be displayed when your content is shared.

og:image:width
number

The width of the image in pixels.

og:image:height
number

The height of the image in pixels.

og:locale
string

The locale of the page, typically in the format language_TERRITORY (e.g., en_US).

og:logo
string

The URL or identifier of the logo image of your website that will be displayed when your content is shared.

Twitter Properties

twitter:title
string

The title of your page as it should appear in a tweet.

twitter:description
string

The description of your page as it should appear in a tweet.

twitter:handle
string

The Twitter handle of the page creator or site.

twitter:image
string

The URL or identifier of the image that will be displayed in a tweet.

twitter:site
string

The name of your website as it should appear in a tweet.

twitter:url
string

The URL of your page.

twitter:card
string

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

Indexing Properties

noindex
boolean

If set to true, the page will not be indexed by search engines.

nofollow
boolean

If set to true, a search engine will not follow any links present on the page.

Built with