@dkothule/md2pdf 1.0.0

package/lib/pandoc_mermaid_filter.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+"""
+Pandoc filter for mermaid code blocks. Outputs SVG by default (vector quality in PDF).
+Based on timofurrer/pandoc-mermaid-filter; modified to use SVG for LaTeX/PDF.
+
+Requires: mmdc (mermaid-cli) on PATH or MERMAID_BIN.
+For PDF: install librsvg so pandoc can embed SVG (e.g. brew install librsvg).
+Python: pip install pandocfilters (or use PYTHON env to point to a venv that has it).
+Optional: set MERMAID_CONFIG to pass a Mermaid config JSON to mmdc.
+Optional: set MERMAID_IMAGE_PREFIX to control temporary Mermaid asset directory prefix.
+Optional: set MERMAID_LATEX_FORMAT (pdf|svg|png). Default is svg.
+Optional: set MERMAID_PDF_FIT=true|false (default true). If true, Mermaid PDF
+output uses fit-to-content page boxes to avoid page-sized diagram assets.
+Optional: set MERMAID_AUTO_PDF_FALLBACK=true|false (default true). If SVG uses
+foreignObject labels in PDF output pipeline, fallback rendering uses Mermaid PDF.
+"""
+import os
+import sys
+import subprocess
+
+try:
+    from pandocfilters import toJSONFilter, Para, Image
+    from pandocfilters import get_filename4code, get_caption, get_extension
+except ImportError:
+    sys.stderr.write(
+        "Missing Python dependency: pandocfilters.\n"
+        "Install with: python3 -m pip install pandocfilters\n"
+    )
+    raise SystemExit(1)
+
+MERMAID_BIN = os.environ.get("MERMAID_BIN", "mmdc")
+MERMAID_CONFIG = os.environ.get("MERMAID_CONFIG", None)
+PUPPETEER_CFG = os.environ.get("PUPPETEER_CFG", None)
+MERMAID_IMAGE_PREFIX = os.environ.get("MERMAID_IMAGE_PREFIX", "mermaid")
+MERMAID_LATEX_FORMAT = os.environ.get("MERMAID_LATEX_FORMAT", "svg")
+
+
+def env_bool(name, default):
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+MERMAID_AUTO_PDF_FALLBACK = env_bool("MERMAID_AUTO_PDF_FALLBACK", True)
+MERMAID_PDF_FIT = env_bool("MERMAID_PDF_FIT", True)
+
+
+def render_mermaid(src, dest):
+    cmd = [MERMAID_BIN, "-i", src, "-o", dest, "-q"]
+    if dest.lower().endswith(".pdf") and MERMAID_PDF_FIT:
+        cmd.append("--pdfFit")
+    if MERMAID_CONFIG is not None:
+        cmd.extend(["-c", MERMAID_CONFIG])
+    if PUPPETEER_CFG is not None:
+        cmd.extend(["-p", PUPPETEER_CFG])
+    if os.path.isfile(".puppeteer.json"):
+        cmd.extend(["-p", ".puppeteer.json"])
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        sys.stderr.write("Failed to render Mermaid diagram with mermaid-cli.\n")
+        sys.stderr.write("Command: " + " ".join(cmd) + "\n")
+        if result.stderr:
+            sys.stderr.write(result.stderr.strip() + "\n")
+        raise SystemExit(result.returncode)
+
+
+def svg_has_foreign_object(path):
+    try:
+        with open(path, "rb") as f:
+            return b"<foreignObject" in f.read()
+    except OSError:
+        return False
+
+
+def mermaid(key, value, format_, _):
+    if key == "CodeBlock":
+        [[ident, classes, keyvals], code] = value
+        if "mermaid" in classes:
+            caption, typef, keyvals = get_caption(keyvals)
+            filename = get_filename4code(MERMAID_IMAGE_PREFIX, code)
+            filetype = get_extension(
+                format_,
+                MERMAID_LATEX_FORMAT,
+                html="svg",
+                latex=MERMAID_LATEX_FORMAT,
+                pdf=MERMAID_LATEX_FORMAT,
+            )
+            src = filename + ".mmd"
+            dest = filename + "." + filetype
+            txt = code.encode(sys.getfilesystemencoding())
+            with open(src, "wb") as f:
+                f.write(txt)
+
+            if not os.path.isfile(dest):
+                render_mermaid(src, dest)
+                sys.stderr.write("Created image " + dest + "\n")
+
+            # Flowchart/graph SVG labels may be emitted via <foreignObject>, which
+            # some SVG->PDF pipelines drop. Keep SVG default, but fallback to Mermaid
+            # PDF for only affected diagrams when generating PDF output.
+            if (
+                MERMAID_AUTO_PDF_FALLBACK
+                and filetype == "svg"
+                and format_ in {"", "pdf", "latex"}
+                and svg_has_foreign_object(dest)
+            ):
+                fallback_dest = filename + ".pdf"
+                if not os.path.isfile(fallback_dest):
+                    render_mermaid(src, fallback_dest)
+                    sys.stderr.write(
+                        "Created PDF fallback image "
+                        + fallback_dest
+                        + " (foreignObject detected)\n"
+                    )
+                dest = fallback_dest
+
+            return Para([Image([ident, [], keyvals], caption, [dest, typef])])
+
+
+def main():
+    toJSONFilter(mermaid)
+
+
+if __name__ == "__main__":
+    main()

