# 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. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs.

## Top-level folders

<Files>
  <Folder name="fern" defaultOpen>
    <Folder name="pages" comment="MDX files" />

    <Folder name="assets" comment="Images or videos" />

    <File name="docs.yml" comment="Defines navigation, theme, and hosting" />

    <Folder name="openapi" comment="Or definition/ for the Fern Definition" />

    <File name="generators.yml" comment="References spec, configures SDKs" />

    <File name="fern.config.json" comment="Organization name and CLI version" />
  </Folder>
</Files>

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.

<Files>
  <Folder name="pages" defaultOpen>
    <Folder name="introduction" defaultOpen>
      <File name="quickstart.mdx" />

      <File name="project-structure.mdx" />

      <File name="showcase.mdx" />
    </Folder>

    <Folder name="building-your-docs" defaultOpen>
      <Folder name="navigation">
        <File name="sections.mdx" />

        <File name="tabs.mdx" />

        <File name="versions.mdx" />
      </Folder>

      <File name="configuration.mdx" />
    </Folder>
  </Folder>
</Files>

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.

<Files>
  <Folder name="assets" defaultOpen>
    <File name="favicon.ico" />

    <File name="product-screenshot.svg" />

    <File name="demo-video.mp4" />

    <File name="logo-dark-mode.png" />

    <File name="logo-light-mode.png" />
  </Folder>
</Files>

## `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](/docs/configuration/site-level-settings).

<CodeBlock title="fern/docs.yml of this website">
  ```yml
  instances:
    - url: fern.docs.buildwithfern.com/learn
      custom-domain: buildwithfern.com/learn

  navigation:
    - section: Introduction
      layout:
        - page: QuickStart
          path: pages/introduction/quickstart.mdx
        - page: Project Structure
          path: pages/introduction/project-structure.mdx
        - page: Showcase
          path: pages/introduction/showcase.mdx

  navbar-links:
    - type: filled
      text: Book a demo
      url: https://buildwithfern.com/contact

  logo:
    light: ./images/logo-primary.svg
    dark: ./images/logo-white.svg

  colors:
    accent-primary:
      dark: "#ADFF8C"
      light: "#209d63"

  favicon: ./images/favicon.ico 

  title: Fern's Documentation
  ```
</CodeBlock>

## API definitions and `generators.yml`

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

<Info>
  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](/docs/api-references/sdk-snippets)

   in your API Reference.
</Info>

<AccordionGroup>
  <Accordion title="OpenAPI">
    The `openapi` folder contains your OpenAPI Specification file. Fern supports either YAML or JSON format.

    You must also create a `generators.yml` file that references your spec:

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

    In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations.

    <Files>
      <Folder name="openapi" defaultOpen>
        <File name="openapi.yaml" comment="Or openapi.json" />

        <File name="overrides.yaml" comment="Optional" />
      </Folder>
    </Files>

    To see this in practice, check out [Fluidstack's Fern configuration](https://github.com/fluidstackio/fern-config/tree/main/fern/openapi).
  </Accordion>

  <Accordion title="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](/api-definitions/overview/overrides) for additional customizations.

    <Files>
      <Folder name="definition" defaultOpen>
        <File name="pets.yaml" />

        <File name="owners.yaml" />

        <File name="stores.yaml" />

        <File name="overrides.yaml" comment="Optional" />

        <File name="api.yaml" />
      </Folder>
    </Files>

    [See an example](https://github.com/fern-api/fern/tree/3137938b70e058f3691ddef34d5c1cc29acc4b80/test-definitions/fern/apis/imdb/definition).
  </Accordion>

  <Accordion title="Multiple APIs">
    Organize multiple APIs into separate folders. You can mix OpenAPI and Fern Definition formats:

    <Files>
      <Folder name="apis" defaultOpen>
        <Folder name="admin-api" defaultOpen>
          <File name="openapi.json" highlighted />

          <File name="generators.yml" comment="Required for OpenAPI" />

          <File name="overrides.yaml" comment="Optional" />
        </Folder>

        <Folder name="user-api" defaultOpen>
          <Folder name="definition" defaultOpen comment="Auto-detected for Fern Definition">
            <File name="api.yml" highlighted />

            <File name="overrides.yaml" comment="Optional" />
          </Folder>
        </Folder>
      </Folder>
    </Files>

    Reference each API in `docs.yml` using `api-name` that matches the folder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis).
  </Accordion>
</AccordionGroup>

## `fern.config.json`

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

```json title="fern.config.json"
{
  "organization": "plant-catalog",
  "version": "3.57.0"
}
```

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