Back to "Mermaid.js Deep Dive: Як це насправді працює і як його розширити"

This is a viewer only at the moment see the article on how this works.

To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk

This is a preview from the server running through my markdig pipeline

Diagrams JavaScript Mermaid SVG

Mermaid.js Deep Dive: Як це насправді працює і як його розширити

Sunday, 09 November 2025

Введение

NOTE: Це частина моїх експериментів з штучним інтелектом M SK1 спосіб витрачати МSK2 Calude Code Web credits. ЯMSC4 fed this a BUNCH of papers , my understandingMST6 questions I had to generate this articleM ST7 ItM st8 fun and fills a gap I haven’ t seen filled anywhere elseMst10

Цей пост заснований на попередніх статтях: Якщо ви не маєте Додання русалка.js з htmx, Перемикання тем для Сирена, і Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом. Цей глибокий занурення пояснює, що лежить за цими втіленнями

Сирена.js дійсно блискучеMSC1 Написати простий текстM SK2 отримати красиві діаграми. Нічого більше марнувати з Visio чи малювати .ioMST5 втрачати вихідні файли MST6 або підтримувати окремі зображення файлів M ST7 Все живе у значку внизM ST8 версію М ST9 контролювати разом із вашим кодом МST10

Але я хотіла знати як це насправді працює підhood. Як це працюєM SK1

graph LR
    A[Text] --> B[Magic?]
    B --> C[Beautiful Diagram]

... перетворюється на реальний SVG ? І що важливіше, МSK2 як ви можете під 'єднатися до нього, щоб додати такі funkcje, як panM SK3zoom, перемикання тем МSK5 і виведення funkcjonalnості, яку я створив для цього веб-сайту @влучнішийM SK1морська матка-усилення)?

Після довгого розкопування коду Мерmaid, ' і створення справжніх версій, МSK1 тут, МСК2 - все, що я дізнався про те, як Мерmaid працює всередині і як її правильно розширювати.

Що таке Сирена

Сирена перетворює текстові визначення на діаграми.

Старий спосіб:

  1. Відкрийте інструмент діаграмування
  2. Створити діаграму
  3. Вивезти як PNG
  4. Вставляйте в Docs
  5. Потрібно оновити? Знайти джерело файлуM SK1 редагувати, відновити - вивезти МSK4 замінити зображення

Дорога Сирена:

  1. Написати діаграму в тексті
  2. Завершено

Обновляйте його? Просто редагуйте текстM SK1 Kontrolа версії ? Це' це лише текст МSK4 працює в значку внизMSC5 Так M SK6

Типи діаграм

Сирена підтримує безглуздо багато типів діаграми:

graph LR
    A[Flowcharts] --> B[Sequence Diagrams]
    B --> C[Class Diagrams]
    C --> D[State Diagrams]
    D --> E[ER Diagrams]
    E --> F[Gantt Charts]
    F --> G[Pie Charts]
    G --> H[Git Graphs]
    H --> I[User Journeys]
    I --> J[And many more...]

Подивіться Доки Сирена для повного списку.

Як насправді працює Сирена?

Ось що відбувається, коли Сирена робить діаграму

graph TD
    A[Text Definition] --> B[Lexer/Tokenizer]
    B --> C[Parser]
    C --> D[AST Built]
    D --> E[Diagram Type Detected]
    E --> F[Type-Specific Renderer]
    F --> G[SVG Generated]
    G --> H[Inserted into DOM]
    H --> I[Your Enhancements Run]

    style A stroke:#059669,stroke-width:3px,color:#10b981
    style D stroke:#2563eb,stroke-width:3px,color:#3b82f6
    style G stroke:#7c3aed,stroke-width:3px,color:#8b5cf6
    style I stroke:#d97706,stroke-width:3px,color:#f59e0b

Дозвольте розбити кожен крок

Шаг 1: визначення тексту

Все починається з тексту. Ви пишете діаграми в Мермейді 's DSL M SK2домені МSK3конкретній мові

