How to Automate Markdown to PDF in GitHub Actions

If you store your documentation, reports, or CVs in a GitHub repository, manually rendering them every time you make an update is highly inefficient. By learning how to automate markdown to pdf github actions workflows, you can build a continuous integration pipeline that automatically compiles your Markdown files into beautifully formatted PDF documents every time you push code or merge a pull request.

In this step-by-step guide, we will walk through how to configure a GitHub Actions workflow that converts Markdown files to PDF, styles them with custom CSS, and uploads the final output as a downloadable build artifact.

Why Automate Markdown to PDF in GitHub Actions?

Automating your documentation pipeline offers several benefits for developers and writing teams:

• Continuous Delivery: Your rendered PDFs are always in sync with your source Markdown files.
• Standardized Styling: Avoid formatting discrepancies between team members; the runner compiles files using the exact same CSS and settings.
• Automated Releases: Automatically attach generated PDFs to GitHub Releases, making them instantly available to users.

Step 1: Writing the GitHub Actions Workflow

To get started, create a new workflow file in your repository at .github/workflows/markdown-to-pdf.yml. We will use a popular pre-built action that uses Puppeteer under the hood to render your Markdown with high-quality CSS layouts.

name: Generate PDF Documents

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**/*.md'

jobs:
  build-pdf:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Convert Markdown to PDF
        uses: baileyjm02/markdown-to-pdf@v1.2.0
        with:
          input_dir: docs
          output_dir: dist/pdf
          # If you want to use a custom CSS file:
          # theme: docs/assets/pdf-theme.css

      - name: Upload Generated PDFs
        uses: actions/upload-artifact@v4
        with:
          name: compiled-pdfs
          path: dist/pdf/

This configuration triggers the pipeline whenever files inside the docs/ folder change on the main branch. It outputs the compiled PDFs to a dist/pdf/ directory and archives them as a downloadable zip archive in your GitHub run summary.

Step 2: Styling Your PDFs with Custom CSS

One of the greatest benefits of using a chromium-based runner in GitHub Actions is the ability to style your Markdown documents using standard CSS. In your repository, you can create a style sheet (e.g., docs/assets/pdf-theme.css) to define custom typography, margins, headers, and page breaks.

For example, to specify print-specific styles like page sizes, margins, and page breaks, add this to your CSS file:

@page {
  size: A4;
  margin: 20mm;
}

body {
  font-family: 'Helvetica Neue', Arial, sans-serif;
  color: #333;
  line-height: 1.6;
}

h1, h2 {
  color: #1a56db;
}

/* Force page break before H2 elements */
h2 {
  page-break-before: always;
}

Point the workflow configuration to this theme file by uncommenting the theme option in your workflow file.

Step 3: Triggering and Validating the Workflow

Commit your new workflow file and push it to GitHub:

git add .github/workflows/markdown-to-pdf.yml
git commit -m "ci: add automatic markdown to pdf compilation"
git push origin main

Navigate to the Actions tab in your GitHub repository. You will see your workflow executing. Once complete, scroll to the bottom of the run page to find the compiled-pdfs artifact. Download it to inspect your professionally rendered documents.

Conclusion

Automating your Markdown document compilations within GitHub Actions saves time, reduces formatting errors, and integrates documentation directly into your developer workflows. If you prefer to experiment with different CSS layout configurations or need to convert individual documents instantly, feel free to try our free online editor for immediate real-time previews.