From e54f7ec72eb93d64cd6401c1b7421771102b16c4 Mon Sep 17 00:00:00 2001 From: "cade.sarkin" Date: Mon, 24 Aug 2026 16:03:38 +0000 Subject: [PATCH 1/3] docs: document blog changelog layout Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/changelog/2026-08-24.mdx | 7 ++++ .../docs/pages/navigation/changelogs.mdx | 41 +++++++++++++++++-- .../pages/navigation/site-level-settings.mdx | 2 + 3 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2026-08-24.mdx diff --git a/fern/products/docs/pages/changelog/2026-08-24.mdx b/fern/products/docs/pages/changelog/2026-08-24.mdx new file mode 100644 index 000000000..64936ad25 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-08-24.mdx @@ -0,0 +1,7 @@ +## Blog layouts for changelogs + +navigation, customization + +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:`. + + diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index 20c36b1d3..b0a0c3dcb 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -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. @@ -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. This layout is available only as a per-changelog override; the site-wide `layout.changelog-layout` setting accepts only `timeline` and `classic`. ### Site-wide setting @@ -220,6 +223,38 @@ 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. + +```mdx title="changelog/overview.mdx" +--- +layout: blog +blog-layout: list +authors: + garden-editor: + name: Garden editor + role: Horticulture +--- + +Updates from the Fern Garden team. +``` + +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. +- `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 still require a leading date in the filename. Files named `overview`, `index`, or `summary` are treated as the overview page, and the date can't be overridden in frontmatter. Search, tag filtering, entry pages, and RSS, Atom, and JSON feeds work the same way as they do for a changelog. Everything else about a changelog is unchanged. + ## 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` diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 7869127e8..7667d7a79 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -654,6 +654,8 @@ layout: - `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). + +A changelog can opt into the `blog` layout only through its overview frontmatter; see the [blog layout](/learn/docs/configuration/changelogs#blog-layout). From f4a88b9a45a7a371ee0c7e65a80ca00ce29c077a Mon Sep 17 00:00:00 2001 From: "cade.sarkin" Date: Mon, 24 Aug 2026 16:05:24 +0000 Subject: [PATCH 2/3] docs: refine blog changelog documentation Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/navigation/changelogs.mdx | 8 +++++--- .../docs/pages/navigation/site-level-settings.mdx | 4 +--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index b0a0c3dcb..94e43138f 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -194,7 +194,7 @@ 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. This layout is available only as a per-changelog override; the site-wide `layout.changelog-layout` setting accepts only `timeline` and `classic`. +- `blog` — a blog-style listing of entry cards, available only as a per-changelog override. ### Site-wide setting @@ -229,7 +229,8 @@ The `blog` layout renders one card for each dated entry file. Unlike the `timeli 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. -```mdx title="changelog/overview.mdx" + +```mdx --- layout: blog blog-layout: list @@ -241,6 +242,7 @@ authors: Updates from the Fern Garden team. ``` + Configure blog metadata in the overview and entry frontmatter: @@ -253,7 +255,7 @@ Configure blog metadata in the overview and entry frontmatter: - `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 still require a leading date in the filename. Files named `overview`, `index`, or `summary` are treated as the overview page, and the date can't be overridden in frontmatter. Search, tag filtering, entry pages, and RSS, Atom, and JSON feeds work the same way as they do for a changelog. Everything else about a changelog is unchanged. +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 diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 7667d7a79..fe560e069 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -653,9 +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). - -A changelog can opt into the `blog` layout only through its overview frontmatter; see the [blog layout](/learn/docs/configuration/changelogs#blog-layout). + 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). From 1423c13d3209d1fd77b9cdc41977e3018a50d3ec Mon Sep 17 00:00:00 2001 From: "cade.sarkin" Date: Wed, 26 Aug 2026 13:28:49 +0000 Subject: [PATCH 3/3] docs: clarify blog entry slug is a full slug Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/navigation/changelogs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index 94e43138f..20f8b2791 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -248,7 +248,7 @@ 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. +- `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.