MdToX 1.9.0

MdToX

Convert Markdown into professional PDF, DOCX, HTML, and PPTX documents with themes, TOC, cover pages, Mermaid diagrams, and more.

Install

dotnet tool install -g MdToX

Quick Start

mdtox document.md -o output.pdf
mdtox document.md -o report.docx --theme corporate --toc --cover

Output Formats

Format	Command
PDF	mdtox input.md -o output.pdf
DOCX	mdtox input.md -o output.docx
HTML	mdtox input.md -o output.html
PPTX	mdtox input.md -o output.pptx

SVG Rasterization

Convert SVG files to PNG, JPEG, or WebP images:

mdtox render-svg diagram.svg -o diagram.png
mdtox render-svg chart.svg -o chart.jpg --format jpeg --quality 90
mdtox render-svg icon.svg -o icon.webp --format webp --width 512 --scale 2

Pipe SVG via stdin:

cat diagram.svg | mdtox render-svg --format png -o output.png
echo '<svg>...</svg>' | mdtox render-svg --format png --stdout > output.png

Options: --format (png/jpeg/webp), --quality (0-100, JPEG only), --width, --height, --scale (DPI multiplier), --background (CSS color), --json, --stdout.

Reverse Conversion

Convert DOCX back to Markdown with image extraction:

mdtox document.docx -o output.md

Image Embedding

Embed images referenced in your Markdown into the output document (PDF, HTML). Three modes:

Mode	Flag	Behavior
Disabled	--images disabled	Default. Image references pass through as-is
Inline	--images inline	Images embedded at full page width, aspect ratio preserved
Appendix	--images appendix	Images collected at document end with bidirectional hyperlinks

# Embed images inline
mdtox document.md -o report.pdf --images inline

# Images in appendix with links
mdtox document.md -o report.pdf --images appendix

Local images (relative to the .md file) are resolved automatically. Remote images (http/https) require explicit consent:

• Interactive terminal: you're prompted with a list of URLs to approve (all, none, or specific)
• Agent/pipeline: use --allow-remote-images to download without prompting
• MCP: pass allowRemoteImages: true in the tool call

If an image can't be loaded, the document is still produced — failed images are reported as warnings.

The mode can also be set via frontmatter:

---
images: inline
allow-remote-images: true
---

DOCX Templates

Use a pre-styled DOCX file as a template. MdToX finds the {{CONTENT}} marker in the template and replaces it with the converted Markdown content, preserving the template's styles, headers, footers, and formatting.

mdtox document.md -o output.docx --template template.docx

Or via frontmatter:

---
template: ./template.docx
---

How it works:

• Create a DOCX file with your desired styles, headers, footers, and page layout
• Add a paragraph containing {{CONTENT}} where the Markdown content should be inserted
• Content before and after the marker is preserved
• The template's numbering definitions (lists) are merged automatically

Precedence: --template from CLI overrides the frontmatter template: value.

Multi-token Templates

Templates can contain multiple named placeholders ({{tokenName}}), each replaced independently. This lets you populate headers, footers, and body sections from a single Markdown file.

Token syntax: {{tokenName}} — names must match [A-Za-z0-9_-]+. Token matching is case-insensitive ({{TITLE}} matches a title value).

Value sources (in order of precedence):

Source	Syntax	Produces
YAML frontmatter	key: value	Plain-text value (scalar strings only; reserved keys like format, theme, toc are excluded)
Token block	::: token name ... :::	Rich Markdown content (headings, lists, tables, etc.)
Body fallback	Everything outside frontmatter and token blocks	Implicit content token

If a name appears in both frontmatter and a ::: token block, MdToX raises an error.

Block vs inline replacement:

• Block-level — when {{tokenName}} is the only content in a paragraph, the entire paragraph is replaced with the rendered Markdown content (preserving rich formatting).
• Inline — when {{tokenName}} appears alongside other text in a paragraph, the token is replaced with a plain-text version of the value. If the value contains rich content, it is degraded to text and a warning is emitted.

Dangling tokens and values:

