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

# Write Markdown content in your API Reference

> Write rich Markdown content in API documentation. Add descriptions to endpoints, create summary pages, and customize your API Reference layout.

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 in OpenAPI. This includes callouts, code blocks, and [other components](/learn/docs/writing-content/components/overview).

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.

```yaml
paths:
  /pets:
    get:
      summary: List all pets
      description: |
        Get a list of all pets in the system.

        <Note>This endpoint requires authentication.</Note>

        <Footer>
        ## Related endpoints

        - [Create a pet](/api-reference/pets/create)
        - [Update a pet](/api-reference/pets/update)
        </Footer>
```

## API link syntax

Use `api:` link syntax to link to API endpoints or API Reference sections in any Markdown content. Fern resolves these links at build time, so you don't need to hardcode slugs.

#### Link to an endpoint

Use `api:METHOD/path`, where `METHOD` is an HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) and `/path` is the endpoint path from your API definition. Path parameters use curly braces, such as `api:GET/v2/payments/{paymentId}`.

For projects with [multiple APIs](/learn/docs/api-references/generate-api-ref#include-more-than-one-api-reference), prefix with the API name: `api:API-NAME:METHOD/path`.

**`Markdown`**

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

#### Link to the root of an API Reference section

Use `api:apiName`, where `apiName` matches the API name in your `generators.yml` file. This is useful when your project has multiple APIs and you want to link to the root landing page of a specific API Reference.

**`Markdown`**

```mdx Markdown
Explore the [Plant Store API](api:plant-store) reference.
```

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

```yaml
paths:
  /orders:
    post:
      summary: Create an order
      description: |
        Creates a new order. To list all orders,
        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:

**`docs.yml`**

```yaml title="docs.yml"
navigation:
  - api: API Reference
    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](/learn/docs/api-references/customize-api-reference-layout) guide.

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

**`docs.yml`**

```yaml title="docs.yml"
navigation:
  - api: API Reference
    layout:
      - pet:
          - page: Pet CRUD
            path: ./pages/pet-crud.mdx
          - addPet
          - updatePet
          - deletePet
          - page: Pet Search
            path: ./pages/pet-search.mdx
          - findPets
          - findPetsByStatus
          - findPetsByTags
          - findPetsByType
          - findPetsByBreed
```

> Write rich Markdown content in API documentation. Add descriptions to endpoints, create summary pages, and customize your API Reference layout.