How to convert Markdown to PDF with custom branding

PDF is the universal delivery format. Whether you're sending a proposal, a technical spec, or a compliance report, PDF ensures it looks identical on every device and can't be accidentally edited.

Converting Markdown to PDF while keeping your brand consistent is harder than it looks. Here's why — and how Wagoe Blueprint solves it.

The challenge with Markdown → PDF

There are three common approaches, each with real drawbacks:

1. Markdown → HTML → PDF (wkhtmltopdf, Prince) Works, but requires CSS expertise to get headers, footers, and page breaks right. Font rendering is inconsistent across platforms.

2. Markdown → DOCX → PDF (Word export) Requires Microsoft Word (paid, Windows/macOS only). Not automatable from a Linux server.

3. Markdown → LaTeX → PDF (pdflatex, xelatex) Technically excellent output, but LaTeX has a steep learning curve and fragile template system.

Wagoe Blueprint's approach: Chrome CDP

Wagoe converts Markdown to a styled HTML document and renders it to PDF using Chrome's headless DevTools Protocol (CDP). This gives you:

• Pixel-perfect rendering — Chrome's layout engine is the most tested in the world
• Custom headers and footers — Your logo appears on every page automatically
• CSS-controlled pagination — page-break-before, page-break-after, widow/orphan control
• No Word required — runs entirely on Linux servers

How to generate a branded PDF

Via the web UI

1. Upload a Markdown file in the converter
2. Choose PDF as the output format
3. Optionally select a DOCX template (the styles inform the PDF's typography)
4. Click Convert — download your PDF in seconds

Via the REST API

curl -X POST https://your-org.wagoe.com/api/v1/convert \
  -H "X-API-Key: wbk_live_..." \
  -F "md-file=@proposal.md" \
  -F "output-format=pdf" \
  -o proposal.pdf

GitHub Actions integration

- name: Generate PDF report
  run: |
    curl -X POST https://your-org.wagoe.com/api/v1/convert \
      -H "X-API-Key: ${{ secrets.WAGOE_API_KEY }}" \
      -F "md-file=@docs/report.md" \
      -F "output-format=pdf" \
      -o artifacts/report.pdf

Custom headers per organisation

On Professional and Business plans, every PDF includes a branded header — your organisation's logo, name, and optionally a tagline. This is configured once in your account settings and applied to every PDF conversion automatically.

Tips for clean PDF output

• Use ATX headings (##) rather than setext (--- underlines) for consistent heading hierarchy
• Avoid very wide tables — they wrap poorly in print. Use short column names.
• Code blocks render in a monospace font with a light background; very long lines are truncated
• Images must be referenced by URL (not local paths) when using the API

Summary

Wagoe Blueprint converts Markdown to publication-quality PDF in under 10 seconds, with your branding on every page and no manual reformatting. Add it to your CI/CD pipeline and forget about it.