Діаграми Mermaid у Markdown

Mermaid це спосіб малювати діаграми текстом. Ти пишеш кілька коротких рядків. Засіб читання, який підтримує Mermaid, перетворює їх на малюнок: блок-схему, часову шкалу, діаграму.

Діаграму можна тримати в звичайному файлі Markdown. Не треба експортувати зображення й відкривати програму для малювання. Щоб змінити діаграму, ти змінюєш текст.

Блок коду mermaid

Діаграма Mermaid живе в блоці коду з огородженням. Огородження це три зворотні лапки. Після відкривного огородження напиши mermaid як назву мови:

```mermaid
flowchart LR
    A --> B
```

Перший рядок усередині блока вказує, який це вид діаграми. Тут це flowchart LR. Усе після цього рядка описує діаграму.

Рядки, що починаються з %%, є коментарями. Засіб читання їх ігнорує.

Приклад 1: блок-схема з рішенням

```mermaid
flowchart TD
    Start[Write the note] --> Check{Is it clear?}
    Check -->|Yes| Publish[Share it]
    Check -->|No| Edit[Rewrite it]
    Edit --> Check
```

Як це читати:

Приклад 2: діаграма послідовності

Діаграма послідовності показує, хто з ким спілкується, по черзі.

```mermaid
sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Open the page
    S-->>U: Send the page
    U->>S: Log in
    S-->>U: Welcome
```

Приклад 3: кругова діаграма

```mermaid
pie title Time spent on a project
    "Writing" : 40
    "Reading" : 25
    "Meetings" : 15
    "Other" : 20
```

Кожен сектор це мітка в лапках, двокрапка й число. Число має бути більшим за нуль.

Інші типи діаграм

Mermaid може малювати набагато більше видів. Найпоширеніші:

Кожен тип має власне перше слово й власні правила. У документації Mermaid для кожного є окрема сторінка.

Де малюються діаграми Mermaid

GitHub малює блоки Mermaid у файлах Markdown, обговореннях, запитах на злиття та вікі. Потрібен лише блок коду mermaid. Багато редакторів Markdown і застосунків для нотаток також підтримують Mermaid, але не всі.

Коли засіб читання не підтримує Mermaid, він зазвичай трактує блок як будь-який інший код. Ти бачиш текст, який написано, а не малюнок. Нічого не втрачається. Просто не намальовано.

Типові помилки

Відступи не потрібні. Більшість людей робить відступи в рядках усередині діаграми лише тому, що так легше читати.

Чати зі ШІ та агенти пишуть Mermaid

Чати зі ШІ та агенти для програмування часто вставляють Mermaid у плани, специфікації та нотатки з проєктування. Блок-схема це швидкий спосіб показати кроки. Діаграма послідовності показує, як частини системи спілкуються між собою.

Якщо чат дає тобі діаграму, скопіюй весь блок коду, разом з огородженнями, у свій файл Markdown. Якщо діаграма не малюється, перевір її за помилками вище. Короткі мітки й одна ідея на діаграму полегшують виправлення тексту.

Читання діаграм Mermaid

PilcrowMD малює діаграми Mermaid на Android і на Mac, без потреби в інтернеті. На Android торкнися діаграми, щоб побачити її на весь екран. На Mac Quick Look, порівняння та PDF показують блок коду замість малюнка.

Поширені запитання

Чи потрібно щось установлювати, щоб писати Mermaid? Ні. Ти пишеш звичайний текст у блоці коду. Потрібен лише засіб читання, який його малює.

Чому я бачу код замість діаграми? Або засіб читання не підтримує Mermaid, або в діаграмі є синтаксична помилка. Перевір, що блок починається з mermaid і що перший рядок називає справжній тип діаграми.

Чи можна змінити вигляд діаграми? Так. У Mermaid є параметри для кольорів, форм і компонування. Почни зі стандартних. Для більшості нотаток їх досить.

Також для Mac: PilcrowMD для Mac (бета)