diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-11-09 15:17:23 -0500 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-11-09 16:42:47 -0500 |
commit | d6b49b9738783aee95c8adbb800504eebeda6324 (patch) | |
tree | e21c292333ff38d0297792b5f30e5f3de010181a /bin | |
parent | 729b79c61b9ac979563f34118add1d6b2ebd022f (diff) | |
download | torspec-d6b49b9738783aee95c8adbb800504eebeda6324.tar.gz torspec-d6b49b9738783aee95c8adbb800504eebeda6324.zip |
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.
Diffstat (limited to 'bin')
-rwxr-xr-x | bin/build_html | 57 |
1 files changed, 51 insertions, 6 deletions
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 |