How to Convert Markdown to PDF: The Complete Guide

Why Convert Markdown to PDF?

Markdown is the lingua franca of technical writing — GitHub READMEs, API docs, engineering notes, technical books. But the moment you need to share content with people outside your tooling bubble, the format becomes a liability. PDF is universal: it renders identically on every device, prints reliably, can be signed and annotated, and is the only acceptable format in most legal, academic, and corporate workflows.

The most common reasons to convert .md files to PDF:

• •Sharing READMEs with non-developers — product managers, designers, and executives don't want to navigate to a GitHub link to read your documentation.
• •Distributing technical documentation — software manuals, API references, internal runbooks, and release notes need to be portable and printable.
• •Archiving for compliance — SOX, HIPAA, and ISO 27001 audits demand immutable, time-stamped records. PDFs with digital signatures fit the bill.
• •Submitting reports, proposals, or whitepapers — academic journals, RFP responses, and conference submissions almost always require PDF.
• •Reading offline — long-form Markdown content (e.g., a 50-page book chapter) is more comfortable to read as a paginated PDF on a tablet or e-reader.
• •Printing physical copies — meeting handouts, classroom materials, technical references. PDFs print with consistent page breaks; raw .md files do not.

The good news: you don't need expensive software. There are five excellent ways to convert Markdown to PDF — ranging from a single browser click to fully scripted CI/CD pipelines. Here's how to pick the right one.

The 5 Best Methods at a Glance

Quick recommendation: Use the browser-based Markdown Viewer for everyday conversions — it's the fastest, no install, and your file content never leaves your browser. Use Pandoc if you need batch processing or LaTeX-quality typography. Use the programmatic methodsif you're generating PDFs from a CMS or CI/CD pipeline.

Method 1: Browser-Based (Easiest, No Install)

The simplest way to convert .md to PDF is in your browser — no software to install, no command line, and everything runs client-side so your file content stays private.

Step-by-Step

1. Open the ToolZip Markdown Viewer.
2. Drag your .md file into the editor, click Upload, or paste content directly.
3. (Optional) Switch between light, dark, and sepia themes. The auto-generated Table of Contents appears in the sidebar.
4. Click Export PDF. Your browser's print dialog opens with a print-optimized layout.
5. In the print dialog, set Destination to “Save as PDF”, pick paper size and margins, then Save.

What You Get

• ✓Clickable hyperlinks preserved in the PDF
• ✓Proper page breaks (headings and tables stay together)
• ✓Full GFM support: tables, task lists, strikethrough, code fences
• ✓Headers and footers with page numbers (configurable in the print dialog)
• ✓Your data never leaves the browser — 100% client-side processing

This method works for 90% of use cases. The only time you need something more powerful is when you need batch processing, custom LaTeX styling, or rendering of complex math equations.

Method 2: Pandoc CLI (Most Powerful)

Pandoc is the universal document converter — it speaks 30+ formats and is the de facto standard for technical publishing. If you write technical books, academic papers, or run a documentation pipeline, Pandoc is the right tool.

Installation

# macOS (Homebrew)
brew install pandoc basictex

# Ubuntu / Debian
sudo apt install pandoc texlive-xetex

# Windows (Chocolatey)
choco install pandoc miktex

Pandoc itself can convert Markdown to many formats, but PDF output requires a LaTeX engine (XeLaTeX is recommended for Unicode and modern fonts).

Basic Usage

# Simplest conversion
pandoc README.md -o README.pdf

# With table of contents
pandoc input.md -o output.pdf --toc

# Use XeLaTeX for better fonts and Unicode
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Set margins, font, and font size
pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V mainfont="Helvetica" \
  -V fontsize=11pt \
  -V geometry:margin=1in

Advanced: Custom Template

# Use a custom LaTeX template (for branded reports)
pandoc input.md -o output.pdf \
  --template=my-template.tex \
  --toc \
  --number-sections \
  --highlight-style=tango \
  --listings

