Markdown Diagram Renderer

Automatically identify diagram code blocks (Mermaid/Graphviz/PlantUML) in Markdown documents, render them as images, and replace them.

Security Scan

The skill's code, dependencies, and runtime instructions are consistent with its stated purpose of detecting and rendering Mermaid/Graphviz/PlantUML blocks; nothing shown demands unrelated credentials or hidden access, but it does use third‑party online renderers (documented) and executes local rendering binaries if present.

Purpose & Capability

Name and description match the included code and README: the detector, renderer, and processor implement identification and rendering of Mermaid/Graphviz/PlantUML diagrams. Optional dependencies (mmdc, java, graphviz) are appropriate for the described backends.

Instruction Scope

SKILL.md and README instruct the agent/user to install Python deps and optional local renderers, and show CLI/module usage. The instructions and code operate on supplied Markdown files and temporary files only. Note: the skill falls back to online rendering APIs (mermaid.ink, plantuml.com) and explicitly warns about sending diagram source to those services.

Install Mechanism

There is no automated install spec in the registry; the README/SKILL.md ask the user to run 'pip install -r script/requirements.txt' and optionally install npm/java/graphviz. This is reasonable but means the user must perform dependency installation manually. No downloads from untrusted URLs or extract/install steps were present in the registry metadata.

Credentials

The skill requires only python3; no required environment variables or credentials. An optional PLANTUML_JAR env var is documented and justified for local PlantUML rendering. No unrelated secrets or config paths are requested.

Persistence & Privilege

The skill is not always:true and does not request persistent platform privileges. It reads/writes the user-specified Markdown file(s) and creates temporary files. It does not modify other skills or system-wide configs.

Assessment

This skill appears to do what it says: it finds diagram code blocks and renders them using local tools if available or by calling public rendering services. Before installing or running: (1) be aware that fallback rendering will send diagram source to third‑party services (mermaid.ink, plantuml.com) — do not include secrets or sensitive architecture details if you rely on online rendering; (2) if you want to avoid remote calls, install local renderers (mmdc, Graphviz, Java + plantuml.jar) and set PLANTUML_JAR appropriately; (3) the skill will execute local binaries (mmdc, java, graphviz) via subprocess — only use it in environments where you trust those binaries and the skill source; (4) there is no automated installer in the registry — run pip install -r script/requirements.txt yourself and consider testing on a copy of files (use -o) to avoid accidental overwrite. If you want extra assurance, review script/core.py and script/main.py locally or run the tool in an isolated environment first.

Automatically identify architecture/flowchart code blocks in Markdown documents, render them as images, and replace them.

Features

• Smart Identification: Automatically identify Mermaid, Graphviz, and PlantUML diagrams without specific language tags.
• Multi-backend Rendering: Supports local rendering and online API fallback.
• Base64 Inline: Images are inlined into Markdown as Base64 encoding, version control friendly.
• Source Preservation: Optionally keep the original diagram code as comments.

Supported Diagram Types

Diagram Type	Language Identifier	Local Renderer	Online Renderer
Mermaid	mermaid, mmd	mmdc CLI	mermaid.ink
Graphviz	graphviz, dot, gv	graphviz Python	-
PlantUML	plantuml, puml	Java jar	plantuml.com

Getting Started

Before first use, please install Python dependencies:

# Install dependencies
pip install -r {baseDir}/script/requirements.txt

Optional dependencies (install as needed):

# Mermaid local rendering (recommended)
npm install -g @mermaid-js/mermaid-cli

# Graphviz (for Graphviz diagrams)
# macOS: brew install graphviz
# Ubuntu: sudo apt-get install graphviz

# PlantUML local rendering
# 1. Install Java
# 2. Download plantuml.jar
# 3. Set environment variable: export PLANTUML_JAR=/path/to/plantuml.jar

Note: If local rendering tools are not installed, the system will automatically use online APIs for rendering (requires internet connection).

⚠️ Privacy Warning: Online rendering sends diagram source code to third-party services:

• Mermaid → mermaid.ink
• PlantUML → plantuml.com

Do not include sensitive information (e.g., passwords, keys, internal architecture details) in diagrams. It is recommended to install local rendering tools to avoid data leakage.

Usage

CLI Command Line

# Basic usage
python3 {baseDir}/script/main.py document.md

# Specify output file
python3 {baseDir}/script/main.py document.md -o output.md

# Set confidence threshold
python3 {baseDir}/script/main.py document.md --threshold 0.7

# Output SVG format
python3 {baseDir}/script/main.py document.md --format svg

# Do not preserve source code
python3 {baseDir}/script/main.py document.md --no-preserve

# Detailed logs
python3 {baseDir}/script/main.py document.md -v

Calling as a Python Module

import sys
sys.path.insert(0, '{baseDir}/script')

from main import create_skill

# Create SKILL instance
config = {
    'confidence_threshold': 0.6,
    'output_format': 'png',
    'preserve_source': True,
}
skill = create_skill(config)

# Execute
result = skill.execute(
    input_file='document.md',
    output_file='output.md'
)

print(result)

Configuration Parameters

Parameter	Type	Default	Description
confidence_threshold	float	0.6	Diagram identification confidence threshold (0-1)
output_format	string	png	Output image format (png/svg)
preserve_source	bool	True	Whether to preserve original diagram code

Identification Strategy

Uses a multi-stage filter system:

1. Language Tag Check: Prioritizes identifying mermaid, graphviz, plantuml, etc.
2. First Line Keyword Matching: Checks for typical declarations at the beginning of code blocks.
3. Keyword Density Analysis: Counts the frequency of diagram-specific keywords.
4. Structural Feature Analysis: Detects structural characteristics of diagrams.

Output Example

Before processing:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

After processing:

![mermaid diagram](data:image/png;base64,iVBORw0KGgo...)

<!-- Original diagram code -->
<!--
```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]

-->

## File Structure

{baseDir}/ ├── SKILL.md # This file ├── script/ │ ├── main.py # Main entry point │ ├── core.py # Core logic │ └── requirements.txt # Python dependencies └── README.md # Detailed documentation