md2x - Markdown Converter
Quick Start: Run npx md2x input.md for PDF, add -f docx for Word, -f html for web, or -f png for a full-page screenshot image. Customize with --theme (academic, minimal, etc.). Supports front matter config in markdown files.
Critical Usage Rules
Rule 1: Basic Conversion
# PDF (default)
npx md2x input.md
# DOCX
npx md2x input.md -f docx
# HTML
npx md2x input.md -f html
# Image (full-page screenshot via Puppeteer)
npx md2x input.md -f png
npx md2x input.md -f jpg
npx md2x input.md -f webp
For very tall documents, md2x will automatically split the output into multiple files:
output.part-001.png, output.part-002.png, ...
Rule 2: Output Control
# Specify output path
npx md2x input.md -o output.pdf
# Auto-named output (input name + format extension)
npx md2x README.md -f docx # → README.docx
# Format can be inferred from output extension (no -f needed)
npx md2x README.md README.png
npx md2x README.md README.webp
Rule 3: Theme Selection
# List available themes
npx md2x --list-themes
# Use specific theme
npx md2x input.md --theme academic
npx md2x input.md -t minimal
Rule 4: Page Break Control
# Horizontal rules as page breaks (default for PDF/DOCX)
npx md2x input.md --hr-page-break true
# Keep horizontal rules as visual dividers (default for HTML)
npx md2x input.md --hr-page-break false
Rule 5: HTML Diagram Modes
# Live rendering with CDN (default, requires internet)
npx md2x input.md -f html --diagram-mode live
# Pre-rendered images (offline-ready)
npx md2x input.md -f html --diagram-mode img
# Source code only (no rendering)
npx md2x input.md -f html --diagram-mode none
Rule 6: Front Matter Configuration
---
format: pdf
theme: academic
hrAsPageBreak: true
title: My Document
---
# Document Content
CLI Options Reference
| Option | Alias | Description | Default | Values |
|---|---|---|---|---|
--help | -h | Show help message | - | - |
--version | -v | Show version number | - | - |
--output | -o | Output file path | Input name with format extension | File path |
--format | -f | Output format | pdf | pdf, docx, html, png, jpg/jpeg, webp |
--theme | -t | Theme name | default | See --list-themes |
--diagram-mode | - | HTML diagram rendering mode | live | img, live, none |
--hr-page-break | - | Convert horizontal rules to page breaks | true for PDF/DOCX, false for HTML | true, false |
--list-themes | - | List all available themes | - | - |
Common Pitfalls
| Issue | Solution |
|---|---|
| Input file not found | Use absolute path or verify file exists |
| Theme not found | Run --list-themes to see available options |
| Diagrams not rendering in HTML | Check --diagram-mode setting and internet connection |
| Page breaks not working | Verify --hr-page-break true for PDF/DOCX |
| Output directory doesn't exist | Tool creates directories automatically |
Supported Features
Diagrams
- Mermaid: Flowcharts, sequence diagrams, state machines, Gantt charts
- Graphviz: DOT language graphs
- Vega/Vega-Lite: Data visualizations and charts
- Infographic: Quick KPI and metric displays
- HTML/SVG: Embedded graphics
Content
- Math: LaTeX formulas via KaTeX
- Code: Syntax highlighting for 100+ languages
- Tables: Full markdown table support
- Images: Local and remote image embedding
- Links: Internal and external hyperlinks
Priority Order (CLI vs Front Matter)
CLI arguments explicitly set take precedence over front matter:
- CLI explicit (highest priority)
- Front matter in markdown file
- Default values (lowest priority)
Example:
# Front matter has theme: minimal
# CLI overrides with theme: academic
npx md2x input.md --theme academic # Uses academic
Output Format
# Command
npx md2x input.md -f pdf --theme academic
# Console output
Converting: input.md
Format: PDF
Theme: academic
HR as page break: true
Output: /path/to/input.pdf
Done!
Related Files
For detailed examples and advanced usage patterns, refer to references below:
- examples.md — Common use cases, front matter examples, batch conversion patterns, and troubleshooting