• A template token with no matching value → the paragraph is removed and a warning is emitted.
• A value with no matching template token → the value is discarded with a warning.
• These warnings appear in the warnings array when using --json or MCP tools.

Complete example:

Markdown file (report.md):

---
title: Quarterly Report
author: Jane Smith
date: 2026-Q1
template: ./company-template.docx
---

::: token abstract
This report summarizes **Q1 performance** across all departments.
Key highlights include:
- Revenue up 12%
- Customer satisfaction at 94%
:::

## Introduction

The first quarter showed strong growth across all metrics...

## Conclusion

We expect continued momentum into Q2.

DOCX template (company-template.docx) layout:

• Header: {{title}}
• Footer: {{author}} — {{date}}
• Body: {{abstract}} paragraph, then {{content}} paragraph

Run:

mdtox report.md -o report.docx

The output DOCX will have the header, footer, abstract, and body all populated from the single Markdown source.

Discovering template tokens: Use the inspect_docx_template MCP tool to list all {{tokenName}} placeholders in a template, including their locations (body, header, footer, table cell, text box) and context (block or inline).

Document Features

• Table of Contents -- --toc generates a TOC from headings
• Cover Page -- --cover --author "Name" adds a title page with author and date
• Page Numbers -- --page-numbers adds page numbering (PDF)
• Landscape -- --landscape switches to landscape orientation
• Mermaid Diagrams -- auto-detected and rendered (flowchart, sequence, ER, etc.)
• PDF Bookmarks -- automatically generated from heading structure
• Page-Break Protection -- in print/PDF, diagrams (.mermaid-diagram), HTML embeds (.html-embed), code blocks, tables, blockquotes, and callouts use break-inside: avoid; content taller than a page is scaled to fit (max-height: 92vh with object-fit: contain) so an oversize Mermaid or image renders whole on a single page instead of being split. Opt out per element by wrapping it in <div class="allow-break">…</div> — this restores normal flow and removes the height cap.
• Diff Code Blocks -- a fenced ```diff block is colored per line (+ additions green, - removals red, @@ hunk meta, context unchanged) across HTML, PDF, DOCX, and PPTX; colors are theme-overridable. See Diff Code Blocks.

Extended Callouts & Highlight (GFM alerts + Obsidian-compatible syntax)

MdToX accepts GitHub Flavored Markdown alerts and the extended admonition set popularized by Obsidian, plus ==highlighted text== (Pandoc/CriticMarkup), across every output format. Rendering is independent — see the per-format fidelity matrix below for what survives in each.

Syntax

> [!tip] Optional Custom Title
> Body text on the following lines.
>
> > [!warning] Nested callout
> > Nest by adding another `>` level.

> [!note]- Collapsed foldable
> Hidden until expanded.

> [!note]+ Expanded foldable
> Shown by default, but collapsible.

Inline ==highlighted text== works anywhere in the document.

• > [!type] Title -- the title is optional; omit it to use the type name.
• > > -- nest callouts by adding quote levels.
• > [!type]- -- foldable, collapsed by default; > [!type]+ -- foldable, expanded by default.
• ==text== -- inline highlight.

Callout Types

GitHub's five alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION) are a subset of the extended set below. Each type has a color, icon, and one or more aliases:

Type	Aliases
note	—
abstract	summary, tldr
info	—
todo	—
tip	hint, important
success	check, done
question	help, faq
warning	caution, attention
failure	fail, missing
danger	error
bug	—
example	—
quote	cite

Unknown or misspelled types still render — they fall back to a neutral default style and emit a warning (see Limitations).

Per-format Fidelity

Feature	HTML/PDF	DOCX	PPTX
Color + title + border/bg	✓	✓	✓
Type icon	✓ SVG	◐ unicode glyph	◐ unicode glyph
Foldable (-/+)	✓ interactive (<details>); PDF forced open	✗ always expanded	✗ always expanded
Nesting	✓	✓	◐ limited by slide depth
==highlight==	✓	✓	✓

Limitations

• Icons -- DOCX and PPTX use monochrome unicode glyphs, not the SVG icons used in HTML/PDF.
• Foldables -- the -/+ collapse state is interactive only in HTML; everywhere else (PDF, DOCX, PPTX) the callout is always rendered expanded.
• PPTX nesting -- nesting is emulated with indentation, and shapes do not auto-size; separate heavy slides with ---.
• Deep nesting -- nesting beyond depth 6 flattens to a plain blockquote and emits one warning.
• Malformed/unknown callouts -- surface as human-readable strings in the conversion warnings (visible via --json or MCP).

"Obsidian" is a trademark of Dynalist Inc. MdToX is not affiliated with, endorsed by, or sponsored by Obsidian or Dynalist Inc. The supported syntax is a subset of GitHub Flavored Markdown alerts extended with admonition types popularized by Obsidian; the inline ==highlight== mark originates with Pandoc/CriticMarkup. Rendering is independent and intentionally lossy across formats — see the fidelity matrix above for what each output preserves.

Diff Code Blocks

A fenced code block tagged diff is colored per line by its leading marker, on every output format (HTML, PDF, DOCX, PPTX):

```diff
+ added line
- removed line
  context line
