Project Structure
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
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.
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.
docs.yml
The docs.yml file is the heart of your Fern documentation site. This configuration file controls your documentation’s navigation structure, visual design, site functionality, and hosting settings.
For complete configuration options, see the docs.yml reference.
API Definitions
OpenAPI
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.
In addition to your specification file, you can optionally add an overrides file for additional customizations.
To see this in practice, check out Fluidstack’s Fern configuration.
Fern Definition
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.
In addition to your specification file, you can optionally add an overrides file for additional customizations.
To see this in practice, check out Cartesia’s Fern configuration.
Multiple APIs
If you have multiple APIs, you can organize them into separate folders within the apis folder. Each API should have its own API definition and (optional) overrides file.
For example:
To see this in practice, check out Vapi’s Fern configuration.
If you’re using Fern for both API Reference documentation and SDKs, you’ll use both docs.yml (the Docs configuration file) and generators.yml (the SDK configuration file) to configure how SDK code snippets appear in your API reference documentation.
If you’re only using Fern for API Reference docs, not SDKs, your generators.yml should simply link to your spec:
fern.config.json
The fern.config.json file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds.
When working with a locally installed CLI, set version to "*". See Install Fern CLI locally for details.
