Graphviz docs compiler

Skill broneq/bdk/skills/graphviz-docs-compiler

BDK — Broneq Dev Kit. Reusable Claude Code workflows: skills, agents, and hooks for TDD, planning, code review, and architecture documentation.

Install

npx -y skills add broneq/bdk --skill graphviz-docs-compiler

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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".

SKILL.md

6.8 KB, as published. Nobody here has run it

Relies on BDK foundation (STARTUP_INSTRUCTIONS.md). Assumes environment discovery has already run (language, test runner, build tool are known).

Graphviz Docs Compiler

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.

Prerequisites

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

Quick Start

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

Forward: .dot files → SVG → update markdown refs
Reverse: markdown code blocks → .dot files → SVG → update refs
Both: Reverse + Forward (extract all, compile all)

File Organization

docs/
├── 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

Workflow

Workflow 1: Start with Markdown (Recommended)

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

![Component Diagram](module/images/component-diagram.svg)

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)

Workflow 2: Start with .dot Files

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.

Script Options

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

Diagram Naming (Reverse Mode)

Filenames generated from preceding header:

### Component Diagram       → component-diagram.dot
### Data Flow              → data-flow.dot
### Class: XMLLoader       → class-xmlloader.dot

Lowercase, spaces → hyphens, special chars removed
Duplicates → -2, -3, etc.

Troubleshooting

Graphviz not installed

Error: Graphviz 'dot' command not found

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# Verify installation
dot -V

Code block not replaced in forward mode

.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.

Duplicate diagram names

Multiple diagrams with same header → auto-appends -2, -3:

### Architecture  → architecture.dot
### Architecture  → architecture-2.dot

No diagrams extracted

0 extracted when markdown has diagrams. Check:

Code blocks use ```dot or ```graphviz fence
Blocks preceded by header (### or ##)
Markdown files in docs/ directory

Recommended Workflow

Write docs with embedded Graphviz code blocks
Extract + compile with --mode both before commit
Commit both .dot (source) and .svg (output)
Reviewers see source + rendered diagrams in GitHub

Example: Full Workflow

# 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

4. Compile diagrams

uv run python skills/graphviz-docs-compiler/scripts/compile_diagrams.py docs/ --verbose

Result: docs/my_module.md now contains:

Source: `diagrams/architecture.dot`


## Resources

### scripts/compile_diagrams.py

Handles diagram compilation + markdown updates. Execute directly without loading into context.