Mermaid images (PR #2178)

Author: rbeezer

doc/guide/author/topics.xml

@@ -3143,6 +3143,62 @@ displayed line, and there are no <c>\\</c>s.  Use <c>\amp</c> to mark the alignm
 
                 <p>Note the necessity of using the <c>pretext</c> script (<xref ref="pretext-script"/>) to independently invoke Sage, no matter what sort of output is being created for your document.</p>
             </subsubsection>
+
+            <subsubsection xml:id="topic-mermaid">
+                <title>Mermaid</title>
+
+                <p><url href="https://mermaid.js.org/" visual="mermaid.js.org">Mermaid</url> is a Markdown-inspired tool for authoring various kinds of diagrams. One kind of diagram - a git commit visualization - is shown below. For a full listing of diagram types, see the <url href="https://mermaid.js.org/intro/#diagram-types">Mermaid Documentation</url>. The <url href="https://mermaid.live/" visual="mermaid.live">Mermaid live editor</url>is a great tool for testing the syntax of your mermaid diagrams.</p>
+
+                <p>In PreTeXt, you can specify a Mermaid theme via <attr>common/mermaid/@theme</attr></p>
+
+                <p>To author a Mermaid diagram, use a <tag>image</tag> that contains a <tag>mermaid</tag> element.</p>
+
+                <pre>
+                &lt;figure xml:id="figure-mermaid-git"&gt;
+                    &lt;caption&gt;Mermaid Git Diagram&gt;/caption&gt;
+                    &lt;image xml:id="mermaid-git-image"&gt;
+                        &lt;mermaid&gt;
+                    ---
+                    title: Example Git diagram
+                    ---
+                    gitGraph
+                        commit
+                        commit
+                        branch develop
+                        checkout develop
+                        commit
+                        commit
+                        checkout main
+                        merge develop
+                        commit
+                        commit
+                        &lt;/mermaid&gt;
+                    &lt;/image&gt;
+                &lt;/figure&gt;
+                </pre>
+
+                <figure xml:id="figure-mermaid-git">
+                    <caption>Mermaid Git Diagram</caption>
+                    <image xml:id="mermaid-git-image">
+                        <mermaid>
+                            ---
+                            title: Example Git diagram
+                            ---
+                            gitGraph
+                                commit
+                                commit
+                                branch develop
+                                checkout develop
+                                commit
+                                commit
+                                checkout main
+                                merge develop
+                                commit
+                                commit
+                        </mermaid>
+                    </image>
+                </figure>
+            </subsubsection>
         </subsection>
 
         <subsection>

doc/guide/generated/mermaid/mermaid-git-image-bw.png

@@ -134,6 +134,20 @@
             <p>In the text itself avoid obscure characters or symbols, and do not use any markup.   Keep it simple.  When used with <latex/> output the scharacters <c>\\</c> will survive in the text to create multiple lines of text in the watermark.  This feature is implemented for <latex/> and <init>HTML</init> output.  See <xref ref="watermarks"/> for more detail and an example.</p>
         </subsection>
 
+        <subsection xml:id="common-mermaid">
+            <title>Mermaid</title>
+            <idx><h>Mermaid themes</h></idx>
+
+            <p>
+                Various themes are available for Mermaid diagrams. To use a theme, set
+                <cd>
+                    <cline>/publication/common/mermaid/@theme</cline>
+                </cd>
+                with a value of the theme name. The default theme is <c>default</c>.
+                See <xref ref="topic-mermaid"/> for more information on Mermaid diagrams.
+            </p>
+        </subsection>
+
         <subsection xml:id="common-qrcode-image">
             <title>QR code image</title>
             <idx><h>common option</h><h>qrcode</h></idx>