Get started
Developer guide
Work with the code directly for full control over your docs
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 (upstream reworded this line for the conflict test):
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:
Brand colors for light and dark modes
Fonts for headings and body text
Your brand logo and browser icon
Page width, sidebar, and tabs placement
Sections, pages, tabs, and versioning
Links and buttons in your header
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:
---
title: Page title
subtitle: Optional subtitle
slug: my-page
---
Your content here. Use **bold**, *italic*, `code`, and standard Markdown.
## Headings create sections
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 devThis 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.
| Workflow | Trigger | What it does |
|---|---|---|
check.yml | PRs and pushes to main | Runs fern check to validate your API spec and docs configuration |
preview-docs.yml | Pull requests | Generates a preview URL and posts it as a PR comment so reviewers can see changes before merging |
publish-docs.yml | Push to main | Publishes your docs to production automatically |
These workflows require a FERN_TOKEN repository secret. Generate one with fern token and add it in your repository's Settings → Secrets and variables → Actions.