Project structure
This page provides an overview of the file and folder structure of a Fern Docs project. If you’re spreading docs across multiple repositories that publish to the same domain, see Multi-source docs.
Directory structure
The configuration files for your docs live in the fern folder:
The fern and changelog folders are reserved names — Fern won’t recognize them if renamed. All other folder names are customizable.
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 folder name is customizable.
You can organize the pages folder into subfolders based on the sections of your documentation, or keep pages flat as shown above.
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. The folder name is customizable.
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. Only files referenced in your docs.yml navigation (or discovered via a folder configuration) are included in builds — any unreferenced files are ignored.
Fern treats .yml and .yaml extensions identically. This applies to all YAML files in a Fern project, including docs.yml, generators.yml, and API specification files.
For complete configuration options, see the docs.yml reference.
API definitions and generators.yml
To generate API Reference documentation, you need to provide your API definition. OpenAPI and AsyncAPI specs require a generators.yml file with an api.specs section. You can optionally add a groups section for SDK generation.
docs.yml for your documentation settings and generators.yml to configure SDK code snippets in your API Reference.OpenAPI
Place your OpenAPI specification file in the fern/ directory (or in a subfolder). Fern supports either YAML or JSON format.
Reference it in generators.yml:
You can optionally add an overlays file for additional customizations. To see this in practice, check out Fluidstack’s Fern configuration.
AsyncAPI
Place your AsyncAPI specification file in the fern/ directory alongside your OpenAPI spec. Reference it in generators.yml:
You can optionally add an overrides file for additional customizations.
Multiple APIs
Organize multiple APIs into separate folders:
The apis folder must use this exact name. Reference each API in docs.yml using api-name that matches the subfolder name. To see this in practice, check out Vapi’s Fern configuration.
fern.config.json
The fern.config.json file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds. To keep every project in your organization on a compatible version, set an organization-wide CLI version policy.
When working with a locally installed CLI, set version to "*". See Install Fern CLI locally for details.