package/lib/run_pandoc_mermaid_filter.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+# Wrapper so pandoc can run the mermaid filter as a single executable.
+# Uses PYTHON if set (e.g. path to venv python), else python3.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec "${PYTHON:-python3}" "$SCRIPT_DIR/pandoc_mermaid_filter.py"

package/md2pdf.config.example

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+#
+# Copy this file to one of:
+#   - $HOME/.config/md2pdf/config.env        (global defaults)
+#   - <folder-containing-markdown>/.md2pdfrc (project/doc defaults)
+# or pass it at runtime:
+#   md2pdf input.md --config /path/to/config.env
+#
+# All keys are optional.
+
+# PDF engine command used by pandoc.
+PDF_ENGINE=xelatex
+
+# Pandoc formatting columns.
+PANDOC_COLUMNS=200
+
+# Page margins.
+LR_MARGIN=0.7in
+TB_MARGIN=0.5in
+
+# Optional LaTeX header file (set empty to disable custom header).
+# Default uses bundled: assets/table-style.tex
+# TABLE_STYLE=/absolute/path/to/table-style.tex
+
+# Mermaid/Python executables (command name or absolute path).
+MERMAID_BIN=mmdc
+# Optional Mermaid CLI config JSON.
+# Default uses bundled: assets/mermaid.config.json
+# MERMAID_CONFIG=/absolute/path/to/mermaid.config.json
+
+# Mermaid asset format for LaTeX/PDF output (pdf, svg, png).
+# Default is svg to keep high-resolution vector Mermaid diagrams in PDF output.
+MERMAID_LATEX_FORMAT=svg
+
+# When rendering Mermaid to PDF (directly or via fallback), use fit-to-content page bounds.
+# This avoids page-sized Mermaid PDF assets that can force one diagram per page.
+MERMAID_PDF_FIT=true
+
+# When true, if Mermaid SVG contains foreignObject labels (common with flowchart/graph),
+# md2pdf auto-renders a Mermaid PDF fallback for that diagram to preserve labels in PDF.
+MERMAID_AUTO_PDF_FALLBACK=true
+
+PYTHON=python3
+
+# Optional puppeteer config file for mermaid-cli.
+# PUPPETEER_CFG=/absolute/path/to/puppeteer-config.json
+
+# Temporary Mermaid asset folder behavior.
+# If true, remove generated "<prefix>-<run-id>-images/" folder after conversion.
+CLEANUP_MERMAID_ASSETS=true
+
+# Prefix for generated Mermaid asset folder.
+MERMAID_ASSET_PREFIX=md2pdf-mermaid

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dkothule/md2pdf",
+  "version": "1.0.0",
+  "description": "Markdown to PDF converter with high-resolution Mermaid diagram rendering",
+  "author": "Deepak Kothule",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "bin/",
+    "lib/pandoc_mermaid_filter.py",
+    "lib/run_pandoc_mermaid_filter.sh",
+    "assets/table-style.tex",
+    "assets/mermaid.config.json",
+    "scripts/",
+    "docs/ARCHITECTURE.md",
+    "md2pdf.config.example",
+    "install-system-deps.sh",
+    "setup-local-deps.sh",
+    "requirements.txt"
+  ],
+  "bin": {
+    "md2pdf": "./bin/md2pdf",
+    "md2pdf-install-finder-action": "./scripts/install_md2pdf_quick_action.sh",
+    "md2pdf-uninstall-finder-action": "./scripts/uninstall_md2pdf_quick_action.sh"
+  },
+  "scripts": {
+    "postinstall": "echo \"Mermaid CLI installed\""
+  },
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "10.9.1"
+  }
+}