// Flowchart
const diagram = `
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug time]
`;

Шаг 2: Lexical Analysis

Ліксер розділяє текст на символи.

A[Start] --> B{Decision}

Стає символами, такими як:

[
    { type: 'NODE_ID', value: 'A' },
    { type: 'NODE_TEXT', value: 'Start' },
    { type: 'ARROW', value: '-->' },
    { type: 'NODE_ID', value: 'B' },
    { type: 'NODE_TEXT', value: 'Decision' },
    { type: 'NODE_SHAPE', value: 'diamond' }  // from { }
]

Шаг 3: Parsing і генерування AST

Програміст споживає символи і створює абстрактне дерево синтаксису (ASTM SK1

// Simplified AST structure
{
    type: 'flowchart',
    direction: 'TD',
    nodes: [
        { id: 'A', text: 'Start', shape: 'rect' },
        { id: 'B', text: 'Decision', shape: 'diamond' }
    ],
    edges: [
        { from: 'A', to: 'B', type: 'arrow' }
    ]
}

Сирена використовує різні аналітики для кожного типу діаграми. Вони часто генеруються з файлів граматики, використовуючи Джисон (подібно до Yacc

Шаг 4: Виявление діаграми

Сирена розпізнає тип діаграми з першої лінії:

// Simplified detection logic
if (text.match(/^\s*graph/)) return 'flowchart';
if (text.match(/^\s*sequenceDiagram/)) return 'sequence';
if (text.match(/^\s*classDiagram/)) return 'class';
// ... etc

Шаг 5: ТипМSK1конкретне відображання

Кожен тип діаграми має власний рендерер. Рендерер бере AST і генерує SVG елементи.

Для схем потоку, Сирена використовує Даґре bibliotekа для графічного макету. Для іншихM SK1 він використовує індивідуальні алгоритми або бібліотеки, такі як Cytoscape.

// Simplified flowchart renderer
export const draw = function (text, id, version, diagObj) {
    const graph = diagObj.db;  // The AST
    const svg = d3.select(`#${id}`);

    // Render nodes
    graph.getVertices().forEach(vertex => {
        drawNode(svg, vertex);
    });

    // Render edges
    graph.getEdges().forEach(edge => {
        drawEdge(svg, edge);
    });

    // Apply layout algorithm
    dagre.layout(graph);
};

Шаг 6: генерування SVG

Рендерер створює марку SVG:

<svg xmlns="http://www.w3.org/2000/svg">
    <g class="node">
        <rect x="0" y="0" width="100" height="50"/>
        <text x="50" y="25">Start</text>
    </g>
    <g class="edge">
        <path d="M 100 25 L 200 25" stroke="#333"/>
    </g>
</svg>

Шаг 7: Введення DOM

Сирена знаходить все .mermaid і замінює їх рендерованими SVG:

// From mermaid.ts
export const init = async function (config, nodes) {
    const nodesToProcess = nodes || document.querySelectorAll('.mermaid');

    for (const node of nodesToProcess) {
        const id = `mermaid-${Date.now()}-${Math.random()}`;
        const txt = node.textContent;

        const { svg } = await render(id, txt);
        node.innerHTML = svg;
    }
};

Шаг 8: Пост МSK1 Процедура МSK2 Де ви приходите )

Після того, як Сирена вставляє SVG, ви можете покращити йогоM SK1 Ось тут всі мої покращення закріплені в:

  • Функція Pan/zoom
  • Кнопка управління
  • Виведення можливостей
  • Перемикання тем

Більше про це внизу.

Розширювання Mermaid: Показів розширення

Тепер, коли ми знаємо, як працює Сирена, ми можемо дослідити, як її розширити.

1. Налаштування

Найпростіший варіант - це конфігурація:

import mermaid from 'mermaid';

mermaid.initialize({
    startOnLoad: true,
    theme: 'dark',
    securityLevel: 'loose',
    flowchart: {
        curve: 'basis',
        padding: 15
    }
});

2. Customization Theme

Я розповідав про це в Перемикання тем для СиренаМСК0 , але тут "'" є ключовим кроком .

Проблема з переключенням тематики

Сирена повинна бути inicialізована з темою, і ви можетеMSC1 не змінювати її після., але якщо ви хочете переробитиM SK3 представити діаграми з новою темою doesn' не зберігає в DOM.

Рішення

Поміщайте оригінальний контент перед тим, як відтворювати, тоді відновіть і відтворюйтеM SK1 відтворити при переключенні тем

// From my theme-switcher implementation
const originalData = new Map();

// Save original content before first render
const saveOriginalData = async () => {
    const elements = document.querySelectorAll('.mermaid');
    elements.forEach(element => {
        const id = element.id || `mermaid-${Date.now()}`;
        element.id = id;

        // Store the original diagram source
        if (!originalData.has(id)) {
            originalData.set(id, element.textContent?.trim());
        }
    });
};

// When theme changes, restore and re-render
const loadMermaid = async (theme) => {
    mermaid.initialize({
        startOnLoad: false,
        theme: theme
    });

    const elements = document.querySelectorAll('.mermaid');
    for (const element of elements) {
        const source = originalData.get(element.id);
        if (source) {
            element.innerHTML = '';  // Clear
            element.removeAttribute('data-processed');

            const { svg } = await mermaid.render(
                `mermaid-svg-${element.id}`,
                source
            );
            element.innerHTML = svg;
        }
    }
};

Metodи виявлення багатьох тем (сайти обробляють тему по-іншому ):

function detectTheme() {
    // Check various sources
    if (typeof window.__themeState !== 'undefined') {
        return window.__themeState;
    }
    if (localStorage.theme) {
        return localStorage.theme;
    }
    if (document.documentElement.classList.contains('dark')) {
        return 'dark';
    }
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
        return 'dark';
    }
    return 'light';
}

