feat(changelog): add opt-in Markdown formatting for the output - #1610
Open
ChrisJr404 wants to merge 1 commit into
Open
feat(changelog): add opt-in Markdown formatting for the output#1610ChrisJr404 wants to merge 1 commit into
ChrisJr404 wants to merge 1 commit into
Conversation
|
Thanks for opening this pull request! Please check out our contributing guidelines! ⛰️ |
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #678. Adds an opt-in
[changelog] format = truethat runs the rendered changelog through a Markdown formatter, so you can get tidy output without fighting the template with{%-andtrimeverywhere.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
.mdfile, detected by extension) — point--outputat 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 apulldown-cmark+pulldown-cmark-to-cmarkround-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-coreas a smallmarkdownhelper 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 thegenerate()levelformat = trueproduces the formatted output while leaving it unset is identical to before.cargo test -p git-cliff-coreis green (75 passed),cargo +nightly fmt --checkandcargo clippyare clean. Also smoke-tested the binary withGIT_CLIFF__CHANGELOG__FORMAT=trueagainst this repo.