Converting Markdown to PDF: Comparing VSCode Extensions, Pandoc, and CLI Tools

You want to convert a Markdown document to PDF — an engineer who's thought this is far from rare.

Meeting notes, specifications, procedures, blog drafts. If you could share Markdown-written text as a PDF directly, you'd skip the detour through Word. This article compares three common approaches for converting Markdown to PDF, covering each in enough detail to use in practice.

Three Main Approaches to Markdown-to-PDF Conversion

Conversion from Markdown to PDF breaks down into three main approaches:

Approach	Tool	Characteristics	Recommendation
VSCode extension	Markdown PDF (by yzane)	Complete in the GUI, easiest to set up	★★★
Generic conversion tool	Pandoc	Feature-rich, high quality via LaTeX	★★☆
CLI tool	md-to-pdf	Node.js-based, CSS support, CI/CD friendly	★★☆

Best to pick based on purpose, but let's start with the easiest option — the VSCode extension.

[Recommended] Convert via the VSCode Extension "Markdown PDF"

Installation

Search "Markdown PDF" in VSCode's extension marketplace and install the one authored by yzane. On first install, Chromium (roughly 170-280MB) downloads automatically, so it takes a moment.

Basic Usage

Open a Markdown file (.md) in VSCode
Right-click in the editor
Select "Markdown PDF: Export (pdf)"

That's it — a PDF is output in the same directory. You can also run it from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) with "Markdown PDF: Export."

Output Formats Beyond PDF

The Markdown PDF extension supports more than just PDF:

HTML — Markdown PDF: Export (html)
PNG — Markdown PDF: Export (png)
JPEG — Markdown PDF: Export (jpeg)
All at once — Markdown PDF: Export (all)

Key settings.json Options

{
  // Auto-generate PDF on save
  "markdown-pdf.convertOnSave": false,

  // Output format
  "markdown-pdf.type": ["pdf"],

  // Margins
  "markdown-pdf.margin.top": "1.5cm",
  "markdown-pdf.margin.bottom": "1cm",
  "markdown-pdf.margin.left": "1.3cm",
  "markdown-pdf.margin.right": "1.3cm",

  // Show header and footer
  "markdown-pdf.displayHeaderFooter": true,
  "markdown-pdf.headerTemplate": "<div style='font-size: 9px; margin-left: 1cm;'>Document Title</div>",
  "markdown-pdf.footerTemplate": "<div style='font-size: 9px; margin: 0 auto;'><span class='pageNumber'></span> / <span class='totalPages'></span></div>",

  // Apply custom CSS
  "markdown-pdf.styles": ["style.css"],
  "markdown-pdf.stylesRelativePathFile": true,

  // Enable line breaks
  "markdown-pdf.breaks": true,

  // Output directory
  "markdown-pdf.outputDirectory": "output",
  "markdown-pdf.outputDirectoryRelativePathFile": true
}

💡 Tip: Setting convertOnSave to true PDF-ifies every Markdown file on every save. To target only specific files, controlling via workspace settings (.vscode/settings.json) is practical.

Customize PDF Appearance with CSS

Markdown PDF can reference a CSS file to fully customize PDF styling.

/* markdown-pdf-style.css */
body {
  font-family: 'Noto Sans JP', -apple-system, BlinkMacSystemFont, sans-serif;
  font-size: 11pt;
  line-height: 1.8;
  color: #333;
}

h1 {
  font-size: 22pt;
  border-bottom: 2px solid #2c3e50;
  padding-bottom: 8px;
  margin-top: 32px;
}

h2 {
  font-size: 16pt;
  color: #2c3e50;
  margin-top: 24px;
}

code {
  background-color: #f5f5f5;
  padding: 2px 6px;
  border-radius: 3px;
  font-size: 10pt;
}

pre code {
  display: block;
  padding: 12px;
  overflow-x: auto;
}

table {
  border-collapse: collapse;
  width: 100%;
  margin: 16px 0;
}

th, td {
  border: 1px solid #ddd;
  padding: 8px 12px;
  text-align: left;
}

th {
  background-color: #f0f0f0;
  font-weight: bold;
}

/* Page break control */
h1, h2 {
  page-break-after: avoid;
}

table, pre {
  page-break-inside: avoid;
}

Inserting Page Breaks

At the point where you want a page break in the PDF, add this HTML:

<div style="page-break-after: always;"></div>

Rendering Mermaid Diagrams

Markdown PDF supports Mermaid, but it may not render correctly by default. Add this to settings.json:

{
  "markdown-pdf.mermaidServer": "https://unpkg.com/mermaid/dist/mermaid.min.js"
}

Converting Markdown to PDF with Pandoc

Pandoc is an open-source "universal document converter." It handles conversions between many formats, not just Markdown.

Installation

# macOS
brew install pandoc

# Ubuntu / Debian
sudo apt install pandoc

# Windows (Chocolatey)
choco install pandoc

For generating Japanese PDFs, you also need a LaTeX engine.

# macOS
brew install --cask mactex-no-gui

# Ubuntu
sudo apt install texlive-xetex texlive-lang-japanese

Basic Conversion Command

