Overview

Fern | Write and customize content in docs built with Fern

Add content with Markdown or MDX files

Add pages manually to your documentation by creating Markdown (.md) or MDX (.mdx) files and linking to them in docs.yml.

Example folder structure in docs.yml
$fern/
>├─ fern.config.json
>├─ docs.yml
>└─ pages/
> ├─ welcome.mdx

Custom components

Fern has a built-in component library you can use in Markdown and MDX files. Explore the components.

Frontmatter

You can optionally use frontmatter for individual page configuration.

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

Example frontmatter in .md or .mdx file
1---
2title: Fern Docs Quickstart
3description: Learn how to get started building a documentation site for your product with Fern. Automatically generate a API Reference using your OpenAPI specification, configure site navigation, customize styles, and write documentation in Markdown and MDX. Fern's magic puts it all together and builds an attractive site you can host yourself, or host free with Fern.
4editThisPageUrl: https://github.com/fern-api/fern/blob/main/fern/docs/pages/docs/quickstart.mdx
5image: https://github.com/fern-api/fern/blob/main/fern/docs/images/logo-green.png
6---

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). For more information, see Google’s guidelines for useful titles.

If no title is provided in the frontmatter of a page, the name of the page in docs.yml is used.

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.

When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.

In Markdown, use a / to begin a relative URL instead of ./.

Relative link example
1For more information, see the page on [Authentication](/home/authentication).

Configure your site with docs.yml

Every Fern Docs website has a special configuation file called docs.yml. Use this file to configure the navigation and styles for your documentation site.

An example docs.yml
1navigation:
2 - section: Home
3 contents:
4 - page: Introduction
5 path: ./intro.mdx
6 - page: Authentication
7 path: ./auth.mdx
8 - api: API Reference
9navbar-links:
10 - type: secondary
11 text: Contact support
12 url: https://example.com/support
13 - type: primary
14 text: Login
15 url: https://example.com/login
16colors:
17 accentPrimary: "#a6d388"
18logo:
19 path: ./images/logo.png
20 height: 60
21 href: https://example.com
22favicon: ./images/favicon.png

Sections, contents, and pages

The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each section has a name and a list of contents. The sections appear in the left-side nav bar in the order that they are listed in docs.yml.

In contents, list your pages with names and corresponding file paths. The supported file types for pages are .md or .mdx.

A basic navigation configuration with two sections is shown below. The first section is called Introduction and contains a single page called My Page. The second section is called API Reference. This is a special type of section that’s automatically generated by Fern, and you do not need to add any pages to it by hand. You can read more about it in the API Reference section further below.

Example navigation config
1navigation:
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: ./pages/my-page.mdx
6 - api: API Reference

If you want to add another page to an existing section, create an .md or .mdx file. Then in docs.yml, create a new page in the contents list for that section, providing the path to the .md or .mdx file you created. Example:

Example navigation config
1navigation:
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: ./pages/my-page.mdx
6 - page: Another Page
7 path: ./pages/another-page.mdx
8 - api: API Reference

To add another section, add another section to the navigation. Example:

Example navigation config with additional section
1navigation:
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: ./pages/my-page.mdx
6 - api: API Reference
7 - section: Help Center
8 contents:
9 - page: Contact Us
10 path: contact-us.mdx

Nested sections

If you’d like a section to toggle into more sections and pages, you can nest sections within sections. Here’s an example:

Example navigation config with nested sections
1navigation:
2 - tab: guides
3 layout:
4 - section: Learn
5 contents:
6 - section: Key Concepts
7 contents:
8 - page: Embeddings
9 path: ./docs/pages/embeddings.mdx
10 - page: Prompt Engineering
11 path: ./docs/pages/prompts.mdx
12 - section: Generation
13 contents:
14 - page: Command Nightly
15 path: ./docs/pages/command.mdx
16 - page: Likelihood
17 path: ./docs/pages/likelihood.mdx

Result of above docs.yml example

For links that you want to be easily accessible, you can specify a list of links in navbar-links. These links appear as buttons in the top right of your documentation website.

Example of navbar-links config
1navbar-links:
2 - type: secondary
3 text: Contact support
4 url: https://example.com/support
5 - type: primary
6 text: Login
7 url: https://example.com/login

Set the type to either primary or secondary. Primary links are designed to stand out and indicate that they are clickable with an arrow >. You can have one primary link.

Set the link text that is displayed to the user.

Set the target url for the link.

To use a relative URL, make sure that you use / to begin the URL instead of ./. This link opens in a new browser tab, regardless of whether it is a relative or absolute URL.

You can use a trackable link in your URL. For example, if using UTM parameters, instead of https://www.example.com/login, set the url to https://www.example.com/login?utm_source=docs&utm_medium=navbar.

API Reference

A key benefit of using Fern Docs is that you get your API Reference with just one line. Add - api: API Reference and Fern takes care of the rest! You’ll see your endpoints, types, and errors automatically populated from your OpenAPI specification.

