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: Defines the navigation, theme, and hosting details of your documentation.
• openapi or definition/: Contains your API specification files (if you have an API Reference section).
• generators.yml: Required for OpenAPI to reference your spec location. Also used to configure SDK generation. Not required for Fern Definition docs-only projects.
• 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.

1
instances:
2
  - url: fern.docs.buildwithfern.com/learn
3
    custom-domain: buildwithfern.com/learn
4
5
navigation:
6
  - section: Introduction
7
    layout:
8
      - page: QuickStart
9
        path: pages/introduction/quickstart.mdx
10
      - page: Project Structure
11
        path: pages/introduction/project-structure.mdx
12
      - page: Showcase
13
        path: pages/introduction/showcase.mdx
14
15
navbar-links:
16
  - type: filled
17
    text: Book a demo
18
    url: https://buildwithfern.com/contact
19
20
logo:
21
  light: ./images/logo-primary.svg
22
  dark: ./images/logo-white.svg
23
24
colors:
25
  accent-primary:
26
    dark: "#ADFF8C"
27
    light: "#209d63"
28
29
favicon: ./images/favicon.ico 
30
31
title: Fern's Documentation

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.yml file with an api.specs section. You can optionally add a groups section for SDK generation.
• Fern Definition: Auto-detected when you have a definition/ directory. Only add generators.yml if you’re generating SDKs.

1
api:
2
  specs:
3
    - openapi: ../openapi/openapi.json

fern.config.json

The fern.config.json file stores your organization name and the Fern CLI version. Pinning the version provides deterministic builds.

1
{
2
  "organization": "plant-catalog",
3
  "version": "2.8.2"
4
}