MD.Scribe 3.5.0: Mermaid 12 и починенный ремонт

Версия 3.5.0 меняет то, что видит читатель: диаграммы переезжают на Mermaid 12.3.0, а авторемонт схемы наконец доходит до страницы. Второе — исправление ошибки, которая жила давно и выглядела как «ремонт сработал, но ничего не изменилось». Основной разбор платформы — в статье MD Viewer: просмотрщик Markdown без браузерного движка; здесь про то, что принесла MD.Scribe 3.5.0, чем это проверено и что смотреть после обновления.

TL;DR: три вещи, которые надо знать

1. Mermaid 11.17.2 → 12.3.0. Новые возможности доступны в обычном блоке кода, без плагинов.
2. Вид закреплён. look: 'classic' и layout: 'dagre' оставлены, чтобы существующие схемы не перерисовались сами.
3. Ремонт диаграмм доходит до страницы. Раньше загрузчик читал атрибут с исходником автора и выбрасывал исправленный текст.
4. Бандл вырос. 5 537 838 байт против 3,5 МБ в 11.17.2; в gzip — 1 587 992 байта.
5. Проверка. Открыть страницу с диаграммой и убедиться, что она отрисована, а кнопка копирования отдаёт исходник автора.

Что нового

flowchart TB
  MD["Markdown с блоком кода mermaid"] --> NORM["сервер: нормализатор"]
  NORM --> PRE["pre: исправленный исходник"]
  NORM --> ATTR["атрибут data-mermaid-source"]
  PRE --> JS["клиент: mermaid 12.3.0"]
  ATTR --> COPY["кнопка копирования: исходник автора"]

Про новое умолчание стоит сказать отдельно, потому что это решение автора, а не мелочь. Mermaid 12 по умолчанию рисует блок-схемы темой redux-color, видом neo и раскладкой ELK. Если принять эти умолчания, все существующие диаграммы у всех пользователей перерисуются без спроса. В 3.5.0 оставлены look: 'classic' и layout: 'dagre' — новые возможности есть, а картинка не поехала.

Правда, побочный эффект тоже честно назван: раскладка dagre из новой версии даёт более широкие отступы. В заметках приведён замер на одном и том же документе: геометрия sequence-диаграммы совпала точно (-50 -10 514 451 в обеих версиях), а блок-схема стала шире — 0 0 624.66 140 превратилось в 0 0 837.88 140 при той же высоте.

Ключевые изменения

flowchart TD
  M12["Mermaid 12.3.0"] --> LOOK["look: classic"]
  M12 --> LAY["layout: dagre"]
  LOOK --> SAME["прежний вид диаграмм"]
  LAY --> SAME
  SAME --> NOTE["снять два ключа = включить новые умолчания"]

Ремонт диаграмм

Самое важное исправление релиза. Механика была такая: сервер чинит схему и пишет исправленный текст в тело блока, а исходник автора кладёт в атрибут data-mermaid-source для кнопки копирования. Загрузчик на клиенте читал атрибут — то есть исходник автора — и выбрасывал всю работу по ремонту. Снаружи это выглядело так: бейдж сообщает «схема исправлена», а Mermaid всё равно отклоняет исходник.

Ошибка была воспроизведена и на 11.17.2, значит появилась не в этой версии. Теперь клиент читает исправленный текст, а атрибут остаётся только для копирования. Пример из заметок: метка узла с круглыми скобками без кавычек теперь рисуется с применённым исправлением.

Иконки

Второе исправление — про сборку. Два генератора писали один и тот же файл src/View/Icons.php, но только один добавлял запись circle-alert, на которую опирается Icons::svg() как на запасной вариант. В результате любой запрос иконки вне icons.json давал Undefined array key и пустой <svg>. Теперь правило применяется в обоих генераторах, а тест падает, если запасного варианта нет.

Установка и обновление

# из архива релиза
unzip MD.Scribe-3.5.0.zip -d /srv/docs
chmod -R u+w /srv/docs/storage
# docroot: /srv/docs/public

# или из клона
git clone https://github.com/paulmann/MD.Scribe.git /srv/docs
cd /srv/docs && composer install --no-dev --optimize-autoloader

