Diagrams embedded in PDFs don’t show properly

Symptom

When embedding SVG diagrams in PDFs, text and arrows might not show. Users reported this for diagrams created with Mermaid or Diagrams.net. Other diagram types may be affected as well.

While diagrams show nicely in the preview, they don’t show up as expected in the PDF.

Cause

Looking into the source of the SVG, Mermaid and Diagrams.net use the foreignObject feature to embed HTML for the text inside the SVG. The plugin’s PDF action uses Asciidoctor PDF to create the PDF. Asciidoctor PDF can’t render content in foreignObject as the library prawn-svg doesn’t support it.

How do I fix this?

There are several alternatives to fix this:

Change diagram to PNG.
Use plugin’s Web-PDF rendering (experimental).
Use Asciidoctor Web PDF.

Change diagram to PNG

When using PNG, unsupported SVG attributes will not cause problems. The tradeoff is usually a larger PDF and a rastered image. Rastered images will not scale and print as good as SVGs. Some diagram types (like Mermaid) don’t support PNG when used, for example, with the Kroki-integration.

See Diagrams with Kroki for more information.

Use plugin’s Web-PDF rendering (experimental)

There is an experimental feature to render the preview as PDF. This feature is work-in-progress, and lacks features like page numbers and a table of contents. See issue #592 for progress.

The JCEF Preview needs to be enabled to use this. As this is work-in-progress and experimental, it is behind a feature flag. After enabling the internal mode, users see an action Web PDF in the editor’s toolbar.

Clicking on this action creates a PDF from the preview.

Use Asciidoctor Web PDF

To create a PDF from SVGs that embed HTML, a browser rendering engine is the preferred way. When the plugin’s Web-PDF rendering isn’t enough, and installing software next to the IDE, consider the Asciidoctor Web PDF project.

This requires a local Node installation plus working with package.json and NPM. The result will be command line interface to render AsciiDoc to PDF using an embedded web browser. While it is still in alpha, it supports lots PDF features like page numbers and a table of contents.