Pandoc is the only tool that handles complex requirements like footnotes, citations (via --bibliography), math equations (LaTeX or KaTeX syntax), cross-references, and bookmarks for chapter navigation in the PDF reader.

Method 3: VS Code Markdown PDF Extension

If you live inside VS Code, the Markdown PDF extension (by yzane) lets you export the active .md file as PDF without leaving the editor.

Setup

1. Open VS Code → Extensions sidebar → search “Markdown PDF”
2. Install the extension by yzane
3. Open any .md file
4. Open the Command Palette (Ctrl+Shift+P) and run Markdown PDF: Export (pdf)

Customizing

Edit your VS Code settings.json:

{
  "markdown-pdf.format": "A4",
  "markdown-pdf.margin.top": "1in",
  "markdown-pdf.margin.bottom": "1in",
  "markdown-pdf.displayHeaderFooter": true,
  "markdown-pdf.headerTemplate": "<div style='font-size:9px; margin:auto;'>{{title}}</div>",
  "markdown-pdf.footerTemplate": "<div style='font-size:9px; margin:auto;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
  "markdown-pdf.highlightStyle": "github.css"
}

The extension uses Chromium under the hood, so output quality matches what you'd get from the browser method — with the convenience of staying in your editor.

Method 4: Programmatic (Node.js & Python)

For CI/CD pipelines, CMSs, or generating PDFs at scale, use a programming library. Both Node.js and Python have mature libraries that produce excellent output.

Node.js: md-to-pdf

// npm install md-to-pdf
import { mdToPdf } from "md-to-pdf";

const pdf = await mdToPdf(
  { path: "./input.md" },
  {
    dest: "./output.pdf",
    pdf_options: {
      format: "A4",
      margin: { top: "1in", bottom: "1in", left: "0.8in", right: "0.8in" },
      printBackground: true,
      displayHeaderFooter: true,
    },
    stylesheet: ["./styles/print.css"],
  }
);

console.log("PDF written to", pdf.filename);

md-to-pdf uses Puppeteer under the hood. Excellent quality but pulls in a full headless Chromium (~150MB).

Python: markdown + WeasyPrint

# pip install markdown weasyprint
import markdown
from weasyprint import HTML, CSS

# Read Markdown
with open("input.md") as f:
    md_text = f.read()

# Convert to HTML with GFM extensions
html = markdown.markdown(
    md_text,
    extensions=["tables", "fenced_code", "toc"]
)

# Wrap in document with print styles
full_html = f"""
<!DOCTYPE html>
<html><head><meta charset="utf-8"></head>
<body>{html}</body></html>
"""

# Render to PDF
HTML(string=full_html).write_pdf(
    "output.pdf",
    stylesheets=[CSS(filename="print.css")]
)

WeasyPrint is lightweight (no Chromium dependency), produces excellent typography, and respects modern CSS print styles (@page, page-break-inside, etc.). For Python pipelines, this is the best choice. Validate your generated Markdown structure first with our Markdown to HTML Converter to catch syntax issues before they reach the PDF stage.

Method 5: Online Converters (and Their Pitfalls)

A quick Google search for “markdown to pdf” returns dozens of online converters. They work — but most have serious downsides worth understanding before you upload sensitive content.

The fix: use a converter that runs client-side — meaning all conversion happens in your browser using JavaScript. The file content never leaves your device. Our Markdown Viewer is built this way: zero server uploads, zero tracking of file content, and works fully offline once the page is loaded.

Other things to check before using any online converter: page size limits (some cap at 5-10 pages free), watermarks on the free tier, ad-injected PDFs, output quality (some strip code highlighting or break tables), and whether they retain a copy of your conversion history.

7 Common Issues and How to Fix Them

pre, table { page-break-inside: avoid; }
img { page-break-inside: avoid; max-width: 100%; }
h1, h2, h3 { page-break-after: avoid; }

<!-- Won't work in some converters -->
![Logo](./images/logo.png)

