Building Your Docs

Style your docs to match your brand

Every Fern Docs website has a configuration file called docs.yml. Use this file to set the theme for your docs, including the primary accent color, background image, logo, favicon, light & dark mode, and fonts.

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

In docs.yml, you can set a single primary accent color or specify different colors for light and dark modes:

1colors:
2 accentPrimary: "#ADFF8C"

Background color

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

1colors:
2 accentPrimary: "#a6d388"
3 background: "#0d0e11"

Images

Background image

Customize the background image by including the image(s) in your fern/ project and specifying the path in docs.yml. The PNG, SVG, and JPG image formats are supported.

Add the images
1 fern/
2 ├─ openapi/
3 ├─ pages/
4+ ├─ images/
5+ ├─ background-light.svg
6+ └─ background-dark.svg
7 ├─ docs.yml
8 └─ fern.config.json

In docs.yml, you can set a single background image or specify different images for light and dark modes:

1background-image: ./images/background.svg

Specify a logo in docs.yml which gets displayed in the top left of your docs.

1logo: ./images/logo.png

Logo properties

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

height is optional and sets the logo’s height in pixels.

href is optional and 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.

docs.yml
1logo:
2 light: ./images/logo-light.png
3 dark: ./images/logo-dark.png
4 height: 60
5 href: https://example.com

Favicon image

Add a favicon image that displays in the browser tab. Supported file types are .png and .ico.

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

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
1typography:
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

Layout

There are several layout options you can configure in docs.yml. All of the layout properties are optional and give you more control over the presentation of your docs.

  • header-height: the height of the header in pixels; the default is 4rem (64px)

  • page-width: the maximum width of the page content, including the sidebar and content; the default is 88rem (1408px)

  • content-width: the maximum width of the markdown content; the default is 44rem (704px)

  • sidebar-width: the width of the sidebar in desktop mode; the default is 18rem (288px)

  • searchbar-placement: the placement of the search bar; the options are sidebar (default) or header

  • tabs-placement: the placement of the tabs; the options are sidebar (default) or header

  • content-alignment: the alignment of the markdown content; the options are center (default) and left

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