ConfigurationNavigation

Changelog pages

Keep a chronological record of project changes with tagging, search, and RSS
View as Markdown

Keep a record of how your project has changed by writing changelog entries. The changelog renders as a scannable timeline of entry cards grouped by date, automatically populated from the files in your changelog folder. Search and tag filtering are built into the timeline, with no configuration required. You can also switch to the classic layout of stacked full entries.

Keep your users updated as your project evolves

Configure your changelog

1

Add a changelog folder

Add a changelog folder to your project. This folder must be named changelog exactly — Fern won’t recognize it under any other name.

fern
fern.config.json
docs.yml
changelog
2024-07-08.md
2024-07-31.mdx

Subdirectories within the changelog folder aren’t supported. All changelog entry files must be placed directly in the root of the changelog folder.

2

Reference it in docs.yml

Reference the folder in your docs.yml. You can place the changelog as its own tab or as a section within your navigation.

docs.yml
1tabs:
2  guides:
3    display-name: Guides
4    icon: light book-open
5  api:
6    display-name: API Reference
7    icon: light code
8  changelog:
9    display-name: Changelog
10    icon: light clock
11    changelog: ./changelog
12
13navigation:
14  - tab: guides
15    layout:
16      ...
17  - tab: changelog

View an example of how this renders in the ElevenLabs changelog.

Write a changelog entry

Each entry is a single Markdown file in your changelog folder.

1

Create a dated file

Name the file with the entry’s date using one of the following formats. Fern sorts entries chronologically by this date:

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

Both .md and .mdx are supported. Use .mdx to leverage Fern’s built-in component library within an entry.

2

Write the entry content

Write the entry in Markdown. Each top-level ## heading becomes its own card on the timeline, so a single dated file can document several updates from the same day.

fern/changelog/2024-07-31.mdx
1---
2tags: ["plants-api", "breaking-change", "inventory-management"]
3---
4
5## Summary
6
7In the latest release, we've added endpoints to create a new Plant.
8
9### What's new?
10
11New endpoints:
12
13- `POST /plant` add a new plant to inventory.
14
15New object schemas:
16
17- `CreatePlantRequest`
18
19<Note> Have questions? Reach out to your local botanist. </Note>
3

Add tags

Tags let readers filter the timeline to specific topics. They appear as badges on each entry card and in the filter bar, and link back to a filtered timeline when clicked.

Use specific, descriptive tags that readers would search for — by feature type, product area, release stage, affected platform, or user impact. Apply them per file in the frontmatter or per entry under a heading; per-entry tags replace the frontmatter tags for that entry’s card, while entries without their own tags inherit them.

Add a tags array in the file’s YAML frontmatter to tag all of the entries for that date:

fern/changelog/2024-07-31.mdx
1---
2tags: ["plants-api", "breaking-change", "inventory-management"]
3---
4
5## New plant endpoints
6
7Added `POST /plant` to add a plant to your inventory.
8
9## Bug fixes
10
11Resolved an issue with inventory counts.

Tag individual entries by placing a <ChangelogTags> component directly under each ## heading:

fern/changelog/2024-07-31.mdx
1## New plant endpoints
2<ChangelogTags>plants-api, inventory-management</ChangelogTags>
3
4Added `POST /plant` to add a plant to your inventory.
5
6## Bug fixes
7<ChangelogTags>bug-fix</ChangelogTags>
8
9Resolved an issue with inventory counts.

<ChangelogTags> accepts comma-separated children or a tags prop (<ChangelogTags tags={["plants-api", "inventory-management"]} />).

Customize the filter UI using changelog filter CSS selectors. These selectors only apply when tags are configured.

4

Add an overview page (optional)

Add an overview.mdx file to your changelog folder to include a high-level overview at the top of your changelog. This is useful for summarizing major themes, linking to external release notes, or giving users context before diving into specific entries. If present, it will automatically appear above the list of changelog entries.

Customize layout

Changelogs support two layouts:

  • timeline (default) — a searchable timeline of condensed entry cards with plain-text excerpts.
  • classic — stacked full entries rendered inline, preserving code formatting, copy buttons, and links.

Site-wide setting

Set the default layout for all changelogs in docs.yml:

docs.yml
1layout:
2  changelog-layout: classic

Per-changelog override

Override the site-wide layout for a single changelog by adding a layout property to that changelog’s overview.mdx frontmatter:

changelog/overview.mdx
1---
2layout: classic
3---
4
5Release history for the self-hosted Docker image.

The per-changelog override takes priority over the site-wide layout.changelog-layout setting.

Linking and sharing

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

Search queries sync to the ?q= URL parameter, so a search result is shareable as a link.

RSS feed

Changelogs automatically come with an 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