Диаграммы

Mermaid

Mermaid-диаграммы лежат в папке mermaid/, а результат сборки сохраняется в figures/.

В Zensical можно вставлять Mermaid напрямую в Markdown через кодовый блок mermaid. Такая диаграмма рендерится в браузере и автоматически подстраивается под светлую или темную тему:

flowchart LR
    MMD["mermaid/*.mmd"] --> SCRIPT["compile-mermaid"]
    SCRIPT --> FIGURES["figures/*.pdf"]
    FIGURES --> LATEX["LaTeX-документ"]
    MMD -. native preview .-> ZENSICAL["Zensical-документация"]

Жизненный цикл диаграмм в проекте:

flowchart TD
    EDIT["Редактирование<br/>mermaid/*.mmd"] --> LOCAL{"Где собрать?"}
    LOCAL -->|"локально"| CLI["task mermaid"]
    LOCAL -->|"Docker"| DOCKER["task mermaid:docker"]
    CLI --> OUT["figures/*.pdf"]
    DOCKER --> OUT
    OUT --> TEX["LaTeX-документ"]
    EDIT --> DOCS["Markdown-превью<br/>в Zensical"]

Для итогового PDF диплома по-прежнему нужны сгенерированные файлы из figures/, потому что LaTeX подключает готовые изображения.

Просмотр .mmd на GitHub

GitHub не всегда показывает содержимое файлов Mermaid с расширением .mmd как обычный текстовый код.¹ Если вместо исходника отображается предпросмотр или файл не открывается удобным образом, нажмите View raw на странице файла. Так GitHub откроет исходный .mmd-код диаграммы без обработки.

Ручная сборка Mermaid

Чтобы пересобрать диаграмму в PDF:

1. Отредактируйте нужную диаграмму в mermaid/*.mmd.
2. Установите mmdc: https://github.com/mermaid-js/mermaid-cli
3. Пересоберите диаграмму:

mmdc -i <file.mmd> -o <file.pdf> -f

Флаг -f нужен, чтобы mmdc перезаписывал уже существующий PDF. В проектной автоматической сборке поля дополнительно обрезаются через pdfcrop, поэтому для локального запуска нужны pdfcrop и Ghostscript.

Автоматическая сборка Mermaid

Запустите скрипт:

task mermaid

uvx --from git+https://github.com/ethercod3/compile_mermaid.git compile-mermaid

Скрипт прогоняет файлы из mermaid/, кладет результат в figures/ и после генерации обрезает поля через pdfcrop. По умолчанию пересобираются только диаграммы, у которых исходный .mmd новее соответствующего PDF или PDF еще не создан. Чтобы принудительно пересобрать все Mermaid-диаграммы, используйте --force.

Если pdfcrop или Ghostscript не установлены, можно временно отключить обрезку:

task mermaid -- --no-crop

Mermaid через Docker

Сборка Mermaid через Docker:

task mermaid:docker

docker compose --profile mermaid run --build --rm mermaid_diagrams

Docker-образ Mermaid включает Chromium, Mermaid CLI, pdfcrop и Ghostscript, поэтому обычная команда собирает уже обрезанные PDF.

Python-диаграммы

Python-диаграммы лежат в папке python_diagrams/.

Ручная сборка:

1. Установите Python. В проекте использовалась версия 3.13+.
2. Установите зависимости:

task deps

uv sync

1. Запустите генерацию:

task diagrams

uv run python scripts/compile_python_diagrams.py

Сборка через Docker:

task diagrams:docker

docker compose --profile python up