Md To PDF

Markdown to PDF Converter

将 Markdown 文件转换为高质量的 PDF 文档，支持代码语法高亮、自定义样式表以及完整的 Puppeteer PDF 自定义功能——使用独立的 Node.js.js.js 环境，无需系统级安装。

Core Principles

• 自包含：集成 Node.js + md-to-pdf；可在任何支持 bash 的机器上运行
• 优先级解析：命令行参数 > > > 前置内容 > > 配置文件 > 默认值
• 跨平台：Linux/macOS（完全自动），Windows（WSL 或主机上的 Node.js）
• 支持方式：单文件、批处理、标准输入管道、监视模式、自定义 CSS、代码高亮

Quick Start

# 1. Convert a single file (auto-installs if needed)
bash scripts/md-to-pdf-convert.sh document.md

# 2. Convert with syntax highlighting
bash scripts/md-to-pdf-convert.sh document.md --highlight-style monokai

# 3. Convert with custom page size and margins
bash scripts/md-to-pdf-convert.sh document.md \
  --pdf-options '{"format":"A4","margin":{"top":"1in","bottom":"1in","left":"0.75in","right":"0.75in"}}'

# 4. Batch convert all markdown files in a directory
for f in docs/*.md; do bash scripts/md-to-pdf-convert.sh "$f"; done

# 5. Watch mode (auto-regenerate on save)
bash scripts/md-to-pdf-convert.sh document.md --watch

Workflow

User provides .md file(s)
       │
       ▼
┌─────────────────┐
│ Check md-to-pdf  │── not found ──► Run install.sh
│ available?       │
└────────┬────────┘
         │ found
         ▼
┌─────────────────┐
│ Parse options    │   Read args: CSS, highlight, PDF config
│ & input file     │   Read front-matter if present
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Run md-to-pdf    │   md-to-pdf [options] input.md
│ Convert .md → .pdf │   Output: same dir, same name, .pdf extension
└────────┬────────┘
         │
         ▼
   Report output file path

Detailed Instructions

Step 1: Ensure Environment

The skill ships with two scripts:

On first use, the convert script auto-detects missing dependencies and offers to install. Accept the installation prompt, or run manually:

bash scripts/install.sh

Windows note: On native Windows (no WSL), install Node.js 18+ from https://nodejs.org/ then run:

npm install md-to-pdf --prefix .hermes/skills/md-to-pdf/.local-md-to-pdf

Step 2: Convert Files

Basic conversion — PDF output in same directory as source:

bash scripts/md-to-pdf-convert.sh report.md
# Output: report.pdf (same directory)

Multiple files (bash):

for f in chapters/*.md; do
  bash scripts/md-to-pdf-convert.sh "$f"
done

Single command for multiple files using shell globbing:

bash scripts/md-to-pdf-convert.sh docs/guide.md docs/api.md
# Note: each file generates its own PDF in its own directory

Step 3: Apply Styling & Formatting

Code Syntax Highlighting

bash scripts/md-to-pdf-convert.sh document.md --highlight-style monokai

Popular themes: monokai, solarized-light, github-dark, atom-one-dark, vs2015

When using a theme with a background color, enable printBackground:

bash scripts/md-to-pdf-convert.sh document.md \
  --highlight-style monokai \
  --pdf-options '{"printBackground":true}'

Custom Stylesheet (CSS)

Local CSS file:

bash scripts/md-to-pdf-convert.sh document.md --stylesheet ./custom-style.css

Remote CSS URL:

bash scripts/md-to-pdf-convert.sh document.md \
  --stylesheet https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/monokai.min.css

Multiple stylesheets:

bash scripts/md-to-pdf-convert.sh document.md \
  --stylesheet ./base.css \
  --stylesheet ./custom.css

Inline CSS

bash scripts/md-to-pdf-convert.sh document.md \
  --css 'body { font-family: "Noto Sans SC", sans-serif; font-size: 12pt; }'

Front-matter Configuration (YAML)

Add to the top of your .md file:

---
documentTitle: "My Document"
highlightStyle: monokai
pdfOptions:
  format: A4
  margin:
    top: 1in
    bottom: 1in
    left: 0.75in
    right: 0.75in
headerTemplate: '<div style="font-size:10px;text-align:center"><span class="date"></span></div>'
footerTemplate: '<div style="font-size:10px;text-align:center"><span class="pageNumber"></span> / <span class="totalPages"></span></div>'
---

Step 4: Advanced Options

PDF Page Configuration

bash scripts/md-to-pdf-convert.sh doc.md \
  --pdf-options '{"format":"Letter","margin":{"top":"20mm","bottom":"20mm","left":"15mm","right":"15mm"}}'

Supported formats: A3, A4, A5, Legal, Letter, Tabloid, or custom {width, height} objects.

Headers and Footers

bash scripts/md-to-pdf-convert.sh doc.md \
  --pdf-options '{
    "headerTemplate": "<div style=\"font-size:9px;text-align:right\"><span class=\"date\"></span></div>",
    "footerTemplate": "<div style=\"font-size:9px;text-align:center\">Page <span class=\"pageNumber\"></span> / <span class=\"totalPages\"></span></div>"
  }'

Page Breaks

Insert a page break in your Markdown:

<div class="page-break"></div>

Or in raw Markdown:

---

<div class="page-break"></div>

---

Watch Mode

Auto-regenerate PDF when Markdown changes:

bash scripts/md-to-pdf-convert.sh doc.md --watch

Adjust polling for editors that modify files after save:

bash scripts/md-to-pdf-convert.sh doc.md \
  --watch --watch-options '{"awaitWriteFinish":{"stabilityThreshold":500,"pollInterval":100}}'

DevTools (Debug)

bash scripts/md-to-pdf-convert.sh doc.md --devtools

Opens headless Chrome with DevTools to inspect the rendered HTML before PDF generation.

Environment Variable Overrides

Set these to customize behavior:

Batch Processing Example

Convert an entire documentation directory tree:

#!/bin/bash
# batch-convert.sh — placed in the same directory as SKILL.md
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"

find . -name "*.md" -not -path "*/.node-dist/*" -not -path "*/node_modules/*" | while read -r mdfile; do
  echo "[$mdfile] ..."
  bash "$SKILL_DIR/scripts/md-to-pdf-convert.sh" "$mdfile" \
    --highlight-style solarized-light \
    --pdf-options '{"format":"A4","margin":{"top":"1in","bottom":"1in","left":"0.75in","right":"0.75in"}}'
done

echo "=== Batch complete ==="

Troubleshooting

Bundled Resources

External References

• md-to-pdf GitHub: https://github.com/simonhaenisch/md-to-pdf
• highlight.js themes: https://highlightjs.org/static/demo/
• Puppeteer PDF options: https://pptr.dev/api/puppeteer.puppeteerpdfoptions/

Based on simonhaenisch/md-to-pdf. Adapted for cross-agent portability by Hermes Agent skill-maker.