Changelog

Docula can generate a changelog section for your site from markdown files. This is useful for documenting release notes, updates, and changes to your project in a structured, browsable format.

Table of Contents

• Setup
• Entry Format
  • Front Matter Fields
• Draft Entries
• File Naming
• Generated Pages
• JSON Feeds
  • Example Structure
• Styling

Setup

Create a changelog folder inside your site directory and add markdown (.md or .mdx) files for each entry:

site
├───changelog
│   ├───2025-01-15-initial-release.md
│   ├───2025-02-01-new-features.md
│   └───2025-03-10-bug-fixes.md
├───logo.svg
├───favicon.ico
└───docula.config.mjs

Entry Format

Each changelog entry is a markdown file with front matter:

---
title: "Initial Release"
date: 2025-01-15
tag: "Release"
---

We're excited to announce the initial release! Here's what's included:

- Feature A
- Feature B
- Bug fix C

Front Matter Fields

Draft Entries

To hide a changelog entry from the build output, add draft: true to the front matter:

---
title: "Upcoming Feature"
date: 2025-04-01
tag: "Feature"
draft: true
---

This entry won't appear on the site until `draft` is removed or set to `false`.

Draft entries are still parsed but excluded from the changelog listing, individual entry pages, sitemaps, and feeds. This is useful for preparing entries ahead of a release.

File Naming

Files can optionally be prefixed with a date in YYYY-MM-DD- format. The date prefix is stripped to create the URL slug:

• 2025-01-15-initial-release.md → /changelog/initial-release/
• new-features.md → /changelog/new-features/

Generated Pages

When changelog entries are found, Docula generates:

• Changelog listing page at /changelog/ — shows all entries sorted by date (newest first) with titles, dates, tags, and content
• Individual entry pages at /changelog/{slug}/ — a dedicated page for each entry with a back link to the listing

Changelog URLs are also automatically added to the generated sitemap.xml.

JSON Feeds

When changelog entries exist, Docula automatically generates two JSON Feed files at the root of your output directory:

• changelog.json — contains all changelog entries
• changelog-latest.json — contains only the most recent entries, limited by the changelogPerPage setting (default 20)

Both files follow the JSON Feed v1.1 specification and include full entry content in both HTML and markdown formats, making them useful for programmatic consumption, integrations, or building custom changelog UIs.

Example Structure

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "My Project",
  "description": "Project description",
  "home_page_url": "https://your-site.com/",
  "feed_url": "https://your-site.com/changelog.json",
  "items": [
    {
      "id": "initial-release",
      "title": "Initial Release",
      "url": "https://your-site.com/changelog/initial-release",
      "date_published": "2025-01-15",
      "date_modified": "2025-01-15",
      "summary": "We're excited to announce the initial release!",
      "content_html": "
We're excited to announce the initial release!
",
      "content_text": "We're excited to announce the initial release!",
      "tags": ["Release"]
    }
  ]
}

Styling

Tags receive a CSS class based on their value (e.g., a tag of "Bug Fix" gets the class changelog-tag-bug-fix). Both the modern and classic themes include built-in colors for the following tags:

Any custom tag value also works — it receives a CSS class derived from the tag name in kebab-case. You can style custom tags by adding classes in your variables.css:

.changelog-tag-my-custom-tag {
  background-color: #e0f2fe;
  color: #0369a1;
}