Changelog
Publish and manage a changelog to keep users informed about documentation and product updates.
Overview
The Changelog feature lets you publish a running log of product updates, new features, bug fixes, and documentation changes. Entries can be created manually in the dashboard or generated automatically from GitHub deployments with AI. Published entries appear on a dedicated page on your documentation site and are also available through RSS and JSON feeds.
Access the changelog from the Changelog item under the Manage section in your project sidebar.
Creating a Changelog Entry
Open the changelog
Navigate to Changelog in the sidebar. You see a list of all existing entries with their status, date, and tags.
Click New Entry
Click the New Entry button in the top-right corner. A new entry form opens in an editor panel.
Fill in the details
Complete the entry fields (described in the next section). Write the body content using the same Visual or Code editor available in the main documentation editor.
Publish or schedule
Click Publish to make the entry live immediately, or click Schedule to set a future publication date.
Entry Fields
| Field | Required | Description |
|---|---|---|
| Title | Yes | A concise headline for the update (e.g., "Introducing AI-Powered Search") |
| Date | Yes | Publication date. Defaults to today. Can be set to a future date for scheduling. |
| Description | Yes | The full body content. Supports MDX with all HolyDocs components. |
| Tags | No | Categorize entries with tags. Common tags: feature, fix, improvement, deprecation, breaking. |
| Author | No | Displayed with the entry. Defaults to the logged-in user's display name and avatar. |
| Image | No | A hero image displayed at the top of the entry. Recommended size: 1200x630px. |
Automatic Changelog from Deploys
If your project is connected to GitHub, HolyDocs can generate a changelog entry automatically after each successful production deployment.
- Open Settings → Add-ons
- Enable Changelog page
- Enable AI release notes from deploys
When this is enabled, HolyDocs compares the latest deployed commit against the previous successful deployment, sends the diff to the configured AI model, and publishes a user-facing changelog entry automatically.
Auto-generated entries are stored in the same changelog system as manual entries. You can edit, unpublish, or delete them from the dashboard before or after they go live.
Tags
Tags help readers filter the changelog by category. Create custom tags or use the suggested defaults:
Publishing and Scheduling
Publish Immediately
Click Publish to make the entry visible on your changelog page right away. A deployment is triggered automatically to update the live site.
Schedule for Later
Set the Date field to a future date and click Schedule. The entry is stored as a draft and automatically published at midnight (in your project timezone) on the specified date.
Scheduled entries are processed by a Cloudflare Queue job that runs every hour. The actual publication time may be up to 60 minutes after midnight on the scheduled date.
Draft Entries
Save an entry without publishing by clicking Save draft. Drafts appear in your dashboard changelog list with a "Draft" badge but are not visible to readers.
Changelog Page on Your Doc Site
When the changelog feature flag is enabled (see Settings > Advanced), your documentation site includes a /changelog page that displays all published entries in reverse chronological order.
The changelog page includes:
- Entry cards — Each entry shows the title, date, author, tags, and a preview of the description
- Tag filter — Readers can filter entries by tag using a dropdown at the top of the page
- Pagination — Entries are paginated with 10 entries per page
- Full entry view — Clicking an entry opens the full content with all MDX components rendered
RSS Feed
HolyDocs automatically generates an RSS feed for your changelog at:
texthttps://your-project.holydocs.com/changelog/rss.xml
The RSS feed includes:
- Entry title, date, and description (as HTML)
- Author information
- Tags as RSS categories
- A link back to the full entry on your doc site
Share the RSS feed URL with your users so they can subscribe in their preferred RSS reader. You can also link to the feed from your documentation pages or embed it in a Slack channel using Slack's RSS integration.
Headless Endpoints
For sites that want to reuse changelog content outside the docs renderer, HolyDocs also exposes headless endpoints on the same docs domain:
text/changelog/index.json/changelog/{slug}.json/changelog/rss.xml
This makes it easy to power a marketing-site changelog, in-app release feed, or email automation from the same published entries that render inside your docs site.
Linking from Documentation Pages
Reference changelog entries from within your documentation using standard Markdown links:
mdxCheck out our [latest updates](/changelog) to see what's new.We recently shipped [AI-powered search](/changelog/ai-powered-search) —read the full announcement for details.
Changelog entry URLs follow the pattern /changelog/{slug}, where the slug is auto-generated from the entry title.
Managing Entries
Editing
Click any entry in the changelog list to open it in the editor. Changes are saved when you click Update. Updating a published entry triggers a redeployment.
Unpublishing
Click the status badge on a published entry and select Unpublish to revert it to draft status. The entry is removed from the live changelog page on the next deployment.
Deleting
Click the Delete button on an entry's detail view. A confirmation dialog prevents accidental deletion. Deleted entries cannot be recovered.
Reordering
Entries are always displayed in reverse chronological order by date. To change the order, adjust the date field.
Best Practices
Changelog entries should communicate value to the reader, not list internal ticket numbers. Instead of "Fixed issue #4521," write "Fixed a bug where search results were not loading on pages with special characters."
Establish a tagging convention early and stick with it. Readers rely on tags to filter for the updates they care about. Five to seven tags is a good range — enough to be useful, few enough to stay meaningful.
A screenshot or short GIF of a new feature communicates more than a paragraph of text. Use the hero image field for major announcements and inline images for step-by-step walkthroughs.
Publish your changelog entry at the same time the feature goes live. Stale changelogs erode trust. If a feature ships on Tuesday, the entry should go out on Tuesday — not the following Friday.
Use the breaking tag and lead with a clear description of what changed and what action is required. Include migration steps or a link to a migration guide.