Project structure
This page provides an overview of the file and folder structure of a Fern Docs project.
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.
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. How you do this depends on your format:
- OpenAPI/AsyncAPI: Always requires a
generators.ymlfile with anapi.specssection. You can optionally add agroupssection for SDK generation. - Fern Definition: Auto-detected when you have a
definition/directory. Only addgenerators.ymlif you’re generating SDKs.
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.
Fern Definition
The definition folder contains the Fern Definition YAML files used to generate the API Reference section. Fern automatically detects this directory, so no generators.yml is needed for API Reference documentation.
You can optionally add an overrides file for additional customizations.
Multiple APIs
Organize multiple APIs into separate folders. You can mix OpenAPI and Fern Definition formats:
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.
When working with a locally installed CLI, set version to "*". See Install Fern CLI locally for details.
