CHANGELOG into docx

At work we started using CHANGELOG along with Semantic Versioning. But the release notes are distributed with the installer of each tool and it used to be in RTF format. While Markdown is very nice textual format, our users usually don’t have installed any editor for it, so distributing it as such is rather inconvenient.

So I was looking for a solution that would allow us to use the Markdown-based list of changes and still provide users with release notes as they are used to. Here is an example of the changelog file:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.

There is wonderful tool to convert the Markdown into almost anything else - pandoc. You can build yourself a RTF with simple command line this:

pandoc CHANGELOG.md -s -o CHANGELOG.rtf

The type is detected from the suffix of the output option -o and -s specifies that the RTF should be standalone and contain all the setup and such.

Other option I wanted was to allow some portions of the file to be there for reference purpose, but not converted into the output. When I look for a solution, I found this gist. You can mark any heading with tag noexport like this:

## Internal notes {.noexport}

Everything structurally under this heading will be ignored during the output, you just need to call the pandoc like this:

pandoc CHANGELOG.md --lua-filter=noexport-subtrees.lua -s -o CHANGELOG.rtf

It is also possible to change the output format with using of Pandoc Templates. Other option is to use the Word output format (that works for our users, too) and use reference document. You can output the document like this:

pandoc CHANGELOG.md --lua-filter=noexport-subtrees.lua -o CHANGELOG.docx

Then the document can be modified to your liking and used as reference like this:

pandoc CHANGELOG.md --lua-filter=noexport-subtrees.lua --reference-doc reference.docx -o CHANGELOG.docx

Styles and general formatting will be taken from the reference document, just the contents will come from the input Markdown. Overall the pandoc offers tons of options and I was very happy with my solution.