Customization

Fully customize your docs

Add custom CSS, global JavaScript, and UI components.

This page covers how to customize your docs with CSS, JavaScript, and custom components. However, you can customize many things directly in your docs.yml file, including colors, typography, navbar links, layout, analytics, and metadata. Try these built-in options first before adding custom code.

Custom CSS

You can add custom CSS to your docs to further customize the look and feel. The defined class names are applied across all MDX files.

1

Create styles.css

Add a styles.css file and include it in your fern/ project:

Add the styles.css file
$  fern/
>  ├─ openapi/
>  ├─ pages/
>  ├─ images/
>  ├─ styles.css
>  ├─ docs.yml
>  └─ fern.config.json
2

Edit docs.yml

In docs.yml, specify the path to the styles.css file:

docs.yml
1css: ./styles.css
3

Add multiple custom CSS files (optional)

You can specify any number of custom CSS files:

docs.yml
1css:
2  - ./css/header-styles.css
3  - ./css/footer-styles.css

For customizing the background, logo, font, and layout of your Docs via Fern’s built-in styling, check out the Global Configuration.

Common use cases

You can use custom CSS to hide specific Fern docs components that you don’t want to display.

styles.css
1.fern-layout-footer-toolbar { # Hides Fern feedback widget
2  display: none !important;
3}

You can target other Fern UI components using their CSS class names. Use your browser’s developer tools to inspect elements and find their class names.

You can use custom CSS to create brand-specific styling for tables, components, and other elements in your documentation.

styles.css
1.petstore-table {
2    background-color: white;
3    border: 1px solid #DEDEE1;
4    border-radius: 4px;
5}
6
7.dark .petstore-table { 
8    background-color: #1e1e1e;
9    border: 1px solid #2e2e2e;
10}
11
12.petstore-table thead {
13    position: sticky;
14    top: 0;
15}
16
17.petstore-table thead tr {
18    background-color: #edecee;
19    border: 1px solid #DEDEE1;
20    border-radius: 4px 4px 0px 0px;
21}
22
23.dark .petstore-table thead tr {
24    background-color: #2e2e2e;
25    border: 1px solid #2e2e2e;
26}
27
28.petstore-table th {
29    padding: 6px;
30}
31
32.petstore-table tbody td {
33    padding: 6px;
34}
35
36.petstore-table tbody tr:nth-child(odd) {
37    border: 1px solid #DEDEE1;
38}
39.petstore-table tbody tr:nth-child(even) {
40    border: 1px solid #DEDEE1;
41    background-color: #f7f6f8;
42}
43
44.dark .petstore-table tbody tr:nth-child(odd) {
45    border: 1px solid #2e2e2e;
46}
47
48.dark .petstore-table tbody tr:nth-child(even) {
49    border: 1px solid #2e2e2e;
50    background-color: #2e2e2e;
51}

Custom JavaScript

Customize the behavior of your Docs site by injecting custom JavaScript globally.Add a custom.js file and include it in your fern/ project:

Add the custom.js file
$  fern/
>  ├─ openapi/
>  ├─ pages/
>  ├─ images/
>  ├─ custom.js
>  ├─ docs.yml
>  └─ fern.config.json

In docs.yml, specify the path to the custom.js file:

docs.yml
1js: ./custom.js

You can also specify multiple custom JS files stored locally and remote:

docs.yml
1js:
2  - path/to/js/file.js
3  - path: path/to/another/js/file.js
4    strategy: beforeInteractive
5  - url: https://example.com/path/to/js/file.js

We use path for local sources and url for remote sources.

Strategy

Optionally, specify the strategy for each custom JavaScript file. Choose from beforeInteractive, afterInteractive (default), and lazyOnload.

docs.yml
1js:
2  - path: path/to/another/js/file.js
3    strategy: beforeInteractive

Common use cases

Custom components

Pro and Enterprise feature

This feature is available only for the Pro and Enterprise plans. To get started, reach out to support@buildwithfern.com.

You can use custom CSS and JS to replace Fern’s default UI components with your own. The header and footer are the most commonly replaced components. You can replace any component in the docs, including the sidebar, tabs, search bar, and more.

To implement your own components in Fern Docs, write JavaScript to render your custom components in the DOM. Build to CSS and JavaScript files that are stored in fern/ and referenced in docs.yml:

$  fern/
>  ├─ openapi/
>  ├─ pages/
>  ├─ images/
>  ├─ dist/
>    └─ output.css
>    └─ output.js
>  ├─ docs.yml
>  └─ fern.config.json

Example custom components

See this GitHub repo and its generated docs page for an example of how to replace the Fern header and footer with custom React components.

Example custom header

Custom header
1ReactDOM.render(
2  React.createElement(NavHeader),
3  document.getElementById('fern-header'),
4)
Custom footer
1ReactDOM.render(
2  React.createElement(NavFooter),
3  document.getElementById('fern-footer'),
4)

Important notes

  • ReactDOM.render() may need to be called multiple times to prevent it from unmounting (this side-effect will be removed in the future).
  • yarn build or npm build must generate files with deterministic names to be referenced in docs.yml. The above example uses a vite config to accomplish this.
  • For your hosted Docs site, you may need to update your CD steps to include building the react-app.
  • Custom components aren’t supported in local development, but are supported in preview links.

This approach is subject to change, with notice, as we make improvements to the plugin architecture.