MdToX 1.11.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.
• Obsidian-flavored Markdown -- wikilinks ([[note|alias]], internal [[#heading]] anchors), image embeds (![[img.png|width]]), and %%comment%% stripping, on every output format; callout accents are remappable to a house palette via .theme.yaml tokens. See Obsidian-flavored Markdown.
• Infographic Diagrams -- ```infographic fenced blocks render the @antv/infographic DSL as a vector diagram (HTML/PDF: inline SVG; DOCX/PPTX: embedded PNG at 2×). Library vendored offline — no CDN at export time. Custom font via --infographic-font. See Infographic Diagrams.

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).

Theme palette override

By default each callout type carries a fixed accent. A .theme.yaml can remap any type to your house palette with flat tokens — callout-<type>-color, callout-<type>-background, callout-<type>-icon:

extends: technical
callout-warning-color: "#8e44ad"        # border + title
callout-warning-icon: "🚩"               # glyph/emoji, used on every format
callout-danger-color: "#c0392b"
callout-danger-background: "rgba(192, 57, 43, 0.18)"

A color with no background auto-derives a 10% tint, so a single token is usually enough to map a type. Overrides apply across HTML/PDF, DOCX, and PPTX, superseding the former fixed-accent contract.

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.

Obsidian-flavored Markdown: Wikilinks, Embeds & Comments

Beyond callouts, MdToX understands three more Obsidian constructs on every output format. They are always on (no flag) and degrade predictably — see the fidelity matrix below.

Wikilinks [[target]]

[[My Note]]                 → My Note
[[folder/My Note|Alias]]    → Alias
[[#Heading In This Doc]]    → links to that heading (HTML/PDF)

The visible text is the alias if given, otherwise the target's last path segment (brackets are always removed). A [[#Heading]] that matches a heading in the same document becomes a real intra-document anchor in HTML/PDF; cross-note links render as styled text (single-document conversion has no vault to resolve sibling notes against). An unresolved #heading anchor renders as text and emits a warning.

Image embeds ![[image.png]]

![[diagram.png]]            → full-width image
![[diagram.png|320]]        → 320px wide
![[diagram.png|320x200]]    → 320×200px

Image-file embeds reuse the standard image pipeline, so — exactly like ![alt](src) — they are embedded as data URIs only when image embedding is enabled (--images inline / appendix). The optional |width (or |WxH) is honored. Non-image embeds (note transclusion, e.g. ![[Another Note]]) are unsupported in single-document conversion: they render as the note name and emit a warning.

Comments %%...%%

Inline (text %%hidden%% more) and block comments are stripped from every output:

%%
This whole block is a comment and never appears.
%%

Literal %% inside inline code (`%% not a comment %%`) and fenced code blocks is preserved. An unterminated %% block emits a warning and is stripped to the end of the document.

Per-format Fidelity

Feature	HTML/PDF	DOCX	PPTX
Wikilink visible text	✓	✓	✓
Wikilink internal #heading anchor	✓ link	◐ text only	◐ text only
Image embed (with --images)	✓ sized <img>	◐ [Image: name] placeholder	◐ [Image: name] placeholder
%%comment%% stripped	✓	✓	✓

Wikilinks and embeds are intentionally single-document: there is no vault to resolve sibling notes against, so cross-note links and transclusions degrade to text. The "Obsidian" trademark note above applies equally here.

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.

Infographic Diagrams

A fenced ```infographic block renders a visual infographic using the @antv/infographic DSL:

```infographic
infographic list-grid-badge-card
data
  title I 4 principi AI-SDLC
  desc Metodologia universale OnelogicNext
  lists
    - label Markdown-native
      desc Ogni artifact è un .md; DOCX/PDF solo come export
      icon file text
    - label Integration-first
      desc Non riscriviamo PM, CI/CD, test management: li integriamo
      icon plug connection
    - label Agent-supervised human-validated
      desc Gli agenti generano, gli umani validano
      icon shield check
    - label Traceability end-to-end
      desc Tracciabile a input, agent, prompt, model, validazione umana
      icon link
theme
  palette #4f46e5 #06b6d4 #10b981 #f97316
```

The library and a subset of Lucide icons are bundled as offline embedded resources — no CDN is contacted at export time.

Per-format Fidelity

Format	Output
HTML	Inline SVG (self-contained, no external references)
PDF	Inline SVG rendered by Chromium
DOCX	PNG embedded at 2× resolution
PPTX	PNG picture shape embedded at 2× resolution

Fail-graceful: a malformed DSL block is left as the original code block — no crash, no warning noise.

Custom Font

By default the diagram uses the system font stack (system-ui / Segoe UI / Roboto — fully offline). To use a Google Fonts family, pass the font name at conversion time:

mdtox document.md -o output.pdf --infographic-font "Inter"
mdtox document.md -o output.docx --infographic-font "Source Sans Pro"

Or in frontmatter:

---
infographic-font: Inter
---

Puppeteer fetches the font from Google Fonts at render time. The rest of the document uses the theme's own font stack.

MdToX bundles @antv/infographic 0.2.19 as an offline embedded resource. The @antv/infographic library is released under the MIT License; source and license available at https://www.npmjs.com/package/@antv/infographic. The bundled Lucide icon subset (25 icons) is released under the ISC License. MdToX is not affiliated with, endorsed by, or sponsored by Ant Group or the @antv team.

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