Automatically Generate PDFs From Your Markdown With Husky And Git!

In our projects we often want to automatically convert markdown files to PDF whenever we commit to Git. This we can ensure that e.g. an up-to-date PDF representation of our api-guide is always in place and versioned in Git.

For doing that, Git Hooks and Husky are great options to use. In this post, we’ll cover how to install and setup Husky to automate this.

What Is Markdown?

Markdown is a lightweight markup language that makes it easy to write formatted text. It is designed to be human-readable, so it’s a convenient and easy way to provide project documentation like an API-Reference that is versioned together with your code in the Git repository.

What are Git Hooks?

Git Hooks are scripts that run automatically on your machine at certain points when managing code with Git, such as committing or merging. These scripts can contain custom code and help with automation and ensuring code adheres to certain standards.

What Is Husky?

Husky is a Node.js package designed to help with Git Hooks. It allows you to easily configure and manage the scripts which automatically run when certain Git commands are executed.

Installation

To get started, you’ll first need to install Husky. We use husky-init here as this is a one-time command to quickly initialize a project with husky.

npx husky-init && npm install

This command will setup husky, modify the project’s package.json and create a sample pre-commit hook in .husky.

The husky-init needs to be done only once for the project. As soon as you have checked in your changes to Git, all your team-members need to do is check-out and run a npm install on their local machine.

For more information, refer to Husky’s Documentation .

Note

On an Ubuntu Linux environment you may get missing shared libs errors when doing a conversion. In that case, you need to install the following libraries:

sudo apt install libatk-bridge2.0-0 -y
sudo apt install libxkbcommon-x11-0 -y
sudo apt install libxdamage1 -y
sudo apt install libgbm1 -y
sudo apt install libpangocairo-1.0-0 -y

These are required by md-to-pdf which uses Puppeteer under the hood.

Setting Up The Command

Once Husky is installed, modify the pre-commit Git hook in .husky to:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm list -g md-to-pdf > /dev/null || npm install -g md-to-pdf

changedFiles=$(git diff --diff-filter=ACMR --cached --name-only)

echo "$changedFiles" | grep -E '^api-doc.*.md$' | while read -r mdFile; do
    pdfFile=$(echo $mdFile | sed -e "s/.md/.pdf/g")
    echo "Converting md file '$mdFile' to PDF file '$pdfFile'"
    cat "$mdFile"| md-to-pdf > "$pdfFile"
    git add "$pdfFile"
done

This code installs the md-to-pdf package globally (if not already present) and then looks through the api-doc folder and identifies any changed Markdown (.md) files within this directory. For each of these files, the md-to-pdf library is then used to actually do the conversion and create a PDF file with the same name. Finally, the generated/updated PDF file is added before the actual Git commit takes place.

Conclusion

And that’s it! Once you commit this code to your Git repository, Husky will automatically convert any Markdown (.md) files that you commit to PDF files.