Hugo Changelog Theme

Hugo Changelog Theme is an open-source Hugo theme for publishing a product changelog with a structured workflow that separates unreleased, deprecated, and released entries. It runs on the Hugo static site generator and turns Markdown files placed in specific content folders into a versioned changelog website with dark mode and pagination.

What is Hugo Changelog Theme?

Hugo Changelog Theme is a Hugo theme that converts Markdown changelog entries into a clean, two-column static website. It takes content from three folders — experimental/, deprecated/, and released/ — and renders unreleased changes at the top, deprecations in a dropdown, and released entries sorted by weight (which is displayed as the version). The theme is maintained by jsnjack and is available on GitHub for free.

Key Features

• Dark mode — Automatically detects the system color scheme preference and switches the site to dark or light mode without user configuration.
• Two-column layout — Each changelog entry is displayed with version/date information in one column and the change description in the other, suitable for scanning release notes.
• Pagination — Released entries are paginated so long changelogs don't create one endless page.
• Mobile friendly — The layout is responsive and adapts to small screens.
• Shortcode tag types — A shortcode lets you put a colored label before an entry; available types are added, changed, fixed, deprecated, removed, performance, security, and self-hosted.
• Custom CSS and JavaScript — Site settings accept a list of CSS and JS files relative to the static/ folder, so you can extend the theme without editing its templates.
• Release workflow scripts — A Makefile provides commands like make change, make deprecation, make release, and make serve_changelog; release.py moves experimental entries into released and generates a release commit; a .githooks/post-merge hook checks that the experimental folder is empty when merging into the stable branch.

Who is it for?

• Product teams that want to communicate changes to users in a structured, dated format and need a repeatable workflow for each release.
• Open-source maintainers who use a stable/develop branch model and want the release process to automate moving changelog entries to a released section.
• Hugo developers who prefer a static site and want a ready-made theme that handles the changelog content model instead of building one from scratch.

What can you do with Hugo Changelog Theme?

• Create entries quickly — Run make change to generate a uniquely named Markdown file in the experimental folder, avoiding merge conflicts when several developers add changes.
• Flag deprecations — Run make deprecation to create a Markdown file in the deprecated folder; deprecated entries appear in a dropdown on the first page and must be removed manually when the feature reaches end of life.
• Preview and release — Use make serve_changelog to preview locally, then make release to move all experimental files to the released folder, assign a version number, and create a release commit.

How does Hugo Changelog Theme work?

1. A developer runs make change to create a Markdown file in site/changelog/content/experimental/.
2. If needed, make deprecation creates a file in the deprecated/ folder.
3. The developer edits the file content, and the change appears in the experimental section of the site.
4. make serve_changelog runs a local Hugo server for preview.
5. When the working branch is ready, make release moves all experimental Markdown files into released/, assigns a version, and generates a release commit.
6. The developer merges the working branch into the stable branch; the post-merge hook verifies the experimental folder is empty.

Pros and cons

• Pros: Automatic dark mode, clear two-column reading experience, responsive layout, and a built-in release workflow that reduces manual file moves.
• Cons: Deprecation entries are not removed automatically, so you must delete the corresponding Markdown file when a deprecated feature is retired. The release script requires the Python package python-frontmatter installed separately.

Pricing

The theme is free and open source; you clone it from the repository and use it in your own Hugo site without paying a license fee.

FAQ

How do I create a changelog entry?

Run make change in the theme's directory. It creates a Markdown file with a random name in site/changelog/content/experimental/, which you then edit with the change description. The entry appears in the experimental section on the first page.

What tag types are available for entries?

The theme provides a shortcode that accepts eight tag types: added, changed, fixed, deprecated, removed, performance, security, and self-hosted. Each renders as a label before the entry text.

Does the theme support dark mode?

Yes. The theme automatically detects the system color scheme preference and switches between dark and light modes accordingly. There is no manual toggle documented in the theme's settings.

How do I deprecate a feature?

Run make deprecation to create a Markdown file in site/changelog/content/deprecated/. Deprecated entries appear in a dropdown section on the first page. When the feature reaches its end of life, you must delete the corresponding file manually.

How do I release the changes?

Run make release. This moves all Markdown files from the experimental/ folder to the released/ folder, assigns a version number based on weight, and generates a release commit. The post-merge hook then checks that the experimental folder is empty when you merge the working branch into the stable branch.