diff --git a/AGENTS.md b/AGENTS.md index bc3644e237..53706436f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. + - **`` 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 `` 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 ``. - 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 ``` +When a single file holds multiple releases under separate headings, tag each heading with `` instead of frontmatter: + +```mdx +## New dashboard analytics + +customization, configuration + +Track page views and API usage from the dashboard. + + + +## Bug fixes + +api-reference, bug-fix + +Resolved an issue where SDK snippets failed to render for paginated endpoints. + + +``` + +`` accepts comma-separated children (above) or a `tags` prop: ``. + ### 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 `` 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`. diff --git a/fern/products/docs/pages/changelog/2026-06-23.mdx b/fern/products/docs/pages/changelog/2026-06-23.mdx new file mode 100644 index 0000000000..9d09d26791 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-06-23.mdx @@ -0,0 +1,28 @@ +## Changelog timeline redesign + +navigation, search + +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. + + + + + + + +## Per-entry changelog tags + +navigation, components + +Changelog entries with multiple releases under separate headings can tag each heading independently using the `` component: + +```mdx +## New dashboard analytics +analytics, dashboard +``` + +Tags on individual entry pages are clickable and link back to the timeline with that tag pre-selected as a filter. + + diff --git a/fern/products/docs/pages/navigation/changelog.png b/fern/products/docs/pages/navigation/changelog.png new file mode 100644 index 0000000000..857e48b045 Binary files /dev/null and b/fern/products/docs/pages/navigation/changelog.png differ diff --git a/fern/products/docs/pages/navigation/changelogs.mdx b/fern/products/docs/pages/navigation/changelogs.mdx index 77c1409ec0..641d94aa1e 100644 --- a/fern/products/docs/pages/navigation/changelogs.mdx +++ b/fern/products/docs/pages/navigation/changelogs.mdx @@ -1,20 +1,23 @@ --- 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. - + ## Configure your changelog + + + Add a `changelog` folder to your project. This folder must be named `changelog` exactly — Fern won't recognize it under any other name. @@ -22,8 +25,8 @@ Add a `changelog` folder to your project. This folder must be named `changelog` - - + + @@ -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. -Then, reference it in your `docs.yml`. You can place the changelog as its own tab or as a section within your navigation. + + + +Reference the folder in your `docs.yml`. You can place the changelog as its own tab or as a section within your navigation. @@ -58,7 +64,7 @@ navigation: ``` -[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. @@ -83,46 +89,101 @@ Section-level changelogs **can't** be nested within an `api` entry. -## Write a changelog entry + + -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 - +Each entry is a single Markdown file in your `changelog` folder. -### Entry date + + -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. + + + + +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. + + -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: + + + +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: -```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. ``` -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. + + + +Tag individual entries by placing a `` component directly under each `##` heading: + + +```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. -### Linking to an entry + + -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 + + -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` diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index edaedf7fd8..8ca0f10aed 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/fern/products/docs/pages/navigation/overview.mdx @@ -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 - Chronological record of changes with tagging and RSS + Chronological record of changes with search, tagging, and RSS diff --git a/fern/products/docs/snippets/changelog-example.mdx b/fern/products/docs/snippets/changelog-example.mdx index d3ca37b453..a00c357915 100644 --- a/fern/products/docs/snippets/changelog-example.mdx +++ b/fern/products/docs/snippets/changelog-example.mdx @@ -1,4 +1,4 @@ - + ```mdx --- tags: ["plants-api", "breaking-change", "inventory-management"]