Skip to content

Enhanced Mermaid Diagrams Usage Guide

This guide shows how to use the reusable enhanced Mermaid diagram functionality.

Setup

Add these files to your MkDocs configuration:

mkdocs.yml

extra_css:
  - stylesheets/mermaid-enhanced.css

extra_javascript:
  - javascripts/mermaid-enhanced.js

Basic Usage

Place your Mermaid diagram followed by diagram controls. The CSS will automatically detect and style them:

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]

### Method 1a: Container Wrapper (Legacy)

For backward compatibility, you can still wrap diagrams in a container:

```html
<div class="mermaid-container">
```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]


### Method 2: Custom Diagram Code

For complex diagrams, pass the diagram code directly to the enlarge function:

```html
<div class="mermaid-container">
```mermaid
graph TB
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]


### Method 3: JavaScript Helper (Advanced)

Use the JavaScript helper function for dynamic diagrams:

```javascript
// Generate enhanced container HTML
const containerHTML = createEnhancedMermaidContainer(`
graph LR
    A[Dynamic] --> B[Diagram]
    B --> C[Generated]
`, 'my-diagram-id');

// Insert into page
document.getElementById('diagram-placeholder').innerHTML = containerHTML;

Features

Responsive Scaling

  • Large screens (>1400px): 1.4x scale
  • Medium screens (1200-1400px): 1.2x scale
  • Standard screens (900-1200px): 1.0x scale
  • Smaller screens (<900px): 0.8x scale

MkDocs Material Integration

  • Uses Material Design CSS variables for theming
  • Automatic dark/light mode support
  • Consistent styling with existing buttons and modals

Keyboard Support

  • Escape key: Close enlarged diagram
  • Click outside: Close modal

Error Handling

  • Graceful fallback to code display if Mermaid fails to render
  • Console logging for debugging

CSS Classes Available

  • .mermaid-container: Main container with Material Design styling
  • .diagram-controls: Control button container
  • .enlarge-diagram: Styled enlarge button
  • .diagram-modal: Full-screen modal overlay
  • .diagram-modal-content: Modal content container

JavaScript Functions

  • enlargeDiagram(button, diagramCode?): Opens diagram in modal
  • closeDiagramModal(event?): Closes the modal
  • createEnhancedMermaidContainer(diagramCode, containerId?): Helper function

Customization

Custom Button Text

<button class="md-button md-button--primary enlarge-diagram" onclick="enlargeDiagram(this)">
    🔍 View Larger
</button>

Custom Styling

Add custom CSS to override default styles:

.mermaid-container {
    border: 2px solid var(--md-accent-fg-color);
}

.enlarge-diagram {
    background: var(--md-accent-fg-color);
}

Multiple Diagrams

The system supports multiple diagrams on the same page. Each diagram gets its own enlarge button and can be opened independently.

Performance Notes

  • The modal HTML is injected once when the page loads
  • Each diagram is re-rendered fresh in the modal for best quality
  • Smart scaling calculations minimize performance impact
  • Fallback rendering ensures diagrams always display something useful

Browser Support

  • Modern browsers with CSS Grid and Flexbox support
  • Backdrop filter support for best visual experience
  • Graceful degradation for older browsers