Inkscape-based TikZ rendering in Quarto

How to configure Quarto to render native TikZ diagrams as crisp SVGs using a local LaTeX engine and Inkscape — with a working example.
Programming
Documentation
Author

Souvik Sarkar

Published

August 20, 2024

Overview

This guide explains how to configure Quarto to compile native TikZ diagrams into high-quality SVG graphics using a local LaTeX engine and Inkscape.

Phase 1: Install system dependencies

You must install three tools and ensure they are available on your system PATH.

1. Install a LaTeX engine

Quarto requires a LaTeX engine to compile TikZ code into an intermediate PDF.

Recommended: TinyTeX

quarto install tinytex

Alternatives

  • MacTeX (macOS)
  • MiKTeX (Windows)
  • TeX Live (Linux)

2. Install Inkscape

Inkscape converts the generated PDF diagram into an SVG suitable for HTML output.

macOS

brew install --cask inkscape

Linux

sudo apt install inkscape

Windows

Download and install Inkscape from the official website.

If Windows cannot find the inkscape command, add the Inkscape installation directory (for example, C:\Program Files\Inkscape\bin) to your system environment variables.

3. Verify the installation

Open a terminal and verify that both tools are available:

latex --version
inkscape --version

Phase 2: Project setup

1. Install the diagram extension

From your Quarto project directory:

quarto add pandoc-ext/diagram

Press Y when prompted.

This creates an _extensions/ directory in your project.

2. Configure your document

Add the diagram filter to your document front matter:

---
title: "TikZ Diagram Document"

format:
  html:
    embed-resources: true

filters:
  - diagram
---

Phase 3: Writing TikZ code blocks

You can now write native TikZ diagrams using the .tikz language identifier.

Basic example

Advanced example: Scaling and text integration

Use the scale option to resize the entire diagram without manually changing dimensions.

Phase 4: Render the document

Render the document as usual:

quarto render document.qmd

What happens behind the scenes?

  1. Quarto extracts the .tikz code block.
  2. Your local LaTeX engine compiles it into a standalone PDF.
  3. Inkscape trims whitespace and converts the PDF into SVG.
  4. Quarto embeds the resulting SVG directly into the generated HTML output.

The result is a crisp, scalable vector graphic that renders cleanly in modern browsers.