Диаграммы: Mermaid, TLDraw, Excalidraw

Зачем это нужно

Документация без диаграмм скучная и малопонятная. Архитектура
системы, поток данных, пользовательский сценарий — всё это
объясняется на картинке в разы быстрее, чем в десяти абзацах текста.

Nextdocs даёт три разных способа рисовать. Все они живут прямо в
странице — не нужно никаких внешних инструментов, внешних файлов или
скриншотов.

Какой инструмент когда выбрать

Инструмент

Формат ввода

Подходит для

Не подходит для

Mermaid

Текстовый DSL

Flow-чарты, sequence diagrams, ER, гантты, state machines — когда структура важнее эстетики

Свободного рисования, произвольных форм

TLDraw

Мышь / тачпад

Схемы архитектуры, wireframes, UI-макеты — геометрически точные диаграммы

Текстовой DSL-диаграммы (flowchart и т.п.)

Excalidraw

Мышь / тачпад

Скетчи, whiteboard-наброски, эскизы — hand-drawn стилистика

Точных технических схем (выглядит «рукописно»)

Общее правило: если диаграмму хочется редактировать в PR-ревью — берёте Mermaid (она в git diff видна). Если хочется быстро накидать «идею на салфетке» — Excalidraw. Если нужна точная схема с выравниванием и притягиванием — TLDraw.

Mermaid

Как вставить

  1. В слеш-меню выберите Code.

  2. В правом верхнем углу блока — выпадающий список языков. Выберите
    mermaid.

  3. Вводите код диаграммы:

flowchart LR
    A[Start] --> B{Is user authed?}
    B -->|Yes| C[Load page]
    B -->|No| D[Redirect to login]

Под блоком сразу рендерится картинка. Редактируете код — картинка
перерисовывается в реальном времени.

Что умеет Mermaid

Полная грамматика — на https://mermaid.js.org.

Подсказки

Коллаборация

При редактировании Mermaid-блока коллеги видят ваш курсор (в коде, не
на SVG). Картинка перерисовывается у всех автоматически.

TLDraw

Как вставить

  1. В слеш-меню — Diagram.

  2. Появится встроенный холст ~400 пикселей высотой.

  3. Рисуете: выберите инструмент слева (прямоугольник, эллипс, стрелка,
    текст), кликаете-тащите по холсту.

  4. Для полноценной работы — нажмите иконку «расширить» в правом
    верхнем углу. Откроется на всё окно.

Что умеет TLDraw

Коллаборация

Работает в реальном времени: видны курсоры коллег, все изменения
применяются синхронно. Двое могут одновременно таскать разные
фигуры — конфликтов нет.

Excalidraw

Как вставить

  1. Слеш-меню — Excalidraw.

  2. То же — встроенный холст, fullscreen по иконке.

Отличие от TLDraw

Excalidraw лучше подходит для коммуникации идеи «в разговоре»:
«Смотри, это фронт, это бэк, стрелка — запрос». Для строгой
документации, которая останется на годы — предпочтительнее TLDraw
или Mermaid.

Коллаборация

Тоже в реальном времени, включая живые курсоры участников.

Поиск по диаграммам

Внутренний поиск Nextdocs ищет по текстовому содержимому диаграмм:

То есть если вы подписали прямоугольник словом «Auth Service»,
глобальный поиск (Cmd/Ctrl+K) найдёт эту диаграмму по запросу
«Auth».

Поиск в Google на публичной документации диаграммы не индексирует
как изображения — только текст вокруг и подписи.

Fullscreen режим

Кнопка «расширить» (иконка в правом верхнем углу любой диаграммы)
разворачивает редактор на весь viewport. ESC или повторный клик —
выход.

В fullscreen удобно работать с большими диаграммами; вне fullscreen
— быстро посмотреть и чуть-чуть подправить.

Ограничения