Merge branch 'kathryn/changelogs-guide' of https://github.com/mintlify/docs into kathryn/changelogs-guide

Author: ethanpalm

changelog.mdx

@@ -1,7 +1,6 @@
 ---
 title: "Product Updates"
 description: "New updates and improvements"
-mode: "center"
 ---
 
 <Update label="May 2025">

components/update.mdx

@@ -22,27 +22,24 @@ Use the `Update` component to display changelog entries, version updates, and re
   ### Features
   - Responsive design
   - Anchor for each update
+  - Generated RSS feed entry for each update
 </Update>
 
 ## How to use
 
 ```mdx Update example
-<Update label="2024-10-12" description="v0.1.1">
-  This is how you use a changelog with a label 
-  and a description.
-</Update>
-<Update label="2024-10-11" description="v0.1.0">
-  This is how you use a changelog with a label 
-  and a description.
+<Update label="2024-10-11" description="v0.1.0" tags={["Mintlify"]}>
+  This is how you use a changelog with a label, description,
+  and tags.
 </Update>
 ```
 
-Use multiple `Update` components to create changelogs. Each `label` creates an anchor and an item in the table of contents.
+Use multiple `Update` components to create [changelogs](/guides/changelogs).
 
 ## Props
 
 <ResponseField name="label" type="string" required>
-  Label for the update. Appears to the left of the update and creates an anchor link.
+  Label for the update. Appears to the left of the update and creates an anchor link. For this reason, labels should be unique.
 </ResponseField>
 
 <ResponseField name="tags" type="string[]">
@@ -53,6 +50,21 @@ Use multiple `Update` components to create changelogs. Each `label` creates an a
   Description of the update. Appears below the label and tag.
 </ResponseField>
 
-<ResponseField name="rss" type="object: { title: string; description: string; }">
-  The title and description that will appear in the RSS feed entry. Learn more about [subscribable changelogs](/guides/changelogs).
+<ResponseField name="rss" type="object">
+  Title and description that will appear in the RSS feed entry for the update.
+  
+  ```md
+  <Update label="v1.0.1" rss={{ title: "v1.0.1 released", description: "Bug fixes and improvements" }}>
+    # What's New in v1.0.1
+    
+    * Bug fixes
+    * Improvements
+  </Update>
+  ```
+
+<div style={{ border: '2px solid #ff00ff' }}>
+  TODO: insert screenshot of RSS feed with title and description
+</div>
+
+  Learn more about [subscribable changelogs](/guides/changelogs#subscribable-changelogs).
 </ResponseField>

docs.json

@@ -118,6 +118,7 @@
               "react-components",
               "settings/custom-scripts",
               "settings/seo",
+              "guides/changelogs",
               "guides/hidden-pages",
               "settings/broken-links",
               "guides/monorepo",
@@ -492,4 +493,4 @@
       "destination": "authentication-personalization/personalization-setup"
     }
   ]
-}
+}

guides/changelogs.mdx

@@ -8,9 +8,17 @@ Adding a changelog page to your docs is as simple as adding an MDX file with [Up
 
 Check out the [Mintlify changelog](/changelog) as an example: you can include links, images and text content, and demos of your new product features in each update.
 
+# Table of contents
+
+Each `Update` element label is automatically used to create a table of contents on the right side of the page:
+
+<Frame caption="Table of contents">
+![Changelogs with table of contents](/images/changelog-toc.png)
+</Frame>
+
 # Tag filters
 
-Adding tags to your Update components will make a tag list appear on the right side of your changelog document which can be used for filtering Update items:
+Adding tags to your `Update` components will make a tag list appear on the right side of your changelog document which can be used for filtering entries:
 
 ```mdx
 <Update label="v0.0.10" tags={["Wintergreen", "Spearmint"]}>
@@ -26,20 +34,31 @@ Adding tags to your Update components will make a tag list appear on the right s
 </Update>
 ```
 
-![Changelogs with filters](/images/changelog-filters-1.png)
+<Frame caption="Tag filters">
 ![Changelogs with activated filters](/images/changelog-filters-2.png)
+</Frame>
+
+<Tip>
+  Some page settings may automatically hide the table of contents and changelog filters: when your page has mode: 'custom', 'center', or 'wide'. Learn more about [page modes](/pages#page-mode).
+</Tip> 
 
 # Subscribable changelogs
 
-Using the Update component on your changelog page also automatically creates a subscribable RSS feed for your changes at the page URL + "/rss.xml"
+Using the `Update` component on your changelog page also automatically creates a subscribable RSS feed for your changes at the page URL + "/rss.xml".
 
-After publishing a new Update on the page, it will be automatically included in the RSS feed for that page. RSS feeds can be integrated with Slack, email, or other subscription tools for your users. 
+<div style={{ border: '2px solid #ff00ff' }}>
+  TODO: insert XML screenshot
+</div>
 
-You can customize the text included for each Update item with the rss property: 
+After publishing a new `Update` on the page, it will be automatically included in the RSS feed for that page. RSS feeds can be integrated with Slack, email, or other subscription tools for your users.
 
-```mdx
-<Update label="v0.0.10" rss={title: "Version 0.0.10 is now live", description: "Including updates to AI models and more"} feedDescription=>
-  Lorem ipsum dolor sit amet, consectetur adipiscing elit...
-</Update>
-```
+The `"rss"` property in docs.json accepts an array of pages where the RSS feed link will be added to the contextual menu:
 
+```json
+"rss": {
+  "pages": ["changelog", "status"]
+}
+```
+<div style={{ border: '2px solid #ff00ff' }}>
+  TODO: insert changelog contextual menu screenshot
+</div>