diff --git a/changelog.mdx b/changelog.mdx index 57cfd65a..6f2d60cd 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -1,9 +1,16 @@ --- title: "Product Updates" description: "New updates and improvements" -mode: "center" --- + + ## Subscribable changelogs + - Automatically generate an RSS feed from changelog pages + - Integrate RSS-enabled updates with Slack, email, and other tools + + Learn more in our new [Changelog guide](/guides/changelogs) + + ## API playground stability updates - Search to find an endpoint diff --git a/components/update.mdx b/components/update.mdx index 52719e23..ecca76df 100644 --- a/components/update.mdx +++ b/components/update.mdx @@ -1,70 +1,76 @@ --- title: "Update" description: "Keep track of changes and updates" -icon: 'list-collapse' +icon: "list-collapse" --- -The `Update` component is used to keep track of changes and updates. +Use the `Update` component to display changelog entries, version updates, and release notes with consistent formatting. - + + ## Example update + + You can add anything here, like a screenshot, a code snippet, or a list of changes. + - ## Changelog - - You can add anything here, like a screenshot, a code snippet, or a list of changes. - - #### Features + ### Features - Responsive design - - Sticky section for each changelog + - Anchor for each update + - Generated RSS feed entry for each update - - ### How to use - ```mdx - - This is how you use a changelog with a label - and a description. - - - This is how you use a changelog with a label - and a description. - - ``` +## How to use - You can use multiple `Update` components to create changelogs. +```mdx Update example + + This is how you use a changelog with a label, description, + and tags. +``` - - Each `label` creates an anchor and also shows up on the table of contents on the right. - +Use multiple `Update` components to create [changelogs](/guides/changelogs). ## Props - The label give to the update, appears as sticky text to the left of the changelog. + Label for the update. Appears to the left of the update and creates an anchor link. For this reason, labels should be unique. - Tags for the changelog, will be shown as filters in the right side panel. + Tags for the update. Shown as filters in the right side panel. - Description of the update, appears below the label and tag. + Description of the update. Appears below the label and tag. + + Title and description that will appear in the RSS feed entry for the update. + + ```mdx wrap + + # What's New in v1.0.1 + + * Bug fixes + * Improvements + + ``` - - -```mdx Update Example - - This is how you use a changelog with a label - and a description. - +```xml Example Update item in RSS feed + + <![CDATA[v1.0.1 released]]> + + https://mintlify.com/changelog#v101 + https://mintlify.com/changelog#v101 + Fri, 20 Jun 2025 21:32:19 GMT + ``` - + Learn more about [subscribable changelogs](/guides/changelogs#subscribable-changelogs). + diff --git a/docs.json b/docs.json index 684eb124..ec09d583 100644 --- a/docs.json +++ b/docs.json @@ -118,6 +118,7 @@ "react-components", "settings/custom-scripts", "settings/seo", + "guides/changelogs", "guides/hidden-pages", "settings/broken-links", "guides/monorepo", @@ -362,6 +363,9 @@ "claude" ] }, + "rss": { + "pages": ["changelog"] + }, "redirects": [ { "source": "/content/components/accordions", @@ -492,4 +496,4 @@ "destination": "authentication-personalization/personalization-setup" } ] -} \ No newline at end of file +} diff --git a/guides/changelogs.mdx b/guides/changelogs.mdx new file mode 100644 index 00000000..09868d4c --- /dev/null +++ b/guides/changelogs.mdx @@ -0,0 +1,152 @@ +--- +title: "Changelogs" +description: "Post product updates in your docs with a subscribable RSS feed" +icon: "newspaper" +--- + +Create a changelog for your docs by adding [Update components](/components/update) to a page. + +Check out the [Mintlify changelog](/changelog) as an example: you can include links, images, text, and demos of your new features in each update. + +## Setting up your changelog + + + + 1. Create a new page in your docs such as `changelog.mdx` or `updates.mdx`. + 2. Add your changelog page to your navigation scheme in your `docs.json`. + + + Add an `Update` for each changelog entry. + + Include relevant information like feature releases, bug fixes, or other announcements. + + + +```mdx Example changelog.mdx +--- +title: "Changelog" +description: "Product updates and announcements" +--- + + Added a new Wintergreen flavor. + + Released a new version of the Spearmint flavor, now with 10% more mint. + + + + Released a new version of the Spearmint flavor. + +``` + +## Customizing your changelog + +Control how people navigate your changelog and stay up to date with your product information. + +### Table of contents + +Each `label` for an `Update` automatically creates an entry in the right sidebar's table of contents. This is the default navigation for your changelog: + + + Changelog with table of contents displayed in light mode. + Changelog with table of contents displayed in dark mode. + + +### Tag filters + +Add `tags` to your `Update` components to replace the table of contents with tag filters. Users can filter the changelog by selecting one or more tags: + +```mdx Tag filters example wrap + + Added a new Wintergreen flavor. + + Released a new version of the Spearmint flavor, now with 10% more mint. + + + + Released a new version of the Spearmint flavor. + + + + Deprecated the Peppermint flavor. + + Released a new version of the Spearmint flavor. + +``` + + + Changelog in light mode with the Peppermint tag filter selected. + Changelog in dark mode with the Peppermint tag filter selected. + + + + The table of contents and changelog filters are hidden when using `custom`, `center`, or `wide` page modes. Learn more about [page modes](/pages#page-mode). + + +### Subscribable changelogs + +Using `Update` components creates a subscribable RSS feed at your page URL + `/rss.xml`. For example, `mintlify.com/docs/changelog/rss.xml`. New updates are automatically included in the feed when published. + +```xml Example RSS feed + + + <![CDATA[Product Updates]]> + + https://mintlify-changelogs-guide.mintlify.app + RSS for Node + Fri, 20 Jun 2025 21:36:14 GMT + + + https://mintlify-changelogs-guide.mintlify.app + + <![CDATA[Subscribable changelogs]]> + + https://mintlify-changelogs-guide.mintlify.app/changelog#june-20-2025 + https://mintlify-changelogs-guide.mintlify.app/changelog#june-20-2025 + Fri, 20 Jun 2025 21:04:47 GMT + + + +``` + +RSS feeds can integrate with Slack, email, or other subscription tools to notify users of product changes. Some options include: + +* [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) +* [Email](https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email) via Zapier +* Discord bots like [Readybot](https://readybot.io) or [RSS Feeds to Discord Bot](https://rss.app/en/bots/rssfeeds-discord-bot) + +To add RSS feed links to your page's [contextual menu](/ai-ingestion#contextual-menu), add the `rss` property to your `docs.json`: + +```json +"rss": { + "pages": ["changelog", "status"] +} +``` + + + Changelog page in light mode with RSS feed in context menu enabled. + Changelog page in dark mode with RSS feed in context menu enabled. + diff --git a/images/changelog-filters-dark.png b/images/changelog-filters-dark.png new file mode 100644 index 00000000..a2b4e379 Binary files /dev/null and b/images/changelog-filters-dark.png differ diff --git a/images/changelog-filters-light.png b/images/changelog-filters-light.png new file mode 100644 index 00000000..0a1daef7 Binary files /dev/null and b/images/changelog-filters-light.png differ diff --git a/images/changelog-rss-ctx-dark.png b/images/changelog-rss-ctx-dark.png new file mode 100644 index 00000000..3c3f4d98 Binary files /dev/null and b/images/changelog-rss-ctx-dark.png differ diff --git a/images/changelog-rss-ctx-light.png b/images/changelog-rss-ctx-light.png new file mode 100644 index 00000000..299b6ea4 Binary files /dev/null and b/images/changelog-rss-ctx-light.png differ diff --git a/images/changelog-toc-dark.png b/images/changelog-toc-dark.png new file mode 100644 index 00000000..126cbcb9 Binary files /dev/null and b/images/changelog-toc-dark.png differ diff --git a/images/changelog-toc-light.png b/images/changelog-toc-light.png new file mode 100644 index 00000000..3d7368c9 Binary files /dev/null and b/images/changelog-toc-light.png differ