Getting Started

Global Configuration

Customize your documentation using the docs.yml file

YAML Schema Validation

To enable intelligent YAML validation and autocompletion in your editor, add this line at the top of your docs.yml file:

docs.yml
1# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json

This enables real-time schema validation and autocompletion based on our complete schema.

Core configuration

Every Fern documentation website requires a docs.yml file that contains the core configuration settings. Here are the essential top-level properties you can configure:

docs.yml
1# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
2
3title: Stripe API Documentation        
4favicon: assets/stripe-favicon.ico     
5default-language: typescript          # Default code sample language
6
7logo:                                
8  href: https://stripe.com
9  dark: assets/stripe-logo-dark.svg
10  light: assets/stripe-logo-light.svg
11
12colors:                              
13  accent-primary:
14    light: "#635BFF"                 # Stripe's primary purple
15    dark: "#9B90FF"                  # Lighter purple for dark mode
16  background:
17    light: "#FFFFFF" 
18    dark: "#0A2540"                  
19
20navbar-links:                       
21  - type: filled
22    text: "Dashboard"
23    href: "https://dashboard.stripe.com"
24  - type: minimal 
25    text: "Support"
26    href: "https://support.stripe.com"
title
string

A string that is used as the tab bar title.

logo
object

Learn more about the logo configuration.

favicon
string

Relative filepath to the favicon.

colors
objectsRequired

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

redirects
list of objects

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

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.

background-image
object

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

typography
object

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

layout
object

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

landing-page
object

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

default-language
string

Sets the default language displayed by code snippets in the API Reference.

Options include: typescript, python, java, go, ruby, csharp, curl

metadata
object

Configure SEO metadata for your documentation website. Learn more about the metadata configuration.

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
instances
list of objects

Configure one or more documentation websites.

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.

instances.edit-this-page
object

If specified, adds 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 configuration.

Colors configuration

docs.yml
1colors:
2  accent-primary:
3    light: "#418326"  # Primary brand color for light mode
4    dark: "#ADFF8C"   # Primary brand color for dark mode
5  
6  background:
7    light: "#ffffff"
8    dark: "#0d0e11"
9  
10  border:
11    light: "#e5e7eb"
12    dark: "#1f2937"
13  
14  sidebar-background:
15    light: "#f9fafb"
16    dark: "#111827"
17  
18  header-background:
19    light: "#ffffff"
20    dark: "#0d0e11"
21  
22  card-background:
23    light: "#f3f4f6"
24    dark: "#1f2937"
accent-primary
objectRequired

The primary brand color used for interactive elements like links, buttons, and highlighted text. Configure separate colors for light and dark modes to ensure proper contrast and visibility.

background
object

The main background color for all documentation pages. Choose colors that provide good contrast with text and complement your brand colors. Dark mode colors should reduce eye strain.

border
object

Used for dividing lines, borders around elements, and visual separators. Choose subtle colors that create clear boundaries without being too prominent.

sidebar-background
object

Background color for the navigation sidebar. When specified, includes a 1px border on the right side. If omitted, the sidebar uses a transparent background without a border.

header-background
object

Background color for the top navigation header. When specified, includes a 1px solid border on the bottom. If omitted, the header uses a transparent background with a subtle gradient border.

card-background
object

Background color for cards, code blocks, and other contained elements. Should be slightly different from the main background to create visual hierarchy while maintaining readability.

Logo configuration

docs.yml
1logo: 
2  href: https://example.com
3  dark: assets/images/logo-dark.svg
4  light: assets/images/logo-light.svg
logo.href
string

The URL that users will be directed to when clicking the logo. Typically your company’s homepage or app.

logo.dark
string

Path to your dark mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: assets/images/logo-dark.svg

logo.light
string

Path to your light mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: assets/images/logo-light.svg

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

