diff --git a/doc/guide/author/topics.xml b/doc/guide/author/topics.xml index dfe43a8f89..92e4571001 100644 --- a/doc/guide/author/topics.xml +++ b/doc/guide/author/topics.xml @@ -3143,6 +3143,62 @@ displayed line, and there are no \\s. Use \amp to mark the alignm

Note the necessity of using the pretext script () to independently invoke Sage, no matter what sort of output is being created for your document.

+ + + Mermaid + +

Mermaid 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 Mermaid Documentation. The Mermaid live editoris a great tool for testing the syntax of your mermaid diagrams.

+ +

In PreTeXt, you can specify a Mermaid theme via common/mermaid/@theme

+ +

To author a Mermaid diagram, use a image that contains a mermaid element.

+ + 
+                <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>
+
+ +
+ Mermaid Git Diagram + + + --- + title: Example Git diagram + --- + gitGraph + commit + commit + branch develop + checkout develop + commit + commit + checkout main + merge develop + commit + commit + + +
+ diff --git a/doc/guide/publisher/publication-file.xml b/doc/guide/publisher/publication-file.xml index b97d451d2e..fb273cf697 100644 --- a/doc/guide/publisher/publication-file.xml +++ b/doc/guide/publisher/publication-file.xml @@ -134,6 +134,20 @@

In the text itself avoid obscure characters or symbols, and do not use any markup. Keep it simple. When used with output the scharacters \\ will survive in the text to create multiple lines of text in the watermark. This feature is implemented for and HTML output. See for more detail and an example.

 + + Mermaid + Mermaid themes + +

+ Various themes are available for Mermaid diagrams. To use a theme, set + + /publication/common/mermaid/@theme + + with a value of the theme name. The default theme is default. + See for more information on Mermaid diagrams. +

+ + QR code image common optionqrcode diff --git a/examples/sample-article/sample-article.xml b/examples/sample-article/sample-article.xml index 995ddd29bf..9ada2bd807 100644 --- a/examples/sample-article/sample-article.xml +++ b/examples/sample-article/sample-article.xml @@ -3413,6 +3413,94 @@ along with MathBook XML. If not, see . + + Mermaid Diagrams + Mermaid diagrams + +

Mermaid is a Markdown-inspired tool for authoring various kinds of diagrams. Below, three of the available diagram types are demonstrated. For a full listing of diagram types, see the Mermaid Documentation. The Mermaid live editoris a great tool for testing the syntax of your mermaid diagrams.

+ +

In PreTeXt, you can specify a Mermaid theme via common/mermaid/@theme

