> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Project structure

> An overview of the file and folder structure of a Fern Docs project.

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](/learn/docs/preview-publish/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](/learn/docs/configuration/navigation#auto-populate-from-folder)) 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](/learn/docs/configuration/site-level-settings).

#### Example fern/docs.yml

```yml
instances:
  - url: plantstore.docs.buildwithfern.com

title: Fern Docs Starter

tabs:
  home:
    display-name: Docs
    icon: home
  API Reference:
    display-name: API Reference
    icon: puzzle

navigation:
  - tab: home
    layout:
      - section: Get started
        contents:
          - page: Welcome
            path: docs/pages/welcome.mdx
          - page: Edit your docs
            path: docs/pages/editing-your-docs.mdx
      - section: Changelog
        contents:
          - changelog: docs/changelog
  - tab: API Reference
    layout:
      - api: Plant Store API

navbar-links:
  - type: minimal
    text: Fork this repo
    url: https://github.com/fern-api/docs-starter
  - type: filled
    text: Dashboard
    url: https://dashboard.buildwithfern.com

logo:
  light: docs/assets/logo.svg
  dark: docs/assets/logo-dark.svg

colors:
  accent-primary:
    dark: "#70E155"
    light: "#008700"

favicon: docs/assets/favicon.svg

css: styles.css
```

## API definitions and `generators.yml`

To generate [API Reference](/learn/docs/api-references/generate-api-ref) 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.

Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/learn/docs/api-references/sdk-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`:

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: openapi.yml
```

You can optionally [add an overlays file](/learn/api-definitions/openapi/overlays) for additional customizations. To see this in practice, check out [Fluidstack's Fern configuration](https://github.com/fluidstackio/fern-config/tree/main/fern/openapi).

#### AsyncAPI

Place your AsyncAPI specification file in the `fern/` directory alongside your OpenAPI spec. Reference it in `generators.yml`:

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: openapi.yml
    - asyncapi: asyncapi.yaml
```

You can optionally [add an overrides file](/learn/api-definitions/asyncapi/overrides) 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](https://github.com/VapiAI/docs/tree/main/fern/apis).

## `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](/learn/cli-api-reference/cli-reference/version-policy).

**`fern.config.json`**

```json title="fern.config.json"
{
  "organization": "plantstore",
  "version": "5.23.3"
}
```

When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/learn/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.

> An overview of the file and folder structure of a Fern Docs project.