Customization: Extend Mermaid-only Pandoc diagram pipeline to support PlantUML (PDF/vector output)

[chhil]

This document describes a customized setup required to generate PDFs with vector diagrams using Pandoc, supporting both Mermaid and PlantUML.

Note
This is not a bug or defect. The changes described here are a customization involving script updates and additional dependencies to extend an existing Mermaid-only workflow to also support PlantUML.

The setup was developed on an Apple Silicon (M1) macOS system. With limited shell scripting experience, some assistance was taken from Gemini to complete the glue logic.

This document serves as a complete inventory of every installation, configuration, and custom script required to reproduce the setup on a new machine.

---

Here is the complete inventory of every installation, configuration, and custom script ("glue") required to make your M1 Mac generate PDFs with vector PlantUML and Mermaid diagrams.

You can use this list to replicate the setup on a new machine.

1. System Installations (Homebrew & NPM)

These are the core binaries required by the script.

# 1. Core PDF and Graphing tools
brew install pandoc basictex graphviz

# 2. PlantUML and the PDF Libraries (Batik)
brew install plantuml batik

# 3. Chromium (Required for Mermaid on M1 Macs)
brew install --cask chromium

# 4. Mermaid CLI (The node tool used by the filter)
npm install -g @mermaid-js/mermaid-cli

---

2. The "Glue" Scripts (Custom Wrappers)

A. The PlantUML Wrapper

Problem: Homebrew installs PlantUML and Batik separately. PlantUML cannot find the PDF/Vector libraries, causing ClassNotFoundException.
The Glue: A script that creates a custom Java Classpath combining both tools.

• Location: $HOME/.local/share/pandoc/plantuml
• The Script:

  #!/bin/bash
  # Hardcoded paths for M1 Homebrew
  PLANTUML_JAR="/opt/homebrew/opt/plantuml/libexec/plantuml.jar"
  BATIK_LIB_DIR="/opt/homebrew/opt/batik/libexec/lib"
  
  # Run Java including PlantUML AND all Batik/FOP libraries (via wildcard *)
  exec java -cp "$PLANTUML_JAR:$BATIK_LIB_DIR/*" net.sourceforge.plantuml.Run "$@"

• Command to apply: chmod +x $HOME/.local/share/pandoc/plantuml

B. The Chromium Quarantine Fix

Problem: macOS security blocks the downloaded Chromium binary, causing Mermaid generation to hang/timeout.
The Glue: Removing the quarantine attribute.

• Command:

  xattr -cr /Applications/Chromium.app

---

3. Pandoc Extensions

A. The Diagram Filter

Problem: The old mermaid-filter is deprecated. We moved to the Lua-based filter that handles both Mermaid and PlantUML.
The Glue: Downloading the raw Lua code to the local data directory.

• Location: $HOME/.local/share/pandoc/filters/diagram.lua
• Source: https://raw.githubusercontent.com/pandoc-ext/diagram/main/_extensions/diagram/diagram.lua

B. Templates & Styles

Your script relies on specific assets being present in $HOME/.local/share/pandoc/templates:

1. Template: custom_eisvogel.latex (The Eisvogel template).
2. Citation Style: ieee-with-url.csl.

---

4. The Build Script (memo) Configuration

The main script itself acts as the final glue, holding everything together.

Key Configurations inside the script:

1. Path Exports:
   Ensures the script finds xelatex, brew, and your custom plantuml wrapper.

   export PATH="$HOME/.local/share/pandoc:/Library/TeX/texbin:/opt/homebrew/bin:$PATH"

2. M1 Mermaid Environment:
   Tells the Mermaid CLI to use the installed Chromium instead of the broken internal one.

   if [[ $(uname) == "Darwin" && $(uname -m) == "arm64" ]]; then
      export PUPPETEER_EXECUTABLE_PATH="/Applications/Chromium.app/Contents/MacOS/Chromium"
   fi

3. Diagram Filter Argument:
   Invoking the specific Lua filter.

   --lua-filter="$HOME/.local/share/pandoc/filters/diagram.lua"

---

Updated memo script.
memo.txt