Обновление с 3.1.0 на 3.5.0 — замена файлов с сохранением контента; структура каталогов та же.

Проверка после обновления

flowchart LR
  OLD["3.1.0 и новее"] --> ZIP["архив релиза 4,2 МБ"]
  ZIP --> PHP["проверка PHP 8.5 и расширений"]
  PHP --> MIG["миграции и манифест"]
  MIG --> CHECK["проверка: страница с диаграммой"]

Замеры и цифры

Проверено 14.11.2026, двумя проверками.

Из этих чисел два вывода. Первый: рост бандла реален — 5,5 МБ сырого текста против примерно 3,5 МБ у 11.17.2, и в gzip это 1,59 МБ. Заметки обещают, что скрипт подключается только на страницах с диаграммой; проверить это на демо-контенте не удалось — в нём самом есть схемы, поэтому бандл присутствует и на главной, и на странице документации.

Второй: атрибут data-mermaid-source в отдаваемом HTML есть, то есть контракт, на котором держится кнопка копирования, сохранился. Это и есть та часть, которую сломало исправление, — теперь роли разделены: тело блока для отрисовки, атрибут для копирования.

Совместимость

Главное изменение совместимости — минимум PHP поднялся до 8.5. Если сервер работает на 8.3 или 8.4, обновление не запустится; проверять это надо до замены файлов, а не после.

Подводные камни

• PHP 8.5 — жёсткое требование. На 8.4 приложение не стартует; проверяйте до обновления.
• Вид диаграмм зависит от двух ключей. Снять look и layout — значит принять новые умолчания Mermaid 12 и перерисовать всё.
• Блок-схемы станут шире. Раскладка dagre из 12-й версии добавляет отступы: та же диаграмма займёт больше места по ширине.
• Бандл вырос на 2 МБ. На медленном канале первая загрузка страницы с диаграммой заметно тяжелее.
• Кэш браузера может отдать старый бандл. После обновления проверяйте с очисткой кэша, иначе увидите старую версию движка.
• Кнопка копирования — не то же, что отрисовка. Копируется исходник автора, включая ошибки; это задумано, но удивляет.
• Авторемонт не гарантирует корректность. Он чинит типовые случаи вроде незакавыченных скобок, но не угадывает замысел.
• Тесты иконок — про сборку, а не про рантайм. Ошибка возникала при пересборке вендора, а не при обычной работе.
• Демо-контент содержит диаграммы. Проверить «подключается ли скрипт только там, где нужно» на нём нельзя.
• Манифест надо смотреть после обновления. Если версия в манифесте не 3.5.0, файлы заменились не полностью.

FAQ

Итог

MD.Scribe 3.5.0 — релиз про диаграммы: движок обновлён до Mermaid 12.3.0, но вид закреплён, чтобы чужие схемы не перерисовались без спроса, а главное — исправлена ошибка, из-за которой авторемонт схемы не доходил до страницы. Замеры подтверждают цифры релиза: архив 4 199 751 байт, 1 011 файлов, манифест 3.5.0 с минимумом PHP 8.5, бандл 5 537 838 байт и 1 587 992 в gzip, версия 12.3.0 внутри. Границы тоже названы: без PHP 8.5 не обновиться, диаграммы станут шире, а проверять условную загрузку надо на своих страницах.

Цитата: Обновление движка диаграмм хорошо тогда, когда читатель не замечает разницы, — и плохо, когда замечает без предупреждения.

Связанные материалы

• MD Viewer: просмотрщик Markdown без браузерного движка — основной разбор платформы.
• MD.Scribe 3.1.0: переименование и починка обновлятора — предыдущий разбор релиза и история смены имени.
• github-wiki-llm-writer: вики репозитория с проверкой фактов — документация с проверкой утверждений.
• ctf-collect-to-file: весь код в один документ — сборка контекста для модели из дерева файлов.
• Релиз v3.5.0 — заметки и архив.

LLM Summary

• Тема: MD.Scribe 3.5.0 — обновление движка диаграмм и исправление авторемонта схем.
• Mermaid: 11.17.2 → 12.3.0; новые возможности доступны в обычном блоке кода: идентификаторы рёбер с анимацией, пошаговая анимация (step, stepDuration, stepNumbers), маркеры ---o и ---x, семейство фигур @{ shape: … }.
• Закрепление вида: look: 'classic' и layout: 'dagre' — чтобы не включать умолчания Mermaid 12 (тема redux-color, вид neo, раскладка ELK). Замер на одном документе: sequence-диаграмма совпала точно, блок-схема стала шире (0 0 624.66 140 → 0 0 837.88 140).
• Исправление ремонта: сервер писал исправленный исходник в тело блока, а исходник автора — в data-mermaid-source; загрузчик читал атрибут и выбрасывал ремонт. Ошибка воспроизводилась и на 11.17.2.
• Исправление иконок: два генератора писали src/View/Icons.php, только один добавлял запись circle-alert, на которую опирается запасной путь Icons::svg().
• Проверено 14.11.2026: архив MD.Scribe-3.5.0.zip — 4 199 751 байт, SHA-256 4aa257dfa4a4ae130ee0d9d2924420bfb7d4c3191cc44c006a6031c2f66ccdf7, 1 011 файлов; манифест — MD.Scribe 3.5.0, php_min 8.5.0, 979 файлов.
• Бандл: public/assets/vendor/mermaid/mermaid.min.js — 5 537 838 байт, в gzip 1 587 992 байта, внутри версия 12.3.0.
• Прогон: PHP 8.5.4, главная — 200, страница документации — 200, data-mermaid-source в HTML присутствует.
• Границы: минимум PHP поднят до 8.5; диаграммы шире; условную загрузку бандла на демо-контенте проверить нельзя — там есть схемы.
• Ссылки: https://github.com/paulmann/MD.Scribe, https://sysadministrator.ru/md-viewer/

Промт для агента (установка и настройка)

Готовый промт: скопируйте блок целиком. Источник шагов — AGENTS.md и README.md репозитория (оба файла входят в архив 3.5.0), сверено с прогоном на PHP 8.5.4.

Задача: обновить MD.Scribe до 3.5.0 и убедиться, что диаграммы рисуются, а вид существующих схем не поехал.

Материалы:
- репозиторий: https://github.com/paulmann/MD.Scribe
- AGENTS.md: https://github.com/paulmann/MD.Scribe/blob/main/AGENTS.md
- README: https://github.com/paulmann/MD.Scribe/blob/main/README.md
- релиз: https://github.com/paulmann/MD.Scribe/releases/tag/v3.5.0

Шаг 1. Проверить PHP: требуется 8.5 (в манифесте php_min 8.5.0), расширения mbstring, dom, libxml, json; для обновлятора и бэкапов — curl, phar, zip.
Шаг 2. Сохранить content/ и storage/, сделать бэкап каталога и базы (если используется).
Шаг 3. Распаковать MD.Scribe-3.5.0.zip, заменить файлы, вернуть content/ и storage/.
Шаг 4. Проверить манифест: version 3.5.0, php_min 8.5.0.
Шаг 5. Открыть главную — ожидается 200; открыть страницу с диаграммой — схема отрисована.
Шаг 6. Проверить кнопку копирования: должен копироваться исходник автора из data-mermaid-source.
Шаг 7. Проверить диаграмму с намеренной ошибкой (например, скобки в метке без кавычек): должен появиться бейдж ремонта и отрисованная схема.
Шаг 8. Открыть страницу без диаграмм в чистом кэше браузера и убедиться, что бандл mermaid не загружается.
Шаг 9. Сравнить геометрию двух-трёх ключевых схем с прежними скриншотами: ширина может вырасти из-за раскладки dagre.
Шаг 10. Решить, оставлять ли look: classic и layout: dagre; снятие этих ключей включает умолчания Mermaid 12.

Запрещено:
- обновляться на PHP ниже 8.5;
- убирать look и layout «для современности», не проверив все схемы;
- править бандл вручную: он собирается из vendor;
- считать, что авторемонт гарантирует корректную диаграмму;
- проверять после обновления с прогретым кэшем браузера;
- публиковать архив без сверки контрольной суммы.

Что считать успехом: манифест показывает 3.5.0 и php_min 8.5.0, главная и страница документации отдают 200, диаграммы рисуются, ремонт виден на странице, копирование отдаёт исходник автора, вид существующих схем сверен со скриншотами.