> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.
# Changelog pages
> Configure changelog pages in Fern, including entry files, timeline, classic, and blog layouts, tag filtering, and the RSS feed.
A changelog is a navigation entry that renders dated entries. Point the `changelog` key at a folder and every Markdown file in it becomes an entry, grouped by date, with search and tag filtering built in. A changelog can go wherever a section can — as its own tab, or as an entry in your sidebar.
## Configure your changelog
#### 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.
Subdirectories within the `changelog` folder aren't supported. All changelog entry files must be placed directly in the root of the `changelog` folder.
#### 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.
`blog:` is an alias for `changelog:` at both the top level and tab level. It has the same behavior, URLs, and feeds, but defaults the navigation title to `Blog` instead of `Changelog`.
#### As a tab
#### 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
```
[View an example](https://elevenlabs.io/docs/changelog) of how this renders in the ElevenLabs changelog.
#### As a section
#### 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
```
Section-level changelogs **can't** be nested within an `api` entry.
## Write a changelog entry
Each entry is a single Markdown file in your `changelog` folder.
#### 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](/learn/docs/writing-content/components/overview) within an entry.
#### 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
```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`
Have questions? Reach out to your local botanist.
```
#### 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.
#### Per-file tags (frontmatter)
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`**
```mdx fern/changelog/2024-07-31.mdx
---
tags: ["plants-api", "breaking-change", "inventory-management"]
---
## New plant endpoints
Added `POST /plant` to add a plant to your inventory.
## Bug fixes
Resolved an issue with inventory counts.
```
#### Per-entry tags
Tag individual entries by placing a `` component directly under each `##` heading:
**`fern/changelog/2024-07-31.mdx`**
```mdx fern/changelog/2024-07-31.mdx
## New plant endpoints
plants-api, inventory-management
Added `POST /plant` to add a plant to your inventory.
## Bug fixes
bug-fix
Resolved an issue with inventory counts.
```
`` accepts comma-separated children or a `tags` prop (``).
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.
#### 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 three layouts:
* `timeline` (default) — a searchable timeline of condensed entry cards with plain-text excerpts, one card per top-level `##` heading.
* `classic` — stacked full entries rendered inline, preserving code formatting, copy buttons, and links.
* `blog` — a blog-style listing with one card per entry file, available only as a per-changelog override.
### Site-wide setting
Set the default layout for all changelogs [in `docs.yml`](/learn/docs/configuration/site-level-settings#changelog-layout):
#### docs.yml
```yaml
layout:
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
```mdx
---
layout: classic
---
Release history for the self-hosted Docker image.
```
The per-changelog override takes priority over the site-wide `layout.changelog-layout` setting.
## Blog layout
The `blog` layout renders one card for each dated entry file.
Set `layout: blog` in the changelog folder's `overview.mdx` frontmatter. Use `blog-layout: grid` for the default card grid or `blog-layout: list` for full-width rows with the image beside the text.
#### changelog/overview\.mdx
```mdx
---
layout: blog
blog-layout: list
authors:
garden-editor:
name: Garden editor
role: Horticulture
---
Updates from the Fern Garden team.
```
An optional `authors` map in the overview frontmatter registers authors by ID. Each author requires `name` and can include `role`, `avatar`, and `url`.
Each entry file sets its own post metadata in frontmatter:
#### Post properties
**`title`** `string` — default: Entry title
Sets the post title.
---
**`slug`** `string` — default: Date-derived URL
Overrides the post URL. The value is a full slug relative to the site base (or the product or version base, when one applies), so a post under a blog at `/blog` needs `slug: blog/my-post`. Omitting the `blog/` prefix publishes the post at `/my-post` instead of under the blog.
---
**`tags`** `list of strings`
Adds tags to the post.
---
**`description`** `string` — default: First \~200 characters of the body
Sets the card excerpt. `subtitle` and `excerpt` are also accepted, in that order of precedence.
---
**`thumbnail`** `string`
Path to the card and hero image. `image` is also accepted.
---
**`author`** `string | object`
Names a key in the overview's `authors` registry, or an inline author object with `name`, `role`, `avatar`, and `url`. `authors` accepts a list of either form.
---
**`draft`** `boolean` — default: false
Excludes the post from the listing. `hidden: true` does the same.
---
## 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`. Atom and JSON feeds are available at `.atom` and `.json`.
Feeds require a recognized segment in the changelog's URL path: `blog`, `blogs`, `posts`, `changelog`, `changelogs`, `release-notes`, `releasenotes`, `whats-new`, or `whatsnew`. `fern check` reports an error for a changelog that resolves elsewhere.
> Keep a chronological record of project changes with tagging, search, and RSS