<!-- Always works -->
![Logo](https://example.com/logo.png)

<!-- Base64 (use Base64 encoder for small images) -->
![Logo](data:image/png;base64,iVBORw0KGgoAAAA...)

table { font-size: 10px; word-wrap: break-word; }
td, th { max-width: 200px; overflow-wrap: break-word; }

/* Or via @page: rotate to landscape */
@page { size: A4 landscape; }

body { font-family: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; }
code, pre { font-family: "SFMono-Regular", Menlo, Consolas, monospace; }

h1, h2, h3 { page-break-after: avoid; }
h2 + p, h3 + p { page-break-before: avoid; }

a, a:link, a:visited {
  color: #2563eb !important;
  text-decoration: underline !important;
}

/* Optional: print URLs next to links */
a[href^="http"]::after { content: " (" attr(href) ")"; font-size: 0.85em; }

# Pandoc auto-generates correct page numbers
pandoc input.md -o output.pdf --toc --toc-depth=3

Customizing PDF Output: Fonts, Margins & Themes

Good Markdown-to-PDF output isn't just about converting characters — it's about typography. Default styles look fine for personal notes but feel amateur for client deliverables. A few CSS tweaks transform “Markdown print” into “professional document.”

A Solid Print Stylesheet

@page {
  size: A4;
  margin: 1in 0.85in;
  @bottom-center {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9pt;
    color: #6b7280;
  }
}

body {
  font-family: "Georgia", "Iowan Old Style", "Palatino", serif;
  font-size: 11pt;
  line-height: 1.55;
  color: #1f2937;
}

h1, h2, h3, h4 {
  font-family: "Inter", -apple-system, "Helvetica Neue", sans-serif;
  color: #0f172a;
  page-break-after: avoid;
}

h1 { font-size: 22pt; margin: 1.5em 0 0.5em; }
h2 { font-size: 16pt; margin: 1.25em 0 0.4em; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.25em; }
h3 { font-size: 13pt; margin: 1em 0 0.3em; }

p, ul, ol { margin: 0.5em 0; }

code, pre code {
  font-family: "SFMono-Regular", "Consolas", monospace;
  font-size: 9.5pt;
}

pre {
  background: #f3f4f6;
  border: 1px solid #e5e7eb;
  border-radius: 4px;
  padding: 0.6em 0.85em;
  page-break-inside: avoid;
  overflow-x: auto;
}

blockquote {
  border-left: 3px solid #9ca3af;
  margin: 0.75em 0;
  padding: 0.25em 0.85em;
  color: #4b5563;
  font-style: italic;
}

a { color: #1e40af; text-decoration: none; }
a:hover { text-decoration: underline; }

This stylesheet uses a serif font for body text (more readable in print), a sans-serif for headings, and a monospace for code. Margins are 1 inch top/bottom and 0.85 inch left/right — standard for business documents. Page numbers appear in the footer via the @page rule.

Formatting Best Practices for Print

A few habits while writing Markdown make the PDF output dramatically better:

• Use heading levels semantically — H1 for the document title, H2 for major sections, H3-H4 for sub-sections. Avoid skipping levels (H1 → H3). This matters for TOC generation and accessibility.
• Keep code blocks short — anything longer than 30 lines is awkward in print. Split into multiple blocks with explanatory text between, or paste into a sidebar.
• Use horizontal rules (---) to separate sections — they help visually segment content and signal natural page breaks to the renderer.
• Prefer tables over indented lists for comparing items — tables print more cleanly and convey structure better than nested bullet lists.
• Run a quick word count first — use our word counter to estimate page count. A typical PDF page holds ~400-500 words of body text.
• Validate your Markdown syntax — broken syntax (unclosed code fences, malformed tables) renders unpredictably. Preview in the Markdown Viewer first.
• Use Base64 for inline images — convert small images with our Base64 Encoder for guaranteed embedding. Useful when sharing the source .md file alongside the PDF.
• Set a print-friendly font size — 11pt body text is the standard for documents. 12pt for technical references with dense content. Anything below 10pt becomes hard to read in print.

Frequently Asked Questions

Related Tools & Articles