Technical diagrams often become stale because editing them requires finding the original design file, opening a separate application, and exporting another image.Mermaid использует другой подход: диаграмма определяется как текст и хранится рядом с документацией.
Чтобы добавить Mermaid к Markdown, поместите определение диаграммы внутри изолированного кодового блока с mermaid идентификатор языка.Используйте Предпросмотр диаграмм Mermaid для локальной визуализации синтаксиса, исправления ошибок, полного копирования ограждения Markdown или загрузки SVG.
Это руководство начинается с небольшой блок-схемы и развивается на основе диаграмм последовательностей, классов, диаграмм Ганта, интеллект-карт и диаграмм сущностей и связей.
Mermaid за 30 секунд
Базовый блок Mermaid выглядит следующим образом:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
Открывающееся ограждение сообщает совместимому средству визуализации, что содержимое имеет синтаксис Mermaid. flowchart LR выбирает блок-схему, расположенную слева направо.Остальные строки определяют узлы и соединения.
Если пункт назначения не поддерживает Mermaid, читатели обычно видят блок кода вместо диаграммы.Этот запасной вариант сохраняет исходный код, но не заменяет проверку совместимости перед публикацией.
Зачем использовать текстовые диаграммы?
Mermaid особенно полезен, когда диаграмма:
- принадлежит документации с контролем версий;
- изменяется вместе с кодом или процедурами;
- требует содержательных различий в запросах на включение;
- использует стандартные формы и связи;
- должен быть доступен для редактирования без собственного файла дизайна;
- необходимо перегенерировать в светлой и темной темах.
Он менее подходит для детальных иллюстраций, макетов с точностью до пикселя, рукописных аннотаций или визуального дизайна, требующего точного размещения вручную.В таких случаях используйте инструмент рисования и экспортируйте доступный SVG или изображение.
Пример 1: Блок-схема
Блок-схемы описывают процесс, решение или правило маршрутизации.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Синтаксис ключей:
TDозначает сверху вниз.LRmeans left to right.[Text]создает прямоугольный узел процесса.{Text}создает узел принятия решений.-->создает направленное соединение.-->|Label|добавляет текст к соединению.
Используйте стабильные короткие идентификаторы узлов, такие как A or validate.Держите видимую этикетку внутри скобок, чтобы изменение формулировки не требовало изменения каждого соединения.
Добавить подграф
Шаги, связанные с группой подграфов:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Используйте подграфы, когда группировка сообщает о владельце, границах системы или фазах.Не добавляйте коробку просто для украшения.
Пример 2: Диаграмма последовательности
Диаграммы последовательности показывают взаимодействия во временном порядке.Они хорошо работают для вызовов API, аутентификации, рабочих процессов браузера и систем, управляемых событиями.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Общие стрелки:
->>отправляет убедительное сообщение.-->>отправляет пунктирный ответ.participantобъявляет систему или услугу.actorобъявляет человеческую или внешнюю роль.autonumberобозначает взаимодействия по порядку.
Сосредоточьтесь на одном сценарии.Диаграмму последовательности, которая пытается показать каждую альтернативу и каждую внутреннюю функцию, становится сложнее понять, чем код.
Показать альтернативный путь
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Использование alt, elseи end для значимых ветвей.Если ветка требует нескольких страниц пояснений, дайте ссылку на прозу под схемой.
Пример 3: Диаграмма классов
Диаграммы классов описывают типы, свойства, операции, наследование и отношения.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
В этом примере утверждается, что MarkdownDocument наследуется от Document.Используйте диаграммы классов для концептуальной модели, а не в качестве автоматической замены полной справочной документации API.
В хороших диаграммах классов опускаются детали, которые не помогают читателю понять конструкцию.Отображение каждого частного поля может превратить диаграмму в менее доступную для поиска версию исходного кода.
Пример 4: диаграмма Ганта
Диаграммы Ганта показывают задачи во времени.Они полезны для планов выпуска, миграции и проектов документации.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Сохраняйте даты явными и используйте идентификаторы задач, когда одна задача зависит от другой.Помните, что диаграмма, хранящаяся в документации, не будет обновляться при изменении реального расписания проекта.Назначьте право собственности для поддержания его актуальности.
Пример 5: Интеллект-карта
Интеллект-карты организуют идеи вокруг центральной темы.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Интеллект-карты наиболее эффективны при планировании или в качестве общего обзора.Они менее полезны для точных отношений, поскольку древовидная структура может подразумевать иерархию, в которой реальные концепции пересекаются.
Пример 6: Диаграмма сущность-связь
ER-диаграммы описывают объекты данных и их отношения.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Используйте диаграмму ER для объяснения модели и схему или файл миграции для определения реализации.В диаграмме могут отсутствовать индексы, ограничения и поля, которые не имеют отношения к текущему объяснению.
Предварительный просмотр Mermaid перед публикацией
Написание диаграмм непосредственно в длинном документе Markdown затрудняет выявление синтаксических ошибок.Цикл сфокусированного предварительного просмотра работает быстрее:
- Откройте . Предпросмотр диаграмм Mermaid.
- Вставьте только определение диаграммы, без внешней границы кода.
- Отобразите диаграмму.
- Прочтите любую синтаксическую ошибку и исправьте указанную область.
- Скопируйте сгенерированный изолированный Markdown.
- Загрузите SVG, если пункту назначения требуется статический ресурс.
- Испытайте последнюю версию Markdown на реальной платформе.
Предварительный просмотр отображается в вашем браузере со строгими настройками безопасности.Обратные вызовы диаграмм и другие интерактивные функции могут быть отключены, даже если другая установка Mermaid разрешает их.Такое консервативное поведение подходит для обычного инструмента предварительного просмотра.
Распространенные ошибки Mermaid
Отсутствует тип диаграммы
Неправильно:
A --> B
Правильно:
flowchart LR
A --> B
Первая строка идентифицирует грамматику диаграммы.
Пунктуация в метке нарушает синтаксический анализ
Цитировать сложные метки:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Это особенно полезно для круглых скобок, знаков препинания и меток, напоминающих синтаксис.
Неожиданно используется зарезервированный Word
Mermaid grammars have keywords.Официальная документация по блок-схемам специально предупреждает, что строчные буквы end может сломать блок-схему.Напишите его с заглавной буквы или поместите видимый текст внутри метки узла в кавычках:
flowchart LR
Start --> Finish["End"]
Неверный код ограждения.
Идентификатор языка располагается сразу после открывающих обратных кавычек:
```mermaid
flowchart LR
A --> B
```
Не делайте отступов по всему ограждению, если этого не требует окружающий синтаксис Markdown.
Работает на одной платформе, но не на другой.
Mermaid развивается, и платформы могут использовать разные средства визуализации, версии, настройки безопасности и включенные типы диаграмм.Функция синтаксиса, поддерживаемая новейшей версией Mermaid, может не работать на платформе, использующей другую реализацию или более старую версию.
Предпочитайте широко поддерживаемый синтаксис для документов, которые перемещаются между платформами.Тестируйте расширенные формы, темы, директивы и новые типы диаграмм во всех необходимых местах назначения.
Совместимость платформ
Совместимость следует проверять, а не предполагать:
| Платформа | Текущий документированный подход | Важное примечание |
|---|---|---|
| GitHub | Используйте огороженную mermaid block | GitHub рендеринг документов в Markdown файлах, задачах, обсуждениях, запросах на включение и вики |
| GitLab (ГитЛаб) | Используйте блок кода Mermaid в GitLab Flavored Markdown. | GitLab документирует поддерживаемую версию Mermaid;самоуправляемые установки могут отличаться |
| Obsidian | Используйте огороженную mermaid в заметке | Механизм рендеринга Obsidian и поддерживаемые функции могут меняться в разных выпусках. |
| Материал для MkDocs | Настройка пользовательского ограждения Mermaid | Для интеграции встроенной темы требуется документированная pymdownx.superfences configuration |
| Общий анализатор Markdown | Часто отображает только код | Для рендеринга Mermaid обычно требуется плагин интеграции или сборки JavaScript. |
Прежде чем использовать новую функцию, проверьте текущую официальную документацию:
- GitHub: Создание диаграмм
- Со вкусом GitLab Markdown
- Obsidian: Расширенный синтаксис форматирования
- Материал для MkDocs: Диаграммы
- Справочник по синтаксису Mermaid
Для сайта документации, который вы контролируете, закрепите версию зависимости Mermaid и протестируйте обновления.В противном случае незначительное изменение синтаксиса может привести к изменению диаграмм на всем сайте.
Mermaid и доступность
Отрисованный SVG не передает свое значение автоматически каждому читателю.Рассматривайте диаграмму как визуальное резюме и дайте эквивалентное объяснение в ближайшей прозе.
Для предыдущей блок-схемы преобразования добавьте текст, например:
Пользователь выбирает файл DOCX.Действительные файлы преобразуются локально и отображаются для просмотра;недействительные файлы вызывают ошибку.Затем пользователь может скопировать или загрузить проверенный Markdown.
Практика обеспечения доступности:
- объясните, что поясняет диаграмма;
- обобщить выводы после сложных диаграмм;
- не кодируйте значение только с помощью цвета;
- используйте читаемые этикетки, а не внутренние сокращения;
- поддерживать достаточный контраст в светлых и темных темах;
- избегайте диаграмм, требующих точного взаимодействия с мышью;
- предоставить текстовую или табличную альтернативу важной информации;
- экспортируйте SVG с осторожностью, если статический файл должен иметь доступное имя.
Исходный код полезен авторам, но не обязательно является хорошей текстовой альтернативой для читателей.
Создание диаграмм, которые остаются читабельными
Сохраняйте одну цель на диаграмме.
Диаграмма должна отвечать на такой вопрос, как «Что происходит после неудачного запроса?»или «Какому сервису принадлежит каждое хранилище данных?»Если он попытается объяснить всю систему, разделите ее.
Предпочитать короткие этикетки
Подробные пояснения дайте в прозе.Длинные метки требуют узких узлов, неудобного переноса строк и больших диаграмм на экранах мобильных устройств.
Намеренно используйте направление
Поток слева направо хорошо работает для коротких процессов и путей запросов.Поток сверху вниз часто лучше подходит для узких экранов.Предварительный просмотр обоих перед фиксацией.
Ограничить визуальный стиль
Пользовательские цвета могут конфликтовать с темным режимом или темами платформы.Начните с настроек рендерера по умолчанию.Добавляйте стили только тогда, когда они передают смысл и остаются читабельными во всех необходимых темах.
Держите источник рядом с его объяснением
По возможности сохраняйте блок Mermaid в том же файле Markdown.Благодаря этому проза и схема меняются вместе в одном обзоре.
Mermaid и статическое изображение
Выбирайте Mermaid, когда:
- диаграмма часто меняется;
- исходные различия имеют важное значение;
- в макете используются стандартные типы диаграмм;
- платформа публикации надежно отображает Mermaid.
Выбирайте SVG или PNG, если:
- конструкция требует точной ручной компоновки;
- пункт назначения не отображает Mermaid;
- точный внешний вид должен оставаться неизменным;
- для внешнего общего доступа требуется отдельный ресурс.
Полезным гибридом является поддержка источника Mermaid и экспорт SVG для мест назначения, которые не могут его отобразить.Храните источник рядом с экспортированным ресурсом и документируйте, как его восстановить.
Использование Markdown в изображение для совместного использования визуализированного содержимого Markdown или загрузите SVG непосредственно с Предпросмотр диаграмм Mermaid , когда активом является сама диаграмма.
FAQ
Является ли Mermaid частью стандартного Markdown?
№ А огороженный mermaid — это расширение, распознаваемое совместимыми приложениями и системами сборки.Базовый анализатор Markdown может визуализировать его как обычный код.
Отображает ли GitHub диаграммы Mermaid?
Да.В документации GitHub описывается рендеринг Mermaid в файлах Markdown и нескольких областях совместной работы.Проверьте новый синтаксис, поскольку GitHub управляет развернутым модулем визуализации и настройками безопасности.
Могу ли я использовать Mermaid в Obsidian?
Официальная справочная система Obsidian документирует изолированные блоки диаграмм в стиле Mermaid в примечаниях.Поддержка функций может меняться в зависимости от средства визуализации приложения, поэтому проверяйте сложные или недавно представленные типы диаграмм в установленной версии.
Может ли Mermaid заменить документацию по архитектуре?
No. A diagram is one view of a system.Сопоставьте это с решениями, владением, ограничениями, поведением при сбоях и ссылками на авторитетные интерфейсы или схемы.
Почему моя диаграмма отображается по-другому в темном режиме?
Платформы могут применять разные темы Mermaid, переменные CSS, шрифты и фоны.Избегайте жестко запрограммированных цветов, пока не протестируете обе темы.
Должен ли я зафиксировать экспортированные файлы SVG?
Используйте SVG, когда месту назначения публикации требуется статический ресурс или результат визуализации должен оставаться стабильным.Также сохраните исходный код Mermaid и задокументированный процесс регенерации, чтобы предотвратить смещение двух версий.
Безопасен ли Mermaid для конфиденциальных диаграмм?
Конфиденциальность зависит от редактора и процесса публикации.Предварительный просмотр WordToMD отображает диаграмму в вашем браузере, но публикация Markdown или SVG в репозитории или на сайте соответствует элементам управления доступом этого места назначения.
Заключение
Mermaid делает диаграммы удобными в обслуживании, поскольку источник находится в Markdown.Начните с небольшого огороженного блока, выберите тип диаграммы, соответствующий вопросу, просмотрите синтаксис и протестируйте его в окончательном средстве визуализации.Используйте прозу, чтобы объяснить основной смысл, и экспортируйте SVG, когда пункту назначения требуется статический ресурс.
Попробуйте примеры в Предпросмотр диаграмм Mermaid, отредактируйте сопутствующую документацию в Markdown Редактор, и сохраняйте диаграмму достаточно четкой, чтобы будущий участник мог понять и обновить ее, не перерисовывая всю страницу.