Learn how to convert Markdown files to professional PDFs using Pandoc, browser tools, and online converters. Covers styling, templates, headers, footers, and automation.
Markdown has become the de facto standard for developer documentation, README files, technical specifications, and knowledge bases. Its simplicity is its greatest strength — plain text with lightweight formatting syntax that reads naturally even without rendering.
But Markdown's simplicity becomes a limitation when you need to share documents with non-technical stakeholders, submit formal reports, or archive documentation in a stable, printable format. That is where PDF comes in.
PDF preserves exact layout, typography, and formatting across every device and operating system. Converting Markdown to PDF gives you the best of both worlds: write in a fast, version-control-friendly format, and distribute in a polished, universal one.
This guide covers every approach to Markdown-to-PDF conversion, from quick online tools to fully automated pipelines with custom styling.
At a fundamental level, Markdown-to-PDF conversion follows a multi-stage pipeline. Understanding these stages helps you troubleshoot issues and customize output.
Different tools handle these stages differently. Some go through HTML as an intermediate step (using a browser engine for layout), while others go through LaTeX (using TeX for typographic precision). The path you choose affects available features, output quality, and complexity.
The Markdown-to-PDF ecosystem offers tools ranging from simple drag-and-drop converters to sophisticated document processing pipelines. Here is how they compare:
| Tool | Method | Styling | Code Highlighting | Math Support | Templates | Difficulty |
|---|---|---|---|---|---|---|
| Pandoc | LaTeX / HTML | CSS or LaTeX | Excellent | LaTeX math | Custom templates | Medium-High |
| ConvertIntoMP4 | Browser engine | Automatic | Yes | Limited | Preset styles | Easy |
| md-to-pdf | Puppeteer | CSS | Yes (highlight.js) | KaTeX | Custom CSS | Medium |
| Typora | Webkit | CSS themes | Yes | MathJax | Theme system | Easy |
| Grip + Print | GitHub API | GitHub CSS | Yes | Limited | None | Easy |
| VS Code + Extension | Varies | CSS | Yes | Varies | Varies | Easy-Medium |
| Quarto | Pandoc + Lua | SCSS/CSS | Excellent | LaTeX math | Project templates | Medium-High |
| WeasyPrint | Custom engine | CSS | Manual | No | CSS templates | Medium |
Pro Tip: For one-off conversions, use our PDF converter — just upload your Markdown file and download a styled PDF. No installation, no configuration, no dependencies.
The fastest path from Markdown to PDF requires no tools, no installation, and no command line. Online converters handle the entire pipeline in the cloud.
Our document converter supports Markdown files natively:
.md file (or paste Markdown content directly)This approach is ideal for:
Online tools prioritize convenience over customization. You may find limitations around:
For these use cases, a local tool like Pandoc provides the control you need.
Pandoc is the most powerful and flexible Markdown-to-PDF converter available. It is open source, actively maintained, and used by thousands of organizations for document processing.
Pandoc is available on all major platforms:
# macOS (Homebrew)
brew install pandoc
# Ubuntu / Debian
sudo apt-get install pandoc
# Windows (Chocolatey)
choco install pandoc
# Windows (Scoop)
scoop install pandoc
For PDF output via LaTeX, you also need a TeX distribution:
# macOS
brew install --cask mactex-no-gui
# Ubuntu / Debian
sudo apt-get install texlive-xetex texlive-fonts-recommended
# Windows
choco install miktex
The simplest Pandoc command converts Markdown to PDF in one step:
pandoc input.md -o output.pdf
This uses Pandoc's default LaTeX template with standard margins, fonts, and page size. For most technical documents, the defaults produce clean, readable output.
Pandoc's power lies in its extensive customization options:
pandoc input.md \
-o output.pdf \
--pdf-engine=xelatex \
-V geometry:margin=1in \
-V fontsize=11pt \
-V mainfont="Inter" \
-V monofont="JetBrains Mono" \
-V colorlinks=true \
-V linkcolor=blue \
--highlight-style=tango \
--toc \
--toc-depth=3 \
-V header-includes="\usepackage{fancyhdr}"
Pandoc is not limited to PDF. It supports a vast matrix of input and output formats, making it a universal document converter:
| Output Format | Engine | Best For | Quality |
|---|---|---|---|
| PDF (LaTeX) | pdflatex / xelatex / lualatex | Academic papers, books | Excellent |
| PDF (HTML) | wkhtmltopdf / weasyprint | Web-styled documents | Good |
| HTML | Built-in | Web publishing | Excellent |
| DOCX | Built-in | Microsoft Word users | Good |
| EPUB | Built-in | E-books, mobile reading | Good |
| ODT | Built-in | LibreOffice users | Good |
| RST | Built-in | Sphinx documentation | Excellent |
| LaTeX | Built-in | Custom TeX workflows | Excellent |
| Reveal.js | Built-in | Presentations | Good |
| man | Built-in | Unix manual pages | Excellent |
Pro Tip: Use xelatex as your PDF engine instead of the default pdflatex. It supports Unicode natively and can use any system font, which eliminates the most common Pandoc PDF issues (missing characters, font errors).
Professional documents need headers and footers with page numbers, document titles, and dates. Pandoc supports this through LaTeX's fancyhdr package:
---
title: "API Documentation"
author: "Engineering Team"
date: "2026-02-18"
header-includes:
- \usepackage{fancyhdr}
- \pagestyle{fancy}
- \fancyhead[L]{API Documentation}
- \fancyhead[R]{v2.4.1}
- \fancyfoot[C]{\thepage}
---
Code highlighting is critical for developer documentation. Pandoc supports over 140 languages with built-in syntax highlighting:
# List available highlight styles
pandoc --list-highlight-styles
# Use a specific style
pandoc input.md -o output.pdf --highlight-style=breezedark
Available styles include pygments, tango, espresso, zenburn, kate, monochrome, breezedark, and haddock. You can also create custom highlight themes as JSON files.
For longer documents, an auto-generated table of contents improves navigation:
pandoc input.md -o output.pdf --toc --toc-depth=3
The --toc-depth flag controls how many heading levels appear. For most documents, depth 2 or 3 strikes the right balance between usefulness and clutter.
If you prefer CSS styling over LaTeX, browser-based tools render Markdown as HTML and then print to PDF using a headless browser engine.
md-to-pdf uses Puppeteer (headless Chrome) to render Markdown and capture the output as PDF:
# Install globally
npm install -g md-to-pdf
# Convert a single file
md-to-pdf input.md
# Convert with custom CSS
md-to-pdf input.md --stylesheet custom.css
Configuration can be embedded in the Markdown file's frontmatter:
---
pdf_options:
format: A4
margin: 20mm
printBackground: true
stylesheet:
- https://cdn.example.com/styles.css
- ./local-styles.css
---
Writing CSS for PDF output requires understanding print-specific properties:
/* Page setup */
@page {
size: A4;
margin: 2cm;
}
/* Force page breaks */
h1 {
page-break-before: always;
}
/* Prevent orphaned headings */
h2,
h3 {
page-break-after: avoid;
}
/* Keep code blocks together */
pre {
page-break-inside: avoid;
}
/* Style for print */
@media print {
a {
color: #000;
text-decoration: underline;
}
a[href]::after {
content: " (" attr(href) ")";
font-size: 0.8em;
color: #666;
}
}
If you write Markdown in Visual Studio Code, several extensions add PDF export functionality directly to your editor.
The most popular option with over 3 million installs:
yzane.markdown-pdf)Ctrl+Shift+P (or Cmd+Shift+P on macOS) and search for "Markdown PDF: Export (pdf)"Configure the extension in VS Code settings:
{
"markdown-pdf.displayHeaderFooter": true,
"markdown-pdf.headerTemplate": "<span style='font-size:8px;'>My Document</span>",
"markdown-pdf.footerTemplate": "<span style='font-size:8px;'><span class='pageNumber'></span>/<span class='totalPages'></span></span>",
"markdown-pdf.margin.top": "1.5cm",
"markdown-pdf.margin.bottom": "1.5cm"
}
For teams that regularly produce PDF documentation from Markdown sources, automation eliminates manual conversion steps and ensures consistent output.
Add Markdown-to-PDF conversion to your CI/CD pipeline to automatically generate PDFs when documentation changes:
# .github/workflows/docs.yml
name: Build Documentation PDFs
on:
push:
paths:
- "docs/**/*.md"
jobs:
build-pdfs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Pandoc
run: sudo apt-get install -y pandoc texlive-xetex
- name: Convert docs to PDF
run: |
for f in docs/*.md; do
pandoc "$f" -o "${f%.md}.pdf" \
--pdf-engine=xelatex \
--template=docs/template.tex \
--toc
done
- name: Upload PDFs
uses: actions/upload-artifact@v4
with:
name: documentation-pdfs
path: docs/*.pdf
For local automation, a Makefile provides a clean interface:
SOURCES := $(wildcard docs/*.md)
PDFS := $(SOURCES:.md=.pdf)
all: $(PDFS)
%.pdf: %.md
pandoc $< -o $@ \
--pdf-engine=xelatex \
--template=template.tex \
--highlight-style=tango \
--toc
clean:
rm -f docs/*.pdf
.PHONY: all clean
Pro Tip: Store your Pandoc templates and CSS stylesheets in version control alongside your Markdown documentation. This ensures everyone on the team produces identically styled PDFs, and style changes are tracked and reviewable.
Image paths in Markdown can cause issues during PDF conversion. Follow these guidelines:
 works reliably across tools{width=80%}For documents with mathematical notation, Pandoc's LaTeX math support is best-in-class:
Inline math: $E = mc^2$
Display math:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
Browser-based tools can use KaTeX or MathJax instead, though rendering quality may vary.
Control page breaks explicitly when automatic pagination produces poor results:
Some content on page one.
\newpage
Content that should start on a new page.
For browser-based tools, use the CSS page-break-before: always property on a <div> element.
Markdown tables convert cleanly to PDF in most tools, but very wide tables can overflow the page. Solutions:
-V geometry:landscapeIf your Markdown contains non-ASCII characters (accented letters, CJK characters, emoji), use xelatex or lualatex as your PDF engine. The default pdflatex engine has limited Unicode support and will fail on many characters.
pandoc input.md -o output.pdf --pdf-engine=xelatex -V mainfont="Noto Sans"
Standard Markdown (CommonMark) provides the basics, but several extensions add features that improve PDF output.
Add metadata that flows into your PDF's title page, headers, and document properties:
---
title: "System Architecture Guide"
subtitle: "Internal Documentation"
author: "Platform Engineering"
date: "February 2026"
abstract: "This document describes the system architecture..."
keywords: [architecture, microservices, infrastructure]
---
Pandoc supports definition lists, which render cleanly in PDF:
Term 1
: Definition for term 1.
Term 2
: Definition for term 2, which can span
multiple lines.
Footnotes appear at the bottom of the page in PDF output:
This claim requires a citation[^1].
[^1]: Source: "The Art of Documentation," 2025.
GitHub-flavored task lists render as checkboxes in PDF:
- [x] Write introduction
- [x] Add code examples
- [ ] Review with team
- [ ] Publish final version
The best tool depends on your specific situation:
Choose online conversion when you need a quick, one-off PDF and do not want to install anything. Our PDF converter handles this effortlessly.
Choose Pandoc when you need maximum control, LaTeX math support, custom templates, or automated pipelines. It is the industry standard for a reason.
Choose browser-based tools when you want CSS styling, web fonts, and a workflow that mirrors web development.
Choose VS Code extensions when you want conversion integrated into your editor with zero context switching.
For converting existing PDFs back to editable formats, check out our guide on how to convert PDF to Word. And if your PDFs are too large for distribution, our guide on reducing PDF file size covers practical compression techniques.
You can also explore our HTML converter if you need to produce web-ready HTML from your Markdown content — it pairs well with a Markdown-to-PDF workflow for multi-format publishing.
Whether you are writing API docs, architecture guides, or runbooks, these practices produce better PDFs:
Markdown-to-PDF conversion is a solved problem with excellent tooling at every level of complexity. Start with the simplest approach that meets your needs, and scale up to more sophisticated tools as your requirements grow.
Alex Thompson
Software engineer and content creator focused on web technologies, image optimization, and developer tooling.