Any2pdf

any2pdf — Markdown to Professionally Typeset PDF

Credits. This skill is adapted from lovstudio/any2pdf by lovstudio, distributed under the MIT license. The original repository ships the Python implementation (md2pdf.py), preview gallery, and reference theme JSONs. This document is the Mercury-compatible SKILL.md adaptation; the runtime code and design credit belong entirely to the original author.

• Upstream: https://github.com/lovstudio/any2pdf
• License: MIT (see upstream LICENSE)
• Author: lovstudio
• Curator (this entry): cosmicstack-labs

This skill converts any Markdown file into a publication-quality PDF using Python's reportlab. It was developed through extensive iteration on real Chinese technical reports and solves several hard problems that naive MD→PDF converters get wrong — CJK/Latin mixed text wrapping, canvas CJK rendering on cover/headers/footers, code-block whitespace preservation, and mixed-font fallbacks across macOS, Linux, and Windows.

When to Use

Trigger this skill whenever the user:

• Wants to convert .md → .pdf
• Has a markdown report or document and wants professional typesetting
• Mentions "markdown to PDF", "md2pdf", "any2pdf", "md转pdf", "报告生成", or asks for a "typeset" or "professionally formatted" PDF from markdown source
• Has a document with CJK characters mixed with Latin text
• Has fenced code blocks, markdown tables, or nested lists that need to survive conversion
• Needs local/remote images, Obsidian callouts, emoji, or LaTeX-style math formulas
• Wants a cover page, table of contents, watermark, or back cover in their PDF

Where the Runtime Lives

After installing this skill via the Mercury CLI:

mercury skills install pdf-generation/any2pdf

the SKILL.md lands at ~/.mercury/skills/pdf-generation/any2pdf/SKILL.md.

The Python implementation (md2pdf.py), preview images, and theme files are not vendored into Mercury Skills — they live in the upstream repository. To use the skill end-to-end, also clone or install the upstream runtime:

# Option A: clone alongside (recommended for development)
git clone https://github.com/lovstudio/any2pdf.git
# The script is at: any2pdf/lovstudio-any2pdf/scripts/md2pdf.py

# Option B: install via the upstream's own installer
npx skills add lovstudio/any2pdf -g -y

When the AI agent runs the conversion, treat the script path as wherever the user cloned it. If unsure, ask:

"Where is the md2pdf.py script on your system? (e.g. ./any2pdf/lovstudio-any2pdf/scripts/md2pdf.py)"

Quick Start

python <path-to>/md2pdf.py \
  --input report.md \
  --output report.pdf \
  --title "My Report" \
  --author "Author Name" \
  --theme warm-academic

All parameters except --input are optional — sensible defaults are applied.

Pre-Conversion Options (MANDATORY)

IMPORTANT for AI agents: You MUST present these options to the user before running the conversion. Use whatever interactive question primitive your runtime provides (AskUserQuestion, a structured prompt, an MCP tool, etc.). Present all options in a single question so the user answers once.

The tone should be a friendly design assistant, not a config form.

Suggested Prompt Template (English)

Starting PDF conversion — quick choices first

━━━ Design Style ━━━
 a) Warm Academic   — terracotta tones, refined and elegant; humanities / social science
 b) Classic Thesis  — brown tones, LaTeX classicthesis inspired; academic papers
 c) Tufte           — minimal whitespace, deep red accents; data narratives, technical writing
 d) IEEE Journal    — navy blue, journal-formal; conferences and journals
 e) Elegant Book    — coffee tones, book-like; long-form monographs / technical books
 f) Chinese Red     — vermilion on warm paper; Chinese formal reports / whitepapers
 g) Ink Wash        — pure grayscale, restrained and elegant; literary / design content
 h) GitHub          — blue-and-white minimal; developer-familiar
 i) Nord Frost      — Nordic blue-gray; clean modern
 j) Ocean Breeze    — teal-green; fresh and natural

━━━ Frontispiece (full-page image after cover) ━━━
 1) Skip
 2) I'll provide a local image path
 3) AI generates one based on document content

━━━ Watermark ━━━
 1) None
 2) Custom text (e.g. "DRAFT", "Internal Use Only")

━━━ Back Cover Material (business card / QR code / brand) ━━━
 1) Skip
 2) I'll provide an image
 3) Plain text only

Example reply: "a, frontispiece skip, watermark: For Reference Only, back cover: /path/qr.png"
Plain English is fine — no need to memorize the letters.

Mapping User Choices to CLI Args

Theme Name Mapping

Handling AI-Generated Frontispiece

If the user chose AI generation: read the document title and the first few paragraphs, use an image-generation tool to create a themed illustration matching the chosen design style, show the result for approval, then pass via --frontispiece /path/to/image.png.

Architecture

Markdown
  → Preprocess (split merged headings)
  → Parse (code-fence aware)
  → Story (reportlab flowables)
  → PDF build

Key components:

1. Font system — Palatino (Latin body), Songti SC (CJK body), Menlo (code) on macOS; auto-fallback on Linux / Windows.
2. CJK wrapper — _font_wrap() wraps CJK character runs in <font> tags for automatic font switching.
3. Mixed text renderer — _draw_mixed() handles CJK/Latin mixed text on canvas (cover, headers, footers).
4. Code block handler — esc_code() preserves indentation and line breaks in reportlab Paragraphs.
5. Smart table widths — proportional column widths based on content length, with 18 mm minimum.
6. Bookmark system — ChapterMark flowable creates PDF sidebar bookmarks and named anchors.
7. Heading preprocessor — _preprocess_md() splits merged headings like # Part## Chapter into separate lines.
8. Image handler — local, relative, file://, and remote markdown images are scaled into the body frame with fallback text on errors.
9. Callout renderer — Obsidian-style > [!NOTE] blocks render as themed boxed callouts.
10. Formula renderer — display formulas use optional matplotlib mathtext images, with styled text fallback.
11. Emoji fallback — emojis render as cached Twemoji PNGs when available, or with a local emoji font fallback.

Hard-Won Lessons

These are real bugs that came out of shipping real reports — preserve the fixes if you're customising the script.

CJK Characters Rendering as □

reportlab's Paragraph only uses the font set in ParagraphStyle. If fontName="Mono" but the text contains Chinese, characters render as □. Fix: always apply _font_wrap() to all text that might contain CJK, including code blocks.

Code Blocks Losing Line Breaks

reportlab treats \n as whitespace. Fix: esc_code() converts \n → <br/> and all spaces →  , preserving indentation and mid-line alignment before _font_wrap().