Customize content using frontmatter

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:

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

Title

Name: title
Type: string
Default: The name of the page as specified in docs.yml

Set the content for the <title> element for a page. This title is displayed in browser tabs, history, and bookmarks, as well as in search engine results. Having a unique and informative title for each page benefits your site’s SEO (Search Engine Optimization).

If no title is provided in the frontmatter of a page, Fern uses the value for that page in docs.yml.

For example, if a page is defined like this in docs.yml:

1
- page: Overview
2
  path: ./docs/pages/api-overview.mdx

Then, if Fern does not find a title in that page’s frontmatter, Overview is used for the default title.

Site-wide title text

You can set a field named title in docs.yml like this:

1
instances:
2
  - url: fern.docs.buildwithfern.com
3

4
title: Fern | Documentation # <-- set site-wide

The value you enter for this field is appended to every page’s title across your docs site, as - TITLE_VALUE.

For example, with the above setting in docs.yml, the Overview page’s title becomes Overview - Fern | Documentation.

Subtitle

Name: subtitle
Type: string
Default: None

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

Slug

Name: slug
Type: string
Default: None

The slug you set in a page’s frontmatter overrides the URL for that page derived from docs.yml. This slug begins from the root of your docs site, ignoring the tab or section that the page is under. This allows you to set a custom full slug for any page.

As an example, consider this navigation setup in docs.yml:

1
navigation:
2
  - tab: overview
3
    layout:
4
      - section: Support
5
        contents:
6
          - page: Email Us
7
            path: ./pages/emailus.mdx
8
            slug: email

The slug set in docs.yml affects only the final part of the URL, so the emailus.mdx page is available at /overview/support/email.

In contrast, the slug that you set in frontmatter affects the full URL. For example, you can set the frontmatter slug to email, as shown:

1
---
2
slug: email
3
---

The page then becomes available at /email.

Meta description

Name: description
Type: string
Default: None

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.

Edit this page

Name: edit-this-page-url
Type: string (absolute URL)
Default: None

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.

Meta image

Name: image
Type: string (absolute URL)
Default: None

Configure the <meta property="og:image"> metadata for a page using an absolute path to an image hosted online. This provides an image to show next to a link to your documentation when the link is shared on social media, using a metadata protocol called OpenGraph. For more information, see the web.dev explanation of OpenGraph.

Table of contents

Name: hide-toc
Type: boolean
Default: false

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

Navigation links

Name: hide-nav-links
Type: boolean
Default: false

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

On-page feedback

Name: hide-feedback
Type: boolean
Default: false

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

Page logo

Name: logo
Type: object
Default: None

You can override the site-wide logo for a page by setting a field named logo in any page’s frontmatter like this:

1
---
2
logo:
3
  light: /path/to/page-logo.png
4
  dark: /path/to/page-logo.png
5
---

This field specifies the logo for this page. If no logo is set, the site-wide logo configuration is used.

SEO metadata

Fern also supports adding SEO-specific metadata in the frontmatter.