AI

Mermaid Diagram Sync Assistant

Keep Mermaid diagrams automatically in sync with source code changes in pull requests.

The Mermaid Diagram Sync Assistant is an intelligent GitHub app that monitors your pull requests and updates Mermaid diagrams when related source files are modified. When a PR is opened, synchronized, or reopened, the app scans the changed files, finds diagrams connected to those files, regenerates the affected diagrams, and adds the updates back to the PR with clear bot attribution — so your docs stay current during review.

.mermaidignore Configuration

Control which files and diagrams are considered using .mermaidignore files (similar to .gitignore):

Key Features:

• Source file filtering - Exclude source files from triggering diagram updates
• Diagram file filtering - Completely exclude specific .mmd files from processing
• Standard gitignore syntax - Supports * wildcards, ** recursive matching, ? single character
• Negation patterns - Use !pattern to create exceptions and include previously excluded files
• Pattern precedence - Later patterns override earlier ones for complex filtering rules

Example .mermaidignore :

# Ignore temporary and build files
*.log
*.tmp
build/
node_modules/

# Ignore test files but keep integration tests
**/*test*
!src/tests/integration.test.js

# Ignore draft diagrams except important ones
draft/**/*.mmd
!temp-important.mmd

Mermaid Diagram Sync Assistant Configuration

Control which PR branches the bot processes using .smart-mermaid-updates.yml:

Key Features:

• Branch filtering - Exclude PR head branches using exact names or wildcard patterns
• Flexible patterns - Supports exact matches (main), wildcards (feature/*), negation (!pattern)
• Multiple syntax - Both excludeBranches (camelCase) and exclude-branches (kebab-case)
• Smart processing - If branch matches exclusion pattern, entire PR is skipped

Example configurations:

# Basic exclusions
excludeBranches:
  - experimental
  - draft/*
  - temp/*
  - wip/*

# Advanced: exclude all except specific branches
excludeBranches:
  - '*'              # Exclude all branches
  - '!feature/*'     # Except feature/* branches  
  - '!main'          # And except main branch

Real-World Example

Scenario: You modify src/auth/UserService.js to add two-factor authentication and update src/api/AuthController.js for new endpoints.

Bot Process:

1. Detects changes in your PR
2. Finds docs/authentication-flow.mmd references both modified files
3. Analyzes code changes and understands new 2FA flow
4. Regenerates Mermaid diagram with new authentication steps and API calls
5. Commits updated diagram: “Automated diagram update”

Result: Your architecture documentation accurately reflects your implementation before PR review.