Mermaid Docstring Diagrams
A powerful VSCode extension that automatically extracts and renders Mermaid diagrams from Python docstrings with inline preview and interactive features.
✨ Features
- 🔍 Automatic Detection: Scans Python files for Mermaid diagrams in function and class docstrings
- 🎨 Inline Rendering: Displays rendered SVG diagrams directly below docstrings in the editor
- 🖱️ Hover Previews: Shows diagram previews when hovering over Mermaid code blocks
- 🖼️ Full-size View: Click hover previews to open diagrams in a dedicated webview panel
- ⚡ Fast Rendering: Uses mermaid-cli for quick, reliable diagram generation
- 🎛️ Toggle Control: Easy on/off toggle for diagram rendering
- 🔄 Auto-refresh: Updates diagrams when you edit the code
- 🧹 Smart Caching: Caches rendered diagrams for better performance
🚀 Quick Start
- Install the extension from the VS Code Marketplace
- Open a Python file with Mermaid diagrams in docstrings
- See diagrams render automatically below the docstrings
- Hover over Mermaid code for quick previews
- Click hover previews to open full-size diagrams
📝 Usage
Add Mermaid diagrams to your Python docstrings using triple backtick code blocks:
def process_workflow():
\"\"\"
Process a typical workflow with decision points.
\`\`\`mermaid
graph TD
A[Start Process] --> B{Check Input}
B -->|Valid| C[Process Data]
B -->|Invalid| D[Show Error]
C --> E[Generate Report]
D --> F[Log Error]
E --> G[End]
F --> G
style C fill:#9f6
style D fill:#f96
\`\`\`
Returns:
str: The result of the workflow processing
\"\"\"
return "Workflow completed successfully"
Supported Diagram Types
This extension supports all Mermaid diagram types:
- 📊 Flowcharts - Process flows and decision trees
- 🔄 Sequence Diagrams - Interaction workflows
- 📈 Gantt Charts - Project timelines
- 🌐 Network Diagrams - System architectures
- 📋 Entity Relationship - Database schemas
- 🧭 User Journey - UX flows
- And many more!
🎮 Commands
Access these commands via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
| Command |
Description |
Shortcut |
| Toggle Mermaid Diagrams |
Enable/disable diagram rendering |
Click 👁️ icon |
| Refresh Mermaid Diagrams |
Clear cache and re-render all diagrams |
Click 🔄 icon |
| Show Mermaid Diagram |
Open diagram in full-size webview (at cursor or first found) |
Command Palette or click hover preview |
⚙️ Installation
From VS Code Marketplace
- Open VS Code
- Go to Extensions (
Ctrl+Shift+X / Cmd+Shift+X)
- Search for "Mermaid Docstring Diagrams"
- Click Install
From Command Line
code --install-extension YOUR_PUBLISHER_NAME.mermaid-docstring-diagrams
🛠️ Development
Prerequisites
Setup
git clone https://github.com/YOUR_USERNAME/mermaid-vscode-extension.git
cd mermaid-vscode-extension
npm install
Build & Test
# Compile the extension
npm run compile
# Test the extension
# Press F5 in VS Code to open Extension Development Host
# Open sample_python_file.py to see diagrams
🐛 Troubleshooting
Common Issues
| Issue |
Solution |
| Diagrams not appearing |
Check file is .py, verify Mermaid syntax, try refresh button |
| Slow rendering |
Complex diagrams take longer, clear cache and retry |
| Error decorations |
Check console logs, verify valid Mermaid syntax |
| Extension not activating |
Ensure you're opening a Python file |
Getting Help
🤝 Contributing
We welcome contributions! See our Contributing Guide for details.
📄 License
MIT © Your Name
🙏 Acknowledgments
- Mermaid - The amazing diagramming library
- mermaid-cli - Command line interface
- VS Code Team - For the excellent extension API
Enjoy creating beautiful diagrams in your Python code! 🎨
