Global Configuration

Customize your documentation using the docs.yml file

Not all of the properties in docs.yml are documented here. If you’d like to see all properties, please check out the the raw schema

Top-level properties

Every Fern documentation website needs a docs.yml file with the core configuration settings.

docs.yml
1title: My Docs
2
3logo: 
4  href: mydomain.com
5  dark: path/to/logo.png
6  light: path/to/logo.png
7
8favicon: path/to/favicon.ico
title
string

A string that is used as the tab bar title.

logo
object

Learn more about the logo configuration here.

favicon
string

Relative filepath to the favicon.

colors
objectsRequired

Configure the primaryAccent and background colors. Learn more about the colors configuration here.

redirects
list of objects

An array of paths you want to configure to permanently redirect to another path. Learn more about the redirects configuration here.

navbar-links
list of objects

Array of names and urls of links you want to include as a call to action. Learn more about the navbar-links configuration here.

background-image
object

Set a custom background image to be displayed behind every page. Learn more about the background-image configuration here.

typography
object

Customize the fonts used in your documentation website. Learn more about the typography configuration here.

layout
object

Customize the layout of your documentation website. Learn more about the layout configuration here.

landing-page
object

Creates a landing page for your documentation website. Learn more about the landing-page configuration here.

Instances configuration

An instance is the backend of a distinct docs website. Each instance is published to a unique domain using the --instance flag. It is most common to use instances to configure staging and production docs which publish to separate URLs.

docs.yml
1instances: 
2  - url: plantstore.docs.buildwithfern.com
3    custom-domain: docs.plantstore.com
4    edit-this-page: 
5      github: 
6        owner: fern
7        repo: plant-store-docs
8        branch: main
instances.url
stringRequired

The URL where your Fern documentation is deployed. Must contain the suffix docs.buildwithfern.com

instances.custom-domain
string or list of strings

The custom domain where your documentation is hosted. Learn more about setting up a custom domain here.

instances.edit-this-page
object

If edit-this-page is set, Fern will add an “Edit this page” link to the bottom of each page that links to the given public GitHub repository.

Learn more about the edit-this-page object here.

Colors configuration

docs.yml
1colors: 
2  accent-primary: 
3    light: "#418326"
4    dark: "#ADFF8C"
5  background: 
6    light: "#ffffff"
7    dark: "#0d0e11"
accent-primary
objectRequired

The configured accent primary color for light and dark mode.

background
object

The configured background colors for light and dark mode.

border
object

The border color is used for the borders of cards and other elements.

sidebar-background
object

If sidebarBackground is set, the sidebar will also render a 1px border on the right side.

By default, the sidebar will render with a transparent background without a border.

header-background
object

If headerBackground is set, the header will render with a solid background, with a 1px solid border on the bottom.

By default, the header will render with a transparent background, with a 1px faded border on the bottom.

card-background
object

The background color of cards and code blocks.

Logo configuration

docs.yml
1logo: 
2  href: mydomain.com
3  dark: path/to/logo.png
4  light: path/to/logo.png
logo.href
string

Where clicking on the logo links you to.

logo.dark
string

Path to the image for the dark mode logo. You can exclude this if you don’t have dark mode enabled. SVG format is recommended.

logo.light
string

Path to the image for the light mode logo. You can exclude this if you don’t have light mode enabled. SVG format is recommended.

Redirects configuration

docs.yml
1redirects:
2  - source: "/old-path"
3    destination: "/new-path"
4  - source: "/old-folder/*"
5    destination: "/new-folder/*"
source
stringRequired

The path that you want to redirect from.

destination
stringRequired

The path that you want to redirect to.

permanent
boolean

Toggle between permanent and temporary redirect (default false). When true, the status code is 308. When false the status code is 307.

docs.yml
1navbar-links:
2  - type: minimal
3    text: Contact support
4    href: https://example.com/support
5  - type: filled
6    text: Login
7    href: https://example.com/login
8    rounded: false
type
enum

One of outlined, minimal, or filled. This value controls the styling of the button.

href
string

The url once you click on the button. Example: https://buildwithfern.com/contact

text
string

Text inside the button.

rounded
booleanDefaults to false

