Embedding Diagrams in DITA Topics Using Mermaid

25 Feb 2022

Read time: 1 minute(s)

DITA Diagrams DITA Publishing Customization

Mermaid is a neat library that takes textual descriptions of diagrams and produces visual diagrams from them.

Suppose you have a DITA topic that embeds such a textual description of a diagram: https://github.com/oxygenxml/dita-ot-diagrams-plugin/blob/master/com.oxygenxml.diagrams.svg/samples/testMermaidDiagram.dita.

<topic id="testMermaidDiagram">
    <title>Test Mermaid diagram</title>
    <body>
        <p>
            <foreign outputclass="embed-mermaid-diagram">graph TD;
                A-->B;
                A-->C;
                B-->D;
                C-->D;</foreign>
        </p>
    </body>
</topic>

To provide support in Oxygen for publishing to HTML using such diagrams in DITA topics, you need to install this free publishing plugin that, once installed in the DITA Open Toolkit, will convert the textual descriptions to SVG diagrams for both the HTML-based and PDF outputs: https://github.com/oxygenxml/dita-ot-diagrams-plugin.

Tip: You can preview the created diagrams using the Mermaid live editor: https://mermaid.live/edit.