fern-api · fern-api · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026 · Jun 24, 2026
@@ -190,7 +190,10 @@ Changelog entries live in `fern/products/docs/pages/changelog/` and `fern/produc
 
 ### Rules
 
-- Always include `tags` in YAML frontmatter. Pick 1–4 from the existing set (e.g., `api-reference`, `components`, `navigation`, `customization`, `search`, `ai`, `security`, `bug-fix`). Tags are categorical — describe the area, not the feature name.
+- Every entry needs tags. Apply them one of two ways:
+  - **Frontmatter `tags`** — a YAML array that tags the whole file. All headings inherit it. Use this when the file covers a single release or several closely related changes.
+  - **`<ChangelogTags>` per heading** — place the component directly under a `##` heading to tag that entry on its own. Use this when one file holds multiple unrelated releases under separate headings. A `<ChangelogTags>` marker replaces the frontmatter tags for that heading; headings without one fall back to the frontmatter tags.
+- Pick 1–4 tags from the existing set (e.g., `api-reference`, `components`, `navigation`, `customization`, `search`, `ai`, `security`, `bug-fix`). Tags are categorical — describe the area, not the feature name. The same vocabulary applies to both frontmatter and `<ChangelogTags>`.
 - Use `##` (h2) for each feature heading. No h1.
 - Lead with what the user can now do: "You can now..." or a direct capability statement.
 - Keep it short: 2–6 sentences per feature. Bullet points for lists of details.
