Markdown Studio: Local PDF Export

Preview modern Markdown and export PDFs locally with Mermaid, PlantUML, WaveDrom, math, TOCs, and bookmarks.

View the sample PDF

Markdown Studio renders Markdown, diagrams, math, code, local assets, TOCs, PDF indexes, and PDF bookmarks from one VS Code workflow. Core Markdown, diagram rendering, and PDF export run on your machine. External resources use whitelist mode by default with GitHub domains allowlisted; switch to block-all for strict LocalOnly documents.

New here? Start with docs/getting-started.md for common Preview, PDF export, diagram, and LocalOnly workflows.

Quick Start

1. Open a Markdown file.
2. Run Markdown Studio: Preview: Open Beside.
3. Run Markdown Studio: PDF: Export when the document is ready.

For PlantUML and PDF export dependencies, run Markdown Studio: Tools: Setup Dependencies if prompted.

Why Markdown Studio?

• Local-first by default: Markdown, diagrams, syntax highlighting, math, and PDF export run on your machine.
• Technical-document ready: Mermaid, PlantUML, WaveDrom, SVG, code highlighting, KaTeX, TOC, PDF index, and bookmarks are integrated.
• Security-aware: external resources default to a GitHub allowlist and can be blocked or allowed explicitly.
• Practical PDF output: page formats, margins, headers/footers, filenames, cover pages, TOC handling, page breaks, and bookmarks are configurable.

Features

Preview

• Live preview with incremental updates — edits reflect instantly without full reload
• Side-by-side panel synced to your editor
• Source jump — double-click in preview to jump to the corresponding source line
• Loading overlay with progress indicator for initial render
• Dark / light theme auto-switching — follows VS Code color theme with manual override (auto / light / dark)

Diagram Rendering

• Mermaid — client-side rendering, theme-aware (dark/light), no external dependencies
• PlantUML — bundled JAR with Smetana layout engine, no Graphviz or remote server needed
• WaveDrom — local timing diagrams from wavedrom, wavejson, and wavedrom-json fenced blocks
• Inline SVG — rendered directly, sanitized for security
• Interactive zoom & pan — scroll-wheel zoom (cursor-centered, 0.25×–4×), mouse-drag pan, toolbar reset

PDF Export

• High-fidelity PDF output via Playwright Chromium (headless, local)
• Configurable page format: A3, A4, A5, Letter, Legal, Tabloid
• Custom header/footer with HTML templates (page numbers, title, date)
• CSS page-break-before / page-break-after support
• Configurable page margins (CSS units)
• PDF Index with page numbers — "Chapter ... p.N" style TOC page with dot leaders and anchor links
• PDF Bookmarks (outlines) — heading-based bookmark tree for PDF viewer sidebar navigation
• Optional Markdown cover page — write a cover block in the same file, or use cover.md as an advanced shared template
• Customizable output filename via template variables (${filename}, ${date}, ${title}, etc.)

Syntax Highlighting

• highlight.js with VS Code Dark+/Light+ color mapping
• 25+ languages: TypeScript, JavaScript, Python, Java, Go, Rust, C/C++, C#, Ruby, PHP, Swift, Kotlin, SQL, Bash, Dockerfile, and more

Extended Markdown

• Task lists / checkboxes: - [ ] unchecked, - [x] checked
• Footnotes: [^1] references with auto-numbered footnote section
• Emoji: :smile: → 😄, :rocket: → 🚀 (full GitHub shortcode set)
• LaTeX math: inline $E = mc^2$ and display $$\int_0^1 x^2 dx$$ via KaTeX
• Definition lists: term + : definition syntax
• Superscript / subscript: ^sup^ and ~sub~

Markdown Compatibility And Known Limits

Markdown Studio targets CommonMark/GitHub-flavored Markdown plus the extensions listed above. The local corpus currently covers Preview/PDF export for common tables, task lists, footnotes, math, diagrams, CJK text, raw HTML, local assets, page breaks, TOC/index/bookmarks, long documents, and security-sensitive links/resources.

Some documentation-tool dialects are intentionally treated as plain Markdown/HTML unless a dedicated parser is added:

