Markdown to PDF Conversion Workflow

Turning a Markdown file into a clean, professional PDF is something every developer eventually needs — whether for a project proposal, technical specification, or client deliverable. The challenge is that Markdown has no inherent styling, so the conversion tool you choose determines the quality of the output. This guide covers three reliable approaches, from command-line power tools to browser-based converters.

Pandoc: The Universal Converter

Pandoc is the most capable Markdown-to-PDF tool available. It converts Markdown through LaTeX as an intermediate format, which means you get typographic quality on par with academic papers — proper ligatures, justified text, hyphenation, and mathematical typesetting.

Install Pandoc and a LaTeX distribution (TeX Live on Linux, MacTeX on macOS, or MiKTeX on Windows), then run:

pandoc document.md -o document.pdf

This minimal command produces a serviceable PDF with default styling. For better results, specify a template and metadata:

pandoc document.md \
  --pdf-engine=xelatex \
  --template=mytemplate.tex \
  --metadata title="Project Specification" \
  -V geometry:margin=1in \
  -V fontsize=12pt \
  -o document.pdf

Key options worth knowing:

Pandoc also supports YAML front matter in your Markdown files, pulling title, author, and date into the PDF header automatically.

The main drawback of Pandoc is the LaTeX dependency. A full TeX Live installation is several gigabytes, and LaTeX errors can be cryptic. If you only need simple documents, the lighter alternatives below may save you time.

WeasyPrint: HTML and CSS Pipeline

WeasyPrint takes a different approach: it converts Markdown to HTML first, then renders the HTML to PDF using CSS for styling. This pipeline is ideal if you already have CSS stylesheets for your documentation and want the PDF to match your web output.

pandoc document.md -t html5 --standalone -o document.html
weasyprint document.html document.pdf

Or chain them in one step:

pandoc document.md -t html5 | weasyprint - document.pdf

The CSS-driven approach gives you precise control over the visual output:

@page {
  size: A4;
  margin: 2cm;
  @bottom-center {
    content: counter(page);
  }
}

body {
  font-family: "Inter", sans-serif;
  line-height: 1.6;
  color: #1a1a1a;
}

h1 { font-size: 24pt; margin-bottom: 12pt; }
h2 { font-size: 18pt; border-bottom: 1px solid #ccc; }
code { background: #f5f5f5; padding: 2px 4px; font-size: 9pt; }
pre code { display: block; padding: 12pt; overflow-wrap: break-word; }

WeasyPrint handles page breaks better than most browser-based solutions. You can use page-break-before: always on headings or page-break-inside: avoid on tables and code blocks to keep related content together.

The limitation is that WeasyPrint's CSS support, while solid for print media, does not match a full browser engine. Complex flexbox layouts and certain CSS grid configurations may render differently than expected.

Online Converters and Browser-Based Workflows

When installing command-line tools is not an option, several online services and browser workflows produce acceptable results.

Markdown to HTML first: Convert your Markdown to styled HTML, then use your browser's built-in print-to-PDF function. This gives you the browser's full rendering engine, which handles CSS correctly. The downside is limited control over page breaks and headers.

# Generate standalone HTML with embedded styles
pandoc document.md --standalone --css=style.css --self-contained -o document.html
# Open in browser, then Ctrl+P → Save as PDF

Dedicated online tools: Services like md2pdf, MarkdowntoPDF, and CloudConvert accept Markdown uploads and return styled PDFs. These are convenient for one-off conversions but may not handle custom CSS, complex tables, or math notation reliably.

VS Code workflow: The "Markdown PDF" extension for VS Code converts .md files to PDF directly from the editor. It uses Chrome's rendering engine under the hood, so the output matches what you see in the Markdown preview pane. Configuration options let you set margins, orientation, and header/footer content.

Choosing the Right Tool

Regardless of which tool you choose, always proof the PDF output. Conversion artifacts — missing images from relative paths, broken table layouts, or code overflowing margins — are common and only visible in the final rendering.

For a quick preview of how your Markdown renders before converting to PDF, use the live preview tool at /tools/markdown-preview. It shows rendered output in real time so you can fix formatting issues before committing to a PDF export.