# Fern Docs Overview
> Learn about key features of Fern's Docs
Fern Docs provides versatile documentation to support all your content needs, including popular formats like:
* **Landing Pages** - High-level introductions with navigation for different audiences
* **Guides** - Step-by-step tutorials, user guides, and recipes/cookbooks
* **API References** - Auto-generated docs with request/response examples and auto-updating SDK snippets
* **Changelogs** - Release notes for new features and fixes
## Key Features
Match your docs to your brand with customizable colors, fonts, and styles.
Auto-generate API docs from OpenAPI and AsyncAPI specs.
Version and manage docs with your Git provider using Markdown or MDX.
Test APIs directly in the docs with auto-populated credentials.
Example code auto-updates as your SDKs evolve.
Use pre-built or custom React components for a polished look.
# Docs Customer Showcase
Fern Docs is a tool for creating beautiful, customizable developer documentation. Achieve best-in-class docs with a modern and branded look and feel, powered by MDX and your API specification, and integrated seamlessly with CI/CD. Below are some companies building with Fern to elevate their developer experience.
***
##
Webflow
Auto-populated API key
Webflow uses Fern's API Explorer to auto-populate API keys using their custom authentication flow, making it easy for developers to authenticate once and then focus on developing.
Check out Webflow's API Explorer here:
View the Webflow API Explorer
***
##
Cohere
SSE
Landing page
Cohere uses Fern's out-of-the-box components to create a landing page that orients users and aids in developer experience. Their API Explorer further aids in that developer experience, allowing users to test out endpoints in their API, including server-sent events.
Check out Cohere's documentation here:
View Cohere's landing page
View the Cohere API Reference
***
##
Cartesia
WebSockets
Custom styling
Cartesia leverages Fern's custom styling capabilities to create modern and branded documentation. They pair these aesthetics with an API Explorer that supports WebSockets, allowing developers to test their Text-To-Speech streaming in real-time.
Check out Cartesia's documentation here:
View Cartesia's documentation overview
View the Cartesia API Reference
***
##
Vellum
SDK documentation
Vellum takes advantage of Fern's adaptable layout and styling capabilities to create custom documentation for their UI SDK, in addition to using Fern's auto-generated API reference for their client libraries (which are generated by Fern, as well).
Check out their references here:
View Vellum's SDK documentation
View Vellum's API reference
***
Ready to build best-in-class documentation? [Get started with Fern today](https://buildwithfern.com/learn/docs/getting-started/quickstart).
# Quickstart
> Start building beautiful documentation in under 5 minutes
With Fern, you can build beautiful developer documentation that matches your brand. Fern supports writing pages (written in Markdown) and generating API Reference documentation (from an OpenAPI Specification).
In this guide, we'll show you how to get started with Fern in under 5 minutes.
### Initialize your `fern` folder
All the configurations for your docs live in the `fern` folder. Inside, you'll
find a `docs.yml` file that contains all the settings for your documentation.
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).
```bash title="SSH"
git clone git@github.com:fern-api/docs-starter.git
```
```bash title="HTTPS"
git clone https://github.com/fern-api/docs-starter.git
```
Next, please update the template settings to use your organization.
Please edit the details `fern.config.json` and `docs.yml` with your organization
name.
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "0.x.x"
}
```
```yml {2}
instances:
- url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com
```
Finally, run `fern generate --docs` to generate your documentation.
If you prefer, you can use our CLI to create a new project. Install the CLI
by running
```bash
npm install -g fern-api
```
Then run
```bash
fern init --docs
```
You will see a new `fern` folder in your project with the following structure:
```bash
fern
├─ docs.yml
└─ fern.config.json
```
Finally, run `fern generate --docs` to generate your documentation.
### Update your docs
We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it
[here](https://buildwithfern.com/contact).
Add content with MDX files.
```markdown
---
title: "Page Title"
description: "Subtitle (optional)"
---
Hello world!
```
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required.
In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You
can reference the Markdown page within a section or as a standalone page.
```yml
navigation:
- page: "Hello World"
path: "pages/hello-world.mdx"
- section: Overview
content:
- page: QuickStart
path: pages/hello-world.mdx
```
Add an API Reference by adding an OpenAPI Specification to your project.
```bash
fern init --openapi /path/to/openapi.yml
```
This will create an `openapi.yml` file in your project. You can reference this file in your
`docs.yml` file by adding an api block.
```yml
navigation:
- api: "API Reference"
```
All of the branding for your docs can be configured in the `docs.yml` file.
For example, to set the logos, colors, and fonts for your docs, you can
add the following to your `docs.yml` file:
```yml
colors:
accentPrimary:
dark: "#f0c193"
light: "#af5f1b"
logo:
dark: ./docs/assets/logo-dark.svg
light: ./docs/assets/logo-light.svg
height: 40
href: https://buildwithfern.com/
favicon: ./docs/assets/favicon.png
```
### Publish to production
Fern supports hosting your docs website on a custom domain or on a
custom subpath (e.g. [https://domain.com/docs](https://domain.com/docs)).
Please reach out to the Fern team at [support@buildwithfern.com](mailto:support@buildwithfern.com) to configure this.
Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,
Google Tag Manager, etc.
Find out more on this [page](/learn/docs/integrations/overview).
Below are some examples of documentation websites that have been published using Fern:
} />
}
/>
} />
} />
} />
}
/>
}
/>
}
/>
# 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](https://github.com/fern-api/fern/blob/69e74d9c27dc031ec2e84e70b878c40e9e9678a5/packages/cli/configuration/fern/definition/docs.yml#L110-L153)
## Top-level properties
Every Fern documentation website needs a `docs.yml` file with the core configuration settings.
```yaml docs.yml
title: My Docs
logo:
href: mydomain.com
dark: path/to/logo.png
light: path/to/logo.png
favicon: path/to/favicon.ico
```
A string that is used as the tab bar title.
Learn more about the `logo` configuration [here](/learn/docs/getting-started/global-configuration#logo-configuration).
Relative filepath to the favicon.
Configure the `primaryAccent` and `background` colors. Learn more about the `colors` configuration
[here](/learn/docs/getting-started/global-configuration#colors-configuration).
An array of paths you want to configure to permanently redirect to another path. Learn more about the
`redirects` configuration [here](/learn/docs/getting-started/global-configuration#redirects-configuration).
Array of names and urls of links you want to include as a call to action. Learn more about the
`navbar-links` configuration [here](/learn/docs/getting-started/global-configuration#navbar-links-configuration).
Set a custom background image to be displayed behind every page. Learn more about the
`background-image` configuration [here](/learn/docs/getting-started/global-configuration#background-image-configuration).
Customize the fonts used in your documentation website. Learn more about the
`typography` configuration [here](/learn/docs/getting-started/global-configuration#typography-configuration).
Customize the layout of your documentation website. Learn more about the
`layout` configuration [here](/learn/docs/getting-started/global-configuration#layout-configuration).
Creates a landing page for your documentation website. Learn more about the
`landing-page` configuration [here](/learn/docs/getting-started/global-configuration#landing-page-configuration).
Sets the default language displayed by code snippets in the API Reference.
Options include: `typescript`, `python`, `java`, `go`, `ruby`, `csharp`, `curl`
## 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.
```yaml docs.yml
instances:
- url: plantstore.docs.buildwithfern.com
custom-domain: docs.plantstore.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: main
```
The URL where your Fern documentation is deployed. Must contain the suffix `docs.buildwithfern.com`
The custom domain where your documentation is hosted. Learn more about setting up a custom domain [here](/learn/docs/building-your-docs/custom-domain).
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](#github-configuration).
## Colors configuration
```yaml docs.yml
colors:
accent-primary:
light: "#418326"
dark: "#ADFF8C"
background:
light: "#ffffff"
dark: "#0d0e11"
```
The configured accent primary color for light and dark mode.
The configured background colors for light and dark mode.
The border color is used for the borders of cards and other elements.
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.
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.
The background color of cards and code blocks.
## Logo configuration
```yaml docs.yml
logo:
href: mydomain.com
dark: path/to/logo.png
light: path/to/logo.png
```
Where clicking on the logo links you to.
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.
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
```yaml docs.yml
redirects:
- source: "/old-path"
destination: "/new-path"
- source: "/old-folder/*"
destination: "/new-folder/*"
```
The path that you want to redirect from.
The path that you want to redirect to.
Toggle between **permanent** and **temporary** redirect (default `false`). When true, the status code is 308. When false the status code is 307.
## NavBar links configuration
```yaml docs.yml
navbar-links:
- type: minimal
text: Contact support
href: https://example.com/support
- type: filled
text: Login
href: https://example.com/login
rounded: false
```
One of `outlined`, `minimal`, or `filled`. This value controls the styling of the button.
The url once you click on the button. Example: [https://buildwithfern.com/contact](https://buildwithfern.com/contact)
Text inside the button.
When `true`, the border radius of the button will be fully rounded.
The [Font Awesome icon](https://fontawesome.com/icons) 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.
The [Font Awesome icon](https://fontawesome.com/icons) 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
```yaml docs.yml
background-image:
light: ./path/to/bg-light.svg
dark: ./path/to/bg-dark.svg
```
Relative filepath to the light-mode background image.
Relative filepath to the dark-mode background image.
## Typography configuration
```yaml docs.yml {2-16}
typography:
bodyFont:
name: Inter-Regular
path: ./fonts/Inter-Regular.woff2
headingsFont:
name: Inter-Bold
paths:
- path: ./fonts/Inter-Bold.woff2
weight: "400"
style: normal
- path: ./fonts/Inter-Bold.woff2
weight: 500 900 # <-- indicates a range of weights
style: normal
codeFont:
name: Roboto-Mono-Regular
path: ./fonts/Roboto-Mono-Regular.woff2
```
Customize page and section titles. If not supplied, defaults to the body font.
Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).
Customize paragraph text and other body text.
Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).
Customize code blocks and inline code snippets.
Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).
### Font configuration
```yaml title="Basic" {3-4}
typography:
bodyFont:
name: Inter-Regular
path: ./fonts/Inter-Regular.woff2
```
```yaml title="Variable Font" {3-10}
typography:
bodyFont:
name: Inter-Regular
paths:
- path: ./fonts/Inter-Bold.woff2
weight: "400"
style: normal
- path: ./fonts/Inter-Bold.woff2
weight: 500 900 # <-- indicates a range of weights
style: normal
```
The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS.
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`.
A list of font files for particular weights. Each element in the list includes a `path`, `weight`, and `style` property.
## Layout configuration
```yaml docs.yml
layout:
header-height: 70px
page-width: 1344px
content-width: 672px
sidebar-width: 336px
searchbar-placement: header
tabs-placement: header
content-alignment: left
```
Sets the height of the header. Defaults to `4rem` (`64px`). Valid options are `{number}rem` or `{number}px`.
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`.
Sets the maximum width of the Markdown article content. Defaults to `44rem` (`704px`).
Valid options are `{number}rem` or `{number}px`.
Sets the width of the sidebar in desktop mode. Defaults to `18rem` (`288px`). Valid options are `{number}rem` or `{number}px`.
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.
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.
Set the alignment of the Markdown content. Can be one of `center` or `left`.
Defaults to `center`.
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
```yaml docs.yml
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: main
```
Be sure the repository is set to **public** visibility.
The owner of the GitHub repository where you host your documentation.
The name of the GitHub repository where you host your documentation.
The branch of the repository you would like the GitHub editor to open a PR to. Default is `main`.
## Landing page configuration
```yaml docs.yml
landing-page:
page: Page Title
path: path/to/landing-page.mdx
```
The name of the landing page.
Relative filepath to the desired landing page Markdown file.
See [VapiAI's landing page live](https://docs.vapi.ai/welcome) and the associated [Markdown file](https://github.com/VapiAI/docs/blob/main/fern/welcome.mdx?plain=1).
# Project Structure
> An overview of the file and folder structure of a Fern Docs project
This page provides an overview of the file and folder structure of a Fern Docs project. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs.
## Top-level folders
```bash
fern
├─ pages
├─ assets
├─ docs.yml
├─ openapi
└─ fern.config.json
```
A Fern Docs project has the following top-level folders:
* `pages`: Contains the Markdown (MDX) files that make up your documentation.
* `assets`: Contains any images or videos used in your documentation.
* `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation.
* `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation).
* `fern.config.json`: The configuration file specifying your organization name and CLI version.
## Pages folder
The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation.
```bash
pages
├─ introduction
│ ├─ quickstart.mdx
│ ├─ project-structure.mdx
│ └─ showcase.mdx
├─ building-your-docs
│ ├─ navigation
│ ├─ sections.mdx
│ ├─ tabs.mdx
│ └─ versions.mdx
└─ └─ configuration.mdx
```
The `pages` folder is organized into subfolders based on the sections of your documentation. Each subfolder contains the MDX files for the pages in that section.
## Assets folder
The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths.
```bash
assets
├─ favicon.ico
├─ product-screenshot.svg
├─ demo-video.mp4
├─ logo-dark-mode.png
└─ logo-light-mode.png
```
## `docs.yml`
The `docs.yml` file is the configuration file that defines the navigation, theme, and hosting details of your documentation. You can customize the appearance and behavior of your documentation by editing this file.
```yml
instances:
- url: fern.docs.buildwithfern.com/learn
custom-domain: buildwithfern.com/learn
navigation:
- section: Introduction
layout:
- page: QuickStart
path: pages/introduction/quickstart.mdx
- page: Project Structure
path: pages/introduction/project-structure.mdx
- page: Showcase
path: pages/introduction/showcase.mdx
navbar-links:
- type: filled
text: Book a demo
url: https://buildwithfern.com/contact
logo:
light: ./images/logo-primary.svg
dark: ./images/logo-white.svg
colors:
accentPrimary:
dark: "#ADFF8C"
light: "#209d63"
favicon: ./images/favicon.ico
title: Fern's Documentation
```
## API Definitions
The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder.
```bash
openapi
└─ openapi.yaml # OR openapi.json
```
To see what this looks like in practice, check out [Vellum's Fern configuration](https://github.com/vellum-ai/vellum-client-generator/tree/main/fern/openapi).
The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder.
```bash
definition
├─ pets.yaml
├─ owners.yaml
├─ stores.yaml
└─ api.yaml
```
To see what this looks like in practice, check out [Pier's Fern configuration](https://github.com/pierdeveloper/pier-fern-def/tree/main/fern/definition).
If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition. For example:
```bash
apis
├─ admin
│ └─ openapi.json
├─ user
│ └─ openapi.yaml
```
To see what this looks like in practice, check out [OctoAI's Fern configuration](https://github.com/octoml/fern-config/tree/main/fern/apis).
## `fern.config.json`
The `fern.config.json` file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization's details.
```json
{
"organization": "my-organization",
"version": "0.24.0"
}
```
# Preview changes locally
> View and share updates to your documentation
Fern offers two ways to preview changes to your documentation: a [local development environment](#local-development) and [unique preview links](#generate-a-preview-link).
## Local development
Fern allows you to view changes to your documentation in a locally-hosted environment.
**Prerequisite**
: Please install Node.js (version 18 or higher) before proceeding.
Follow these steps to install and run the Fern CLI:
**Step 1**: Install the Fern CLI:
```bash npm
npm i -g fern-api
```
```bash yarn
yarn global add fern-api
```
**Step 2**: Navigate to the docs directory (where the `fern` folder is located) and execute the following command:
```bash
fern docs dev
```
A local preview of your documentation will be available at `http://localhost:3000`. The functionality is available offline if you have run local development mode online at least once.
Some features (e.g. search) are disabled in the local development environment.
### Custom ports
By default, Fern uses port 3000. You can customize the port Fern runs on by using the `--port` flag. For example, to run Fern on port 3002,
use this command:
```bash
fern docs dev --port 3333
```
If you attempt to run Fern on a port that's already in use, it will use the next available port:
## Generate a preview link
Fern allows you to generate a shareable preview link displaying the current state of your docs. Each preview link is appended with a UUID and is not indexed. Currently, these links do not expire (this behavior is subject to change in the future).
**Usage**:
```bash
fern generate --docs --preview
```
**Example**:
```bash
fern generate --docs --preview
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
[docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com
┌─
│ ✓ docs.example.com
└─
```
# Publishing your docs
When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI.
## Usage
```bash
fern generate --docs
```
### Example
```bash
fern generate --docs
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
[docs]: ✓ All checks passed
[docs]: Published docs to https://plantstore.docs.buildwithfern.com
┌─
│ ✓ https://plantstore.docs.buildwithfern.com
└─
```
### Usage in GitHub Actions
To automate the publishing process, you can use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token).
```yaml .github/workflows/publish-docs.yml
name: Publish Docs
on:
push:
branches:
- main
jobs:
run:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Publish Docs
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: fern generate --docs
```
## Hosting
When you publish your docs, Fern takes care of hosting them for you. To publish your docs to a custom domain, check out our docs [here](/learn/docs/building-your-docs/custom-domain).
### Self-hosting your docs
This feature is available on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more.
If you need access to your docs offline or would like to host your docs on your own server, Fern offers that option as well. Self-hosted docs have limited access to certain features (including search).
# January 21, 2025
## Improvements to the Accordion Component
The accordion component has been upgraded so that you can now use your in-browser `cmd+f` search to look for text that is otherwise hidden.
* Improved accessibility for all of our customers who are leveraging the `` component
* Improved SEO indexing of content (more html is now generated on the server-side instead of client-side)
Try searching for **burst** on this page: [https://dev.hume.ai/docs/expression-measurement/faq](https://dev.hume.ai/docs/expression-measurement/faq)
## Support for embedding local assets
We've added support for embedding local assets in your docs. This is useful for displaying PDFs, images, videos, and other assets into your docs.
To embed an asset, you can use the `embed` tag.
```mdx
```
Read more [here](https://buildwithfern.com/learn/docs/content/write-markdown#embedding-local-assets)
# January 14, 2025
## Support for /llms.txt
API Docs should be for LLMs and Agents too, not just people!
We're excited to announce compatibility with the `/llms.txt` [emerging standard](https://llmstxt.org/), making your documentation accessible and optimized for AI developer tools such as Cursor, Github Copilot, ChatGPT, Perplexity, and Anthropic's Claude.
Both `/llms.txt` and `/llms-full.txt` are designed to be token-efficient, ensuring faster processing and cost-effective LLM interactions without sacrificing valuable info.
If you use Fern Docs, this feature is auto-enabled like /robots.txt and /sitemap.xml. [Learn more](https://buildwithfern.com/learn/docs/developer-tools/llms-txt)
![LLMs.txt Splash Image](file:5f53d5dd-1331-4a43-bd7f-72cd79ade485)
Check out ElevenLabs:
*loads in \< 1 sec*
*loads in 5+ sec*
# December 30, 2024
## Audio Streaming in API Explorer
Added support for streaming audio directly within the API Explorer. This feature enables testing audio endpoints without leaving the documentation.
Check it out live in ElevenLabs' [API Explorer](https://elevenlabs.io/docs/api-reference/text-to-speech/convert?playground=/docs/api-reference/text-to-speech/convert-as-stream) to let users test text-to-speech endpoints and hear the results instantly.
## Form Data Optimization
Enhanced handling of URL parameters and form data in edge functions. Documentation playground now handles complex data structures more efficiently.
```typescript
const formConfig = {
encoding: 'application/x-www-form-urlencoded',
arrayFormat: 'brackets',
allowNullables: true,
sanitize: true,
maxDepth: 5
}
```
# November 27, 2024
## Auto-Populate Credentials in API Explorer
Save developers the hassle of finding and copying their API key. When authenticated, their API credentials will be automatically filled into the API Playground. This way, they can make their first API call even faster.
![API Explorer Splash Image](file:571c6536-79e9-4aa5-8e40-8a57d42d3315)
Check it out live in [Webflow's API Explorer](https://developers.webflow.com/data/reference/sites/list?playground=/data/reference/sites/list).
## Card Component System
Enhanced documentation card components for better visual organization. Information can now be presented in a more structured and appealing way.
```typescript
interface CardProps {
title: string;
description: string;
icon?: IconName;
variant?: 'default' | 'bordered' | 'filled';
actions?: CardAction[];
}
interface CardAction {
label: string;
href?: string;
onClick?: () => void;
}
```
# October 31, 2024
## JWT API Key Integration
Implemented automatic API key extraction from JWT tokens in the documentation playground. Users can now test authenticated endpoints more easily with automatic credential handling.
## Query Parameter Enhancement
Improved handling of query parameters in documentation middleware. Complex query parameters are now properly handled and displayed in the documentation.
# September 24, 2024
# September 2024
## Environment Testing Interface
Created an editable playground environment system for testing API endpoints. Users can now switch between different API environments seamlessly within the documentation.
```yaml openapi.yml
servers:
- url: https://api.example.com
x-fern-server-name: Production
- url: https://sandbox.example.com
x-fern-server-name: Sandbox
```
# August 20, 2024
# August 2024
## Anchor Link System
Redesigned anchor link handling for improved navigation within documentation pages. Links now account for fixed headers and maintain proper scroll position when opened.
## WCAG Contrast Improvements
Enhanced color contrast throughout the documentation platform for better accessibility. All text and interactive elements now meet WCAG AA standards by default and warnings are shown for any elements that do not meet WCAG AA standards.
## API Page Center Updates
Improved center element positioning and updates for API documentation pages. Content now flows more naturally and maintains position during navigation.
## Streaming Toggle Enhancement
Improved visibility and behavior of streaming response toggles in API playground. Users can now better control and monitor streaming responses.
# July 30, 2024
# July 2024
## Meta Image System
Implemented comprehensive meta image support for better social sharing. Documentation pages now display properly when shared on social media platforms.
```yaml
og:image: /assets/og-image.png
og:type: documentation
twitter:card: summary_large_image
twitter:image: /assets/twitter-card.png
```
# June 25, 2024
# June 2024
## RSS Feed Integration
Added support for RSS feeds to keep users updated on documentation changes. Teams can now offer automated notifications for their documentation.
## JSON-LD Enhancement
Implemented structured data support through JSON-LD for improved SEO. Documentation pages now provide richer information to search engines and social platforms.
```json
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "API Authentication Guide",
"datePublished": "2024-06-15",
"technicalAudience": "Software Developers"
}
```
## Image Zoom Controls
Added configurable image zoom functionality with custom triggers and behaviors. Users can now better examine diagrams and technical illustrations in documentation.
```mdx page.mdx
---
no-image-zoom: true
---
```
## Syntax Extension Support
Added support for additional syntax highlighting languages including BAML and Jinja. Documentation can now properly display a wider range of code examples.
```html
Available Products
{% if products %}
{% for product in products %}
{{ product.name }}
${{ product.price }}
{{ product.description }}
{% if product.in_stock %}
Status: In Stock
{% else %}
Status: Out of Stock
{% endif %}
{% endfor %}
{% else %}
No products are available at the moment.
{% endif %}
```
# May 22, 2024
## Advanced Redirects
Implemented a powerful redirects system supporting pattern matching and parameter preservation. Teams can now manage documentation URL structure while maintaining backwards compatibility.
```yaml
redirects:
- source: /v1/api/*
destination: /v2/api/:splat
permanent: true
- source: /guides/:name
destination: /tutorials/:name
```
## API Authorization Handling
Enhanced API authorization handling in the documentation platform. Developers can now test authenticated endpoints more easily with improved token management.
# April 20, 2024
## Sidebar Navigation Enhancement
Improved sidebar padding and visual hierarchy with refined spacing and typography. The documentation navigation now provides clearer visual structure and better readability.
## Base Path Configuration
Added flexible base path configuration for documentation routing. Organizations can now host documentation under custom paths while maintaining proper navigation.
```yaml docs.yml
instances:
- url: your-site.docs.buildwithfern.com
custom-domain: your-site.com/docs
```
# March 24, 2024
# March 2024
## Virtualized Syntax Highlighting
Implemented performance-optimized code rendering that handles large code blocks efficiently without impacting page performance. Long code samples now load instantly and scroll smoothly.
## Mobile Search Experience
Redesigned the mobile search interface with a sticky search bar and improved results display. Users can now easily search documentation on mobile devices with a native-feeling interface.
## Scrollbar Refinement
Enhanced scrollbar design and behavior across all documentation sections for a more polished look and feel. Scrollbars now adapt to both light and dark themes while maintaining usability.
# February 22, 2024
## WebSocket Support in API Playground
Added real-time WebSocket testing capabilities to the API playground, enabling developers to test streaming and real-time endpoints directly in the documentation. WebSocket connections can now be established, tested, and debugged without leaving the docs.
## Enhanced Code Highlighting
Implemented a new code highlighting system using Shiki for improved syntax highlighting accuracy and performance. The system now supports more languages and provides better dark mode compatibility.
## Feedback System
Introduced a new feedback collection system using Radix UI components for improved accessibility. Users can now provide structured feedback about documentation quality and usefulness directly within the interface.
## Layout Configuration System
Implemented a flexible layout configuration system that allows for custom header, footer, and sidebar arrangements. Documentation can now be customized to match your brand and preferences.
```yaml
layout:
page-width: full
tabs-placement: header
searchbar-placement: header
```
## Custom Styling Support
Added support for custom CSS and scripts, enabling deep customization of documentation appearance and behavior. Organizations can now apply their branding consistently across their documentation.
```yaml docs.yml
css: ./assets/styles.css
```
```css styles.css
/* Custom styles */
.custom-class {
background-color: #f0f0f0;
}
```
# January 24, 2024
## API Playground Launch
Enable interactive API testing directly in the documentation.
* Added full API request testing capability
* Improved error handling and status code display
* Added support for recursive property rendering
## Enhanced Dark Mode
Multiple improvements to dark mode readability for syntax highlighting, dropdowns, and search results.
```css
/* Dark mode improvements */
[data-theme='dark'] {
--syntax-bg: #1a1a1a;
--dropdown-bg: #2d2d2d;
--search-highlight: #ffd700;
}
```
## Mobile-Friendly Navigation
Comprehensive updates to mobile navigation experience with collapsible and scrolling.
## Search Enhancements
Multiple improvements to the search experience.
* Default and configurable keyboard shortcuts (`Cmd+A`, `/`) for search
* Improved search box sizing
* Added auto-focus functionality
## Performance Optimization
Several performance improvements across the platform.
* Moved FontAwesome to CDN
* Improved search dialog loading
* Optimized static props loading
* Added polyfill DOM parser for server-side TOC rendering
# Configure your site navigation
> Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.
## Use `docs.yml`
Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site.
```yaml
navigation:
- section: Home
contents:
- page: Introduction
path: ./intro.mdx
- page: Authentication
path: ./auth.mdx
- api: API Reference
navbar-links:
- type: secondary
text: Contact support
url: https://example.com/support
- type: primary
text: Login
url: https://example.com/login
```
## Sections, contents, and pages
The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each `section` has a name and a list of `contents`. The sections appear in the left-side nav bar in the order that they are listed in `docs.yml`.
In `contents`, list your pages with names and corresponding file paths. The supported file types for pages are `.md` or `.mdx`.
A basic navigation configuration with two sections is shown below. The first section is called `Introduction` and contains a single page called `My Page`. The second section is called **API Reference**. This is a special type of section that's automatically generated by Fern, and you do not need to add any pages to it by hand. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page.
```yaml Example navigation config
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- api: API Reference
```
If you want to add another page to an existing section, create an `.md` or `.mdx` file. Then in `docs.yml`, create a new `page` in the `contents` list for that section, providing the path to the `.md` or `.mdx` file you created. Example:
```yaml Example navigation config
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- page: Another Page
path: ./pages/another-page.mdx
- api: API Reference
```
To add another section, add another `section` to the `navigation`. Example:
```yaml Example navigation config with additional section
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- api: API Reference
- section: Help Center
contents:
- page: Contact Us
path: contact-us.mdx
```
### Hiding content
To hide a page or an entire section of your docs, add `hidden: true`. A hidden page or section will still be discoverable using the exact URL, but it will be excluded from search and will not be indexed.
```yaml Example navigation config with additional section {7, 10}
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- page: Hidden Page
hidden: true
path: ./pages/my-hidden-page.mdx
- section: Hidden Sections
hidden: true
contents:
- page: Another Hidden Page
path: ./pages/also-hidden.mdx
```
## Section overviews
To add an overview page to a section, add a `path` property to the section.
```yaml Example section with an overview {7}
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- section: Guides
path: ./pages/guide-overview.mdx
contents:
- page: Simple Guide
path: ./pages/guides/simple.mdx
- page: Complex Guide
path: ./pages/guides/complex.mdx
```
## Nested sections
If you'd like a section to toggle into more sections and pages, you can nest sections within sections. Here's an example:
```yaml Example navigation config with nested sections
navigation:
- tab: guides
layout:
- section: Learn
contents:
- section: Key Concepts
contents:
- page: Embeddings
path: ./docs/pages/embeddings.mdx
- page: Prompt Engineering
path: ./docs/pages/prompts.mdx
- section: Generation
contents:
- page: Command Nightly
path: ./docs/pages/command.mdx
- page: Likelihood
path: ./docs/pages/likelihood.mdx
```
![Result of above docs.yml example](https://fern-image-hosting.s3.amazonaws.com/fern/nested-sections.png)
## Sidebar icons
For icons to appear next to sections and pages, add the `icon` key. The value should be a valid [Font Awesome icon](https://fontawesome.com/icons) name. Pro and Brand Icons from Font Awesome are supported.
```yaml Example navigation config with icons
navigation:
- section: Home
icon: fa-regular fa-home
contents:
- page: My Page
icon: fa-regular fa-file
path: ./pages/my-page.mdx
- api: API Reference
icon: fa-regular fa-puzzle
```
## Links
You can add a link to an external page within your sidebar navigation with the following configuration:
```yaml title="docs.yml"
navigation:
- section: Home
contents:
- page: Introduction
path: ./intro.mdx
- link: Our YouTube Channel
href: https://www.youtube.com/
```
## Tabs
Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons are supported.
```yaml
tabs:
api:
display-name: API Reference
icon: puzzle
help:
display-name: Help Center
icon: home
github:
display-name: GitHub
icon: brands github
href: https://github.com/fern-api/fern
navigation:
- tab: api
layout:
- section: Introduction
contents:
- page: My Page
path: my-page.mdx
- api: API Reference
- tab: help
layout:
- section: Help Center
contents:
- page: Contact Us
path: contact-us.mdx
- tab: github
```
Here's an example of what the Tabs implementation looks like:
![Screenshot showing two vertically stacked tabs labeled API Reference and Help
Center](https://fern-image-hosting.s3.amazonaws.com/fern/tabs.png)
## Versions
If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning).
# Versioning
> Allow users to navigate between different versions of your docs.
![A dropdown of the available versions](file:cac02330-120e-44e3-ab71-0dd52a92b1e7)
Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well.
**To add versions to your docs:**
### Define your versions
Create a `versions` folder inside of your `fern` folder. TO specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable.
```bash
fern/
├─ fern.config.json
├─ generators.yml
├─ docs.yml
├─ pages/
├─ ...
└─ versions/
├─ v2-1/pages/...
├─ v2-1.yml
├─ v2-2/pages/...
└─ v2-2.yml
```
```yaml
navigation:
- section: Introduction
contents:
- page: My Page
path: ./v2-1/pages/my-page.mdx # relative path to the file
- page: Shared Resource
path: ../shared-pages/shared-resource.mdx
- api: API Reference
```
```yaml
tabs:
api:
title: API Reference
icon: puzzle
help:
title: Help Center
icon: home
navigation:
- tab: api
contents:
- section: Introduction
contents:
- page: My Page
path: ./v2-2/pages/my-page.mdx # relative path to the file
- page: Shared Resource
path: ../shared-pages/shared-resource.mdx
- api: API Reference
- tab: help
contents:
- section: Help Center
contents:
- page: Contact Us
path: contact-us.mdx
```
### Add your version configuration
To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`.
```bash
fern/
├─ fern.config.json
├─ generators.yml
├─ docs.yml
└─ versions/
├─ ...
├─ v2-1.yml
└─ v2-2.yml
```
```yaml
versions:
- display-name: v2.2 # shown in the dropdown
path: ./versions/v2-2.yml # relative path to the version file
- display-name: v2.1
path: ./versions/v2-1.yml
```
### Remove extra `navigation` from `docs.yml`
If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files.
# Add an announcement banner to your docs
> Prominently highlight new features, updates, or important information
An announcement banner is a great way to draw attention to new features and product launches. When configured, the announcement bar appears at the top of your docs site. After the user dismisses the bar, it will reappear the next time you update the announcement.
```yaml docs.yml
announcement:
message: "🚀 New feature: Announcements are available! (Learn more) 🚀"
```
Markdown and HTML is supported in the announcement message. You can include links, images, and other formatting. [Custom css](/learn/docs/building-your-docs/custom-css-global-js#custom-css) can be used to customize the style of the announcement.
# Configure links and redirects for your site
> Set up the navigation for your documentation site built with Fern Docs using the docs.yml file
## Redirects
The `redirects` object allows you to redirect traffic from one path to another. You can also use [`regex`](https://www.npmjs.com/package/path-to-regexp) within redirects.
```yml
redirects:
- source: "/old-path"
destination: "/new-path"
- source: "/incorrect/path"
destination: "/correct/path"
- source: "/old-folder/:slug" # <- using regex
destination: "/new-folder/:slug"
```
By default, the redirects implement temporary (302) redirects. If you would like to implement permanent (301) redirects, you can set `permanent: true`.
```yml
redirects:
- source: "/old-subdomain"
destination: "/new-subdomain"
permanent: true
```
If your docs are hosted on a subpath (like `buildwithfern.com/learn`), be sure to include the subpath in the redirect.
## Links
You can add a link to an external page within your sidebar navigation with the following configuration:
```yaml title="docs.yml"
navigation:
- section: Home
contents:
- page: Introduction
path: ./intro.mdx
- link: Our YouTube Channel
href: https://www.youtube.com/
```
# Customizing slugs within your site
By default, Fern generates the slug of a page based on the navigation structure in the `docs.yml` file.
```yaml docs.yml {5, 7}
instances:
- url: plantstore.docs.buildwithfern.com
navigation:
- section: Get Started
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/get-started/welcome`.
```yaml docs.yml {5, 13, 15}
instances:
- url: plantstore.docs.buildwithfern.com
tabs:
docs:
display-name: Docs
reference:
display-name: API Reference
navigation:
- tab: docs
layout:
- section: Get Started
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/docs/get-started/welcome`.
### Renaming slugs
#### Modify a page or section slug
To modify the slug used for a page or section, you can set the `slug` within the `navigation` object.
```yaml {3, 6}
navigation:
- section: Get Started
slug: start
contents:
- page: Welcome
slug: intro
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/start/intro`.
#### Modify a tab slug
To modify the slug used for a tab, you can set the `slug` within the `tabs` object.
```yaml {4}
tabs:
docs:
display-name: Docs
slug: guides
reference:
display-name: API Reference
navigation:
- tab: docs
layout:
- section: Get Started
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/guides/get-started/welcome`.
#### Override a page's slug
You can set the exact slug of a page within its frontmatter. [You can read more about the frontmatter configuration here](/learn/docs/content/frontmatter#slug).
```yaml title="docs.yml"
navigation:
- section: Get Started
slug: start
contents:
- page: Quick Start
path: ./docs/pages/quick-start.mdx
```
You can set the slug in the frontmatter of `./docs/pages/quick-start.mdx` to `start-up`:
```markdown title="quick-start.mdx" {2}
---
slug: start-up
---
```
The page then becomes available at `plantstore.docs.buildwithfern.com/start-up`.
#### Renaming slugs for subheadings
By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URl.
```yaml docs.yml
navigation:
- section: Get Started
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
```markdown welcome.mdx
...
## Frequently Asked Questions
...
```
The link to this section will be available at `plantstore.docs.buildwithfern.com/get-started/welcome#frequently-asked-questions`.
To rename the slug of the subheading, add the desired slug
```markdown welcome.mdx
## Frequently Asked Questions [#faqs]
```
The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`.
### Skipping slugs
To ignore a tab or section when generating the slug, simply indicate `skip-slug: true`.
```yaml docs.yml {6}
instances:
- url: plantstore.docs.buildwithfern.com
navigation:
- section: Get Started
skip-slug: true
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.
```yaml docs.yml {7, 15}
instances:
- url: plantstore.docs.buildwithfern.com
tabs:
docs:
display-name: Docs
skip-slug: true
reference:
display-name: API Reference
navigation:
- tab: docs
layout:
- section: Get Started
skip-slug: true
contents:
- page: Welcome
path: ./docs/pages/welcome.mdx
```
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.
# Hiding content in your site
If you would like to *hide* a section or a page, you can add `hidden: true` to its configuration. Hidden sections and pages are accessible by URL only.
```yaml title="docs.yml"
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- page: Hide and Seek
hidden: true
path: ./pages/hide-and-seek.mdx
- api: API Reference
```
```yaml title="docs.yml"
navigation:
- section: Introduction
contents:
- page: My Page
path: ./pages/my-page.mdx
- api: API Reference
- section: Hidden Section
hidden: true
contents:
- page: Hide and Seek
path: ./pages/hide-and-seek.mdx
```
# Fully customize your docs
> Add brand-specific styling, user interactions. and components to make your docs your own.
Custom CSS & JS are available on the Basic plan.
Adding Custom Components is available on the Pro 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:
```css maxLines=10
.petstore-table {
background-color: white;
border: 1px solid #DEDEE1;
border-radius: 4px;
}
.dark .petstore-table {
background-color: #1e1e1e;
border: 1px solid #2e2e2e;
}
.petstore-table thead {
position: sticky;
top: 0;
}
.petstore-table thead tr {
background-color: #edecee;
border: 1px solid #DEDEE1;
border-radius: 4px 4px 0px 0px;
}
.dark .petstore-table thead tr {
background-color: #2e2e2e;
border: 1px solid #2e2e2e;
}
.petstore-table th {
padding: 6px;
}
.petstore-table tbody td {
padding: 6px;
}
.petstore-table tbody tr:nth-child(odd) {
border: 1px solid #DEDEE1;
}
.petstore-table tbody tr:nth-child(even) {
border: 1px solid #DEDEE1;
background-color: #f7f6f8;
}
.dark .petstore-table tbody tr:nth-child(odd) {
border: 1px solid #2e2e2e;
}
.dark .petstore-table tbody tr:nth-child(even) {
border: 1px solid #2e2e2e;
background-color: #2e2e2e;
}
```
### Create `styles.css`
Add a `styles.css` file and include it in your `fern/` project:
```bash {5}
fern/
├─ openapi/
├─ pages/
├─ images/
├─ styles.css
├─ docs.yml
└─ fern.config.json
```
### Edit `docs.yml`
In `docs.yml`, specify the path to the `styles.css` file:
```yaml
css: ./styles.css
```
### Add multiple custom CSS files (optional)
You can specify any number of custom CSS files:
```yaml
css:
- ./css/header-styles.css
- ./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](/learn/docs/getting-started/global-configuration).
## 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:
```bash {5}
fern/
├─ openapi/
├─ pages/
├─ images/
├─ custom.js
├─ docs.yml
└─ fern.config.json
```
In `docs.yml`, specify the path to the `custom.js` file:
```yaml
js: ./custom.js
```
You can also specify multiple custom JS files stored locally and remote:
```yaml
js:
- path/to/js/file.js
- path: path/to/another/js/file.js
strategy: beforeInteractive
- 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`.
```yaml
js:
- path: path/to/another/js/file.js
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`:
```bash {5-7}
fern/
├─ openapi/
├─ pages/
├─ images/
├─ dist/
└─ output.css
└─ output.js
├─ docs.yml
└─ fern.config.json
```
```yaml
css: ./dist/output.css
js: ./dist/output.js
```
### Example custom components
See this [GitHub repo](https://github.com/fern-api/docs-custom-js-example)
and its [generated docs page](https://custom-js-example.docs.buildwithfern.com/get-started/welcome)
for an example of how to replace the Fern `header` and `footer` with custom React components.
#### Example custom header
```JavaScript
ReactDOM.render(
React.createElement(NavHeader),
document.getElementById('fern-header'),
)
```
#### Example custom footer
```JavaScript
ReactDOM.render(
React.createElement(NavFooter),
document.getElementById('fern-footer'),
)
```
### 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](https://github.com/fern-api/docs-custom-js-example/blob/main/custom-app/vite.config.ts) to accomplish this.
* For your hosted Docs site, you may need to update your CD steps to include building the react-app.
* Custom components are not supported in local development. They are supported in preview links.
This approach is subject to change, with notice, as we make improvements to the plugin architecture.
# Pull request previews
> Fern's PR previews feature lets you preview changes to your docs from pull requests before merging to the live docs site. Use manually or in GitHub Actions.
`PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. This is useful for reviewing documentation changes before publishing them to your live documentation site. Use manually or in GitHub Actions.
## Usage
```bash
fern generate --docs --preview
```
## Example
```bash
fern generate --docs --preview
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.
[docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com
┌─
│ ✓ docs.example.com
└─
```
## Usage in GitHub Actions
The following is a GitHub Action workflow that generates a preview URL for every pull request. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token).
```yaml
name: Preview Docs
on:
pull_request
jobs:
run:
runs-on: ubuntu-latest
permissions: write-all
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Generate preview URL
id: generate-docs
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: |
OUTPUT=$(fern generate --docs --preview 2>&1) || true
echo "$OUTPUT"
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
echo "Preview URL: $URL"
echo "🌿 Preview your docs: $URL" > preview_url.txt
- name: Comment URL in PR
uses: thollander/actions-comment-pull-request@v2.4.3
with:
filePath: preview_url.txt
```
Fern's PR previews GitHub Action requires a Fern token to run. Depending on your repository's permissions, you may need to use the following workflow to allow PR previews from forks to access this token.
```yaml .github/workflows/preview-docs.yml
name: preview-docs
on:
pull_request_target:
branches:
- main
jobs:
run:
runs-on: ubuntu-latest
permissions:
pull-requests: write # Only for commenting
contents: read # For checking out code
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install Fern
run: npm install -g fern-api
- name: Checkout PR
if: github.event_name == 'pull_request_target'
run: |
git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }}
git checkout pr-${{ github.event.pull_request.number }}
- name: Generate preview URL
id: generate-docs
env:
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
run: |
OUTPUT=$(fern generate --docs --preview 2>&1) || true
echo "$OUTPUT"
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
echo "Preview URL: $URL"
echo "🌿 Preview your docs: $URL" > preview_url.txt
- name: Comment URL in PR
uses: thollander/actions-comment-pull-request@v2.4.3
with:
filePath: preview_url.txt
```
## Link expiration
Preview links do not expire. However, the time to live (TTL) is subject to change in the future.
# Bring your custom domain
> Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath.
Bring Fern Docs to your custom domain.
You can use:
* A subdomain on your custom domain, such as `docs.example.com`
* A subpath on your custom domain, such as `example.com/docs`
This feature is available on the Basic plan and above.
[Contact us](https://buildwithfern.com/contact)
to get set up.
To host your documentation on a subdomain, i.e. `docs.mydomain.com`, you need to create a CNAME record in your DNS settings.
### Update the domain in `docs.yml`
```yaml
instances:
- url: example.docs.buildwithfern.com
custom-domain: docs.mydomain.com
```
Merge your changes into `main`. [Here's an example](https://github.com/octoml/fern-config/blob/389b67679953856ba0716537981a6d749635556f/fern/docs.yml#L1-L3).
### Create a CNAME record
1. Log in to your domain registrar's dashboard.
2. Navigate to the DNS settings for your domain.
3. Add a new CNAME record with the following details:
* **Type**: `CNAME`
* **Name**: `docs` (or any subdomain you want to use)
* **Value**: `cname.vercel-dns.com.`
### Reach out to us
Once you've completed the steps above, reach out via your dedicated Slack channel or [email](mailto:support@buildwithfern.com).
You may need to create a TXT record to verify your domain. If you do, we'll provide you with the record to add.
### Verify the setup
Once we've completed the setup on our end, you should be able to access your documentation at `docs.mydomain.com`. SSL will be automatically provisioned for your domain, but it may take a few minutes to propagate globally.
It's helpful to check that you can access your new docs site from a mobile device or incognito browser.
To host your documentation on a subpath, i.e. `mydomain.com/docs`, you need to edit your `docs.yml` configuration and then get provider-specific instructions for setting up the subpath. Common providers include Cloudflare, AWS Route53 and Cloudfront, Netlify, and Vercel.
### Configure the `url` in `docs.yml`
Append that subpath to the end of the `url`. This example use `docs` for the subpath, but you can use any word you like, such as `reference` or `developer`.
```yaml
instances:
- url: example.docs.buildwithfern.com/docs
```
### Configure the `custom-domain`
Below the `url`, add a `custom-domain` key as shown in the examples below.
```yaml
instances:
- url: example.docs.buildwithfern.com/docs
custom-domain: example.com/docs
```
[Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3)
### Update the Fern Docs site
If you created your Fern Docs site using one of our [Docs Quickstarts](/learn/docs/getting-started/quickstart), push the changes you made to your GitHub repository. This runs a GitHub Action to update the site with your new configuration.
If you need to update your Fern Docs site manually, run `fern generate --docs`.
### Reach out to us
This feature is available on the Fern Docs Basic plan and above. Reach out to [sales@buildwithfern.com](mailto:sales@buildwithfern.com) to set up your subscription and obtain the configuration for setting up your custom subpath.
# Collecting feedback and suggestions from users
Fern offers a variety of ways to track feedback and suggested improvements from users.
## On-page feedback
By default, every Markdown page of your docs contains a feedback component at the bottom of the page:
This feature is available on the Basic plan and above.
[Contact us](https://buildwithfern.com/contact)
to get set up.
The feedback can be sent to you in real-time via the method of your choosing (e.g. Slack, email).
To disable this feature on a page, set `hide-feedback: true` in the frontmatter of that page. You can read more about the frontmatter configuration [here](/learn/docs/content/frontmatter#on-page-feedback).
## Edit this page
Allow users to open directly to the current page in your GitHub repository and suggest changes.
You can configure this feature for the entire site in the [global configuration](/learn/docs/getting-started/global-configuration#instances-configuration), or for an individual page in the [frontmatter of that page](/learn/docs/content/frontmatter#edit-this-page).
# Write docs content using Markdown
> Use Markdown and MDX to add content to your Fern documentation site, including Fern's built-in component library.
## Add Markdown or MDX pages
Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/).
NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.
Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file.
In the example below, the MDX files are inside a folder named `pages/`.
```bash
fern/
├─ fern.config.json
├─ docs.yml
└─ pages/
├─ welcome.mdx
└─ quickstart.mdx
```
```yml
navigation:
- section: Overview
contents:
- page: Welcome
path: ./pages/welcome.mdx
- page: Quickstart
path: ./pages/quickstart.mdx
```
## Page header
Fern automatically generates the `
` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now:
```yml
- page: Write Markdown content
path: ./docs/pages/fern-docs/content/write-markdown.mdx
```
The value for `page` is used as the content of the top `
` element of this page. Thus, when adding content to your Markdown pages, begin with `
` instead of `
`.
## Fern components
Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview)
## Links in Markdown
### Link target
When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.
### Link format
Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:
```mdx
Read the [Introduction](/learn/overview/introduction).
```
## Images
You can use locally stored images or URLs to include images in your Markdown pages. Use either [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images-1) or the [`` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) to insert the image.
## Embedding local assets
You can embed local assets in your Markdown pages using the [`