• Obsidian-style wiki links and embeds, such as [[Page]] and ![[image.png]], are not resolved as workspace links.
• GitHub alert blocks, such as > [!NOTE], render as ordinary blockquotes.
• MDX/JSX-like tags are passed through as raw HTML-like content; component semantics are not evaluated.
• YAML front matter is rendered as Markdown text rather than parsed as document metadata.
• Automatic visual-diff regression testing is not included; local corpus screenshots are available for manual visual review.

Style Presets

Five built-in presets with per-setting overrides:

Security

• CSP policy: default-src 'none' by default
• External resource control: block-all / whitelist / allow-all
• Default external-resource mode is whitelist; GitHub domains are included by default for common README assets
• Use block-all for strict LocalOnly documents
• SVG sanitization via sanitize-html

Automatic Dependency Management

• One-command setup: Amazon Corretto JDK + Playwright Chromium
• Auto-detection and installation on first activation
• Manual reinstall via Setup Dependencies command

Local-First Architecture

Commands

Configuration

See docs/configuration.md for the full settings reference. See docs/glossary.md for terminology used across UI strings and docs.

Common settings:

The same CSS stack applies to both preview and PDF export. Preview width is controlled separately by markdownStudio.preview.contentWidth and does not change PDF page size.

For the simplest cover page, keep the cover content in the same Markdown file:

<!-- markdown-studio:cover -->
# Company Spec A4

<svg viewBox="0 0 240 80" xmlns="http://www.w3.org/2000/svg">
  <rect width="240" height="80" fill="#123b6d" />
  <text x="24" y="50" fill="white">Enterprise PDF</text>
</svg>

Prepared for Markdown Studio
<!-- /markdown-studio:cover -->

# Main Document

PDF export renders the cover block first and removes it from the body pages. Raw HTML and inline SVG can be used in the cover when your workspace security settings allow them. If no embedded cover block exists, Markdown Studio falls back to cover.md next to the exported Markdown file. Set markdownStudio.export.cover.enabled to false to disable cover assembly.

Team-Shared PDF Settings

Portable PDF settings can be shared as JSON. Commit one JSON file to a repository when a team needs the same PDF page size, CSS, security mode, headers, cover behavior, TOC, PDF index, and bookmarks across contributors.

In a workspace, every successful Export PDF writes a timestamped settings snapshot under .vscode/ and keeps the latest three PDF-export history files. Manual Export Current Settings to JSON prompts for a display name, uses a separate filename prefix, includes creation metadata, and is not pruned automatically. Import Settings from JSON shows recent exports by display name and metadata before applying the selected JSON to User or Workspace settings.

{
  "schemaVersion": 1,
  "name": "Company Spec A4",
  "createdAt": "2026-05-28T03:20:15.000Z",
  "source": "manual-export",
  "pageFormat": "A4",
  "stylePreset": "github",
  "styleTheme": "markdown-pdf",
  "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
  "fontSize": 14,
  "lineHeight": 1.6,
  "margin": "20mm",
  "customCss": "h1 { color: navy; }",
  "securityMode": "block-all",
  "allowedDomains": ["github.com", "raw.githubusercontent.com"],
  "headerEnabled": true,
  "headerTemplate": null,
  "footerEnabled": true,
  "footerTemplate": null,
  "pageBreakEnabled": true,
  "includeBookmarks": true,
  "includePdfIndex": true,
  "pdfIndexTitle": "Table of Contents",
  "hidePdfToc": true,
  "coverEnabled": true,
  "coverPath": "cover.md",
  "tocLevels": "1-3",
  "tocOrderedList": false,
  "tocPageBreak": true,
  "codeBlockLineNumbers": true,
  "outputFilename": "${filename}"
}

PDF export history files are named .vscode/markdown-studio-pdf-settings-*.json. Manual settings files are named .vscode/markdown-studio-settings-*.json. Use Markdown Studio: Settings: Import to choose from either recent list, or browse to another JSON file. Import applies the selected JSON to User or Workspace settings.

Example shared settings files are available in examples/settings/:

