Automating Document Compilation with Git Hooks

Keeping project documentation updated is a constant challenge for development teams. Often, developers modify code and forget to recompile the corresponding PDF guides or user manuals. This leads to outdated instructions and mismatched versions. By setting up local git hooks markdown to pdf compile tasks, you can automate document generation directly on your local machine, ensuring that every commit or push contains updated, accurate PDF outputs.

In this guide, we will configure a pre-commit or pre-push Git hook that detects edited Markdown files and renders them to PDFs using lightweight CLI tools.

Understanding Git Hooks

Git hooks are scripts that Git executes automatically when specific events occur in your workflow, such as:

• pre-commit: Runs before you type a commit message. Excellent for linting, checking code formatting, or updating local artifacts.
• pre-push: Runs before files are sent to a remote repository. Great for running test suites or full compilation pipelines.

Using hooks ensures documentation is compiled locally before code hits your shared remote branches.

Setting Up a Pre-Commit hook

Let’s write a Shell script that hooks into the pre-commit event, detects modified Markdown files in a specific folder, and compiles them.

Step 1: Locating the Hooks Directory

Open your terminal and navigate to the hidden .git folder in your project repository:

cd .git/hooks

Here, you will find several sample files (e.g., pre-commit.sample). Create a new, clean file named exactly pre-commit (no extension):

touch pre-commit
chmod +x pre-commit

Step 2: Writing the Compilation Script

Open the pre-commit file in your favorite editor and paste the following bash script:

#!/bin/sh

# Find all staged Markdown files in the 'docs/' directory
staged_files=$(git diff --cached --name-only --diff-filter=ACM | grep '^docs/.*\.md$')

if [ -z "$staged_files" ]; then
    # No documentation changed, exit cleanly
    exit 0
fi

echo "Compiling staged Markdown documents to PDF..."

# Ensure output directory exists
mkdir -p dist/pdf

for file in $staged_files; do
    filename=$(basename "$file" .md)
    echo "Processing: $file"
    
    # We will use md-to-pdf CLI in this hook
    if command -v md-to-pdf >/dev/null 2>&1; then
        md-to-pdf "$file" --output-path "dist/pdf/${filename}.pdf"
        
        # Stage the newly compiled PDF file
        git add "dist/pdf/${filename}.pdf"
    else
        echo "Error: md-to-pdf CLI utility not found on your system."
        echo "Install it via: npm install -g md-to-pdf"
        exit 1
    fi
done

echo "Documents successfully updated and staged."
exit 0

How the Script Works:

1. git diff --cached --name-only: Checks which files are staged for the upcoming commit.
2. grep '^docs/.*\.md$': Filters the list to target only Markdown files inside the docs/ folder.
3. md-to-pdf: Calls the CLI tool to convert the files.
4. git add ...: Automatically stages the compiled PDF, ensuring it is included in the same commit.

Managing Git Hooks via Husky

If you are working in a JavaScript or Node.js environment, managing raw .git/hooks files can be challenging since they are not pushed to Git. Instead, you can use Husky to configure and share Git hooks across your entire team.

Install Husky and initialize it:

npm install husky --save-dev
npx husky init

This creates a .husky/ directory in your root folder. You can add your script to .husky/pre-commit to ensure every developer on your team compiles PDFs identically.

Conclusion

Automating documentation rendering via Git hooks ensures that your compiled PDF assets never fall out of sync with your codebase. By compiling locally on commit or push, you protect your repositories from stale files. If you need to make quick, visual adjustments to a document or want a clean real-time sandbox editor, feel free to try our web-based online editor.