Tamamo - Mermaid Diagram Validator & Renderer

A Python tool for validating and rendering Mermaid diagrams with comprehensive error reporting and multi-format output support.

Installation

pip install git+https://git.sly.so/kade/tamamo.git

For development with all dependencies:

pip install git+https://git.sly.so/kade/tamamo.git[dev,rendering]

Quick Start

# Validate a diagram
tamamo validate diagram.mmd

# Render to SVG
tamamo render diagram.mmd --output diagram.svg

# Validate and render in one step
tamamo check diagram.mmd --output diagram.svg

# Batch validate directory
tamamo validate --batch diagrams/

Architecture

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513',
}}}%%

graph TB
    subgraph "Tamamo Architecture"
        CLI[CLI Interface] --> Validator[Validator Module]
        CLI --> Renderer[Renderer Module]
        Validator --> MermaidCLI[mermaid-cli]
        Renderer --> MermaidCLI
        Validator --> Parser[Syntax Parser]
        Renderer --> Formats[Multi-Format Output]
    end
    
    subgraph "Output Formats"
        Formats --> SVG[SVG]
        Formats --> PNG[PNG]
        Formats --> PDF[PDF]
    end
    
    subgraph "Error Handling"
        Validator --> Errors[Error Detection]
        Errors --> Messages[Detailed Messages]
        Errors --> LineNumbers[Line Numbers]
    end

Features

Diagram Validation

• Syntax Validation: Comprehensive Mermaid syntax checking
• Error Reporting: Detailed error messages with line numbers
• Batch Processing: Validate multiple diagrams at once
• Diagram Type Detection: Automatic identification of diagram types

Rendering Capabilities

• Multiple Formats: SVG, PNG, PDF output support
• Performance Estimation: Time estimation for large diagrams
• Error Recovery: Graceful handling of rendering failures
• Size Reporting: File size information for rendered outputs

CLI Interface

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513',
}}}%%

flowchart TD
    A[tamamo command] --> B{subcommand}
    B -->|validate| C[Single File]
    B -->|validate| D[Batch Directory]
    B -->|render| E[Format Options]
    B -->|check| F[Validate + Render]
    B -->|info| G[System Information]
    
    C --> H[Validation Result]
    D --> I[Batch Summary]
    E --> J[Output File]
    F --> K[Combined Result]
    G --> L[CLI Version]

Supported Diagram Types

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513',
}}}%%

graph LR
    A[Flowchart] --> B[Sequence]
    B --> C[Class]
    C --> D[State]
    D --> E[ER Diagram]
    E --> F[Gantt]
    F --> G[Pie Chart]
    G --> H[Git Graph]
    H --> I[Mind Map]
    I --> J[Timeline]
    J --> K[Block Diagram]
    K --> L[Architecture]

Usage Examples

Basic Validation

# Validate single file
tamamo validate --file diagram.mmd

# With verbose output
tamamo validate --file diagram.mmd --verbose

# Batch validation
tamamo validate --batch ./diagrams/

Rendering

# Render to SVG (default)
tamamo render diagram.mmd

# Render to PNG with custom size
tamamo render diagram.mmd --format png --width 1600 --height 900

# Render to PDF
tamamo render diagram.mmd --format pdf --output report.pdf

Combined Operations

# Validate and render in one step
tamamo check diagram.mmd --output diagram.svg

# Check with verbose output
tamamo check diagram.mmd --output diagram.svg --verbose

System Information

# Show supported formats and diagram types
tamamo info

API Usage

Validation

from tamamo.validator import TamamoValidator

validator = TamamoValidator()
result = validator.validate_syntax(mermaid_code)

if result.is_valid:
    print("Diagram is valid")
else:
    print(f"Error: {result.error_message}")
    if result.error_line:
        print(f"Line: {result.error_line}")

Rendering

from tamamo.renderer import TamamoRenderer

renderer = TamamoRenderer()
result = renderer.render_to_svg(mermaid_code, "output.svg")

if result.success:
    print(f"Rendered to {result.output_path}")
    print(f"Size: {result.file_size} bytes")