Подивіться повний код перемикача тем для деталей.

МSK0 Пост-Позитивні покращення

Ось де відбувається справжня магія.

Я розповідав про це в Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом, тож я ' розповім про ключові прийоми

Згортання діаграм

Створити контейнер для упаковок для управління:

function wrapDiagram(element) {
    if (element.closest('.mermaid-wrapper')) {
        return element.closest('.mermaid-wrapper');
    }

    const wrapper = document.createElement('div');
    wrapper.className = 'mermaid-wrapper';
    wrapper.id = `wrapper-${element.id}`;

    element.parentNode.insertBefore(wrapper, element);
    wrapper.appendChild(element);

    return wrapper;
}

Додаємо Pan/Zoom

Використовуючи svg-panM SK1zoom:

import svgPanZoom from 'svg-pan-zoom';

const panZoomInstances = new Map();

function initPanZoom(svgElement, diagramId) {
    // Clean up existing instance
    if (panZoomInstances.has(diagramId)) {
        panZoomInstances.get(diagramId).destroy();
        panZoomInstances.delete(diagramId);
    }

    const instance = svgPanZoom(svgElement, {
        zoomEnabled: true,
        controlIconsEnabled: false,
        fit: true,
        center: true,
        minZoom: 0.1,
        maxZoom: 10
    });

    panZoomInstances.set(diagramId, instance);
    return instance;
}

Кнопка управління

Створити плавучу панель управління:

function createControlButtons(container, diagramId) {
    const controlsDiv = document.createElement('div');
    controlsDiv.className = 'mermaid-controls';

    const buttons = [
        { icon: 'bx-fullscreen', title: 'Fullscreen', action: 'fullscreen' },
        { icon: 'bx-zoom-in', title: 'Zoom In', action: 'zoomIn' },
        { icon: 'bx-zoom-out', title: 'Zoom Out', action: 'zoomOut' },
        { icon: 'bx-reset', title: 'Reset', action: 'reset' },
        { icon: 'bx-move', title: 'Pan', action: 'pan' },
        { icon: 'bx-image', title: 'Export PNG', action: 'exportPng' },
        { icon: 'bx-code-alt', title: 'Export SVG', action: 'exportSvg' }
    ];

    buttons.forEach(btn => {
        const button = document.createElement('button');
        button.className = `mermaid-control-btn bx ${btn.icon}`;
        button.setAttribute('data-action', btn.action);
        button.setAttribute('data-diagram-id', diagramId);
        controlsDiv.appendChild(button);
    });

    container.appendChild(controlsDiv);
}

