From bdk
Compile Graphviz diagrams (.dot files) to SVG in-place. Use when working with .dot files or markdown with Graphviz code blocks, or when user says "compile diagrams", "generate SVG from dot files", "update documentation diagrams".
npx claudepluginhub broneq/bdk --plugin bdkThis skill uses the workspace's default tool permissions.
> Relies on BDK foundation (STARTUP_INSTRUCTIONS.md). Assumes environment discovery has already run (language, test runner, build tool are known).
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Relies on BDK foundation (STARTUP_INSTRUCTIONS.md). Assumes environment discovery has already run (language, test runner, build tool are known).
Compile Graphviz diagrams in docs — converts .dot files to SVG, updates markdown references in-place.
Argument: path to docs dir or .md file ($ARGUMENTS). Defaults to docs/.
Use $ARGUMENTS as target path passed to compile_diagrams.py.
dot must be in PATH. Script calls it directly via subprocess.
# macOS
brew install graphviz
# Ubuntu/Debian
sudo apt-get install graphviz
# Verify installation
dot -V
Three modes:
# Forward mode: Compile existing .dot files to SVG
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/
# Reverse mode: Extract diagrams from markdown to .dot files
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --mode reverse
# Both mode: Extract from markdown, then compile all (recommended)
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --mode both
.dot files → SVG → update markdown refs.dot files → SVG → update refsdocs/
├── module_name.md # Main documentation file
└── module_name/
├── diagrams/
│ ├── architecture.dot # Source Graphviz files
│ ├── dataflow.dot
│ └── components.dot
└── images/ # Generated SVG files (auto-created)
├── architecture.svg
├── dataflow.svg
└── components.svg
Step 1: Write docs with embedded code blocks:
# Component Architecture
### Component Diagram
```dot
digraph architecture {
rankdir=LR;
"Parser" -> "Loader";
"Loader" -> "Document";
}
```
Step 2: Extract + compile:
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --mode both
Result: Markdown updated to:
### Component Diagram

Source: [`diagrams/component-diagram.dot`](module/diagrams/component-diagram.dot)
Generated:
docs/module/diagrams/component-diagram.dot (extracted from header)docs/module/images/component-diagram.svg (compiled)Step 1: Create diagram source:
mkdir -p docs/my_module/diagrams
cat > docs/my_module/diagrams/architecture.dot << 'EOF'
digraph flow {
rankdir=TB;
"Parser" -> "Loader";
}
EOF
Step 2: Compile:
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --mode forward
Step 3: Manually add markdown ref or let script update existing code blocks.
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py [docs_root] [options]
Arguments:
docs_root Root directory for documentation (default: docs/)
Options:
--mode {forward,reverse,both}
Operation mode (default: forward)
- forward: .dot → SVG + update markdown
- reverse: markdown → .dot → SVG + update markdown
- both: reverse + forward (extract all, compile all)
--dry-run Show what would be done without making changes
--verbose, -v Show detailed output for each diagram
Filenames generated from preceding header:
### Component Diagram → component-diagram.dot
### Data Flow → data-flow.dot
### Class: XMLLoader → class-xmlloader.dot
-2, -3, etc.Error: Graphviz 'dot' command not found
# macOS
brew install graphviz
# Ubuntu/Debian
sudo apt-get install graphviz
# Verify installation
dot -V
.dot compiled but markdown not updated. Cause: code block content doesn't match .dot exactly (whitespace sensitive). Fix: use --mode both or --mode reverse to extract first.
Multiple diagrams with same header → auto-appends -2, -3:
### Architecture → architecture.dot
### Architecture → architecture-2.dot
0 extracted when markdown has diagrams. Check:
```dot or ```graphviz fence### or ##)docs/ directory--mode both before commit.dot (source) and .svg (output)# 1. Create documentation structure
mkdir -p docs/my_module/diagrams
# 2. Create diagram source
cat > docs/my_module/diagrams/architecture.dot << 'EOF'
digraph flow {
rankdir=TB;
node [shape=box, style=filled, fillcolor=lightblue];
"Input" -> "Processor";
"Processor" -> "Output";
}
EOF
# 3. Create markdown file with code block
cat > docs/my_module.md << 'EOF'
# My Module
## Architecture
```dot
digraph flow {
rankdir=TB;
node [shape=box, style=filled, fillcolor=lightblue];
"Input" -> "Processor";
"Processor" -> "Output";
}
EOF
uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --verbose
diagrams/architecture.dot
## Resources
### scripts/compile_diagrams.py
Handles diagram compilation + markdown updates. Execute directly without loading into context.