else:
    print(f"Error: {result.error_message}")

Batch Processing

from tamamo.validator import TamamoValidator

validator = TamamoValidator()
diagrams = ["diagram1.mmd", "diagram2.mmd", "diagram3.mmd"]

results = validator.validate_batch(diagrams)
for i, result in enumerate(results):
    status = "✅" if result.is_valid else "❌"
    print(f"{status} Diagram {i+1}")

Error Handling

Tamamo provides comprehensive error reporting:

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513',
}}}%%

flowchart TD
    A[Input Diagram] --> B{Syntax Valid?}
    B -->|Yes| C[Parse Structure]
    B -->|No| D[Error Detection]
    
    C --> E{Renderable?}
    E -->|Yes| F[Generate Output]
    E -->|No| G[Render Error]
    
    D --> H[Error Message]
    H --> I[Line Number]
    I --> J[Suggestion]
    
    F --> K[Success Result]
    G --> L[Render Error Message]
    
    K --> M[Output File]
    L --> N[Error Recovery]

Performance

Render Time Estimation

from tamamo.renderer import TamamoRenderer

renderer = TamamoRenderer()
time_estimate = renderer.estimate_render_time(mermaid_code, 'svg')
print(f"Estimated render time: {time_estimate:.2f} seconds")

Batch Performance

• Validation: ~50ms per diagram
• SVG Rendering: ~2-5 seconds depending on complexity
• PNG Rendering: ~3-8 seconds with image processing
• PDF Rendering: ~4-10 seconds with layout generation

Dependencies

Core Requirements

• Python 3.10+
• mermaid-py: Python interface for Mermaid
• Node.js + mermaid-cli: External CLI for validation/rendering

Optional Dependencies

• pillow: PNG image processing
• reportlab: PDF generation
• beautifulsoup4: HTML parsing
• markdown: Markdown processing

Development Dependencies

• pytest: Test framework
• black: Code formatting
• ruff: Linting
• mypy: Type checking

Integration

Forgejo Client Integration

from tamamo.validator import TamamoValidator
from forgejo_client import ForgejoClient

validator = TamamoValidator()
client = ForgejoClient(config)

# Validate diagram before creating issue
result = validator.validate_syntax(diagram_code)
if result.is_valid:
    # Create issue with embedded diagram
    client.issues.create_issue(
        title="Architecture Update",
        body=f"```mermaid\n{diagram_code}\n```"
    )

CI/CD Integration

# Example GitHub Actions
- name: Validate diagrams
  run: |
    pip install git+https://git.sly.so/kade/tamamo.git
    tamamo validate --batch docs/diagrams/
    
- name: Render diagrams
  run: |
    tamamo render docs/diagrams/architecture.mmd --output docs/images/architecture.svg

Troubleshooting

Common Issues

1. mermaid-cli not found

   pip install cloakbrowser
   

2. Permission denied on output files

   chmod +w output_directory
   

3. Large diagram timeout

   # Increase timeout in code or use smaller diagrams
   

Debug Mode

# Enable verbose output for debugging
tamamo validate diagram.mmd --verbose

# Check system configuration
tamamo info

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Theme Detection and Validation

Tamamo now includes comprehensive theme detection and validation capabilities for Mermaid diagrams, ensuring consistent theming across documentation.

Theme Validation Commands

Check Themes

Validate themes in individual files or directories:

# Check a single file
tamamo theme-check --file README.md --theme dark_red_fox

# Scan a directory recursively
tamamo theme-check --dir docs/ --theme dark_red_fox --recursive

# Output results in JSON format
tamamo theme-check --dir docs/ --format json --output theme-results.json

Scan Directory

Comprehensive directory scanning with detailed reporting:

# Scan directory with summary output
tamamo theme-scan docs/ --theme dark_red_fox --format summary

# Verbose scanning with detailed output
tamamo theme-scan docs/ --verbose --theme dark_red_fox

# Save results to file
tamamo theme-scan docs/ --output theme-issues.txt --format text

Theme Configuration

