How it compares¶

svg-plus occupies a narrow gap: figures defined in code, laid out as boxes, set with real typography, output as plain SVG. Most tools do some of that better than svg-plus and the rest not at all. This page says which.

The short version¶

Diagram-as-code tools¶

Mermaid¶

The obvious comparison, and for many diagrams the right answer. You write graph TD; A-->B; and Mermaid lays it out for you — no coordinates, no sizing, and it renders inside GitHub, Notion and most documentation sites without a build step.

Prefer Mermaid when the diagram is a graph — flowcharts, sequence diagrams, state machines, ER diagrams — and you want it to appear in a Markdown file with no tooling.

Prefer svg-plus when the shape is not a graph. A poster is not a graph. A layered stack diagram with a caption under each brick and a legend at the bottom is not a graph. Mermaid gives you its layout algorithm and its themes; you cannot justify a paragraph inside a node, set the leading, place a logo, or make the figure exactly 842 × 1191 for print. Its text handling is deliberately basic — a label is a label.

The two coexist happily: Mermaid for the flowcharts in your docs, svg-plus for the figures in the report.

examples/diagrams/ ports four real Mermaid diagrams — a layered architecture, a build pipeline, a cross-tier integration and a sequence diagram. Three of the four sources carry workarounds for the layout engine: invisible ~~~ edges to force an ordering, direction LR inside a TB graph to turn a phase sideways, a global wrappingWidth to control where labels break. Those are the shape of the problem svg-plus solves — the arrangement is knowledge you already have, and there is nowhere to put it.

PlantUML¶

Broader than Mermaid — UML in all its forms, plus mindmaps, Gantt charts, JSON and wireframes — and much older, so the diagram vocabulary is deep and the rendering is mature. Layout is Graphviz underneath for most diagram types.

Prefer PlantUML when you want UML proper, or one of its many specialised diagram grammars, and a Java runtime (or a server) is acceptable.

Prefer svg-plus when you do not want a JVM in the pipeline, when your figure has no diagram grammar to fit into, or when the typography matters. PlantUML's strength is that it knows what a sequence diagram is; that is also the boundary — a marketing poster has no @startuml form.

Graphviz¶

The layout engine underneath much of the field, and unmatched at what it does: give it a graph of any size and it will place the nodes and route the edges better than you would by hand.

Prefer Graphviz when you do not know or do not control the shape — a dependency tree, a call graph, anything generated from data whose size varies.

Prefer svg-plus when you do know the shape. In an architecture diagram, the arrangement usually carries meaning: these three sit in a layer, that one spans the others. Automatic layout will move them. svg-plus routes an arrow between two boxes you placed, and no further — see the honest limits.

D2¶

