Building Your Docs

Fully customize your docs

Add custom CSS, global JavaScript, and UI components.

Custom CSS & JS are available on the Business plan. Adding Custom Components is available on the Enterprise plan.

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.

Here’s an example of what you can do with custom CSS:

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}

Create styles.css

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

Add the styles.css file
1 fern/
2 ├─ openapi/
3 ├─ pages/
4 ├─ images/
5+ ├─ styles.css
6 ├─ docs.yml
7 └─ fern.config.json

Edit docs.yml

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

docs.yml
1css: ./styles.css

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 Customize Styling.

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 styles.css file
1 fern/
2 ├─ openapi/
3 ├─ pages/
4 ├─ images/
5+ ├─ custom.js
6 ├─ docs.yml
7 └─ 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

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

Custom Components

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:

1 fern/
2 ├─ openapi/
3 ├─ pages/
4 ├─ images/
5+ ├─ dist/
6+ └─ output.css
7+ └─ output.js
8 ├─ docs.yml
9 └─ 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.

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