Manage theme validation settings:

# Initialize configuration file
tamamo theme-config init --output tamamo-config.yaml

# Show current configuration
tamamo theme-config show --config tamamo-config.yaml

Configuration

Create a tamamo-config.yaml file to customize theme validation:

theme_validation:
  default_theme: "dark_red_fox"
  warn_on_missing: true
  required_colors:
    - "#4a2c2a"  # primaryColor
    - "#8b4513"  # primaryBorderColor, lineColor
    - "#1a0e08"  # background
    - "#2d1810"  # sectionBkgColor, mainBkg
    - "#cd853f"  # tertiaryColor

file_patterns:
  - "**/*.md"
  - "**/*.mmd"

exclude_patterns:
  - "**/node_modules/**"
  - "**/.git/**"
  - "**/target/**"
  - "**/__pycache__/**"

# Custom theme definitions
custom_themes:
  my_theme:
    required_colors:
      - "#ff0000"
      - "#00ff00"
    color_mappings:
      primaryColor: "#ff0000"
      primaryTextColor: "#ffffff"
    warn_on_missing: true
    allow_variations: false

Fox Theme Support

Tamamo includes built-in support for the dark red fox theme used in the Reynard ecosystem:

Required Colors

• #4a2c2a - Primary color (dark brown)
• #8b4513 - Primary border color and line color
• #1a0e08 - Background color
• #2d1810 - Section background and main background
• #cd853f - Tertiary color

Complete Theme Configuration

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513',
}}}%%

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a2c2a',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#8b4513',
    'lineColor': '#8b4513',
    'sectionBkgColor': '#2d1810',
    'altSectionBkgColor': '#1a0e08',
    'gridColor': '#4a2c1a',
    'secondaryColor': '#8b4513',
    'secondaryTextColor': '#ffffff',
    'tertiaryColor': '#cd853f',
    'tertiaryTextColor': '#2d1810',
    'background': '#1a0e08',
    'mainBkg': '#2d1810',
    'secondBkg': '#4a2c2a',
    'tertiaryBkg': '#8b4513'
}}}%%

API Usage

Theme Detection

from tamamo.theme_detector import ThemeDetector

detector = ThemeDetector()

# Extract theme from mermaid code
theme = detector.extract_theme_from_mermaid(mermaid_code)

# Validate theme against fox theme
result = detector.validate_theme(mermaid_code, "dark_red_fox")

if result.is_valid:
    print("✅ Theme is valid")
else:
    print(f"❌ Theme validation failed: {result.warnings}")

File and Directory Scanning

# Scan single file
results = detector.scan_file("README.md", "dark_red_fox")

# Scan directory recursively
results = detector.scan_directory("docs/", "dark_red_fox", recursive=True)

# Get summary statistics
summary = detector.get_theme_summary(results)
print(f"Found {summary['invalid_diagrams']} diagrams with theme issues")

Integration Examples

CI/CD Pipeline

- name: Validate Mermaid Themes
  run: |
    pip install git+https://git.sly.so/kade/tamamo.git
    tamamo theme-scan docs/ --theme dark_red_fox --format summary

Pre-commit Hook

#!/bin/sh
# Check mermaid themes before commit
tamamo theme-check --dir docs/ --theme dark_red_fox
exit $?

Output Formats

Text Format

Theme Validation Results: 3/5 valid

✅ docs/architecture.md:1
❌ docs/guide.md:2
   ⚠️  Missing required colors: #2d1810, #cd853f
   🎨 Missing colors: #2d1810, #cd853f

JSON Format

[
  {
    "is_valid": true,
    "theme_name": "dark_red_fox",
    "file_path": "docs/architecture.md:1",
    "missing_colors": [],
    "extra_colors": [],
    "warnings": []
  }
]

Summary Format

{
  "total_diagrams": 10,
  "valid_diagrams": 7,
  "invalid_diagrams": 3,
  "files_with_issues": 2,
  "missing_colors": {"#2d1810": 2, "#cd853f": 1},
  "common_warnings": {"Missing required colors: #2d1810, #cd853f": 2}
}