docs.yml
1typography:
2  # Font for headings and titles
3  headingsFont:
4    name: Inter-Bold
5    paths: 
6      - path: ./fonts/Inter-Bold.woff2
7        weight: 700
8        style: normal
9  
10  # Font for body text
11  bodyFont:
12    name: Inter-Regular
13    path: fonts/Inter-Regular.woff2
14    style: normal
15  
16  # Font for code snippets
17  codeFont: 
18    name: JetBrains-Mono
19    path: ./fonts/JetBrains-Mono-Regular.woff2
typography.bodyFont
object

The font used for all body text including paragraphs, lists, and general content. For optimal performance, use WOFF2 format.

typography.headingsFont
object

The font used for headings, titles, and other prominent text elements. Can be the same as your body font if you prefer a unified look. Supports multiple weights for different heading levels.

typography.codeFont
object

The font used for code blocks and inline code. Monospace fonts are recommended for better code readability. Popular choices include JetBrains Mono, Fira Code, and Source Code Pro.

Font configuration

1typography:
2  bodyFont:
3    name: Inter-Regular
4    path: fonts/Inter-Regular.woff2
5    style: normal
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

The path to your font file, relative to your docs folder. Use this when you have a single font file. For multiple font files (like separate files for bold, italic etc), use paths instead.

weight
string | number

The weight of the font. Can be a number (400, 700) or a range for variable fonts (400 700). Common values: 400 (normal), 700 (bold).

style
string

The font style, either “normal” or “italic”. Defaults to “normal” if not specified.

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

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

The GitHub repository must be public for the “Edit this page” feature to work correctly.

github.owner
stringRequired

The GitHub organization that owns the documentation repository.

github.repo
stringRequired

The name of the GitHub repository containing your fern folder.

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 Vapi’s landing page live and the associated Markdown file.

Metadata configuration

docs.yml
1metadata:
2  # Core platform identity
3  og:site_name: "Square Developer Documentation"
4  og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
5  og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services. Complete documentation for developers building the future of commerce."
6  og:url: "https://developer.squareup.com/docs"
7
8  # Social sharing assets
9  og:image: "https://developer.squareup.com/images/docs-social-card.png"
10  og:image:width: 1200
11  og:image:height: 630
12  og:locale: "en_US"
13  og:logo: "https://developer.squareup.com/images/square-logo.png"
14
15  # Twitter (I mean X) optimization
16  twitter:title: "Square Developer Platform Documentation"
17  twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform. Get started with our APIs, SDKs, and comprehensive guides."
18  twitter:handle: "@SquareDev"
19  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
20  twitter:site: "@Square"
21  twitter:card: "summary_large_image"
metadata.og:site_name
string

The name of your website for Open Graph tags.

metadata.og:title
string

The title shown in social media previews.

metadata.og:description
string

The description shown in social media previews.

metadata.og:url
string

The canonical URL of your documentation.

metadata.og:image
string

The image shown in social media previews. Recommended size is 1200x630 pixels.

metadata.og:image:width
number

The width of your Open Graph image in pixels.

metadata.og:image:height
number

The height of your Open Graph image in pixels.

metadata.og:locale
string

The locale of your content (e.g., “en_US”).

metadata.og:logo
string

URL to your company logo.

metadata.twitter:title
string

The title shown in Twitter Card previews.

metadata.twitter:description
string

The description shown in Twitter Card previews.

metadata.twitter:handle
string

Your company’s Twitter handle.

metadata.twitter:image
string

The image shown in Twitter Card previews.

metadata.twitter:site
string

The Twitter handle for your website.

metadata.twitter:card
string

The Twitter Card type. Options are summary, summary_large_image, app, or player.

Analytics configuration

docs.yml
1analytics:
2  ga4:
3    measurement-id: "G-XXXXXXXXXX"
4  gtm:
5    container-id: "GTM-XXXXXX"
6  posthog:
7    api-key: "phc_xxxxxxxxxxxx"
analytics.ga4.measurement-id
string

Your Google Analytics 4 measurement ID. Must start with “G-”.

analytics.gtm.container-id
string

Your Google Tag Manager container ID. Must start with “GTM-”.

analytics.posthog
object

Configuration for PostHog Analytics integration.

analytics.posthog.api-key
string

Your PostHog project API key. Defaults to the api-host of “https://us.i.posthog.com”.