Changelog

Keep your end-users up to date on the latest updates and/or announcements using the Changelog.

How It Works

Feed

The Changelog feed displays posts from newest to oldest. New posts always appear at the top of the feed.

Posts

Each posts represents new updates and/or announcements. A post can include content, an author, and a post date.

Customize

You can customize how your Changelog appears in Appearance > Changelog.

Layout

• Continuous: Displays the image, header, and content directly in the feed
• Collapsed: Displays the image and header only. Content expands when selected.

Date Display

• Exact: Show the post's publish date.
• Relative: Shows the date relative to the current day.

Author Display

• Choose whether to show or hide the author on each post

Create a Post

In Edit Mode, you can create and edit Changelog posts in the same manner as a Guides page, with a few key differences:

• New posts automatically appear at the top of the sidebar and feed (newest to oldest).
• Nesting is not supported.
• Changelog posts are not versioned.

You can also assign a type to each post to help categorize updates. Available types include: Added, Fixed, Improved, Deprecated, Removed, and No type.

Manage Metadata

You can edit metadata from the post's drop-down menu, just like a Guides page. Metadata controls how your post appears for SEO and when shared on social media.

Git-Backed Changelogs

On projects with bi-directional sync enabled, changelogs are stored in your Git repository under the changelogs/ directory on the main branch. You can write a changelog as a Markdown file, commit it, and bi-directional sync brings it into ReadMe. Edit it in ReadMe, and the change syncs back to the repo.

File Structure

Changelog files use the following frontmatter:

---
title: string        # Title of the changelog post
author: string       # Author name displayed on the post
date: string         # Publish date (e.g., "2025-01-15")
type: string         # Post type: Added, Fixed, Improved, Deprecated, Removed
hidden: boolean      # Visibility of the post
---

Your changelog content goes here…

The publish date in the frontmatter drives ordering across every surface: the changelog list, sidebar, RSS feed, sitemap, llms.txt, and the API. Make sure this field is set correctly.

Page History, Diff, and Restore

Git-backed changelogs support page history, diff, and restore, matching the behavior of docs and reference pages. You can view what changed in a changelog post and recover an earlier version from the page history.

RSS Feed

Users can subscribe to your changelog. Simply add .rss to the end of your changelog URL

yoursubdomain.readme.io/changelog.rss

Or for custom domains:

customdomain.com/changelog.rss

and for enterprise projects with a custom domain:

customdomain.com/[project]/changelog.rss

Once you have your URL, you can use any RSS feed widget/tool to input the URL and generate HTML to embed it (here's an example)!