update to latest mermaid, remove workaround, fix crossrefs, and improve code font (#68)

Author: chrisfenner

Dockerfile

@@ -67,18 +67,16 @@ RUN apk --no-cache add msttcorefonts-installer fontconfig && \
 RUN wget https://github.com/kaienfr/Font/raw/master/font/ARIALUNI.TTF -P /usr/share/fonts/TTF/ && \
     fc-cache -f
 
-# Install Source Code Pro
-RUN wget https://github.com/adobe-fonts/source-code-pro/archive/refs/tags/2.042R-u/1.062R-i/1.026R-vf.zip && \
-    unzip 1.026R-vf.zip && \
-    cp source-code-pro-2.042R-u-1.062R-i-1.026R-vf/TTF/*.ttf /usr/share/fonts/TTF/ && \
+# Install Noto Sans Mono
+RUN apk --no-cache add font-noto && \
     fc-cache -f
 
 RUN pip install pandocfilters
 
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
     PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 
-RUN npm install --global --unsafe-perm [email protected] puppeteer@19.8.5 imgur@2.2.0 [email protected] typescript@5.0.4
+RUN npm install --global --unsafe-perm puppeteer@21.7.0 imgur@2.3.0 [email protected] typescript@5.3.3
 
 # Install latest pandiff, which has not been released in a while
 # This pre-release build has --reference-doc support for docx output

build.sh

@@ -243,25 +243,18 @@ if [ "${table_rules}" == "yes" ]; then
 	extra_pandoc_options+=" --lua-filter=table-rules.lua"
 fi
 
-# Transform 1
-# GitHub Mermaid doesn't recognize the full ```{.mermaid ...} attributes-form
-# Pandoc doesn't recognized mixed ```mermaid {...} form
-# Hack: use sed to transform the latter to the former so everyone is happy
-# Only transform if there is exactly one space after ```mermaid
-# Instructional documentation may use more than one space in the source code to suppress this.
-sed 's/```mermaid {/```{.mermaid /g' "${input_file}" > "${build_dir}/${input_file}.1"
-sed 's/```mermaid *{/```mermaid {/g' "${input_file}" > "${build_dir}/${input_file}.1"
-
-# Transform 2
+cp "${input_file}" "${build_dir}/${input_file}"
+
+# Hacks
+
 # \newpage is rendered as the string "\newpage" in GitHub markdown.
 # Transform horizontal rules into \newpages.
 # Exception: the YAML front matter of the document, so undo the instance on the first line.
-sed 's/^---$/\\newpage/g;1s/\\newpage/---/g' "${build_dir}/${input_file}.1" > "${build_dir}/${input_file}.2"
+sed -i.bak 's/^---$/\\newpage/g;1s/\\newpage/---/g' "${build_dir}/${input_file}"
 
-# Transform 3
 # Transform sections before the table of contents into section*, which does not number them.
 # While we're doing this, transform the case to all-caps.
-sed '0,/\\tableofcontents/s/^# \(.*\)/\\section*\{\U\1\}/g' "${build_dir}/${input_file}.2" > "${build_dir}/${input_file}.3"
+sed -i.bak '0,/\\tableofcontents/s/^# \(.*\)/\\section*\{\U\1\}/g' "${build_dir}/${input_file}"
 
 if test "${do_gitversion}" == "yes"; then
 	# If using the git information for versioning, grab the date from there
@@ -288,13 +281,21 @@ RESULT=0
 # Generate the pdf
 if [ -n "${pdf_output}" ]; then
 	echo "Generating PDF Output"
+	# workaround to make mermaid and crossref play nice together: https://github.com/raghur/mermaid-filter/issues/39#issuecomment-1703911386
 	pandoc \
-	    --pdf-engine=lualatex \
+		--filter=mermaid-filter \
+		--standalone \
+		--metadata=date:"${DATE}" \
+		--metadata=date-english:"${DATE_ENGLISH}" \
+		--metadata=year:"${YEAR}" \
+		--from=markdown \
+		"${build_dir}/${input_file}" \
+		--to=markdown \
+	| pandoc \
+		--pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--template=eisvogel.latex \
-		--filter=mermaid-filter \
-		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
 		--lua-filter=divide-code-blocks.lua \
@@ -303,9 +304,6 @@ if [ -n "${pdf_output}" ]; then
 		--top-level-division=section \
 		--variable=block-headings \
 		--variable=numbersections \
-		--metadata=date:"${DATE}" \
-		--metadata=date-english:"${DATE_ENGLISH}" \
-		--metadata=year:"${YEAR}" \
 		--metadata=titlepage:true \
 		--metadata=titlepage-background:/resources/img/cover.png \
 		--metadata=crossrefYaml:/resources/filters/pandoc-crossref.yaml \
@@ -316,7 +314,6 @@ if [ -n "${pdf_output}" ]; then
 		--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
 		${extra_pandoc_options} \
 		--to=pdf \
-		"${build_dir}/${input_file}.3" \
 		--output="${pdf_output}"
 	echo "PDF Output Generated to file: ${pdf_output}"
 	if [ $? -ne 0 ]; then
@@ -327,13 +324,21 @@ fi
 # Generate the LaTeX output
 if [ -n "${latex_output}" ]; then
 	echo "Generating LaTeX Output"
+	# workaround to make mermaid and crossref play nice together: https://github.com/raghur/mermaid-filter/issues/39#issuecomment-1703911386
 	pandoc \
-	    --pdf-engine=lualatex \
+		--filter=mermaid-filter \
+		--standalone \
+		--metadata=date:"${DATE}" \
+		--metadata=date-english:"${DATE_ENGLISH}" \
+		--metadata=year:"${YEAR}" \
+		--from=markdown \
+		"${build_dir}/${input_file}" \
+		--to=markdown \
+	| pandoc \
+		--pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--template=eisvogel.latex \
-		--filter=mermaid-filter \
-		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
 		--lua-filter=divide-code-blocks.lua \
@@ -342,8 +347,6 @@ if [ -n "${latex_output}" ]; then
 		--top-level-division=section \
 		--variable=block-headings \
 		--variable=numbersections \
-		--metadata=date-english:"${DATE_ENGLISH}" \
-		--metadata=year:"${YEAR}" \
 		--metadata=titlepage:true \
 		--metadata=titlepage-background:/resources/img/cover.png \
 		--metadata=crossrefYaml:/resources/filters/pandoc-crossref.yaml \
@@ -354,7 +357,6 @@ if [ -n "${latex_output}" ]; then
 		--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
 		${extra_pandoc_options} \
 		--to=latex \
-		"${build_dir}/${input_file}.3" \
 		--output="${latex_output}"
 	echo "LaTeX Output Generated to file: ${latex_output}"
 	if [ $? -ne 0 ]; then
@@ -365,13 +367,21 @@ fi
 # Generate the docx output
 if [ -n "${docx_output}" ]; then
 	echo "Generating DOCX Output"
+	# workaround to make mermaid and crossref play nice together: https://github.com/raghur/mermaid-filter/issues/39#issuecomment-1703911386
 	pandoc \
-	    --pdf-engine=lualatex \
+		--filter=mermaid-filter \
+		--standalone \
+		--metadata=date:"${DATE}" \
+		--metadata=date-english:"${DATE_ENGLISH}" \
+		--metadata=year:"${YEAR}" \
+		--from=markdown \
+		"${build_dir}/${input_file}" \
+		--to=markdown \
+	| pandoc \
+		--pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--filter=/resources/filters/info.py \
-		--filter=mermaid-filter \
-		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
 		--resource-path=.:/resources \
@@ -380,7 +390,6 @@ if [ -n "${docx_output}" ]; then
 		--reference-doc=/resources/templates/tcg_template.docx \
 		${extra_pandoc_options} \
 		--to=docx \
-		"${build_dir}/${input_file}.3" \
 		--output="${docx_output}"
 	echo "DOCX Output Generated to file: ${docx_output}"
 	if [ $? -ne 0 ]; then
@@ -393,16 +402,24 @@ export MERMAID_FILTER_FORMAT="svg"
 # Generate the html output
 if [ -n "${html_output}" ]; then
 	echo "Generating html Output"
+	# workaround to make mermaid and crossref play nice together: https://github.com/raghur/mermaid-filter/issues/39#issuecomment-1703911386
 	pandoc \
+		--filter=mermaid-filter \
+		--standalone \
+		--metadata=date:"${DATE}" \
+		--metadata=date-english:"${DATE_ENGLISH}" \
+		--metadata=year:"${YEAR}" \
+		--from=markdown \
+		"${build_dir}/${input_file}" \
+		--to=markdown \
+	| pandoc \
 		--toc \
 		-V colorlinks=true \
 		-V linkcolor=blue \
 		-V urlcolor=blue \
 		-V toccolor=blue \
 		--embed-resources \
 		--standalone \
-		--filter=mermaid-filter \
-		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
 		--lua-filter=divide-code-blocks.lua \
@@ -411,8 +428,6 @@ if [ -n "${html_output}" ]; then
 		--top-level-division=section \
 		--variable=block-headings \
 		--variable=numbersections \
-		--metadata=date-english:"${DATE_ENGLISH}" \
-		--metadata=year:"${YEAR}" \
 		--metadata=titlepage:true \
 		--metadata=titlepage-background:/resources/img/cover.png \
 		--metadata=crossrefYaml:/resources/filters/pandoc-crossref.yaml \
@@ -423,7 +438,6 @@ if [ -n "${html_output}" ]; then
 		--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
 		${extra_pandoc_options} \
 		--to=html \
-		"${build_dir}/${input_file}.3" \
 		--output="${html_output}"
 	echo "HTML Output Generated to file: ${html_output}"
 	if [ $? -ne 0 ]; then
@@ -438,5 +452,6 @@ fi
 # on success remove this output
 rm -f mermaid-filter.err
 rm -f .puppeteer.json
+rm  "${build_dir}/${input_file}.bak"
 
 exit 0

guide.md

@@ -271,7 +271,7 @@ are expected to use this macro.
 
 Users familiar with Git and who prefer to use their own tools may choose to skip this section.
 
-```mermaid {caption="GitHub Collaboration workflow"}
+```mermaid {caption="GitHub Collaboration Workflow" #fig:collaboration-workflow}
     gitGraph
        commit id: "head"
        branch proposed-edits-1
@@ -288,7 +288,7 @@ Users familiar with Git and who prefer to use their own tools may choose to skip
        merge proposed-edits-2
 ```
 
-As visualized above, proposed changes to a GitHub Markdown repository take the form of
+As visualized in @fig:collaboration-workflow, proposed changes to a GitHub Markdown repository take the form of
 "Pull Requests" (PRs). A *proposer* of a change proposes a PR that changes some files in the repository.
 This PR contains an initial *commit*, which is a unit of change to files.
 *Reviewers* can provide comments and suggestions on the proposed edits. The *proposer* can respond to
@@ -531,10 +531,10 @@ See the Mermaid website for a more exhaustive list of types of diagrams.
 
 ### Sequence Diagrams
 
-Mermaid supports swim-lane digrams like the below with the following notation:
+Mermaid supports swim-lane digrams like @fig:startup with the following notation:
 
 ````md
-```mermaid  {caption="Startup Sequence"}
+```mermaid {caption="Startup Sequence" #fig:startup}
 sequenceDiagram
 Host->>TPM: TPM2_Startup
 loop Measurements
@@ -545,7 +545,7 @@ TPM->>Host: <quoted PCRs>
 ```
 ````
 
-```mermaid {caption="Startup Sequence"}
+```mermaid {caption="Startup Sequence" #fig:startup}
 sequenceDiagram
 Host->>TPM: TPM2_Startup
 loop Measurements
@@ -555,14 +555,15 @@ Host->>TPM: TPM2_Quote
 TPM->>Host: <quoted PCRs>
 ```
 
-Crossreferences to Mermaid diagrams are not currently supported.
+Crossreferences to Mermaid diagrams are supported by providing both `caption`
+and `#fig:xxxxx` classes in curly braces.
 
 ### Flow Charts
 
-Mermaid supports flow-charts like the below with the following notation:
+Mermaid supports flow-charts like @fig:flowchart with the following notation:
 
 ````md
-```mermaid  {caption="Flowchart"}
+```mermaid {caption="Flowchart" #fig:flowchart}
 graph TD;
     A-->B;
     A-->C;
@@ -571,7 +572,7 @@ graph TD;
 ```
 ````
 
-```mermaid {caption="Flowchart"}
+```mermaid {caption="Flowchart" #fig:flowchart}
 graph TD;
     A-->B;
     A-->C;

template/eisvogel.latex

@@ -389,7 +389,7 @@ $endif$
 \usepackage{fontspec}
 \setmainfont{Arial}
 \setsansfont{Arial}
-\setmonofont[Scale=0.9]{Source Code Pro}
+\setmonofont{Noto Sans Mono}
 
 \usepackage{newunicodechar}
 % Use Arial Unicode to display various unicode symbols that might be present