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 configuration file that defines the navigation, theme, and hosting details of your documentation. You can customize the appearance and behavior of your documentation by editing this file.
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.
To see what this looks like in practice, check out Vellum’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.
To see what this looks like 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. For example:
To see what this looks like in practice, check out OctoAI’s Fern configuration.
fern.config.json
The fern.config.json
file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization’s details.