package/requirements.txt

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+pandocfilters==1.5.1

package/scripts/convert-md-to-pdf.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+# Simple standalone utility for local use from this repo checkout.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+exec "$PROJECT_ROOT/bin/md2pdf" "$@"

package/scripts/install_md2pdf_quick_action.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+set -euo pipefail
+
+resolve_script_dir() {
+  local source="${BASH_SOURCE[0]}"
+  while [[ -L "$source" ]]; do
+    local dir
+    dir="$(cd -P "$(dirname "$source")" && pwd)"
+    source="$(readlink "$source")"
+    if [[ "$source" != /* ]]; then
+      source="$dir/$source"
+    fi
+  done
+  cd -P "$(dirname "$source")" && pwd
+}
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "Error: Finder Quick Action installer is only supported on macOS." >&2
+  exit 1
+fi
+
+WORKFLOW_NAME="${WORKFLOW_NAME:-Convert Markdown to PDF}"
+WORKFLOW_DIR="$HOME/Library/Services/${WORKFLOW_NAME}.workflow"
+CONTENTS_DIR="$WORKFLOW_DIR/Contents"
+SCRIPT_DIR="$(resolve_script_dir)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+MD2PDF_SCRIPT=""
+if [[ -x "$PROJECT_ROOT/bin/md2pdf" ]]; then
+  MD2PDF_SCRIPT="$PROJECT_ROOT/bin/md2pdf"
+elif command -v md2pdf >/dev/null 2>&1; then
+  MD2PDF_SCRIPT="$(command -v md2pdf)"
+fi
+
+if [[ -z "$MD2PDF_SCRIPT" ]]; then
+  cat >&2 <<'EOF'
+Error: could not find md2pdf executable.
+Install from this repo first:
+  ./setup-local-deps.sh
+Or install globally:
+  npm i -g @dkothule/md2pdf
+EOF
+  exit 1
+fi
+
+ACTION_UUID="$(uuidgen)"
+INPUT_UUID="$(uuidgen)"
+OUTPUT_UUID="$(uuidgen)"
+
+mkdir -p "$CONTENTS_DIR"
+
+cat > "$CONTENTS_DIR/Info.plist" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>NSServices</key>
+  <array>
+    <dict>
+      <key>NSBackgroundColorName</key>
+      <string>background</string>
+      <key>NSIconName</key>
+      <string>NSActionTemplate</string>
+      <key>NSMenuItem</key>
+      <dict>
+        <key>default</key>
+        <string>Convert Markdown to PDF</string>
+      </dict>
+      <key>NSMessage</key>
+      <string>runWorkflowAsService</string>
+      <key>NSRequiredContext</key>
+      <dict>
+        <key>NSApplicationIdentifier</key>
+        <string>com.apple.finder</string>
+      </dict>
+      <key>NSSendFileTypes</key>
+      <array>
+        <string>net.daringfireball.markdown</string>
+        <string>md</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>
+PLIST
+
+cat > "$CONTENTS_DIR/document.wflow" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>AMApplicationBuild</key>
+  <string>533</string>
+  <key>AMApplicationVersion</key>
+  <string>2.10</string>
+  <key>AMDocumentVersion</key>
+  <string>2</string>
+  <key>actions</key>
+  <array>
+    <dict>
+      <key>action</key>
+      <dict>
+        <key>ActionBundlePath</key>
+        <string>/System/Library/Automator/Run Shell Script.action</string>
+        <key>ActionName</key>
+        <string>Run Shell Script</string>
+        <key>ActionParameters</key>
+        <dict>
+          <key>CheckedForUserDefaultShell</key>
+          <true/>
+          <key>COMMAND_STRING</key>
+          <string>export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/TeX/texbin:$HOME/.npm-global/bin"
+MD2PDF_SCRIPT="$MD2PDF_SCRIPT"
+if [[ ! -x "\$MD2PDF_SCRIPT" ]] &amp;&amp; [[ -z "\$(command -v md2pdf 2&gt;/dev/null)" ]]; then
+  print -u2 -- "Error: md2pdf is not in PATH: \$PATH"
+  exit 127
+fi
+for f in "\$@"; do
+  case "\$f" in
+    *.md|*.MD) ;;
+    *) continue ;;
+  esac
+  if [[ -x "\$MD2PDF_SCRIPT" ]]; then
+    "\$MD2PDF_SCRIPT" "\$f"
+  else
+    md2pdf "\$f"
+  fi
+done
+</string>
+          <key>inputMethod</key>
+          <integer>1</integer>
+          <key>shell</key>
+          <string>/bin/zsh</string>
+          <key>source</key>
+          <string></string>
+        </dict>
+        <key>AMAccepts</key>
+        <dict>
+          <key>Container</key>
+          <string>List</string>
+          <key>Optional</key>
+          <true/>
+          <key>Types</key>
+          <array>
+            <string>com.apple.cocoa.string</string>
+          </array>
+        </dict>
+        <key>AMActionVersion</key>
+        <string>2.0.3</string>
+        <key>AMApplication</key>
+        <array>
+          <string>Automator</string>
+        </array>
+        <key>AMParameterProperties</key>
+        <dict>
+          <key>CheckedForUserDefaultShell</key>
+          <dict/>
+          <key>COMMAND_STRING</key>
+          <dict/>
+          <key>inputMethod</key>
+          <dict/>
+          <key>shell</key>
+          <dict/>
+          <key>source</key>
+          <dict/>
+        </dict>
+        <key>AMProvides</key>
+        <dict>
+          <key>Container</key>
+          <string>List</string>
+          <key>Types</key>
+          <array>
+            <string>com.apple.cocoa.string</string>
+          </array>
+        </dict>
+        <key>BundleIdentifier</key>
+        <string>com.apple.RunShellScript</string>
+        <key>CanShowSelectedItemsWhenRun</key>
+        <false/>
+        <key>CanShowWhenRun</key>
+        <true/>
+        <key>Category</key>
+        <array>
+          <string>AMCategoryUtilities</string>
+        </array>
+        <key>CFBundleVersion</key>
+        <string>2.0.3</string>
+        <key>Class Name</key>
+        <string>RunShellScriptAction</string>
+        <key>InputUUID</key>
+        <string>$INPUT_UUID</string>
+        <key>OutputUUID</key>
+        <string>$OUTPUT_UUID</string>
+        <key>UUID</key>
+        <string>$ACTION_UUID</string>
+        <key>isViewVisible</key>
+        <integer>1</integer>
+      </dict>
+      <key>isViewVisible</key>
+      <integer>1</integer>
+    </dict>
+  </array>
+  <key>connectors</key>
+  <dict/>
+  <key>workflowMetaData</key>
+  <dict>
+    <key>applicationBundleID</key>
+    <string>com.apple.finder</string>
+    <key>applicationBundleIDsByPath</key>
+    <dict>
+      <key>/System/Library/CoreServices/Finder.app</key>
+      <string>com.apple.finder</string>
+    </dict>
+    <key>applicationPath</key>
+    <string>/System/Library/CoreServices/Finder.app</string>
+    <key>applicationPaths</key>
+    <array>
+      <string>/System/Library/CoreServices/Finder.app</string>
+    </array>
+    <key>inputTypeIdentifier</key>
+    <string>com.apple.Automator.fileSystemObject</string>
+    <key>outputTypeIdentifier</key>
+    <string>com.apple.Automator.nothing</string>
+    <key>presentationMode</key>
+    <integer>15</integer>
+    <key>processesInput</key>
+    <false/>
+    <key>serviceApplicationBundleID</key>
+    <string>com.apple.finder</string>
+    <key>serviceApplicationPath</key>
+    <string>/System/Library/CoreServices/Finder.app</string>
+    <key>serviceInputTypeIdentifier</key>
+    <string>com.apple.Automator.fileSystemObject</string>
+    <key>serviceOutputTypeIdentifier</key>
+    <string>com.apple.Automator.nothing</string>
+    <key>serviceProcessesInput</key>
+    <false/>
+    <key>systemImageName</key>
+    <string>NSActionTemplate</string>
+    <key>useAutomaticInputType</key>
+    <false/>
+    <key>workflowTypeIdentifier</key>
+    <string>com.apple.Automator.servicesMenu</string>
+  </dict>
+</dict>
+</plist>
+PLIST
+
+plutil -lint "$CONTENTS_DIR/Info.plist" >/dev/null
+plutil -lint "$CONTENTS_DIR/document.wflow" >/dev/null
+
+echo "Installed Quick Action: $WORKFLOW_NAME"
+echo "Location: $WORKFLOW_DIR"
+echo "Using md2pdf executable: $MD2PDF_SCRIPT"
+echo
+echo "If it does not appear immediately in Finder context menu, restart Finder:"
+echo "  killall Finder"

package/scripts/uninstall_md2pdf_quick_action.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+set -euo pipefail
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "Error: Finder Quick Action uninstaller is only supported on macOS." >&2
+  exit 1
+fi
+
+WORKFLOW_NAME="${WORKFLOW_NAME:-Convert Markdown to PDF}"
+WORKFLOW_DIR="$HOME/Library/Services/${WORKFLOW_NAME}.workflow"
+
+if [[ -d "$WORKFLOW_DIR" ]]; then
+  rm -rf "$WORKFLOW_DIR"
+  echo "Removed Quick Action: $WORKFLOW_NAME"
+  echo "Deleted: $WORKFLOW_DIR"
+else
+  echo "Quick Action not found: $WORKFLOW_DIR"
+fi
+
+echo
+echo "Restart Finder to refresh the context menu:"
+echo "  killall Finder"

package/setup-local-deps.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Deepak Kothule
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "python3 not found. Install Python 3 first."
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "npm not found. Install Node.js/npm first."
+  exit 1
+fi
+
+if [[ ! -d ".venv" ]]; then
+  python3 -m venv .venv
+fi
+
+./.venv/bin/python -m pip install --upgrade pip
+./.venv/bin/pip install -r requirements.txt
+
+npm install
+
+echo
+echo "Local dependencies installed."
+echo "Python: $SCRIPT_DIR/.venv/bin/python"
+echo "Mermaid CLI: $SCRIPT_DIR/node_modules/.bin/mmdc"