termaid

name	termaid
description	Terminal and Python Mermaid diagram rendering using Termaid library. When Claude needs to create, render, or visualize Mermaid diagrams in terminal output, documentation, Python scripts, or technical presentations. Supports 9 diagram types (flowcharts, sequence, class, ER, state, block, git graphs, pie charts, treemaps) with 6 color themes and ASCII fallback.

Termaid Mermaid Diagram Renderer

Comprehensive skill for rendering Mermaid diagrams in terminal and Python applications using the Termaid library. Provides CLI tools, Python APIs, and examples for creating professional diagrams without browser dependencies.

Quick Start

Installation Check

First, check if termaid is installed:

python scripts/install_termaid.py --check

If not installed, install it:

python scripts/install_termaid.py --install

Basic Usage

Render a Mermaid diagram file:

python scripts/render_mermaid.py assets/examples/flowchart.mmd

Render from stdin:

echo "graph LR; A-->B-->C" | python scripts/render_mermaid.py

Use the wrapper script:

./scripts/cli_wrapper.sh render assets/examples/flowchart.mmd --theme neon

Core Workflow

1. Diagram Creation

Create Mermaid diagrams using standard syntax. See chart_types.md for all supported diagram types.

2. Rendering Options

Choose rendering method based on your needs:

• CLI: Use scripts/render_mermaid.py or termaid command
• Python API: Import and use in Python scripts
• Interactive TUI: Use Textual widgets for applications

3. Output Configuration

• Themes: 6 color themes (see themes.md)
• Format: ASCII or Unicode box-drawing
• Target: stdout, files, or integration with other tools

When to Use This Skill

Use This Skill When:

1. Creating technical documentation - Embed diagrams in README files, API docs, or tutorials
2. Visualizing system architecture - Generate architecture diagrams from code
3. Explaining workflows - Create flowcharts for processes and decision trees
4. Teaching concepts - Visualize algorithms, data structures, or system interactions
5. Monitoring systems - Generate real-time status diagrams
6. Code documentation - Visualize class relationships or API sequences

Do Not Use When:

• Pixel-perfect rendering is required (use browser-based Mermaid)
• Complex SVG/PDF output is needed
• Interactive web diagrams are required

Available Resources

Scripts (scripts/)

• render_mermaid.py - Main rendering script with CLI interface
• install_termaid.py - Installation helper and dependency checker
• cli_wrapper.sh - Convenient shell wrapper for common operations

References (references/)

• overview.md - Termaid library features and capabilities
• chart_types.md - All 9 supported diagram types with syntax examples
• python_api.md - Complete Python API usage and patterns
• cli_usage.md - CLI command reference and practical examples
• themes.md - Color theme comparison and selection guide

Assets (assets/)

• examples/ - Ready-to-use Mermaid diagram examples:
  • flowchart.mmd - Basic workflow with decisions
  • sequence.mmd - API request sequence diagram
  • class_diagram.mmd - Object-oriented class relationships
  • git_graph.mmd - Git repository history visualization
• templates/ - Reusable templates:
  • api_flow.mmd - API request flow template
  • system_architecture.mmd - System architecture template

Common Tasks

Task 1: Render a Diagram File

# Basic rendering
python scripts/render_mermaid.py diagram.mmd

# With color theme
python scripts/render_mermaid.py diagram.mmd --theme phosphor

# ASCII-only output
python scripts/render_mermaid.py diagram.mmd --ascii

# Save to file
python scripts/render_mermaid.py diagram.mmd -o output.txt

Task 2: Use in Python Code

from termaid import render, render_rich

# Plain text rendering
diagram_text = render("graph LR\n A --> B --> C")

# Colored rendering
from rich.console import Console
console = Console()
rich_diagram = render_rich("graph TD\n Start --> End", theme="neon")
console.print(rich_diagram)

Task 3: Generate Documentation

import os
from pathlib import Path

def generate_docs_with_diagrams(source_dir, output_dir):
    """Generate markdown files with embedded diagrams."""
    for mmd_file in Path(source_dir).glob("*.mmd"):
        # Read Mermaid code
        with open(mmd_file, 'r') as f:
            mermaid_code = f.read()
        
        # Render diagram
        from termaid import render
        diagram = render(mermaid_code)
        
        # Create documentation
        doc_file = output_dir / f"{mmd_file.stem}.md"
        with open(doc_file, 'w') as f:
            f.write(f"# {mmd_file.stem}\n\n")
            f.write("```mermaid\n")
            f.write(mermaid_code)
            f.write("\n```\n\n")
            f.write("## Rendered Output\n\n```\n")
            f.write(diagram)
            f.write("\n```\n")

Task 4: Create Interactive Dashboard

from termaid import MermaidWidget
from textual.app import App, ComposeResult

class DiagramDashboard(App):
    """Interactive TUI dashboard with live diagrams."""
    
    def compose(self) -> ComposeResult:
        yield MermaidWidget("graph TD\n [*] --> Loading")
        
    def update_diagram(self, new_source):
        """Update diagram dynamically."""
        self.query_one(MermaidWidget).source = new_source

Best Practices

1. Keep Diagrams Simple

Terminals have limited width. Aim for:

• Maximum 50-60 characters wide
• 15-20 nodes maximum per diagram
• Clear, hierarchical structure

2. Choose Appropriate Themes

• Default: General purpose, most compatible
• Mono: For printing or accessibility
• Neon/Phosphor: For presentations and dark terminals
• Terra: For documentation and reports

3. Use Templates for Consistency

Start with the templates in assets/templates/ for common diagram types.

4. Validate Syntax

Always test render diagrams before including in documentation:

python scripts/render_mermaid.py diagram.mmd > /dev/null && echo "Valid"

Troubleshooting

Common Issues

"ModuleNotFoundError: No module named 'termaid'"

python scripts/install_termaid.py --install

Unicode characters not displaying

# Use ASCII mode
python scripts/render_mermaid.py diagram.mmd --ascii

Colors not working

# Check terminal color support
echo -e "\033[0;31mRed\033[0m"
# Install rich extras if needed
pip install termaid[rich]

Diagram too wide

# Adjust terminal width or use smaller diagrams
TERMINAL_WIDTH=100 python scripts/render_mermaid.py diagram.mmd

Debug Mode

# Enable verbose output
TERMAID_DEBUG=1 python scripts/render_mermaid.py diagram.mmd 2>&1

Performance Tips

1. Use ASCII for batch processing - Faster rendering
2. Cache frequently used diagrams - Store rendered output
3. Limit diagram complexity - Simple diagrams render faster
4. Consider async rendering - For web applications

Related Skills

• docx - For creating professional documents with embedded diagrams
• xlsx - For data analysis and chart generation
• pptx - For presentation slides with visualizations

---

For complete API documentation and advanced usage patterns, see the reference files in the references/ directory.