feat(docs): add offline mermaid support to PDF export (#2530)

## Issue Link / Problem Description
- Fixes https://github.com/vibrantlabsai/ragas/issues/2529

## Changes Made
- Added the `mkdocs-mermaid-to-svg` plugin to the `docs-pdf` dependency
group in `pyproject.toml`.
- Configured `mkdocs-pdf.yml` to use `mermaid-to-svg` (gated by
`ENABLE_PDF_EXPORT`), converting Mermaid diagrams to SVG images before
PDF generation.
- Added a new `check-mermaid-deps` Makefile target to verify Node.js and
Mermaid CLI (`mmdc`) are available before PDF build.
- Updated the PDF export documentation to mention offline Mermaid
rendering requirements.

## Testing
### How to Test
- [ ] Automated tests added/updated
- [ ] Manual testing steps:
  1. Run `make build-docs-pdf` in your local environment.
2. Open `site/pdf/document.pdf` and verify that Mermaid diagrams are
rendered as SVGs (not as raw code blocks).
3. Confirm that HTML builds (via `make build-docs` or `make serve-docs`)
are unaffected.

## References
- Documentation: `docs/community/pdf_export.md`

Makefile

@@ -177,7 +177,20 @@ check-pdf-deps: ## Check if WeasyPrint is properly installed with all dependenci
 		exit 1)
 
 
-build-docs-pdf: check-pdf-deps ## Build documentation with PDF export (requires WeasyPrint)
+check-mermaid-deps: ## Check Mermaid CLI is available and can render a diagram
+	@command -v node >/dev/null || (echo "Node.js is required for Mermaid PDF rendering"; exit 1)
+	@command -v mmdc >/dev/null || (echo "Missing 'mmdc' (Mermaid CLI). Mermaid diagrams in PDF depend on Mermaid CLI."; exit 1)
+	@tmp_dir="$$(mktemp -d)"; \
+	printf "graph TD\n  A-->B\n" > "$$tmp_dir/diag.mmd"; \
+	mmdc -i "$$tmp_dir/diag.mmd" -o "$$tmp_dir/diag.svg" >/dev/null 2>&1 || \
+		(echo "Mermaid CLI found, but rendering failed (mmdc couldn't produce SVG)."; rm -rf "$$tmp_dir"; exit 1); \
+	test -s "$$tmp_dir/diag.svg" || \
+		(echo "Mermaid CLI ran but produced an empty SVG."; rm -rf "$$tmp_dir"; exit 1); \
+	rm -rf "$$tmp_dir"; \
+	echo "Mermaid CLI is installed and can render diagrams"
+
+	
+build-docs-pdf: check-pdf-deps check-mermaid-deps ## Build documentation with PDF export (requires WeasyPrint)
 	@echo "Building documentation with PDF export..."
 	$(Q)MKDOCS_CI=false ENABLE_PDF_EXPORT=1 uv run --group docs --group docs-pdf mkdocs build -f mkdocs-pdf.yml
 	@echo "PDF generated at: site/pdf/document.pdf"

docs/community/pdf_export.md

@@ -23,6 +23,15 @@ make build-docs
 
 The `make build-docs-pdf` command automatically checks for system dependencies before building.
 
+## Mermaid diagrams in PDF (offline)
+Mermaid diagrams are rendered **offline** during the PDF build (converted to SVG before WeasyPrint runs). This requires a few additional dependencies besides WeasyPrint.
+
+### Required tools
+- Node.js (needed to run Mermaid tooling).
+- Mermaid CLI (`mmdc`), installed via `@mermaid-js/mermaid-cli`. 
+- A headless browser for Puppeteer (recommended: `chrome-headless-shell`).
+
+
 ## Current Limitations
 
 **System Dependencies**: WeasyPrint requires OS-specific system libraries (Pango, Cairo) that must be installed separately. If you encounter issues, refer to the [WeasyPrint setup instructions](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) and [troubleshooting guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#troubleshooting).

mkdocs-pdf.yml

@@ -6,6 +6,19 @@ plugins:
   - social:
       enabled: !ENV [MKDOCS_CI, true]
 
+
+  # --- Mermaid PLUGIN (Exclusive to this file) ---
+  - mermaid-to-svg:
+      enabled_if_env: ENABLE_PDF_EXPORT
+      mmdc_path: "mmdc"
+      error_on_fail: true
+      mermaid_config:
+        htmlLabels: false
+        flowchart:
+          htmlLabels: false
+        class:
+          htmlLabels: false
+
   # --- PDF PLUGIN (Exclusive to this file) ---
   - to-pdf:
       enabled_if_env: ENABLE_PDF_EXPORT

pyproject.toml

@@ -186,4 +186,5 @@ docs = [
 
 docs-pdf = [
     "mkdocs-to-pdf>=0.10.1",
+    "mkdocs-mermaid-to-svg"
 ]