MyST TikZ Plugin: Render TikZ/PGFPlots/tikzcd diagrams at build time

MyST TikZ Plugin: Render TikZ/PGFPlots/tikzcd diagrams at build time

Summary

Create a MyST Markdown plugin that renders TikZ, PGFPlots, and tikzcd LaTeX code into SVG images at build time. This would allow TikZ diagrams to be authored natively in MyST Markdown documents rather than requiring a separate pre-rendering step.

Background

The DP Volume II book conversion from LaTeX to MyST Markdown includes 9 TikZ/PGFPlots/tikzcd figures. Currently these are handled via a pre-rendering script (render_tikz.py) that:

1. Wraps TikZ code in a standalone LaTeX document
2. Compiles with XeLaTeX
3. Converts PDF → SVG via pdf2svg
4. Outputs SVG files to mystmd/figures/

This works but requires a manual step outside the MyST build pipeline.

Proposed Plugin

A MyST plugin providing a {tikz} directive:

```{tikz}
:label: fig-my-diagram
:caption: My TikZ diagram

\begin{tikzpicture}
  \draw (0,0) circle (1cm);
\end{tikzpicture}
```

Features

• Directive types: {tikz} for tikzpicture, {pgfplot} for pgfplots, {tikzcd} for commutative diagrams
• Build-time compilation: XeLaTeX + pdf2svg (or dvisvgm) to produce SVG
• Caching: Hash-based caching to avoid recompilation when source hasn't changed
• Configurable preamble: Custom packages, TikZ libraries, and macros via myst.yml
• Error reporting: Surface LaTeX compilation errors as MyST build warnings
• Font support: Configurable font setup (e.g., STIX Two for academic books)

Plugin Architecture

Following the MyST plugin system:

• Type: Executable plugin (shells out to XeLaTeX)
• Registration: project.plugins in myst.yml
• Output: Replaces directive AST node with an image node pointing to the generated SVG
• Cache location: .myst/tikz-cache/ with hash-indexed entries

Configuration

# myst.yml
project:
  plugins:
    - myst-tikz-plugin
  tikz:
    engine: xelatex          # or pdflatex, lualatex
    converter: pdf2svg       # or dvisvgm
    packages:
      - tikz-cd
      - pgfplots
    libraries:
      - positioning
      - arrows.meta
      - decorations.pathreplacing
    preamble: |
      \usepackage{fontspec}
      \setmainfont{STIX Two Text}
      \setmathfont{STIX Two Math}
    macros:
      \RR: \mathbb{R}
      \EE: \mathbb{E}

Alternatives Considered

1. Pre-rendering script (current approach) — Works but adds a manual step outside the MyST build
2. TikZJax (browser-side WebAssembly) — Compiles TikZ in the browser via tikzjax. Increases page load time, adds ~5MB WASM dependency, and doesn't support all TikZ libraries

Related

• MyST Plugin System
• TikZJax — TikZ via WebAssembly in browser
• sphinxcontrib-tikz — Similar plugin for Sphinx
• QuantEcon/book-dp2#140 — MyST conversion PR with TikZ pre-rendering

Priority

Low — the pre-rendering approach works well for the current project. This would be valuable as a general-purpose MyST extension for the broader community.

Start by reading the existing render_tikz.py pre-rendering script and the MyST plugin system documentation. The work is done when a registered plugin supports the tikz, pgfplot, and tikzcd directives with build-time SVG rendering, caching, configurable LaTeX settings, and surfaced compilation errors.