pandoc input.md -o output.pdf

For Markdown containing Japanese, specify a font and engine:

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V mainfont="Noto Sans CJK JP" \
  -V geometry:margin=2cm

Pandoc's Strengths

Via LaTeX, strong on documents containing mathematical formulas
Template functionality for consistent formatting
Automatic table of contents generation (--toc option)
Bibliography management (BibTeX integration)

Pandoc's Caveats

LaTeX installation required (several GB)
Initial setup is involved
Style control via LaTeX templates rather than CSS

Generate PDFs from Markdown with a CLI Tool (md-to-pdf)

md-to-pdf is a Node.js-based CLI tool that uses headless Chrome (Puppeteer) to convert Markdown to PDF.

Installation

npm install -g md-to-pdf

Basic Usage

md-to-pdf input.md

input.pdf is generated in the same directory.

Specifying CSS

Specify CSS via YAML frontmatter at the top of the file:

---
stylesheet: style.css
pdf_options:
  format: A4
  margin: 20mm
---

# Document Title

The body begins here...

Use in CI/CD

Since md-to-pdf is a CLI tool, it's easy to embed in CI/CD pipelines like GitHub Actions.

# .github/workflows/generate-pdf.yml
- name: Generate PDF
  run: |
    npm install -g md-to-pdf
    md-to-pdf docs/manual.md --dest output/

You can set up a system that detects document updates and automatically generates and deploys PDFs.

Summary Comparison of the Three Approaches

Item	VSCode Markdown PDF	Pandoc	md-to-pdf
Ease of setup	★★★	★☆☆	★★☆
Japanese support	◎ Default	△ Font spec needed	◎ Via CSS
Style control	CSS	LaTeX templates	CSS
Math support	△	◎	△
CI/CD integration	✗	○	◎
Mermaid support	○ (needs config)	△ (needs filter)	○
Batch file conversion	△	◎	○

Recommended splits:

Daily document creation → VSCode Markdown PDF
Academic papers, documents with formulas → Pandoc
CI/CD automation, team operations → md-to-pdf

Real-World Scenarios for Markdown-to-PDF Conversion

Markdown-to-PDF conversion is particularly useful in these scenarios:

Technical specs and design documents: Write in Markdown → manage with Git → export to PDF for internal sharing. Change history stays in Git, freeing you from the "v2_final_FINAL(2).docx" problem.

Procedure manuals: Using markdown-it-include, you can write procedure manuals in chapter-separated files and compile them into a single PDF. Good for parallel team authoring.

Client-facing proposals: Apply your brand colors and logo with CSS, and you can produce polished-looking proposals from Markdown alone.

Meeting minutes: Take notes in Markdown during the meeting, then export to PDF for distribution afterwards. Being text-based, it's also highly searchable.

Common Issues and Fixes

Japanese Characters Appear as Garbled Text in Markdown PDF

This occurs when Chromium lacks installed Japanese fonts. Either specify a font explicitly in CSS or install Noto Sans CJK JP on your system.

body {
  font-family: 'Noto Sans JP', 'Hiragino Kaku Gothic ProN', 'Meiryo', sans-serif;
}

PDF File Size Is Too Large

Happens when there are many images. Pre-compress images, or use JPEG instead of PNG, to reduce file size.

Mermaid Doesn't Render in Markdown PDF

Check the mermaidServer setting in settings.json. If the default CDN URL is outdated, update it to the latest Mermaid CDN URL.

Pandoc Can't Generate Japanese PDFs

You need both a LaTeX engine (xelatex) and Japanese fonts. Use --pdf-engine=xelatex and -V mainfont to specify the font.

Summary

There are several approaches to converting Markdown to PDF, each fitting a different purpose:

Ease-first → VSCode extension "Markdown PDF" — one right-click
Quality-first → Pandoc for high-quality PDFs via LaTeX
Automation-first → md-to-pdf with CI/CD integration

With any of these, dressing up the styling with CSS or templates produces documents on par with Word. Write in Markdown, distribute as PDF — once you've set up this workflow, your document creation efficiency should improve significantly.

Converting Markdown to PDF: Comparing VSCode Extensions, Pandoc, and CLI Tools

Three Main Approaches to Markdown-to-PDF Conversion

[Recommended] Convert via the VSCode Extension "Markdown PDF"

Installation

Basic Usage

Output Formats Beyond PDF

Key settings.json Options

Customize PDF Appearance with CSS

Inserting Page Breaks

Rendering Mermaid Diagrams

Converting Markdown to PDF with Pandoc

Installation

Basic Conversion Command

Pandoc's Strengths

Pandoc's Caveats

Generate PDFs from Markdown with a CLI Tool (md-to-pdf)

Installation

Basic Usage

Specifying CSS

Use in CI/CD

Summary Comparison of the Three Approaches

Real-World Scenarios for Markdown-to-PDF Conversion

Common Issues and Fixes

Japanese Characters Appear as Garbled Text in Markdown PDF

PDF File Size Is Too Large

Mermaid Doesn't Render in Markdown PDF

Pandoc Can't Generate Japanese PDFs

Summary

サービス

コンテンツ

企業情報