Customize content using frontmatter

You can optionally use front matter to set each page’s title, full slug override, meta description, a URL to suggest edits to the page, and its OpenGraph image.

Front matter 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 front matter, as shown:

1
---
2
title: Introduction to the Fern toolkit for REST APIs
3
slug: introduction
4
description: Define your API with OpenAPI or Fern's simpler format, then generate SDKs, server boilerplate, and a documentation website with an API Reference. 
5
editThisPageUrl: https://github.com/fern-api/fern/blob/main/fern/docs/pages/overview/introduction.mdx
6
image: https://github.com/fern-api/fern/blob/main/fern/images/logo-green.png
7
---

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 appended from docs.yml

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.

slug

Type: string
Default: None

The slug you set in a page’s front matter 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 front matter affects the full URL. For example, you can set the front matter slug to email, as shown:

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

The page then becomes available at /email.

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.

editThisPageUrl

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.

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.