Делегація на події (Performance!)

Don' не прив 'язувати слухачів кожнісіньким кнопкамM SK1 використовувати делегацію подій:

document.addEventListener('click', (e) => {
    const target = e.target;
    if (!target.classList.contains('mermaid-control-btn')) return;

    const action = target.getAttribute('data-action');
    const diagramId = target.getAttribute('data-diagram-id');
    const panZoom = panZoomInstances.get(diagramId);

    switch (action) {
        case 'zoomIn': panZoom?.zoomIn(); break;
        case 'zoomOut': panZoom?.zoomOut(); break;
        case 'reset': panZoom?.reset(); break;
        // ... etc
    }
});

Виведення функцій

Виклик Elementи SVG мають динамічне розмірування, панельM SK1 трансформації зйомки , і успадковані стилі. Для правильного виведенняMSC4 вам потрібноMSSK5

  1. Клоні SVG
  2. Захищати виміри
  3. Перетвори
  4. Перетворити на PNG або SVG

Використовуючи html-наM SK1зображення:

import { toPng, toSvg } from 'html-to-image';

async function exportDiagram(container, format, diagramId) {
    const svgElement = container.querySelector('svg');
    if (!svgElement) return;

    // Clone to avoid modifying original
    const clonedSvg = svgElement.cloneNode(true);

    // Get or calculate viewBox
    let viewBox = clonedSvg.getAttribute('viewBox');
    if (!viewBox) {
        const bbox = svgElement.getBBox();
        viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
        clonedSvg.setAttribute('viewBox', viewBox);
    }

    // Set explicit dimensions
    const [, , width, height] = viewBox.split(' ').map(Number);
    clonedSvg.setAttribute('width', width);
    clonedSvg.setAttribute('height', height);

    // Remove pan-zoom transforms
    clonedSvg.removeAttribute('style');

    // Create off-screen container
    const temp = document.createElement('div');
    temp.style.position = 'absolute';
    temp.style.left = '-9999px';
    temp.appendChild(clonedSvg);
    document.body.appendChild(temp);

    // Export
    const dataUrl = format === 'png'
        ? await toPng(clonedSvg, { pixelRatio: 2 })
        : await toSvg(clonedSvg);

    downloadFile(dataUrl, `diagram-${Date.now()}.${format}`);

    // Cleanup
    document.body.removeChild(temp);
}

Критичні деталі:

  • Запам 'ятайте ViewBox - Захоплює всю діаграмуM SK1 не лише видиму частину
  • Офф-рендерінг екрану - уникати впливу на представлену діаграму
  • Рatio пікселів: M SK1 - WysokiM SK1DPI для крихітного експорту ПНГ

Подивіться повний код eksportу для більших деталей.

Повний пакет покращення

Я пакував всі ці покращення, як @влучнішийM SK1морська матка-усилення. Подивіться Опублікувати покращення для морської дівчини як пакет npm для повних деталей.

Ось як це все працює.

graph TB
    A[User Initializes] --> B[init Function]
    B --> C[initMermaid]
    B --> D[enhanceMermaidDiagrams]

    C --> E[Theme Detection]
    C --> F[Event Listeners]
    C --> G[Mermaid Rendering]

    E --> E1[Global State]
    E --> E2[LocalStorage]
    E --> E3[DOM Class]
    E --> E4[OS Preference]

    F --> F1[Custom Events]
    F --> F2[Media Query]

    G --> H[Apply Enhancements]
    D --> H

    H --> I[Wrap Diagrams]
    H --> J[Init Pan/Zoom]
    H --> K[Add Controls]

    I --> L[Interactive Diagram]
    J --> L
    K --> L

    L --> M[User Interactions]
    M --> M1[Zoom In/Out]
    M --> M2[Pan]
    M --> M3[Fullscreen]
    M --> M4[Export PNG/SVG]

    style A stroke:#059669,stroke-width:3px,color:#10b981
    style L stroke:#2563eb,stroke-width:3px,color:#3b82f6
    style M stroke:#7c3aed,stroke-width:3px,color:#8b5cf6

