md2pdf-export

name: md2pdf-export description: > Convert Markdown files to PDF, PNG, or JPEG using headless Chrome (Puppeteer), following the same methodology as VS Code's Markdown Preview Enhanced extension. Use this skill whenever the user asks to: export/convert/render markdown to PDF or image, generate a printable document from .md files, create publication-ready PDFs from markdown, set up a markdown-to-PDF pipeline, or install/configure the Node.js + Puppeteer + Chrome environment needed for headless rendering. Also trigger when the user mentions "md2pdf", "markdown export", "puppeteer PDF", "headless chrome PDF", "crossnote", "mume", or wants WYSIWYG-quality PDF output from markdown source files. This skill covers both environment setup AND the actual conversion process.

Markdown → PDF/PNG/JPEG Export (Puppeteer Method)

Architecture Overview

The conversion pipeline mirrors Markdown Preview Enhanced's chromeExport():

Markdown (.md)
    │
    ▼  [markdown-it + plugins]
Standalone HTML (with embedded CSS, math, diagrams)
    │
    ▼  [Puppeteer launches headless Chrome]
Chrome loads the HTML via file:// protocol
    │
    ├──▶ page.pdf()        → PDF output
    ├──▶ page.screenshot() → PNG output
    └──▶ page.screenshot() → JPEG output

The key insight: Chrome IS the rendering engine. What Chrome renders is what you get — true WYSIWYG.

Step 0: Environment Check & Setup

Before any conversion, verify the environment is ready. Run the setup script:

bash skills/md2pdf-export/scripts/setup-env.sh

This script is idempotent — safe to run multiple times. It handles:

• Detecting OS (macOS / Ubuntu / Debian / Alpine / CentOS)
• Installing Node.js (via nvm, prefers LTS)
• Installing npm packages globally: puppeteer (which bundles Chromium)
• Verifying Chrome/Chromium is launchable in headless mode
• Printing a diagnostic summary

If the user's system already has Node.js ≥ 18 and puppeteer installed, the script skips those steps.

Manual Setup (if the script fails)

For environments where the automated script doesn't work (e.g. restricted Docker containers):

# 1. Install Node.js >= 18
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc  # or ~/.zshrc
nvm install --lts

# 2. Install puppeteer (bundles Chromium automatically)
npm install -g puppeteer

# 3. For Linux headless environments, install system dependencies
# Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y \
  ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 \
  libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 xdg-utils wget

# 4. Verify
node -e "const p = require('puppeteer'); p.launch({headless:'new'}).then(b => { console.log('OK'); b.close(); })"

Using an Existing Chrome Installation

If the system already has Chrome/Chromium installed, set the environment variable to skip Chromium download:

export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome  # or /usr/bin/chromium-browser

Step 1: Convert Markdown to HTML

Use markdown-it with plugins for a feature-rich render. The conversion script at skills/md2pdf-export/scripts/md2pdf.js handles this internally, but the logic is:

1. Read the .md file
2. Parse YAML front-matter (for puppeteer config overrides)
3. Render Markdown → HTML via markdown-it with these plugins:
   • markdown-it-texmath + KaTeX for math ($...$, $$...$$)
   • markdown-it-highlightjs for syntax highlighting
   • markdown-it-anchor + markdown-it-toc-done-right for TOC
   • markdown-it-footnote for footnotes
4. Wrap in a full HTML document with:
   • A CSS theme (GitHub-light by default, configurable)
   • Embedded styles for print (@media print rules)
   • All resources inlined (no external dependencies)

Step 2: Launch Headless Chrome & Export

The script then:

1. Launches Puppeteer with headless: 'new' (new headless mode)
2. Creates a new page, sets viewport (for PNG/JPEG) or paper size (for PDF)
3. Loads the HTML via page.setContent() or page.goto('file://...')
4. Waits for rendering to complete (waitUntil: 'networkidle0')
5. Calls the appropriate Puppeteer API:
   • PDF: page.pdf({ path, format, printBackground, margin, ... })
   • PNG: page.screenshot({ path, fullPage: true, type: 'png' })
   • JPEG: page.screenshot({ path, fullPage: true, type: 'jpeg', quality })
6. Closes the browser

Running the Conversion

Basic Usage

# PDF (default)
node skills/md2pdf-export/scripts/md2pdf.js input.md

# PNG
node skills/md2pdf-export/scripts/md2pdf.js input.md --type png

# JPEG with quality
node skills/md2pdf-export/scripts/md2pdf.js input.md --type jpeg --quality 90

# Custom output path
node skills/md2pdf-export/scripts/md2pdf.js input.md -o output.pdf

# A3 landscape
node skills/md2pdf-export/scripts/md2pdf.js input.md --format A3 --landscape

Front-Matter Configuration

Users can embed Puppeteer config directly in the Markdown file's YAML front-matter:

---
puppeteer:
  format: A4
  landscape: false
  margin:
    top: "20mm"
    right: "20mm"
    bottom: "20mm"
    left: "20mm"
  printBackground: true
  displayHeaderFooter: true
  headerTemplate: '<span style="font-size:8px;width:100%;text-align:center;"><span class="title"></span></span>'
  footerTemplate: '<span style="font-size:8px;width:100%;text-align:center;"><span class="pageNumber"></span> / <span class="totalPages"></span></span>'
screenshot:
  fullPage: true
  width: 1200
  deviceScaleFactor: 2
export_on_save:
  puppeteer: true
---

CLI Options Reference

Programmatic Usage (Node.js)

For integration into agent pipelines:

const { convertMarkdown } = require('skills/md2pdf-export/scripts/md2pdf.js');

const result = await convertMarkdown({
  inputPath: './paper.md',
  outputPath: './paper.pdf',
  type: 'pdf',               // 'pdf' | 'png' | 'jpeg'
  puppeteerConfig: {
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' },
  },
  theme: 'github',
  chromePath: null,           // auto-detect
  waitTimeout: 1000,
  toc: true,
});

console.log(`Exported to: ${result.outputPath}`);

Troubleshooting

Advanced: Batch Conversion

For converting an entire directory of Markdown files:

# Convert all .md files in a directory to PDF
for f in docs/*.md; do
  node skills/md2pdf-export/scripts/md2pdf.js "$f" -o "output/$(basename "${f%.md}.pdf")"
done

Reference Files

• references/puppeteer-config.md — Full Puppeteer page.pdf() and page.screenshot() API options
• references/themes.md — Available CSS themes and how to create custom ones