dot-export
Export DOT/Graphviz diagrams from documents to SVG images. Use after creating documents with DOT code blocks when you need to render them as static images for distribution, GitHub, wikis, or static sites. Supports multiple layout engines (dot, neato, circo, fdp, twopi, osage, patchwork). Processes .md, .html, .mdx, .rst, .adoc files.
When & Why to Use This Skill
The DOT/Graphviz Diagram Export skill is a specialized utility designed to automate the conversion of text-based DOT/Graphviz code blocks into high-quality, scalable SVG images. It streamlines the technical documentation workflow by processing various file formats like Markdown, HTML, and AsciiDoc, ensuring that complex diagrams are rendered correctly for distribution on platforms like GitHub, wikis, and static sites. With support for multiple layout engines, it provides a professional way to manage visual architecture and flowcharts directly within the source code of your documents.
Use Cases
- GitHub README Enhancement: Automatically transform DOT code blocks into SVG images within Markdown files to provide clear, visual system architectures for developers.
- Automated Technical Documentation: Integrate with static site generators or wikis to render complex flowcharts and dependency graphs from .mdx, .rst, or .adoc files.
- Multi-Engine Visualization: Use specialized layout engines like 'neato' for network diagrams or 'circo' for cyclic structures to achieve the best visual representation of data within a single document.
- Documentation Maintenance: Easily update diagrams by editing the preserved DOT code comments and re-running the export tool, ensuring visual assets never fall out of sync with the text.
| name | dot-export |
|---|---|
| description | Export DOT/Graphviz diagrams from documents to SVG images. Use after creating documents with DOT code blocks when you need to render them as static images for distribution, GitHub, wikis, or static sites. Supports multiple layout engines (dot, neato, circo, fdp, twopi, osage, patchwork). Processes .md, .html, .mdx, .rst, .adoc files. |
| allowed-tools | Bash, Read, Write, Edit |
DOT/Graphviz Diagram Export Skill
Automatically render DOT/Graphviz diagrams in documents to SVG images using the dot-renderer tool.
Tool Location
~/.claude/tools/dot-renderer/
├── render-dot.js # Single diagram renderer
└── process-document.js # Full document processor
Workflow
Step 1: Create Document with DOT Diagrams
When creating a document with DOT diagrams, use the standard DOT syntax in code blocks:
# My Document
Here's the graph:
```dot
digraph G {
rankdir=LR
A [label="Start"]
B [label="Process"]
C [label="End"]
A -> B -> C
}
More content...
### Step 2: Export Diagrams to SVG
After creating/editing a document with DOT blocks, run:
```bash
node ~/.claude/tools/dot-renderer/process-document.js <document-path> --verbose
Options:
--layout=<engine>- Force layout engine for all diagrams:dot,neato,circo,fdp,twopi,osage,patchwork--verbose- Show detailed progress--dry-run- Preview without making changes
Step 3: Result Structure
The tool will:
- Extract all DOT code blocks (
\``dot,```graphviz, or```gv`) - Render each to SVG in
diagrams/{document-name}/ - Replace the code block with an image reference
- Preserve original code in a comment for future editing
Output structure:
document.md
diagrams/
└── document/
├── diagram-1.svg
├── network-topology.svg
└── class-hierarchy.svg
Document transformation:
<!-- Before -->
```dot
digraph { A -> B }
---
## Layout Engines
Choose the appropriate layout engine for your graph type:
| Engine | Best For | Description |
|--------|----------|-------------|
| `dot` | Hierarchical graphs | Directed graphs, org charts, flowcharts (default) |
| `neato` | Undirected graphs | Network diagrams, social networks |
| `fdp` | Large graphs | Force-directed placement, clusters |
| `circo` | Circular layouts | Ring structures, cyclic dependencies |
| `twopi` | Radial layouts | Tree-like structures radiating from center |
| `osage` | Clustered layouts | Nested clusters, module diagrams |
| `patchwork` | Treemaps | Space-filling rectangular layout |
### Specifying Layout
Three ways to specify layout engine:
**1. In the code fence:**
```markdown
```dot:neato
graph G { A -- B -- C -- A }
**2. In the DOT code (comment):**
```dot
// layout: fdp
graph G { A -- B -- C }
3. In the DOT code (attribute):
digraph G {
layout=circo
A -> B -> C -> A
}
4. CLI override (applies to all diagrams):
node ~/.claude/tools/dot-renderer/process-document.js doc.md --layout=neato
Rendering Single Diagrams
To render a single diagram without processing a full document:
# From a .dot file
node ~/.claude/tools/dot-renderer/render-dot.js diagram.dot output.svg
# From stdin
echo "digraph { A -> B }" | node ~/.claude/tools/dot-renderer/render-dot.js --stdin output.svg
# With specific layout
node ~/.claude/tools/dot-renderer/render-dot.js diagram.dot output.svg --layout=neato
# Other output formats
node ~/.claude/tools/dot-renderer/render-dot.js diagram.dot output.json --format=json
Supported Document Types
| Extension | Image Syntax Used |
|---|---|
.md, .markdown |
 with HTML comment |
.html, .htm |
<img> tag with HTML comment |
.mdx |
JSX <img> with JSX comment |
.rst |
.. image:: directive |
.adoc |
image:: macro |
Supported Code Fence Syntax
All these are equivalent:
\``dot` - Standard DOT\``graphviz` - Full name alias\``gv` - Short alias
With layout hint:
\``dot:neato`\``graphviz:circo`\``gv:fdp`
Integration with Diagramming Skill
This skill works together with the diagramming skill:
- Design: Use the diagramming skill with 19-DOT-GRAPHVIZ-GUIDE.md for DOT syntax and semantic coloring
- Export: Use this skill to render diagrams to SVG for distribution
Recommended workflow:
- Create document with DOT code blocks (using diagramming skill for styling)
- Review diagrams in a tool like Graphviz Online or VS Code extension
- Run export to generate final SVGs
- Commit both document and generated SVGs
Diagram Naming
Diagrams are named based on:
- Graph name in DOT syntax:
digraph MyGraph {→mygraph.svg - Label attribute:
label="Network Topology"→network-topology.svg - Fallback:
diagram-1,diagram-2, etc.
To control naming, use a named graph:
digraph NetworkTopology {
A -> B -> C
}
→ Generates networktopology.svg
Editing Rendered Diagrams
To edit a previously rendered diagram:
- Find the commented original code in the document
- Uncomment the DOT block
- Edit the diagram
- Re-run the export tool
- The new SVG will replace the old one
Output Formats
The renderer supports multiple output formats:
| Format | Extension | Use Case |
|---|---|---|
svg |
.svg |
Web, documents, scalable (default) |
dot |
.dot |
Canonical DOT output |
json |
.json |
Graph structure as JSON |
dot_json |
.json |
DOT with JSON output |
xdot_json |
.json |
Extended DOT with JSON |
Troubleshooting
"Cannot find module 'node-graphviz'"
Install dependencies: cd ~/.claude/tools/dot-renderer && npm install
Diagram doesn't render
- Check DOT syntax at https://dreampuf.github.io/GraphvizOnline/
- Ensure graph type matches layout (use
graphfor undirected with neato,digraphfor directed)
Layout looks wrong
- Try different layout engines
- For undirected graphs, use
neatoorfdp - For hierarchical data, use
dot - For circular, use
circoortwopi
SVG too large/small
The tool auto-sizes based on diagram content. For custom sizing, edit the generated SVG or use CSS in your document.
Example Commands
# Process a markdown file
node ~/.claude/tools/dot-renderer/process-document.js ./docs/README.md --verbose
# Process with specific layout for all diagrams
node ~/.claude/tools/dot-renderer/process-document.js ./docs/network.md --layout=neato
# Dry run to see what would happen
node ~/.claude/tools/dot-renderer/process-document.js ./docs/README.md --dry-run
# Render single diagram with circo layout
node ~/.claude/tools/dot-renderer/render-dot.js ./diagrams/cycle.dot ./output/cycle.svg --layout=circo
DOT Quick Reference
Basic Directed Graph
digraph G {
A -> B -> C
B -> D
}
Basic Undirected Graph
graph G {
A -- B -- C
B -- D
}
With Styling (Cagle Palette)
digraph G {
node [style=filled]
// Infrastructure (blue)
Cloud [fillcolor="#E3F2FD" color="#1565C0" fontcolor="#0D47A1"]
// Service (green)
API [fillcolor="#E8F5E9" color="#2E7D32" fontcolor="#1B5E20"]
// Data (amber)
DB [fillcolor="#FFF8E1" color="#F57F17" fontcolor="#E65100"]
Cloud -> API -> DB
}
Subgraphs/Clusters
digraph G {
subgraph cluster_frontend {
label="Frontend"
style=filled
fillcolor="#E3F2FD"
UI; Components
}
subgraph cluster_backend {
label="Backend"
style=filled
fillcolor="#E8F5E9"
API; Services
}
UI -> API
}