# Keep a Changelog

> Record the notable changes to your project

Keep a record of how your project has changed by writing changelog entries that users can sort by tag. The changelog will automatically populate with the files contained within the `changelog` folder.

<Frame caption="Keep your users updated as your project evolves" background="subtle">
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/0b3ccfe1ff2eebc21a2a5ff7edea02fcbc77c7fce9116e8099e3bf5cba8a6950/products/docs/pages/navigation/changelog-humanloop.png" />
</Frame>

## Configure your Changelog

<AccordionGroup>
  <Accordion title="Top-level Changelog">
    Configure a changelog for your project by creating a changelog folder.

    <CodeBlock title="Configure a Changelog">
      ```yaml {4-6}
      fern/
      ├─ fern.config.json
      ├─ docs.yml
      ├─ changelog/
          ├─ 07-08-24.md
          └─ 08-21-24.mdx
      ```
    </CodeBlock>

    Once you've configured your changelog, specify where it should appear within your docs in your `docs.yml`.

    <CodeBlock title="docs.yml">
      ```yaml {8-11,17}
      tabs:
        guides:
          display-name: Guides
          icon: light book-open
        api:
          display-name: API Reference
          icon: light code
        changelog:
          display-name: Changelog
          icon: light clock
          changelog: ./changelog

      navigation: 
        - tab: guides
          layout: 
            ...
        - tab: changelog
      ```
    </CodeBlock>

    [View an example](https://elevenlabs.io/docs/changelog) of how this renders in the ElevenLabs Changelog.
  </Accordion>

  <Accordion title="Section-level Changelog">
    Configure a changelog for your project by creating a changelog folder.

    <CodeBlock title="Configure a Changelog">
      ```yaml {4-6}
      fern/
      ├─ fern.config.json
      ├─ docs.yml
      ├─ pages/
      ├─ changelog/
          ├─ 07-08-24.md
          └─ 08-21-24.mdx
      ```
    </CodeBlock>

    Once you've configured your changelog, specify where it should appear within your navigation in your `docs.yml`.

    <CodeBlock title="docs.yml">
      ```yaml {9-11}
      navigation:
        - section: Introduction
          contents: 
            - page: Authentication
              path: ./pages/authentication.mdx
            - page: Versioning
              path: ./pages/versioning.mdx
        - api: API Reference
        - changelog: ./changelog
          title: Release Notes
          slug: api-release-notes
      ```
    </CodeBlock>

    <Note>
      Section-level changelogs **cannot** be nested within an `api` entry.
    </Note>
  </Accordion>
</AccordionGroup>

## Create a Changelog Overview

You can include a high-level overview at the top of your changelog by adding an `overview.mdx` file to your `changelog` folder.

This is useful for summarizing major themes, linking to external release notes, or giving users context before diving into specific entries.

If an `overview.mdx` file is present, it will appear above the list of changelog entries automatically—no additional configuration needed.

## Write a Changelog Entry

Create a new changelog entry by writing a Markdown file. You can use `.md` or `.mdx` files. The benefit of using `.mdx` is that you can leverage the built-in [component library](/learn/docs/content/components/overview) within an entry.

<CodeBlock title="fern/openapi/changelog/2024-07-31.mdx">
  ```mdx
  ---
  tags: ["plants-api", "breaking-change", "inventory-management"]
  ---

  ## Summary

  In the latest release, we've added endpoints to create a new Plant.

  ### What's new?

  New endpoints:

  - `POST /plant` add a new plant to inventory.

  New object schemas:

  - `CreatePlantRequest`

  <Note> Have questions? Reach out to your local botanist. </Note>
  ```
</CodeBlock>

### Entry date

Changelog entries are automatically sorted chronologically by the date specific in the file name. Specify the date of your entry using one of the following formats:

* MM-DD-YYYY (e.g., 10-06-2024)
* MM-DD-YY (e.g., 10-06-24)
* YYYY-MM-DD (e.g., 2024-04-21)

### Tags

Add tags to changelog entries to help users filter and find relevant updates. Tags are defined in the frontmatter of your changelog entry as an array of strings:

<CodeBlock>
  ```mdx
  ---
  tags: ["plants-api", "breaking-change", "inventory-management"]
  ---
  ```
</CodeBlock>

When you have multiple changelog entries, users can filter the changelog page by selecting specific tags. Use specific, descriptive tags that your users would naturally search for. Consider tagging by feature type, product area, release stage, affected platform, or user impact.

<Note>
  Customize the filter UI using [changelog filter CSS selectors](/learn/docs/customization/css-selectors-reference#changelog-filter-components). These selectors only apply when tags are configured.
</Note>

### Linking to an Entry

Each changelog entry has a unique URL you can direct users to. For example, `https://elevenlabs.io/docs/changelog/2025/3/31`

### RSS Feed

Changelogs automatically come with a RSS feed so users can subscribe to updates. Navigate to the RSS feed by appending `.rss` to the changelog path. For example, `https://elevenlabs.io/docs/changelog.rss`