• company-spec-a4.json — A4 technical specs with GitHub styling and PDF index.
• local-only-a4.json — strict LocalOnly A4 export with all external resources blocked.
• release-notes-letter.json — Letter-sized release notes with date-based filenames.
• covered-spec-a4.json — A4 specs that prepend examples/cover.md before the body PDF.

WaveDrom

WaveDrom timing diagrams are rendered locally in Preview and PDF export from fenced blocks:

```wavedrom
{ signal: [
  { name: "clk", wave: "p......" },
  { name: "bus", wave: "x.34.5x", data: ["head", "body", "tail"] }
]}
```

Aliases wavejson and wavedrom-json are also supported. JSON is parsed directly; WaveJSON object-literal examples are parsed with bundled JSON5 inside the webview. Raw <script type="WaveDrom"> blocks are intentionally not executed.

Distribution note: WaveDrom is an MIT-licensed npm dependency pinned in package-lock.json and bundled into the webview script by esbuild. The upstream package is not manually modified or vendored under third_party/; license and copyright details are listed in third-party-notices.md.

PlantUML

PlantUML v1.2024.8 is bundled at third_party/plantuml/plantuml.jar (GPLv2). Uses Smetana layout engine — no external Graphviz installation needed. See third-party-notices.md for license details.

Table of Contents (TOC)

• Insert TOC command generates a TOC from document headings
• Auto-updates on save when TOC markers (<!-- TOC -->...<!-- /TOC -->) are present
• Configurable heading level range, ordered/unordered list, page break in PDF

Code Block Line Numbers

• Line numbers displayed alongside code blocks (configurable)
• Copy-safe: line numbers are excluded when copying code text

Network / Proxy Support

• Proxy auto-detection from VS Code settings and environment variables
• Custom CA certificate paths for SSL inspection environments (e.g. Zscaler)

Troubleshooting

See docs/troubleshooting.md for dependency setup, proxy/CA guidance, and offline installation notes.

v1.0 Highlights

• Local-first Preview and PDF export with Mermaid, PlantUML, WaveDrom, KaTeX, syntax highlighting, and local assets.
• Current-tab and full-width Preview commands with configurable preview width.
• Source jump is enabled by default; double-click rendered Markdown or diagrams to jump back to the source line.
• Interactive diagram zoom/pan with focus-gated wheel zoom, drag pan, toolbar reset, and crisp SVG re-rendering.
• PDF index pages, PDF bookmarks, custom headers/footers, page breaks, and output filename templates.
• GitHub allowlist external-resource policy by default, with strict LocalOnly available via block-all.
• Japanese localization for commands, settings, and extension metadata.
• Clean first-run dependency setup for managed Corretto, bundled PlantUML, and local Playwright Chromium.

Positioning

Markdown Studio v1.0 focuses on technical Markdown documents that need dependable Preview and PDF output without leaving VS Code. It is built for local rendering, diagram-heavy README/spec documents, and export workflows where security settings, PDF navigation, and repeatable output matter.

Key differences:

• Preview and PDF export share the same rendering stack, so diagrams, math, code highlighting, local assets, and custom CSS stay consistent.
• Mermaid, PlantUML, WaveDrom, and inline SVG are integrated without requiring a remote diagram service.
• PDF output includes document-oriented features such as indexes, bookmarks, page breaks, headers/footers, and filename templates.
• External resources are controlled by policy: GitHub assets are allowlisted by default, and strict LocalOnly mode is available with block-all.
• First-run setup installs only the managed dependencies needed for local rendering: Corretto for PlantUML and Playwright Chromium for PDF export.

Build and Run

npm install
npm run build

Press F5 to launch Extension Development Host.

Package and Install

npm run package
code --install-extension dist/markdown-studio-*.vsix

Development reinstall (clears all caches):

scripts/dev/reinstall.sh

Tests

npm run test:unit          # Unit tests
npm run test:integration   # Integration tests
npm run test:ci            # lint + unit + integration

See testing.md for details.

Demo

Open examples/demo.md and run Markdown Studio: Preview: Open Beside to see all features in action. Use examples/demo_win.md for Windows path/rendering checks, and examples/demo_load.md for PDF export load testing.

Coexistence

Markdown Studio focuses on preview/render/export and coexists with editing extensions like Markdown All in One.

License

MIT