+ +
+ Mermaid Git Diagram + + + A git diagram in Mermaid + + + --- + title: Example Git diagram + --- + gitGraph + commit + commit + branch develop + checkout develop + commit + commit + checkout main + merge develop + commit + commit + + +
+ +
+ Mermaid Class Diagram + + + A class diagram in Mermaid + + + classDiagram + Animal <|-- Duck + Animal <-- Fish + Animal <|-- Zebra + Animal : +int age + Animal : +String gender + Animal: +isMammal() + Animal: +mate() + class Duck{ + +String beakColor + +swim() + +quack() + } + class Fish{ + -int sizeInFeet + -canEat() + } + class Zebra{ + +bool is_wild + +run() + } + + +
+ +
+ Mermaid Seuqnece Diagram + + + A sequence diagram in Mermaid + + + sequenceDiagram + participant Alice + participant Bob + Alice->>John: Hello John, how are you? + loop HealthCheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts <br/>prevail! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! + + +
+ + Sage Plots Sage plots diff --git a/pretext/pretext.cfg b/pretext/pretext.cfg index a8a2a2b9f5..14aa901639 100644 --- a/pretext/pretext.cfg +++ b/pretext/pretext.cfg @@ -58,6 +58,7 @@ pdflatex = pdflatex xelatex = xelatex pdfsvg = pdf2svg asy = asy +mermaid = mmdc sage = sage pdfpng = convert pdfeps = pdftops diff --git a/pretext/pretext.py b/pretext/pretext.py index 8957550131..7eb8223150 100755 --- a/pretext/pretext.py +++ b/pretext/pretext.py @@ -2056,6 +2056,70 @@ def qrcode(xml_source, pub_file, stringparams, xmlid_root, dest_dir): log.info("QR code creation complete") +##################################### +# +# Mermaid images +# +##################################### + +def mermaid_images( + xml_source, pub_file, stringparams, xmlid_root, dest_dir +): + msg = 'converting Mermaid diagrams from {} to png graphics for placement in {}' + log.info(msg.format(xml_source, dest_dir)) + + tmp_dir = get_temporary_directory() + log.debug("temporary directory: {}".format(tmp_dir)) + ptx_xsl_dir = get_ptx_xsl_path() + extraction_xslt = os.path.join(ptx_xsl_dir, "extract-mermaid.xsl") + + # support publisher file, subtree argument + if pub_file: + stringparams["publisher"] = pub_file + if xmlid_root: + stringparams["subtree"] = xmlid_root + + log.info("extracting Mermaid diagrams from {}".format(xml_source)) + log.info( + "string parameters passed to extraction stylesheet: {}".format(stringparams) + ) + #generate mmd files with markdown to be converted to png + xsltproc(extraction_xslt, xml_source, None, tmp_dir, stringparams) + + #Need a prettier way to get set value from pub file... + mermaid_theme = "default" + if pub_file: + pub_tree = ET.parse(pub_file) + mmd_elt = pub_tree.xpath("/publication/common/mermaid") + if mmd_elt: + attrs = mmd_elt[0].attrib + if "theme" in attrs: + mermaid_theme = mmd_elt[0].attrib['theme'] + + import glob + # Resulting *.mmd files are in tmp_dir, switch there to work + with working_directory(tmp_dir): + mmd_executable_cmd = get_executable_cmd("mermaid") + log.debug("Mermaid executable command: {}".format(mmd_executable_cmd)) + for mmddiagram in glob.glob(os.path.join(tmp_dir, "*.mmd")): + filebase, _ = os.path.splitext(mmddiagram) + versions = [ + {"name":"-color", "opts":["-s", "4", "-t", mermaid_theme]}, + {"name":"-bw", "opts":["-s", "4", "-t", "neutral"]} + ] + for version in versions: + mmdout = "{}.{}".format(filebase + version['name'], 'png') + mmd_cmd = mmd_executable_cmd + ["-i", mmddiagram, "-o", mmdout] + version['opts'] + log.debug("mermaid conversion {}".format(" ".join(mmd_cmd))) + subprocess.call(mmd_cmd, stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT) + if os.path.exists(mmdout): + shutil.copy2(mmdout, dest_dir) + else: + msg = [ + "the Mermaid output {} was not built".format(mmdout), + ] + log.warning("\n".join(msg)) + ##################################### # # Interactive preview screenshotting diff --git a/xsl/extract-mermaid.xsl b/xsl/extract-mermaid.xsl new file mode 100644 index 0000000000..999583cc2d --- /dev/null +++ b/xsl/extract-mermaid.xsl @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/xsl/pretext-assembly.xsl b/xsl/pretext-assembly.xsl index bb0c410a9d..c82d20686f 100644 --- a/xsl/pretext-assembly.xsl +++ b/xsl/pretext-assembly.xsl @@ -1224,7 +1224,7 @@ along with PreTeXt. If not, see . - + @@ -2269,6 +2269,48 @@ along with PreTeXt. If not, see . + + + + + + + + + + + + + + + + + + mermaid/ + + + + + -bw.png + + + -color.png + + + + + + + + + + + + + + + + diff --git a/xsl/pretext-html.xsl b/xsl/pretext-html.xsl index d680121d20..0f88d42675 100644 --- a/xsl/pretext-html.xsl +++ b/xsl/pretext-html.xsl @@ -198,6 +198,7 @@ along with MathBook XML. If not, see . + @@ -5985,6 +5986,12 @@ along with MathBook XML. If not, see . + + 
+        
+
+ + @@ -9820,6 +9827,10 @@ along with MathBook XML. If not, see . + + + + @@ -10648,6 +10659,7 @@ along with MathBook XML. If not, see . + @@ -12934,6 +12946,19 @@ TODO: + + + + + + + diff --git a/xsl/publisher-variables.xsl b/xsl/publisher-variables.xsl index 9a8f14bd89..920a847ed8 100644 --- a/xsl/publisher-variables.xsl +++ b/xsl/publisher-variables.xsl @@ -143,6 +143,10 @@ along with PreTeXt. If not, see . + + + + @@ -3065,6 +3069,9 @@ along with PreTeXt. If not, see . + + +