Використовування

npm install @mostlylucid/mermaid-enhancements
import { init } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';

await init();

Те, що МСК0 , це "!". Ваші діаграми Сирена тепер мають МСК2 .

  • ✅ Interactive panM SK1zoom
  • ✅ Світлоbox на весь екран
  • ✅ PNGM SK1SVG
  • ✅ Автоматичний перемикач тем
  • ✅ Реакційний дизайн

Інтеграція з HTMX

Як я описав Додання русалка.js з htmx, вам потрібно перезапустити МSK1ініціалізувати Мермейду після обміну контентом HTMX

// On page load
document.addEventListener('DOMContentLoaded', function () {
    mermaid.initialize({ startOnLoad: true });
});

// After HTMX swaps content
document.body.addEventListener('htmx:afterSwap', function(evt) {
    mermaid.run();
});

З пакетом покращень:

import { init, enhanceMermaidDiagrams } from '@mostlylucid/mermaid-enhancements';

// Initial load
await init();

// After HTMX swap
document.body.addEventListener('htmx:afterSwap', async function() {
    await init();  // Re-init Mermaid with current theme
    enhanceMermaidDiagrams();  // Re-apply enhancements
});

Найкращі практики, які я вивчив

Після того, як я збудував цю штуку і виправив дивні краєвидні cases,

1. Знову зберігати оригінальний контент

Сирена не зберігає оригінального джерела діаграми після відтворення.

const originalData = new Map();

// Before first render
element.setAttribute('data-original-code', element.textContent);
originalData.set(element.id, element.textContent);

// When re-rendering
element.innerHTML = originalData.get(element.id);

2. Почистити інстанції

Потіки пам 'яті є справжніми. Зруйнуйте instanції перед створенням нових:

if (panZoomInstances.has(id)) {
    try {
        panZoomInstances.get(id).destroy();
    } catch (e) {
        console.warn('Failed to destroy:', e);
    }
    panZoomInstances.delete(id);
}

3. Використовуйте delegatію подій

Не прикріпляйте слухачів до окремих кнопок:

// ❌ Don't do this
buttons.forEach(btn => {
    btn.addEventListener('click', handler);
});

// ✅ Do this
document.addEventListener('click', (e) => {
    if (e.target.matches('.mermaid-control-btn')) {
        handleClick(e.target);
    }
});

4. Ручка

Ракетний Лодер затягує виконання JavaScript. Почекайте на залежністьM SK1

function waitForDependencies(maxAttempts = 50) {
    return new Promise((resolve) => {
        let attempts = 0;

        const check = () => {
            if (window.mermaid && window.htmx && window.Alpine) {
                resolve();
            } else if (attempts >= maxAttempts) {
                resolve();  // Give up
            } else {
                attempts++;
                setTimeout(check, Math.min(50 * Math.pow(1.2, attempts), 500));
            }
        };

        check();
    });
}

І виключити вашу головну стрічку з Rocket Loader

<script src="main.js" data-cfasync="false"></script>

5. Час - це все

Використовувати requestAnimationFrame для кращого часу, ніж довільний setTimeout:

// After Mermaid renders
await mermaid.run();

// Wait for paint before enhancing
await new Promise(resolve => {
    requestAnimationFrame(() => {
        requestAnimationFrame(() => {
            enhanceMermaidDiagrams();
            resolve();
        });
    });
});

6. Охоронний SVG Рух

SVGs можуть бути дивними. Звісно перевіряйтеM SK1

