Skip to content

feat(changelog): add opt-in Markdown formatting for the output - #1610

Open
ChrisJr404 wants to merge 1 commit into
orhun:mainfrom
ChrisJr404:feat/changelog-format-markdown
Open

feat(changelog): add opt-in Markdown formatting for the output#1610
ChrisJr404 wants to merge 1 commit into
orhun:mainfrom
ChrisJr404:feat/changelog-format-markdown

Conversation

@ChrisJr404

Copy link
Copy Markdown
Contributor

Closes #678. Adds an opt-in [changelog] format = true that runs the rendered changelog through a Markdown formatter, so you can get tidy output without fighting the template with {%- and trim everywhere.

It's off by default and the output is byte-for-byte what it is today unless you turn it on. When enabled it only kicks in for Markdown output (stdout or a .md file, detected by extension) — point --output at something else and it's skipped with a warning.

On the crate choice: the issue floated prettify-markdown, but as the last commenter noted that one's still alpha and doesn't cover much of Markdown. I went with a pulldown-cmark + pulldown-cmark-to-cmark round-trip instead — both are actively maintained and GFM-complete. The formatting is deliberately conservative: it keeps - as the bullet marker (matching the default templates, so existing changelogs don't churn - -> *), enables tables/strikethrough/task lists/footnotes so those survive, and doesn't reflow text or rewrite links.

One tradeoff worth flagging: the round-trip escapes bare bracket text, so a heading like ## [unreleased] or a first release's ## [1.0.0] with no compare URL comes out as ## \[unreleased\]. That's standard CommonMark formatter behavior (prettier and mdformat do the same — bare [text] is an ambiguous undefined shortcut link) and headings that are real links like ## [1.0.0](…/compare/…) are untouched. Didn't want to hack around it silently; happy to add an option to disable bracket escaping if you'd rather.

Kept it in git-cliff-core as a small markdown helper so it's unit-testable. Tests: the helper normalizes a messy-but-valid changelog and is idempotent, a clean one round-trips unchanged, and at the generate() level format = true produces the formatted output while leaving it unset is identical to before. cargo test -p git-cliff-core is green (75 passed), cargo +nightly fmt --check and cargo clippy are clean. Also smoke-tested the binary with GIT_CLIFF__CHANGELOG__FORMAT=true against this repo.

@ChrisJr404
ChrisJr404 requested a review from orhun as a code owner August 18, 2026 04:46
@welcome

welcome Bot commented Aug 18, 2026

Copy link
Copy Markdown

Thanks for opening this pull request! Please check out our contributing guidelines! ⛰️

@ChrisJr404

Copy link
Copy Markdown
Contributor Author

Heads up on the two red checks, both look unrelated to this change. The Test suite job runs every test green and only fails on the codecov upload step (gpg: Can't check signature: No public key), which is the same failure that's currently red on main. The Links check is a lychee timeout on the contributor-covenant.org URL in CODE_OF_CONDUCT.md, a file this PR doesn't touch. A re-run should clear both whenever you get a chance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Format markdown

1 participant