Edit online

Presenting DITA Task Steps as Diagrams

2 Sep 2022
Read time: 4 minute(s)

By using our free DITA Open Toolkit plugin, you can embed diagram text descriptions (either in PlantUML or Mermaid format) in DITA topics and have them rendered as diagram images in the published output.

I experimented with dynamically constructing diagrams (using the Mermaid framework) for DITA tasks at the time of publishing.

Suppose you have a DITA task with a set of steps.

<steps>
  <step>
    <cmd>Begin by cutting out all the dead branches.</cmd>
    <substeps>
      <substep>
        <cmd>Find shears</cmd>
      </substep>
      ....
    </substeps>
  </step>
  <step>
    <cmd>Remove all tangled or crossed over branches. This allows air to circulate and
      reduces bug and fungi infestation. </cmd>
  </step>
  .......
</steps>
A DITA Open Toolkit plugin can use an XSLT customization to dynamically create a Mermaid text diagram representation from the DITA task steps:
  <xsl:template match="steps[step]">
    <xsl:variable name="var">
      <foreign outputclass="embed-mermaid-diagram" class="- topic/foreign ">
stateDiagram-v2
Title: <xsl:value-of select="normalize-space(ancestor::task/title)"/>
Title --> State1
<xsl:for-each select="step">
<xsl:variable name="statePos" select="position()"/>
  State<xsl:value-of select="$statePos"/>: <xsl:value-of select="normalize-space(cmd)"/>
<xsl:if test="position() > 1">
  State<xsl:value-of select="$statePos - 1"/> --> State<xsl:value-of select="$statePos"/> 
</xsl:if>
<xsl:if test="substeps/substep">
<xsl:for-each select="substeps/substep">
State<xsl:value-of select="$statePos"/><xsl:value-of select="position()"/>: <xsl:value-of select="normalize-space(cmd)"/>   
</xsl:for-each>
state State<xsl:value-of select="$statePos"/>{
<xsl:for-each select="substeps/substep">
<xsl:if test="position() > 1">
State<xsl:value-of select="$statePos"/><xsl:value-of select="position() - 1"/> --> State<xsl:value-of select="$statePos"/><xsl:value-of select="position()"/> 
</xsl:if>
</xsl:for-each>
}
</xsl:if>
</xsl:for-each>
      </foreign>
    </xsl:variable>
    <xsl:apply-templates select="$var"/>
    <xsl:next-match/>
  </xsl:template>
</xsl:stylesheet>

A complete DITA Open Toolkit that contains the customization can be found here: ../resources/com.oxygenxml.task.diagram.zip.

At the time of publishing, the task's HTML page will contain this diagram inside it: