md-tech-pdf for Visual Studio Code
Export Markdown documents with embedded Mermaid and PlantUML diagrams into clean, high-quality technical PDFs directly inside Visual Studio Code.
Overview
md-tech-pdf is a technical document PDF exporter built specifically for software engineering documents, architecture design records, system specifications, and documentation pipelines.
It renders vector diagrams cleanly, applies modern typography optimized for technical documentation, and provides seamless export actions within VS Code.
A standalone command-line interface (CLI) is also available in the repository for automated CI/CD documentation builds.
Features
- Dual Preview Modes (Paged & Continuous):
- Paged View: Realistic print preview matching actual PDF paper dimensions, custom margins, page drop-shadows, and page number badges. Respects Front Matter
pdf geometry or default settings.
- Continuous View: Seamless, full-width continuous scroll mode similar to standard Markdown previews (MarkdownPreviewEnhanced-like). Page break indicators appear as divider lines without physical page gaps.
- MarkdownLint-Compliant Page Breaks: Use 8 consecutive hashes (
########) on an isolated line to force a page break without triggering MD033 inline HTML warnings.
- Synchronized Scrolling (Scroll Sync): Accurate two-way scrolling synchronization between the Markdown editor and preview panel, with bidirectional toggle controls, configurable animation modes (
smooth vs instant), and adjustable sync delay (0ms to 100ms).
- Scroll Position Preservation: Typing and editing maintains your current scroll location in the preview pane without abrupt resets.
- Sticky Preview Toolbar: Keep actions like Export PDF, View Mode switcher (
Paged / Continuous), Refresh, Sync toggle, Scroll Animation (smooth / instant), Debounce Delay (0ms / 20ms / 50ms / 100ms), and Page Zoom (Fit / 50% - 150%) immediately accessible at the top while scrolling.
- Fast In-Memory Diagram Cache: Sub-10ms warm re-rendering for documents with complex Mermaid and PlantUML diagrams.
- Direct PDF Export: Convert Markdown files to PDF with a single command.
- Save As Dialog: Choose a customized output directory and filename interactively.
- Explorer Context Menu: Right-click any
.md or .markdown file in the Explorer view to preview or export.
- Mermaid Diagram Support: Render flowcharts, sequence diagrams, class diagrams, state diagrams, and ER diagrams without external dependencies.
- PlantUML Diagram Support: Render PlantUML diagrams with local Java and PlantUML JAR integration.
- Front Matter Configuration: Control document-level layout, margins, orientations, and custom fonts directly within Markdown.
- Custom Typography: Embedded Google Fonts and local font support with refined headings, bold weights, and technical table layouts.
- Strict Security & CSP: Isolation through nonce-based Content Security Policy for all preview webview resources.
Usage
1. Open Preview
Open a real-time side-by-side print preview matching target paper dimensions:
- Open a Markdown file in the editor.
- Click the md-tech-pdf: Open Preview icon in the editor title bar, or open the Command Palette (
Ctrl+Shift+P / Cmd+Shift+P) and run md-tech-pdf: Open Preview.
- The preview panel opens beside your editor, rendering typography and vector diagrams with high-speed in-memory caching.
2. Export to PDF
Export the currently active Markdown document directly to a PDF in the same directory:
- Open a Markdown file in the editor.
- Open the Command Palette (
Ctrl+Shift+P or Cmd+Shift+P).
- Run
md-tech-pdf: Export to PDF.
Output: document.md is compiled to document.pdf.
3. Export to PDF As
Export with a custom destination path and filename:
- Open a Markdown file in the editor.
- Open the Command Palette.
- Run
md-tech-pdf: Export to PDF As....
- Choose the target destination in the Save Dialog.
- In the VS Code File Explorer, right-click on any
.md or .markdown file.
- Select
md-tech-pdf: Open Preview or md-tech-pdf: Export to PDF.
Front Matter Configuration
You can customize PDF rendering options and global diagram defaults at the top of your Markdown file using YAML front matter.
Example:
---
title: System Architecture Design
pdf:
format: A4
landscape: false
margin:
top: 20mm
bottom: 20mm
left: 20mm
right: 20mm
diagram:
width: 140mm
height: 80mm
fit: contain
align: center
style:
font:
family: 'Noto Sans JP'
codeFamily: 'Roboto Mono'
google:
families:
- name: 'Noto Sans JP'
weights: [400, 700]
- name: 'Roboto Mono'
weights: [400, 700]
css:
- ./custom-theme.css
---
# 1. System Overview
This document demonstrates high-quality PDF export using `md-tech-pdf`.
Diagram Sizing and Positioning
md-tech-pdf gives you precise control over how Mermaid and PlantUML diagrams are sized and aligned in both print preview and exported PDFs.
Global Diagram Settings (Front Matter)
Set document-wide defaults for all diagrams under the diagram front matter section:
width: Default diagram container width (supported units: mm, cm, in, px, pt, %).height: Default diagram container height (supported units: mm, cm, in, px, pt, %).fit: Scaling behavior:
contain (default): Preserves aspect ratio while fitting within container dimensions.fill: Stretches the diagram SVG to fill the specified width and height.
align: Horizontal positioning (center [default], left, or right).
Per-Diagram Block Attributes
Override defaults for individual diagram blocks using curly brace attributes {...} following the code fence language:
```mermaid {width=160mm height=90mm align=center fit=contain}
graph TD
Client[Client] --> API[API Gateway]
API --> Service[Backend Service]
Service --> DB[(Database)]
```
PlantUML diagrams support the identical syntax:
```plantuml {width=120mm align=left}
@startuml
actor User
participant Server
User -> Server: Request
Server --> User: Response
@enduml
```
Requirements
- Browser (Mermaid & PDF): An installed Google Chrome, Microsoft Edge, Brave, or Chromium is detected automatically and used for both Mermaid rendering and PDF export, so preview and PDF look identical. Set
md-tech-pdf.browser.executablePath to use a specific browser.
- PlantUML: Requires a local Java runtime (Java 8+) and a PlantUML JAR file. Run
md-tech-pdf: Download PlantUML Jar to download the jar automatically, or specify the paths in Settings.
- Network: Required only when downloading external Google Fonts during export, or when downloading the PlantUML jar.
Environment Setup & Troubleshooting
md-tech-pdf: Run Doctor (環境診断): Checks the browser, Java runtime, PlantUML jar, Mermaid CLI, and PDF export engine, then writes a report to the md-tech-pdf: Doctor output channel. When everything is fine it prints All systems are ready!; otherwise it shows the cause and how to fix it.md-tech-pdf: Download PlantUML Jar: Downloads the latest plantuml.jar from the official GitHub releases into the extension storage (globalStorage/bin/plantuml.jar), with a cancellable progress notification. The jar is used automatically while md-tech-pdf.plantuml.jarPath is empty, and open previews are refreshed after the download.- Error cards: When a diagram cannot be rendered because of a missing environment, the preview shows a friendly message (Japanese or English, following the VS Code display language) with one-click buttons: Run Doctor, Download PlantUML Jar, and Open Settings. The raw error is available under Error details.
Configuration
Configure extension settings via VS Code Settings (Preferences: Open User Settings (JSON) or GUI):
md-tech-pdf.preview.defaultViewMode: Default preview display mode: "paged" (page-split print preview) or "continuous" (seamless scroll preview) (default: "paged").md-tech-pdf.preview.refresh: Controls when an open preview is refreshed ("manual", "onSave", or "onType", default: "onSave").md-tech-pdf.preview.debounceDelay: Debounce delay in milliseconds before refreshing the preview on typing edits when preview.refresh is "onType" (minimum: 100, default: 500).md-tech-pdf.preview.scrollSync.enabled: Default scroll synchronization state (true or false, default: true).md-tech-pdf.preview.scrollSync.behavior: Default scroll animation behavior ("smooth" or "instant", default: "smooth").md-tech-pdf.preview.scrollSync.delay: Default editor-to-preview scroll sync debounce delay in milliseconds (0, 20, 50, or 100, default: 50).md-tech-pdf.preview.zoom: Default preview zoom scale ("fit", "50%", "75%", "100%", "125%", or "150%", default: "fit").md-tech-pdf.preview.cache.persistent: Enable persistent disk caching for rendered Mermaid and PlantUML diagrams across VS Code sessions (default: true).md-tech-pdf.styles: List of custom CSS file paths (relative to workspace or document) to apply to preview and PDF export (default: []).md-tech-pdf.browser.executablePath: Absolute path to a Chromium-based browser used for Mermaid rendering and PDF export. Leave empty to auto-detect Chrome / Edge / Brave / Chromium (default: "").md-tech-pdf.plantuml.javaPath: Path to the Java executable (default: "java").md-tech-pdf.plantuml.jarPath: Path to the local plantuml.jar file. When empty, the jar downloaded by md-tech-pdf: Download PlantUML Jar is used (default: "").md-tech-pdf.export.outputDirectory: Default output directory for exports. Leave empty to output next to the source Markdown file (default: "").md-tech-pdf.export.afterExport: Action to perform automatically after export: "none", "open" (open in editor), or "reveal" (reveal in OS file manager) (default: "none").md-tech-pdf.default.pdf.format: Default PDF paper format when unspecified in Front Matter (default: "A4").md-tech-pdf.default.pdf.landscape: Default PDF page orientation (default: false).md-tech-pdf.default.pdf.margin.top: Default PDF page top margin (default: "15mm").md-tech-pdf.default.pdf.margin.bottom: Default PDF page bottom margin (default: "15mm").md-tech-pdf.default.pdf.margin.left: Default PDF page left margin (default: "15mm").md-tech-pdf.default.pdf.margin.right: Default PDF page right margin (default: "15mm").md-tech-pdf.default.diagram.width: Default diagram container width when unspecified in Front Matter (default: "").md-tech-pdf.default.diagram.height: Default diagram container height when unspecified in Front Matter (default: "").md-tech-pdf.default.diagram.fit: Default diagram fit behavior ("contain" or "fill", default: "contain").md-tech-pdf.default.diagram.align: Default diagram alignment ("center", "left", or "right", default: "center").md-tech-pdf.default.style.font.family: Default body font family when unspecified in Front Matter (default: "").md-tech-pdf.default.style.font.codeFamily: Default code font family when unspecified in Front Matter (default: "").md-tech-pdf.default.style.font.google.families: Default Google Fonts to load when unspecified in Front Matter (default: []).
Known Limitations
- Very large diagrams may push following content to a new page or leave white space if they exceed page dimensions.
- PlantUML requires Java on your machine (the jar can be downloaded with
md-tech-pdf: Download PlantUML Jar).
- Google Fonts fetching requires an active internet connection during rendering.
License
Apache License 2.0. See LICENSE for details.
Repository
Source code and issue tracker: https://github.com/ikaruga-tech/md-tech-pdf
| |
