Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions fern/products/docs/pages/changelog/2026-08-24.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
## Blog layouts for changelogs

<ChangelogTags>navigation, customization</ChangelogTags>

You can now present a changelog as a blog, with dated entries rendered as cards in a grid or list. Set `layout: blog` and `blog-layout` in the changelog overview frontmatter; the `blog:` navigation key is an alias for `changelog:`.

<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/changelogs#blog-layout">Read the docs</Button>
43 changes: 40 additions & 3 deletions fern/products/docs/pages/navigation/changelogs.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Changelog pages
subtitle: Keep a chronological record of project changes with tagging, search, and RSS
description: Configure changelog pages in Fern, including entry files, the timeline and classic layouts, tag filtering, and the RSS feed.
description: 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 a dated timeline of 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.
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] <Microsoft.OxfordComma> reported by reviewdog 🐶
Use the Oxford comma in ', with search and tag filtering built in.'.


<Frame
caption="Keep your users updated as your project evolves"
Expand Down Expand Up @@ -48,6 +48,8 @@ Subdirectories within the `changelog` folder aren't supported. All changelog ent

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`.

<Tabs>
<Tab title="As a tab">
<CodeBlock title="docs.yml">
Expand Down Expand Up @@ -188,10 +190,11 @@ Add an `overview.mdx` file to your `changelog` folder to include a high-level ov

## Customize layout

Changelogs support two layouts:
Changelogs support three 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.
- `blog` — a blog-style listing of entry cards, available only as a per-changelog override.

### Site-wide setting

Expand Down Expand Up @@ -220,6 +223,40 @@ 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. Unlike the `timeline` layout, which creates a card for each top-level `##` heading, the `blog` layout creates one card per 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. List rows stack on narrow viewports. Values other than `list` use the grid layout.

<CodeBlock title="changelog/overview.mdx">
```mdx
---
layout: blog
blog-layout: list
authors:
garden-editor:
name: Garden editor
role: Horticulture
---

Updates from the Fern Garden team.
```
</CodeBlock>

Configure blog metadata in the overview and entry frontmatter:

- An optional `authors` map in the overview frontmatter registers authors by ID. Each author requires `name` and can include `role`, `avatar`, and `url`.
- `title` sets the post title and falls back to the entry title.
- `slug` overrides the date-derived 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`.
- `tags` adds tags to the post.
- The excerpt uses `description`, then `subtitle`, then `excerpt`, and falls back to the first approximately 200 characters of the body.
- `thumbnail` or `image` sets the card and hero image.
- `author` or `authors` can name keys in the overview's `authors` registry or provide inline author objects with `name`, `role`, `avatar`, and `url`.
- `draft: true` or `hidden: true` excludes the post from the listing.

Entry files, dates, and reserved overview filenames follow the standard changelog rules. Search, tag filtering, entry pages, and RSS, Atom, and JSON feeds work the same way as they do for a changelog.

## 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`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -653,7 +653,7 @@ layout:
- `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.

Individual changelogs can override this setting with the `layout` frontmatter property in their [overview page](/learn/docs/configuration/changelogs#add-an-overview-page-optional).
Individual changelogs can override this setting with the `layout` frontmatter property in their overview page, including the per-changelog-only [`blog` layout](/learn/docs/configuration/changelogs#blog-layout).
</ParamField>

<ParamField path="layout.show-nav-availability-badges" type="boolean" required={false} default="false" toc={true}>
Expand Down