Markdown Block Formatting

Closing Backticks on Same Line

Mermaid diagrams in markdown files may have their closing ``` on the same line as content:

```mermaid
flowchart TD
    A --> B```

This is a common mistake that causes Mermaid 11.x to fail parsing. Tamamo now:

1. Extracts blocks correctly regardless of closing style
2. Warns about same-line closing during validation
3. Reports the issue in validation results

Fixing Same-Line Closing

Move the closing ``` to its own line:

```mermaid
flowchart TD
    A --> B

### Validation Results

When Tamamo finds same-line closing, it adds a format warning:

```python
result = processor.validate_markdown_document(markdown)
result['format_warnings']  # List of same-line closing issues
result['diagrams'][i]['closing_on_same_line']  # Boolean flag per diagram

CLI Output

tamamo validate --file README.md

# Output:
# ⚠️  Diagram 1: Closing ``` is on same line as content (line 7).
#     Mermaid may fail to parse. Move ``` to its own line.

Rendering

Tamamo uses CloakBrowser (stealth Chromium) for rendering Mermaid diagrams. No Puppeteer, no mermaid-cli, no Chrome version mismatch issues.

How It Works

1. Primary renderer: mermaid-cli via Puppeteer
2. Fallback renderer: CloakBrowser (stealth Chromium) + Mermaid.js CDN

When Chrome version mismatch is detected:

Error: Could not find Chrome (ver. 148.0.7778.97)

Tamamo automatically switches to CloakBrowser renderer.

Requirements

• cloakbrowser package (already in ~/ansible/.venv)
• Internet access for Mermaid.js CDN

Usage

from tamamo.renderer import TamamoRenderer

renderer = TamamoRenderer()
# Uses CloakBrowser directly
result = renderer.render_to_svg(diagram_code, "output.svg")

Direct CloakBrowser Renderer

from tamamo.cloak_renderer import CloakBrowserRenderer

renderer = CloakBrowserRenderer()
result = renderer.render_to_svg(diagram_code)
if result.success:
    print(result.svg_output)  # SVG string

Supported Formats

• SVG: Full support via CloakBrowser
• PNG: Full support via CloakBrowser screenshot
• PDF: Falls back to SVG (PDF conversion requires cairosvg)

Benefits

• No version lock: CloakBrowser uses system Chromium
• Stealth mode: Passes bot detection (not needed for rendering, but available)
• Same API: Drop-in replacement for Playwright

Testing

Tamamo has a two-tier test suite: unit tests (fast, no browser) and E2E tests (slow, require CloakBrowser).

Running Tests

# Unit tests only (fast, ~1s)
pytest tests/ -m "not e2e" -v

# E2E render tests (slow, ~10-30s, requires CloakBrowser)
pytest tests/ -m "e2e" -v

# All tests (requires CloakBrowser)
pytest tests/ -v

E2E Test Markers

E2E tests are marked with @pytest.mark.e2e and @pytest.mark.integration. They are skipped by default in CI to avoid slow builds.

import pytest

@pytest.mark.e2e
@pytest.mark.integration
def test_render_to_svg_valid():
    """Requires CloakBrowser/Chrome to render."""
    ...

CI/CD Integration (Woodpecker)

For Woodpecker CI pipelines, run unit tests by default and E2E tests on main branch:

# .woodpecker.yml
steps:
  test-unit:
    image: python:3.14-slim
    commands:
      - pip install -e .[dev]
      - pytest tests/ -m "not e2e" -v

  test-e2e:
    image: python:3.14-slim
    when:
      - event: [push]
        branch: main
    commands:
      - pip install -e .[dev,rendering]
      - pip install cloakbrowser
      - pytest tests/ -m "e2e" -v --timeout=120

E2E Test Requirements

• CloakBrowser installed (pip install cloakbrowser)
• Chromium binary available (CloakBrowser bundles Chromium)
• Internet access for Mermaid.js CDN (11.15.0)
• Timeout: 120s minimum for E2E tests (browser launch + render)