The most modern of the four: three layout engines, all free and open source — dagre (layered, based on Graphviz's DOT), ELK (the mature academic one), and TALA (built specifically for software architecture). Plus containers with dot notation, edge labels, themes, sketch mode, variables and imports, Markdown and LaTeX inside shapes, and multi-board composition through layers, scenarios and steps.

Prefer D2 when you want automatic layout with more control than Mermaid gives, or when its multi-board model fits — steps, where each board inherits from the previous one, is a neat way to build a diagram up in stages.

Prefer svg-plus when the figure has to be generated from Python data, or when it is a poster rather than a diagram.

There is an instructive inversion here. D2's own documentation is candid that manual positioning is its soft spot, and engine-dependent at that: near referencing another object works only in TALA, width and height on containers only in ELK, top and left position locking only in TALA. That is precisely what svg-plus does well, and automatic layout is precisely what it does not do at all. The two are complements, not competitors.

We borrowed three ideas from D2 outright: labels on connectors, arrowheads at either or neither end, and placing something near another thing. We did not borrow automatic layout, and the reasoning is written down under parked.

Charting and plotting¶

matplotlib, plotly, Vega¶

Made for plots — axes, scales, statistical transforms, dozens of chart types, and years of accumulated correctness in the details of tick placement. svg-plus has one bar chart.

Prefer matplotlib for anything whose subject is data: distributions, time series, anything needing a log scale or an axis.

Prefer svg-plus when the chart is one element of a designed page rather than the page itself — a bar chart under a headline, beside a callout, above a footer. Composing a matplotlib figure into a poster means fighting its layout manager; here the chart is a block among blocks.

They compose: export a matplotlib figure as SVG and place it with Image.

SVG toolkits¶

svgwrite, drawsvg, xml.etree¶

These give you SVG primitives and stop. That is exactly what the figures this library was extracted from used, and the arithmetic was the problem: box heights computed by hand, a running y threaded through every call, text widths eyeballed.

Prefer them when you are generating shapes rather than laying out content — a chart, a generative pattern, a diagram whose geometry is computed.

Prefer svg-plus when the figure contains prose. The whole difference is that a block knows how tall it is.

ReportLab¶

The heavyweight of Python document generation, and svg-plus sits on part of it (via svglib) for PDF output. Its Platypus layer has flowables and frames — genuinely comparable layout ideas — and it is far more capable for long documents: page breaks, tables, running headers, an entire report.

Prefer ReportLab when the output is a document with pages.

Prefer svg-plus when the output is a figure, and SVG is the primary artefact rather than a PDF. The API is a fraction of the size, and the SVG is not an export of a PDF.

Typesetting systems¶

TikZ / PGF, LaTeX¶

The best typography available and the deepest drawing language. A figure drawn in TikZ inside a LaTeX document will out-typeset anything here, and \usetikzlibrary{positioning} gives real relative layout.

Prefer TikZ when the figure lives inside a LaTeX document and you are already in that world.

Prefer svg-plus when the figure is generated from Python data, or when the artefact is an SVG for the web, a poster for print, or an image for a slide. svg-plus borrows TeX's line-breaking algorithm precisely because that part was worth taking; it does not pretend to replace TeX.

Typst¶

The most interesting competitor: modern, fast, excellent typography, real flow layout, scripting that does not hurt, and SVG output. If you are choosing a system for a document with figures in it, look at Typst seriously.

Prefer svg-plus when the figure has to be produced by a Python program — computed from a DataFrame, generated in a loop over a spreadsheet, built in a CI job alongside the data it describes. Crossing into Typst means a separate language and a template to pass data through.

Browser-based rendering¶

HTML + CSS, screenshotted¶

Flexbox and CSS text layout are better than anything svg-plus will ever have, and web fonts, gradients and shadows come free. Render with Playwright and screenshot.

Prefer this when you need real CSS layout, or you already have a browser in the pipeline.

Prefer svg-plus when you do not want to ship a browser to render a picture, when the output must be deterministic — the same input gives byte-identical SVG, which means figures diff cleanly in review — or when you want vector output with selectable text rather than a raster screenshot.

Design tools¶

Figma, Illustrator, Affinity Designer¶

For a one-off poster where the design is the work, these win. Direct manipulation beats a compile loop.

Prefer svg-plus when the figure has any of these properties:

• It comes from data. Numbers in the figure should come from the source, not be retyped. examples/manual/line_breaking.py computes the numbers it charts, so the figure cannot go stale.
• There are many of them. Fifty conference badges, one per attendee, is a loop.
• It is reviewed. A figure that is a script gets a diff and a pull request.
• It is translated. The same poster in French and English lays itself out differently because the text measures itself; nothing has to be nudged.
• It is regenerated. When next quarter's numbers land, you re-run the script.

Composing rather than choosing¶

Image embeds SVG, and every diagram-as-code tool emits it. So automatic layout is already available without svg-plus implementing any:

d2 architecture.d2 architecture.svg
mmdc -i flow.mmd -o flow.svg
dot -Tsvg deps.dot -o deps.svg

doc.add(
    heading("Service dependencies", size=16.0),
    Image("deps.svg", height=320.0),
    note("Generated from the lockfile; regenerated with the docs."),
)

You get their layout inside your page format, your theme and your typography. The honest caveat: the embedded diagram keeps its fonts and colours, so it will read as a D2 or Graphviz diagram sitting in your figure unless you match the theme by hand.

What svg-plus is not¶

Being fair about it:

• Not an auto-layout engine. You place the boxes. For a graph whose shape you do not control, use Graphviz or D2 — and embed the result.
• Connectors do not steer around obstacles. A route is computed from its two endpoints alone, so an edge skipping a tier can cross a box between them.
• Not a plotting library. One bar chart. For anything with an axis, use matplotlib.
• Not a document system. No page breaks, no running heads, no multi-page flow. One figure per document.
• Not interactive. Static SVG, no JavaScript, no hover states.
• Not a design tool. No gradients, shadows, blend modes or filters yet — a deliberately flat visual vocabulary.

If two or more of those matter to you, one of the tools above is a better fit, and it is worth saying so plainly.