From d6b49b9738783aee95c8adbb800504eebeda6324 Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Thu, 9 Nov 2023 15:17:23 -0500
Subject: build_html: use mdbook_mermaid when available.

This is much more convenient for folks who don't want to mess
with the jenga tower that is mermaid-cli.
---
 bin/build_html | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

(limited to 'bin')

diff --git a/bin/build_html b/bin/build_html
index 04b1f5e..26fd7d8 100755
--- a/bin/build_html
+++ b/bin/build_html
@@ -10,22 +10,67 @@ cd "${TOPLEVEL}"
 
 ./bin/make_redirects
 
+# Now we deal with mermaid diagrams.
+#
+# This may require changes to the md files in {spec,proposals}
+# or to the mdbook.toml files in mdbook/*/.
+# We will make a copy of whatever we need to change,
+# and then make changes to that copy.
+#
+# When we are done with these changes, we will set some variables:
+# - HTML_OUTPUT_DIR is "", or the location where we have put our output.
+# - MDBOOK_DIR is the parent directory of the possibly modified copies
+#     of mdbook/{spec,proposals}.
+
 if test -n "${MMDC:-}" || command -v "mmdc" >&/dev/null; then
+    # CASE 1: mermaid-cli is installed.
+    #
+    # We will convert mermaid diagrams to svg.  The mermaid_cvt_svg
+    # script does this with a temporary copy of our markdown directories,
+    # so as not to alter the original.
+    #
+    # (The conversion involves npm and a headless chrome browser,
+    # to it is understandable that not everybody would want to do it
+    # this way.)
+
     TMPDIR=$(mktemp -d "${TOPLEVEL}/tmp_mmdc.XXXXXXXX")
     trap 'rm -rf "$TMPDIR"' 0
     ./bin/mermaid_cvt_svg "$TMPDIR"
-    BUILD_ROOT="$TMPDIR"
+    HTML_OUTPUT_DIR="$TMPDIR/html"
+    MDBOOK_DIR="$TMPDIR/mdbook"
+elif test -n "${MDBOOK_MERMAID:-}" || command -v "mdbook-mermaid" >&/dev/null; then
+    # CASE 2: mdbook_mermaid is installed.
+    #
+    # We will make a temporary copy of the mdbook configuration directory
+    # only, and use mdbook-mermaid to alter that.
+    #
+    # This is much easier to run locally, but it requires that your
+    # browser has enough client-side javascript in order to run
+    # mermaid.  It doesn't touch npm.
+    MDBOOK_MERMAID=${MDBOOK_MERMAID:=mdbook-mermaid}
+    TMPDIR=$(mktemp -d "${TOPLEVEL}/tmp_mdbook_mermaid.XXXXXXXX")
+    trap 'rm -rf "$TMPDIR"' 0
+    cp -r ./mdbook/proposals ./mdbook/spec ./mdbook/theme "$TMPDIR"
+    mdbook-mermaid install "$TMPDIR/spec"
+    mdbook-mermaid install "$TMPDIR/proposals"
+    HTML_OUTPUT_DIR=""
+    MDBOOK_DIR="$TMPDIR"
 else
-    BUILD_ROOT="$TOPLEVEL"
+    # CASE 3: No mermaid support.
+    #
+    # In this case we run mdbook on our inputs unchanged.
+    # The mermaid blocks will render as code.
+    HTML_OUTPUT_DIR=""
+    MDBOOK_DIR="$TOPLEVEL/mdbook"
 fi
 
-cd "${BUILD_ROOT}/mdbook/spec"
+cd "${MDBOOK_DIR}/spec"
 $MDBOOK build
 
-cd "${BUILD_ROOT}/mdbook/proposals"
+cd "${MDBOOK_DIR}/proposals"
 $MDBOOK build
 
-if test "${BUILD_ROOT}" != "${TOPLEVEL}"; then
+if test -n "${HTML_OUTPUT_DIR}"; then
    rm -rf "${TOPLEVEL}/html"
-   mv "${BUILD_ROOT}/html" "${TOPLEVEL}/html"
+   mv "${HTML_OUTPUT_DIR}" "${TOPLEVEL}/html"
 fi
-- 
cgit v1.2.3-54-g00ecf