When true, the border radius of the button will be fully rounded.

icon
string

The Font Awesome icon to be used in the button. This icon will appear to the left of the text content. Pro and Brand Icons from Font Awesome are supported.

rightIcon
string

The Font Awesome icon to be used in the button. This icon will appear to the right of the text content. Pro and Brand Icons from Font Awesome are supported.

By default, the rightIcon for a filled button is set to arrow-right.

Background image configuration

docs.yml
1background-image: 
2  light: ./path/to/bg-light.svg
3  dark: ./path/to/bg-dark.svg
background-image.light
string

Relative filepath to the light-mode background image.

background-image.dark
string

Relative filepath to the dark-mode background image.

Typography configuration

1typography:
2  bodyFont:
3    name: Inter-Regular
4    path: ./fonts/Inter-Regular.woff2
5  headingsFont:
6    name: Inter-Bold
7    paths: 
8      - path: ./fonts/Inter-Bold.woff2
9        weight: "400"
10        style: normal
11      - path: ./fonts/Inter-Bold.woff2
12        weight: 500 900 # <-- indicates a range of weights
13        style: normal    
14  codeFont: 
15    name: Roboto-Mono-Regular
16    path: ./fonts/Roboto-Mono-Regular.woff2
typography.bodyFont
object

Customize page and section titles. If not supplied, defaults to the body font.

Learn more about font configuration here.

typography.headingsFont
object

Customize paragraph text and other body text.

Learn more about font configuration here.

typography.codeFont
object

Customize code blocks and inline code snippets.

Learn more about font configuration here.

Font configuration

1typography:
2  bodyFont:
3    name: Inter-Regular
4    path: ./fonts/Inter-Regular.woff2
name
string

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
string

Relative filepath to a variable font file. If the font file is not variable, use paths instead.

Supported font file types are .woff and woff2.

paths
object

A list of font files for particular weights. Each element in the list includes a path, weight, and style property.

Layout configuration

docs.yml
1layout:
2  header-height: 70px
3  page-width: 1344px
4  content-width: 672px
5  sidebar-width: 336px
6  searchbar-placement: header
7  tabs-placement: header
8  content-alignment: left
layout.header-height
string

Sets the height of the header. Defaults to 4rem (64px). Valid options are {number}rem or {number}px.

layout.page-width
string

Sets the maximum width of the docs layout, including the sidebar and content. Defaults to 88rem (1408px). Valid options are {number}rem, {number}px, or full.

layout.content-width
string

Sets the maximum width of the Markdown article content. Defaults to 44rem (704px). Valid options are {number}rem or {number}px.

layout.sidebar-width
string

Sets the width of the sidebar in desktop mode. Defaults to 18rem (288px). Valid options are {number}rem or {number}px.

layout.searchbar-placement
string

Sets the placement of the searchbar. Can be one of header, sidebar or header_tabs (places the searchbar in the header but on the tabs row). Defaults to sidebar.

This setting is ignored when disable-header is set to true.
layout.tabs-placement
string

Set the placement of the tabs. Can be one of header or sidebar. Defaults to sidebar.

This setting is ignored when disable-header is set to true.
layout.content-alignment
string

Set the alignment of the Markdown content. Can be one of center or left. Defaults to center.

layout.disable-header
boolean

If set to true, the header will not be rendered. Instead, the logo will be rendered as part of the sidebar, and a 1px border will separate the sidebar from the content.

GitHub configuration

docs.yml
1edit-this-page: 
2  github: 
3    owner: fern
4    repo: plant-store-docs
5    branch: main

Be sure the repository is set to public visibility.

github.owner
stringRequired

The owner of the GitHub repository where you host your documentation.

github.repo
stringRequired

The name of the GitHub repository where you host your documentation.

github.branch
stringRequired

The branch of the repository you would like the GitHub editor to open a PR to. Default is main.

Landing page configuration

docs.yml
1landing-page: 
2  page: Page Title
3  path: path/to/landing-page.mdx
page
stringRequired

The name of the landing page.

path
stringRequired

Relative filepath to the desired landing page Markdown file.

See VapiAI’s landing page live and the associated Markdown file.