const svgElement = container.querySelector('svg');
if (!svgElement) {
    console.warn('No SVG found');
    return;
}

// Clone before modifying
const cloned = svgElement.cloneNode(true);

// Ensure viewBox exists
let viewBox = cloned.getAttribute('viewBox');
if (!viewBox) {
    const bbox = svgElement.getBBox();
    viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
}

Вказівки для розв 'язання проблем

Виход Konsolи

З правильною ініціалізацією, треба побачитиM SK1

Saving original data
Loading mermaid with theme: dark
Mermaid initialized
Enhanced 3 diagrams

Випробовування списку перевірок

Після втілення покращень:

  • Діаграми відтворюють на завантаження сторінки
  • ПанM SK1навігальне управління
  • Полний екран відкривається МSK1 закривається МSK2XM SK3 натискає назовні , ESC)
  • Eksport PNG захоплює повну діаграму
  • Eksport SVG зберігає вектори
  • Працює після обміну контентом HTMX
  • Перемикання тем reM SK1правильна
  • мобільний реагуючий
  • Темний стиль
  • Доступність клавіатура

Поширені проблеми

Грамматика не відображається:

  • Подивіться на консоль браузера на помилки
  • Перевірити завантаження Сирена (window.mermaid)
  • Проверка синтаксису діаграми

Пан/зом не працюєM SK1

  • Перевірити інициалізацію svg-panM SK1zoom
  • Проверка конфлікту CSS (pointer-events: none)
  • Проаналізувати карту інстанцій

Виведення захоплює лише куток:

  • Не вистачає збереження viewBox
  • Перетворення не видалено
  • Проверка логіки клонування

Тема не змінюється:

  • Початкові дані не заpisane
  • data-processed не відновити
  • Слухачі подій не зареєстровані

Рівень ефективності

Зачаток ліни

Допоки не потрібне, не вдосконалювати навантаження'

let enhancementsLoaded = false;

async function loadEnhancements() {
    if (enhancementsLoaded) return;

    const { enhanceMermaidDiagrams } = await import('./enhancements.js');
    enhanceMermaidDiagrams();
    enhancementsLoaded = true;
}

// Load on first interaction
document.addEventListener('click', (e) => {
    if (e.target.closest('.mermaid')) {
        loadEnhancements();
    }
}, { once: true });

Обсерватор перехрестя

Рендерувати діаграми тільки тоді, коли вони помітні:

const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            renderDiagram(entry.target);
            observer.unobserve(entry.target);
        }
    });
}, { rootMargin: '100px' });

document.querySelectorAll('.mermaid').forEach(el => {
    observer.observe(el);
});

Викидати позиціонери

Під час зміни розміру або теми:

let timeout;
window.addEventListener('resize', () => {
    clearTimeout(timeout);
    timeout = setTimeout(() => {
        panZoomInstances.forEach(instance => {
            instance.resize();
            instance.fit();
        });
    }, 250);
});

На завершення

Mermaid.js - це фантастична річ, яка виходить з коробки , але розуміння того, як вона працює всередині, дає вам змогу побудувати справді круті покращення.

  1. Рендерування ланцюга: Текст → Лексер МSK2 Розшифровувач МSK3 AST M→ Рендер МСК5 SVG
  2. Точки розширення: Конфигурація МSK1 Теми МSK2 пост - покращення передачі
  3. Поміщати оригінальні дані: Сирена не робить цього для вас
  4. Чисти ресурси: Потік пам 'яті реальний
  5. Відповідання про події: Кращі результати
  6. Багато джерел тем: Вебсайти обробляють тему по-різному
  7. Справа в часі: Використовувати requestAnimationFrame

Всі методи, які я описав тут, використовуються для виробництва на цьому сайті і упаковані в @влучнішийM SK1морська матка-усилення. Полне джерело доступно на більшістьlucidweb/mostlylucid-mermaid.

Подібні статті

Ресурс

Попробуйте контролювати на діаграмі вище! M SK1

logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.