Developer guide

Fern Editor is the fastest way to make changes, but when you need full control you can work with the source files directly.

Project structure

Your docs project is organized like this:

For details on each file, see the project structure documentation.

Configure with docs.yml

docs.yml is the single file that controls your site’s look, feel, and structure — no custom code needed. Here’s what you can adjust:

For the full reference, see the site-level settings documentation.

Writing pages in MDX

Pages are MDX files — Markdown with support for Fern components. Each page starts with frontmatter:

1
---
2
title: Page title
3
subtitle: Optional subtitle
4
slug: my-page
5
---
6
7
Your content here. Use **bold**, *italic*, `code`, and standard Markdown.
8
9
## Headings create sections
10
11
Add components like <Note>, <Card>, and <Tabs> alongside your Markdown.

After creating a page, add it to docs.yml to include it in your navigation.

Editing, previewing, and publishing

Clone the repository and open it in your editor of choice. Install the Fern CLI to preview changes locally as you work:

$
npm install -g fern-api
$
fern docs dev

This starts a local dev server with hot-reloading at http://localhost:3000. Edit MDX files, update docs.yml, and see changes instantly.

When you open a pull request

When you’re ready, push your changes and open a pull request. This repository has GitHub Actions workflows (in .github/workflows/) that take it from there — your docs are validated, a shareable preview link is posted as a comment on your PR, and once merged to main, your docs are published to production automatically.

Going further