@@ hunk header @@
```

Marker	Meaning	Style
+	addition	green text on a tinted green background
-	removal	red text on a tinted red background
@ (e.g. @@)	hunk/meta header	attenuated meta color
(space or other)	unchanged context	normal code styling

The palette is driven by theme tokens, overridable in a .theme.yaml:

Token	Default
diff-add-color	#22863A
diff-add-background	#E6FFED
diff-remove-color	#B31D28
diff-remove-background	#FFEEF0
diff-meta-color	#6F42C1

The built-in dark theme ships darker, legible variants. Non-diff code blocks are unaffected and render as plain monospace.

Print/PDF: long code lines wrap (white-space: pre-wrap) instead of being clipped at the page margin; on-screen HTML keeps horizontal scrolling.

Themes

Apply built-in themes for consistent styling:

mdtox input.md -o output.pdf --theme corporate

Built-in themes: default, corporate, technical, academic, minimal, ocean, forest, sunset, dark, elegant.

• --list-themes -- show all available themes
• --extract-theme template.docx -- extract a theme from a DOCX template
• --theme-catalog -- generate a visual preview of all themes

Custom themes can be loaded from .theme.yaml or .theme.json files.

Frontmatter

Control conversion via YAML frontmatter in your Markdown file:

---
format: pdf
theme: corporate
toc: true
cover: true
author: "Author Name"
page-numbers: true
template: ./my-template.docx
---

Then simply run mdtox file.md -- all frontmatter values are applied automatically.

AI Agent Integration

MdToX includes a built-in MCP (Model Context Protocol) server for integration with AI assistants.

MCP Server

Start the MCP server:

mdtox mcp

This exposes tools via stdio transport: convert_file, convert_content, list_themes, rasterize_svg.

The rasterize_svg tool accepts either inline SVG content (svgContent) or a file path (svgFilePath).

All conversion tools accept images ("disabled", "inline", "appendix"), allowRemoteImages (true/false), and templatePath (absolute path to a .docx template with {{CONTENT}} placeholder, DOCX output only) parameters.

VS Code / GitHub Copilot

Add .vscode/mcp.json to your project (included in this repo):

{
  "servers": {
    "mdtox": {
      "type": "stdio",
      "command": "mdtox",
      "args": ["mcp"]
    }
  }
}

Copilot Chat will automatically discover MdToX tools and can convert documents on request.

Visual Studio 2022 / 2026

Visual Studio reads the same .vscode/mcp.json file. Alternatively, configure via Tools > Options > GitHub Copilot > MCP Servers.

Claude Code / Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "mdtox": {
      "command": "mdtox",
      "args": ["mcp"]
    }
  }
}

JSON Output

Use --json for machine-parseable output:

mdtox document.md -o output.pdf --json

{
  "status": "success",
  "input": "document.md",
  "output": "output.pdf",
  "format": "pdf",
  "duration_ms": 2500,
  "warnings": []
}

When image embedding is active, any resolution failures appear in the warnings array.

Requirements

• .NET 10 SDK
• Chromium downloads automatically on first PDF/HTML use

License

MIT