Write Markdown content in your API Reference

Fern Docs allows you to write Markdown content in your API Reference documentation. This feature is useful for providing additional context, examples, or explanations for your API endpoints.

Adding Markdown content to endpoints

You can include Markdown content in your API definition using the description field (OpenAPI) or docs field (Fern Definition). This includes callouts, code blocks, and other components.

You can also use the <Footer> component to add content that renders at the bottom of an API Reference page, below the response section. The content inside the <Footer> component can include any Markdown content or components, such as links, callouts, or code blocks.

1
paths:
2
  /pets:
3
    get:
4
      summary: List all pets
5
      description: |
6
        Get a list of all pets in the system.
7
8
        <Note>This endpoint requires authentication.</Note>
9
10
        <Footer>
11
        ## Related endpoints
12
13
        - [Create a pet](/api-reference/pets/create)
14
        - [Update a pet](/api-reference/pets/update)
15
        </Footer>

Linking to API endpoints

Use the api: link syntax to link to an API endpoint in any Markdown content rendered by Fern. Fern resolves the link to the correct URL at build time, so you don’t have to hardcode slugs.

The format is api:METHOD/path, where METHOD is an HTTP method (GET, POST, PUT, PATCH, DELETE) and /path is the endpoint path from your API definition. If your project has multiple APIs, prefix the link with the API name: api:API-NAME:METHOD/path.

For example:

1
View the [Current user information](api:mcp-tools:GET/api/fern-docs/whoami) endpoint.

Path parameters are also supported. Include them in the endpoint path with curly braces, such as api:GET/v2/payments/{paymentId}.

Here’s how the api: link syntax looks inside API definitions:

1
paths:
2
  /orders:
3
    post:
4
      summary: Create an order
5
      description: |
6
        Creates a new order. To list all orders,
7
        use [List orders](api:GET/v2/orders).

Adding a summary page

You can also create a Markdown page that provides an overview of your API Reference. This page can include general information about your API, such as authentication requirements, rate limits, or other important details.

To add a summary page, create a Markdown file in your fern/ folder and link to it in your docs.yml file:

1
navigation:
2
  - api: API Reference
3
    summary: ./pages/api-summary.mdx

By including the summary field, the API Reference section title will link to the api-summary.mdx page.

Adding Markdown content between endpoints

You can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints.

This feature requires you to use the layout field in your docs.yml file, which is described in the Customize your API Reference guide.

To add Markdown content between endpoints, create a Markdown file in your fern/ folder and link to it in your docs.yml file:

1
navigation:
2
  - api: API Reference
3
    layout:
4
      - pet:
5
          - page: Pet CRUD
6
            path: ./pages/pet-crud.mdx
7
          - addPet
8
          - updatePet
9
          - deletePet
10
          - page: Pet Search
11
            path: ./pages/pet-search.mdx
12
          - findPets
13
          - findPetsByStatus
14
          - findPetsByTags
15
          - findPetsByType
16
          - findPetsByBreed