@@ -217,12 +220,35 @@ To configure this, go to **Settings** > **Page access** in the [Dashboard](https
 <Button intent="none" outlined rightIcon="arrow-right" href="/learn/dashboard/settings/page-access">Read the docs</Button>
 ```
 
+When a single file holds multiple releases under separate headings, tag each heading with `<ChangelogTags>` instead of frontmatter:
+
+```mdx
+## New dashboard analytics
+
+<ChangelogTags>customization, configuration</ChangelogTags>
+
+Track page views and API usage from the dashboard.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/getting-started/analytics">Read the docs</Button>
+
+## Bug fixes
+
+<ChangelogTags>api-reference, bug-fix</ChangelogTags>
+
+Resolved an issue where SDK snippets failed to render for paginated endpoints.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/api-reference/snippets">Read the docs</Button>
+```
+
+`<ChangelogTags>` accepts comma-separated children (above) or a `tags` prop: `<ChangelogTags tags={["api-reference", "bug-fix"]} />`.
+
 ### What not to do
 
 - Don't use h1 (`#`) — the date serves as the title.
 - Don't describe implementation details — focus on user benefit.
 - Don't skip the Button CTA.
-- Don't invent new tags when an existing one fits.
+- Don't invent new tags when an existing one fits — this applies to `<ChangelogTags>` as much as frontmatter. A one-off tag fragments the filter bar.
+- Don't tag by feature name (`changelog`, `dark-mode`). Tag by area (`navigation`, `customization`).
 
 Prefer existing tags when possible. Common tags include: `api-reference`, `components`, `navigation`, `customization`, `configuration`, `search`, `ai`, `security`, `bug-fix`, `performance`, `writing-content`.
 

@@ -0,0 +1,28 @@
+## Changelog timeline redesign
+
+<ChangelogTags>navigation, search</ChangelogTags>
+
+Changelog pages now render as a compact, date-grouped timeline of entry cards, replacing the previous layout that stacked full-height entries inline.
+
+A search bar at the top lets readers find entries across the entire changelog by keyword. The query syncs to the `?q=` URL parameter, so filtered views are shareable.
+
+<Frame>
+  <img src="../navigation/changelog.png" />
+</Frame>
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/changelogs">Read the docs</Button>
+
+## Per-entry changelog tags
+
+<ChangelogTags>navigation, components</ChangelogTags>
+
+Changelog entries with multiple releases under separate headings can tag each heading independently using the `<ChangelogTags>` component:
+
+```mdx
+## New dashboard analytics
+<ChangelogTags>analytics, dashboard</ChangelogTags>
+```
+
+Tags on individual entry pages are clickable and link back to the timeline with that tag pre-selected as a filter.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/changelogs#per-entry-tags">Read the docs</Button>
@@ -1,29 +1,32 @@
 ---
 title: Changelog pages
-subtitle: Keep a chronological record of project changes with tagging and RSS
+subtitle: Keep a chronological record of project changes with tagging, search, and RSS
 ---
 
 
-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.
+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.
 
 <Frame
     caption="Keep your users updated as your project evolves"
     background="subtle"
   >
-      <img src="changelog-humanloop.png" />
+      <img src="changelog.png" />
   </Frame>
 
 ## Configure your changelog
 
+<Steps>
+<Step title="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.
 
 <Files>
   <Folder name="fern" defaultOpen>
     <File name="fern.config.json" />
     <File name="docs.yml" />
     <Folder name="changelog" defaultOpen highlighted>
-      <File name="07-08-24.md" />
-      <File name="08-21-24.mdx" />
+      <File name="2024-07-08.md" />
+      <File name="2024-07-31.mdx" />
     </Folder>
   </Folder>
 </Files>
@@ -32,7 +35,10 @@ Add a `changelog` folder to your project. This folder must be named `changelog`
 Subdirectories within the `changelog` folder aren't supported. All changelog entry files must be placed directly in the root of the `changelog` folder.
 </Note>
 
-Then, reference it in your `docs.yml`. You can place the changelog as its own tab or as a section within your navigation.
+</Step>
+<Step title="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.
 
 <Tabs>
 <Tab title="As a tab">
@@ -58,7 +64,7 @@ navigation:
 ```
 </CodeBlock>
 
-[View an example](https://elevenlabs.io/docs/changelog) of how this renders in the ElevenLabs Changelog.
+[View an example](https://elevenlabs.io/docs/changelog) of how this renders in the ElevenLabs changelog.
 </Tab>
 <Tab title="As a section">
 <CodeBlock title="docs.yml">
@@ -83,46 +89,101 @@ Section-level changelogs **can't** be nested within an `api` entry.
 </Tab>
 </Tabs>
 
-## Write a changelog entry
+</Step>
+</Steps>
 
-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 Fern's built-in [component library](/learn/docs/content/components/overview) within an entry.
+## Write a changelog entry
 
-<Markdown src="/products/docs/snippets/changelog-example.mdx" />
+Each entry is a single Markdown file in your `changelog` folder.
 
-### Entry date 
+<Steps>
+<Step title="Create a dated file">
 
-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:
+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)
 
-### Tags
+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.
+
+</Step>
+<Step title="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.
+
+<Markdown src="/products/docs/snippets/changelog-example.mdx" />
 
-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:
+</Step>
+<Step title="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.
+
+<AccordionGroup>
+<Accordion title="Per-file tags (frontmatter)">
+
+Add a `tags` array in the file's YAML frontmatter to tag all of the entries for that date:
 
 <CodeBlock>
-```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.
 ```
 </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.
+</Accordion>
+<Accordion title="Per-entry tags">
+
+Tag individual entries by placing a `<ChangelogTags>` component directly under each `##` heading:
+
+<CodeBlock>
+```mdx fern/changelog/2024-07-31.mdx
+## New plant endpoints
+<ChangelogTags>plants-api, inventory-management</ChangelogTags>
+
+Added `POST /plant` to add a plant to your inventory.
+
+## Bug fixes
+<ChangelogTags>bug-fix</ChangelogTags>
+
+Resolved an issue with inventory counts.
+```
+</CodeBlock>
+
+`<ChangelogTags>` accepts comma-separated children or a `tags` prop (`<ChangelogTags tags={["plants-api", "inventory-management"]} />`).
+
+</Accordion>
+</AccordionGroup>
 
 <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
+</Step>
+<Step title="Add an overview page (optional)">
 
-Each changelog entry has a unique URL you can direct users to. For example, `https://elevenlabs.io/docs/changelog/2025/3/31`
+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.
 
-### Overview page
+</Step>
+</Steps>
 
-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.
+## 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
+## 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`
@@ -28,7 +28,7 @@ The `docs.yml` file controls your site's appearance, structure, and behavior. Al
     Add a product switcher for multi-product sites
   </Card>
   <Card title="Changelog" icon="fa-duotone fa-clock-rotate-left" href="/learn/docs/configuration/changelogs">
-    Chronological record of changes with tagging and RSS
+    Chronological record of changes with search, tagging, and RSS
   </Card>
 </CardGroup>
 

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