Styles

Colors

Primary accent

You can specify a primary accent color using the hexadecimal color. The primary accent color is used for several purposes, including:

  • to indicate the page a user is on within the navigation
  • as the background of a primary link button
  • to underline hyperlinks
  • the next and previous page navigation buttons
docs.yml
1colors:
2 accentPrimary: "#a6d388"

Background

Just like accentPrimary, you can specify the background color using the hexadecimal color.

docs.yml
1colors:
2 accentPrimary: "#a6d388"
3 background:
4 dark: "#0d0e11"
5 light: "#ffffff"

Add a logo that displays in the top left of your documentation website.

docs.yml
1logo:
2 path: ./images/logo.png
3 height: 60
4 href: https://example.com

Logo path

path specifies the image file location. The supported file types are .png or .svg.

Logo height

height sets the logo’s height in pixels.

Logo href

href provides a link for the logo, often used to point to the website’s homepage. When the logo is clicked, the user is directed to this link.

Favicon

Specifies the path to a favicon image, which is typically displayed in a browser tab or bookmark. Supported file types are .png and .ico.

Advanced features

The following configuration options allow you to further personalize your documentation website using docs.yml.

Fonts

You can specify custom fonts for your documentation website. The supported file types are .woff and .woff2.

Include the custom fonts in your fern/ project:

Example custom fonts
1 fern/
2 ├─ fern.config.json
3 ├─ generators.yml
4 ├─ openapi/
5 ├─ openapi.yml
6+ ├─ fonts/
7+ ├─ your-font-regular.woff2
8+ ├─ your-font-bold.woff2
9+ └─ another-font-regular.woff2

Fern has three font types:

  • headingsFont: affects page and section titles; if not supplied, defaults to the body font
  • bodyFont: affects paragraph text and other body text
  • codeFont: affects code blocks and inline code snippets

To customize the font used for each font type, add a top-level typography list to docs.yml. Then in it, specify the path of your font file for one or more of the font types.

A font has two properties:

  • name: the name of the font; defaults to a generated name that will be used to reference your custom font in the eventually injected CSS
  • path: the path to the font file
Example of specifying custom fonts in docs.yml
1typography:
2 bodyFont:
3 name: Inter-Regular
4 path: ./fonts/Inter-Regular.woff2
5 headingsFont:
6 name: Inter-Bold
7 path: ./fonts/Inter-Bold.woff2
8 codeFont:
9 name: Roboto-Mono-Regular
10 path: ./fonts/Roboto-Mono-Regular.woff2
11 name: Roboto-Mono-Regular

If the font file is not variable, you can specify font weights.

A font path has three properties:

  • path: indicate that there are multiple font files
  • weight: a string of weights that are supported by this font file
  • style: the style of the font file, either normal or italic
Example of specifying font weights in docs.yml
1typograpghy:
2 bodyFont:
3 name: Inter-Regular
4 paths:
5 - path: ./fonts/Inter-Regular.woff2
6 weight: "400"
7 style: normal
8 - path: ./fonts/Inter-Bold.woff2
9 weight: 500 900 # <-- indicates a range of weights
10 style: normal

Tabs

Within the navigation, you can add tabs. Tabs are used to group sections together. The example below shows tabs for Help Center and API Reference. Each tab has a title and icon. Browse the icons available from FontAwesome.

docs.yml
1tabs:
2 api:
3 display-name: API Reference
4 icon: puzzle
5 help:
6 display-name: Help Center
7 icon: home
8
9 navigation:
10 - tab: api
11 layout:
12 - section: Introduction
13 contents:
14 - page: My Page
15 path: my-page.mdx
16 - api: API Reference
17 - tab: help
18 layout:
19 - section: Help Center
20 contents:
21 - page: Contact Us
22 path: contact-us.mdx

Here’s an example of what the Tabs implementation looks like: Screenshot showing two vertically stacked tabs labeled API Reference and Help Center

Versions

If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the versions.

A dropdown of the available versions

When adding an entry to the versions list, specify the version’s display-name, which is visible to users, and path, which is a file that must be in a folder called versions/:

docs.yml
1versions:
2 - display-name: v1.0
3 path: v1-0.yml # must be in a `versions` folder
4 - display-name: v1.1
5 path: v1-1.yml
versions/v1-0.yml
1navigation:
2 - section: Introduction
3 contents:
4 - page: My Page
5 path: my-page.mdx
6 - api: API Reference
versions/v1-1.yml
1tabs:
2 api:
3 title: API Reference
4 icon: puzzle
5 help:
6 title: Help Center
7 icon: home
8
9 navigation:
10 - tab: api
11 contents:
12 - section: Introduction
13 contents:
14 - page: My Page
15 path: my-page.mdx
16 - api: API Reference
17 - tab: help
18 contents:
19 - section: Help Center
20 contents:
21 - page: Contact Us
22 path: contact-us.mdx