md2x

Markdown → PDF/DOCX/HTML/Image converter.

Features

• 📦 Supported formats: pdf, docx, html, png, jpg/jpeg, webp
• 🔌 MCP (Model Context Protocol): built-in MCP server
• 🧠 Skills: includes an agent skill at skills/md2x/SKILL.md for repeatable conversions/workflows
• 🧩 Custom templates: render md2x blocks with Vue SFC (.vue) and Svelte 5 (.svelte) templates (plus plain HTML)

CLI Usage

Export to PDF:

npx md2x input.md

Export to DOCX:

npx md2x input.md -f docx

Export to HTML:

npx md2x input.md -f html

Export to PNG:

npx md2x input.md -f png -o output.png

List themes:

npx md2x --list-themes

Use a theme:

npx md2x input.md -o output.pdf --theme academic

Help:

npx md2x -h

CLI Options

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/Image diagram rendering mode	live	img, live, none
--hr-page-break	-	Convert horizontal rules to page breaks	true for PDF/DOCX, false for HTML/Image	true, false
--templates-dir	-	Extra template dir for md2x blocks (repeatable; resolved against input dir when relative)	-	Directory path
--list-themes	-	List all available themes	-	-

Diagram Modes (HTML/Image)

• live (default): Render diagrams in the browser on load using online CDN scripts (Mermaid, @viz-js/viz, Vega-Lite, Infographic)
• img: Pre-render diagrams as embedded images (offline, stable; no CDN)
• none: Keep diagram source blocks only (no rendering)

Front Matter Options

When converting a markdown file, you can put options in YAML front matter (the CLI merges front matter with CLI flags; explicit CLI flags win).

Common (All Formats)

---
format: pdf        # pdf | docx | html | png | jpg | jpeg | webp
theme: default
hrAsPageBreak: true
---

PDF

---
format: pdf
title: "My Doc"     # used for PDF metadata/header templates
pdf:
  format: A4        # A4 | Letter | Legal | A3 | A5
  landscape: false
  margin:
    top: 1cm
    bottom: 1cm
    left: 1cm
    right: 1cm
  printBackground: true
  scale: 1
  displayHeaderFooter: false
  headerTemplate: "<div style='font-size:10px;width:100%;text-align:center;'><span class='title'></span></div>"
  footerTemplate: "<div style='font-size:10px;width:100%;text-align:center;'>Page <span class='pageNumber'></span> / <span class='totalPages'></span></div>"
---

DOCX

---
format: docx
theme: default
hrAsPageBreak: true
---

HTML

---
format: html
title: "My Doc"
standalone: true    # full HTML document (default)
baseTag: true       # emit <base href="file://.../"> for resolving relative paths (default)
diagramMode: live   # img | live | none
cdn:                # optional: override CDN URLs (used when diagramMode: live)
  mermaid: "https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"
  # Template blocks:
  vue: "https://unpkg.com/vue@3/dist/vue.global.js"
  vueSfcLoader: "https://cdn.jsdelivr.net/npm/vue3-sfc-loader/dist/vue3-sfc-loader.js"
  svelteCompiler: "https://esm.sh/svelte@5/compiler"
  svelteBase: "https://esm.sh/svelte@5/"
---

Image (PNG/JPEG/WebP)

---
format: png
diagramMode: live   # or "img" for offline (no CDN)
image:
  # selector can be a string or an array of selectors (CSS selector list).
  selector:
    - 'div.md2x-diagram[data-md2x-diagram-kind="mermaid"]'
    - 'div.md2x-diagram[data-md2x-diagram-kind="infographic"]'
  # selectorMode: first | each | union | stitch (default: stitch)
  # - union: capture the union bounding box (includes in-between page content)
  # - stitch: stack matched elements and capture only them (no in-between content)
  selectorMode: stitch
  selectorGap: 16      # optional: vertical gap (px) between stitched elements
  selectorPadding: 8   # optional: padding (px) around the stitched region
  split: auto          # optional: split very tall output into multiple images
---

When image.split produces multiple parts, outputs are written as output.part-001.png, output.part-002.png, ...

Diagram blocks are tagged with data-md2x-diagram-kind so you can target specific types via selectors: