xMarkdown2PDF

Convert Markdown with Mermaid and PlantUML to HTML or PDF directly inside VS Code.

xMarkdown2PDF is built for teams that want a focused workflow:

• live side-by-side preview while editing Markdown
• local HTML export
• local PDF export
• Mermaid support in preview and export
• PlantUML support in preview and export
• versioned runtime libraries that you can upgrade intentionally

It is not trying to be a full Markdown authoring platform. The goal is a smaller, clearer extension for documentation workflows that depend on diagrams.

Why This Extension Exists

The VS Code marketplace already has strong Markdown and diagram extensions. xMarkdown2PDF fits in the gap between them:

When xMarkdown2PDF Is a Better Fit

Choose xMarkdown2PDF if you want:

• one extension for Markdown preview plus document export
• Mermaid and PlantUML in the same Markdown document
• a smaller feature surface than Markdown Preview Enhanced
• HTML and PDF output from the same rendering pipeline
• a controlled way to update embedded runtime libraries

Choose other extensions if you want:

• PNG or JPEG export: Markdown PDF is broader here
• advanced Markdown notebooks, code chunks, Pandoc, presentations, or publishing workflows: Markdown Preview Enhanced is broader here
• rich PlantUML authoring features such as snippets, symbol navigation, and standalone diagram project workflows: PlantUML is stronger here
• only Mermaid in the built-in VS Code preview: Markdown Preview Mermaid Support is simpler here

Features

• Preview Markdown in a side-by-side webview panel
• Auto-refresh preview while you edit
• Scroll sync from editor selection to preview
• Optionally show a generated table of contents in the preview
• Export .md to .html
• Export .md to .pdf
• Generate a linked table of contents for exported HTML and PDF
• Generate viewer-friendly document outlines for exported HTML and PDF
• Add configurable branded PDF headers and footers
• Render Mermaid diagrams in preview and export
• Render PlantUML diagrams to inline SVG before export
• Support PlantUML render modes:
  • local
  • self-hosted PlantUML server
  • Kroki
• Upgrade bundled runtime libraries with a command
• Theme support for preview and export:
  • github
  • dark
  • custom

Commands

Default keybinding:

• Ctrl+Shift+V opens the xMarkdown2PDF preview for Markdown files

Installation

From VS Code Marketplace

Search for xMarkdown2PDF in Extensions.

From a VSIX file

code --install-extension /absolute/path/to/xmarkdown2pdf-0.1.1.vsix

Library Setup on Your Machine

After installing the extension, run this once so diagram libraries are present and up to date:

1. Open Command Palette.
2. Run Markdown: Upgrade Libraries.
3. Wait for the success notification.
4. If needed, open output channel xMarkdown2PDF — Upgrade to see details.

This command downloads and stores managed runtime files under media/libs/:

• mermaid.min.js
• highlight.min.js
• plantuml.jar

Configure PlantUML Linking in Settings

Open your VS Code settings.json and choose one mode.

Local mode (recommended)

Use the bundled plantuml.jar managed by the extension:

{
  "xmarkdown2pdf.plantuml.renderMode": "local",
  "xmarkdown2pdf.plantuml.jarPath": ""
}

Use your own custom jar path:

{
  "xmarkdown2pdf.plantuml.renderMode": "local",
  "xmarkdown2pdf.plantuml.jarPath": "/absolute/path/to/plantuml.jar"
}

Server mode

{
  "xmarkdown2pdf.plantuml.renderMode": "server",
  "xmarkdown2pdf.plantuml.serverUrl": "https://your-plantuml-server/plantuml"
}

Kroki mode

{
  "xmarkdown2pdf.plantuml.renderMode": "kroki"
}

Notes

• For local mode, make sure Java is installed on your machine.
• xmarkdown2pdf.plantuml.jarPath is only used when the path exists; otherwise the extension falls back to the managed jar.
• PlantUML server URL must be http or https.

Quick Start

1. Open a Markdown file.
2. Run Markdown: Open Preview (WYSIWYG).
3. Add Mermaid or PlantUML fenced code blocks.
4. Run Markdown: Export to HTML or Markdown: Export to PDF.

Exported files are written next to the source Markdown file using the same base name. By default, exports include a linked table of contents generated from document headings. PDF exports also enable browser-supported outline bookmarks by default, and HTML exports expose a semantic document outline from those same headings.

Example

Mermaid

```mermaid
flowchart TD
    A[Start] --> B{Build docs?}
    B -->|Yes| C[Render diagrams]
    B -->|No| D[Skip]
    C --> E[Export HTML and PDF]
```

PlantUML

```plantuml
@startuml
actor User
User -> System: Export markdown
System --> User: HTML / PDF
@enduml
```

A larger sample document is included in the extension package as sample.md.

Settings

PDF Branding

Use branding settings when you need company headers and footers in exported PDFs.

Quick start:

1. Enable branding in settings.
2. Set company name and optional logo path.
3. Optionally customize templates using inline HTML or file paths.
4. Export to PDF.

Example:

{
  "xmarkdown2pdf.brand.enabled": true,
  "xmarkdown2pdf.brand.companyName": "Acme Corporation",
  "xmarkdown2pdf.brand.logoPath": "/absolute/path/to/logo.png",
  "xmarkdown2pdf.brand.primaryColor": "#0066cc",
  "xmarkdown2pdf.brand.headerTemplatePath": "/absolute/path/to/header.html",
  "xmarkdown2pdf.brand.footerTemplatePath": "/absolute/path/to/footer.html"
}

Sample templates are included:

• media/brand/sample_header.html
• media/brand/sample_footer.html

Template notes:

• Header/footer HTML must use inline styles.
• Puppeteer supports dynamic fields via injected classes:
  • <span class="pageNumber"></span>
  • <span class="totalPages"></span>
  • <span class="title"></span>
  • <span class="date"></span>

Use User-Downloaded JS Libraries

If you downloaded your own JS files, point settings to those absolute paths. When a custom path is missing or invalid, xMarkdown2PDF automatically falls back to bundled libraries.

{
  "xmarkdown2pdf.preview.mermaidJsPath": "/absolute/path/to/mermaid.min.js",
  "xmarkdown2pdf.preview.highlightJsPath": "/absolute/path/to/highlight.min.js"
}

Use a User-Downloaded Browser for PDF Export

If you already have Chromium or Chrome installed/downloaded locally, you can use it instead of Puppeteer's managed browser.

{
  "xmarkdown2pdf.pdf.browserExecutablePath": "/absolute/path/to/chrome-or-chromium",
  "xmarkdown2pdf.pdf.launchArgs": [
    "--no-sandbox",
    "--disable-setuid-sandbox",
    "--disable-dev-shm-usage"
  ]
}

Notes:

• xmarkdown2pdf.pdf.browserExecutablePath must be the exact executable file path, not a folder.
• If the path is empty or invalid, xMarkdown2PDF falls back to Puppeteer's default browser resolution.

PlantUML Modes

Local

Use local PlantUML rendering when you want an offline workflow. In practice, this usually means:

• Java is available
• plantuml.jar is available if your environment does not already provide PlantUML through the underlying tooling

Server

Use a self-hosted PlantUML server when you want centralized rendering and easier setup across a team.

Kroki

Use Kroki when you prefer a hosted HTTP rendering workflow.

Security and Runtime Notes

• PDF export renders through Puppeteer in a headless browser.
• During PDF generation, network requests are blocked except for the self-contained page content used by the export pipeline.
• PlantUML server mode only accepts http and https URLs.

Current Scope

xMarkdown2PDF is intentionally narrower than some established alternatives.

Current strengths:

• Markdown plus Mermaid plus PlantUML in one workflow
• focused HTML and PDF export
• live preview with minimal setup
• controlled library upgrades

Current limitations:

• no PNG or JPEG export
• no PlantUML authoring helpers such as snippets or diagram symbol navigation
• no Pandoc, slide deck, or code-chunk workflow
• no batch export or convert-on-save workflow yet

Roadmap Ideas

• output directory configuration
• convert on save
• additional themes
• better Mermaid render controls in preview
• stronger PlantUML local-mode setup guidance
• smaller packaged VSIX footprint

Development

npm install
npm run build
npm test -- --runInBand

Package a VSIX:

npx @vscode/vsce package --allow-missing-repository

License

MIT