Create changelog as .pdf file

[ckrenslehner]

Hi!
First of all, thanks for the great crate! Thanks to git-cliff we actually keep a changelog via our commits. Otherwise, for sure we would not have a consistent changelog in our project.
I have a general question. Has anyone suggestions about converting the markdown to a pdf. Currently, we use a separate postprocessing step using pandoc. Do you have an alternative approach for me by chance?

Greetings, Christian

[orhun]

Hey!

Thanks to git-cliff we actually keep a changelog via our commits. Otherwise, for sure we would not have a consistent changelog in our project.

Very happy to hear that :)

Has anyone suggestions about converting the markdown to a pdf.

Ah, interesting question! I haven't tried something like that yet.

Currently, we use a separate postprocessing step using pandoc. Do you have an alternative approach for me by chance?

Can you share how that works? I can look into it and either come up with a better alternative or help you improve the workflow.

[ckrenslehner]

Hey :-)

Sure. We use git-cliff in several projects. One project uses CMake as build system and this is the project where we share our changelog as .pdf file with our co-workers.

The flow at the moment is to run a CMake target:

find_package(Git QUIET)
if(GIT_FOUND AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")
  add_custom_target(
    __CREATE_CHANGELOG__
    COMMAND
      git cliff --tag ${VERSION_TAG_SEMVER} -w ${CMAKE_CURRENT_SOURCE_DIR}
      -c ${CMAKE_CURRENT_SOURCE_DIR}/release-util/cliff.toml -o ${CMAKE_CURRENT_SOURCE_DIR}/CHANGELOG.md
    COMMAND
      pandoc --pdf-engine=xelatex --template
      ${CMAKE_CURRENT_SOURCE_DIR}/release-util/eisvogel --from=gfm --to=pdf -o
      ${CMAKE_CURRENT_SOURCE_DIR}/CHANGELOG.pdf ${CMAKE_CURRENT_SOURCE_DIR}/CHANGELOG.md
    )
endif()

Which is more or less the CMake style of e.g. a just file calling git-cliff and then calling pandoc with latex in the background for conversion of the markdown to pdf. I mean there is nothing wrong with this approach, but I was just wondering if there is a different solution.

Greetings

[orhun]

Thanks for sharing! I just tried locally and worked pretty well - I don't think that we can find a more solid way than this :)

Btw feel free to send a PR to add a more minimal version of this command (e.g. pandoc --from=gfm --to=pdf -o CHANGELOG.pdf CHANGELOG.md) to Tips and Tricks

[ckrenslehner]

Thanks,

depending on the configuration of git-cliff one need to specify xelatex as pdf engine because of the unicode characters. Unfortunately, the standard font of pandoc does not support unicode characters, so no 🚀 and so on is rendered in the pdf output.

I did not figure out how to properly set the font in pandoc and which font is the best to use. But as soon as i figure it out, I will open a PR. :-)

[orhun]

Sounds good, thanks for the PR!

[alerque]

Currently, we use a separate postprocessing step using pandoc. Do you have an alternative approach for me by chance?

I think this is the right approach. And Pandoc is a pretty good option for this, possibly for this use case paired with one of the more light weight PDF engines rather than the default LaTeX one which is a beast. It would be completely out of scope for git-cliff to typeset anything, and even conversion from Markdown to HTML is probably best left to specialized tooling. The template system can only realistically be ergonomic to configure and use if it is targeting one output format. Conversion to other formats can be very complex (depending on the output, e.g. coming from Markdown to PDF is much more complicated than to HTML) and building anything into Git Cliff would inevitably be underwhelming. There are good tools for post processing Markdown into other formats already. Using one of them is the right approach.

[orhun]

Thanks for the reply @alerque, I agree with your points :)

[ckrenslehner]

Hi again! I am still on my pursuit to convert a git-cliff markdown (standard config including lots of emoji power) to a pdf file. This is surprisingly hard because of the missing font support for unicode and idk maybe my lack of pandoc power.

However, I was remembering a 🦀 alternative to latex typst. Pandoc does support converting markdown to a typst file (this conversion seems to be relatively straight forward). The resulting .typ file can easily converted into a pdf via the typst cli: typst compile CHANGELOG.typ.

Long story, short: I can now use pandoc and typst to convert a git-cliff changelog with all the emojis without worries.

docker run --rm --volume $"($env.PWD):/data" pandoc/typst ./CHANGELOG.md -o CHANGELOG.pdf --pdf-engine=typst --from-markdown --no-highlight
typst compile CHANGELOG.typ
start CHANGELOG.pdf

Interestingly, there seems to be a direct pdf engine keyword for this, but this again does not render the emojis
docker run --rm --volume $"($env.PWD):/data" pandoc/typst ./CHANGELOG.md -o CHANGELOG.pdf --pdf-engine=typst does not work for me.

If you would be open for a PR which would output a .typ file maybe additionally to a markdown file (triggered by cliff.toml of cli arg), I could try implementing this. Seems to be a funny side quest and would eliminate the need of pandoc for me. :-D
There is even an implementation for typst which supports converting markdown.

https://github.com/SabrinaJewson/cmarker.typ/blob/main/src/lib.rs#L25
https://typst.app/universe/package/cmarker/

Greetings, Christian

[ckrenslehner]

However, the comment of @alerque is also true in this case.
But maybe we could add this to the Tips and Tricks section as well. :-)

[orhun]

If you would be open for a PR which would output a .typ file maybe additionally to a markdown file (triggered by cliff.toml of cli arg), I could try implementing this.

Actually it would be fun to see how that's possible. Feel free to give it a shot :)

But maybe we could add this to the Tips and Tricks section as well. :-)

Yup, please!