Сейчас при сборке проектов на MkDocs Material выскакивает страшное предупреждение:
⚠️ Warning from the Material for MkDocs team
MkDocs 2.0, the underlying framework of Material for MkDocs, will introduce backward-incompatible changes, including:
× All plugins will stop working – the plugin system has been removed
× All theme overrides will break – the theming system has been rewritten
× No migration path exists – existing projects cannot be upgraded
× Closed contribution model – community members can't report bugs
× Currently unlicensed – unsuitable for production use
А дело в том, что движок MkDocs, на котором работает MkDocs Material, уже пару лет не обновлялся, а его создатели анонсировали новую версию MkDocs 2.0, которая работает на другом топливе и принципиально несовместима с MkDocs Material.
В связи с этим разработчики MkDocs Material решили замутить новый генератор статических сайтов с блэк-джеком и поддержкой функций MkDocs Material.
Так в этой истории появился Zensical — независимый от сторонних движков инструмент для создания документационных проектов. Он должен вобрать в себя всё лучшее, что было в MkDocs Material, и стать полноценной ему заменой.
Сам MkDocs Material никуда не пропадёт, но его поддержку прекратят в ноябре 2026 года.
Авторы Zensical понимают, как дорог MkDocs Material пользователям, поэтому очень стараются сделать полностью совместимый продукт.
Я, как активный пользователь MkDocs Material, решил протестировать Zensical, чтобы запланировать миграцию своих проектов.
Ну что ж...
Zensical, как любой молодой продукт, далёк от совершенства. Многое пилится и ещё будет пилиться, но это ожидаемо и не страшно.
Но есть одна большая проблема, которая делает работу старых проектов в Zensical почти невозможной.
MkDocs Material был любим пользователями по многим причинам. Одна из них — огромная библиотека родных и кастомных плагинов, значительно расширяющих функциональность создаваемых док.систем. Плагины подключались как сторонние расширения.
Авторы решили не поддерживать в Zensical старые плагины от MkDocs. Вместо этого они часть плагинов хотят положить в коробку и превратить в базовые функции продукта, а остальное собираются реализовать с помощью новой модульной системы, позволяющей подключать к проекту сторонние модули с дополнительными фичами. На сайте Zensical даже есть план, функциональность каких старых плагинов будут адаптировать в первую и вторую очередь.
Но увы, ничего из этого ещё не сделано, сроки реализации не указаны, а большое количество сторонних кастомных плагинов не попали ни в первую, ни во вторую очередь адаптации.
В таких условиях я не могу перевезти ни один из своих рабочих или домашних проектов на новую платформу.
Выводы
Что же делать? Ведь впереди нас ждёт апокалипсис с появлением нового движка MkDocs 2.0, который сломает все наши док.системы!
Я честно пытался найти подробную информацию о релизе MkDocs 2.0, но не нашёл. Если коротко, там всё очень сложно. Вполне вероятно, что релиз всё-таки состоится и MkDocs 2.0 реально сломает наши проекты, но!
1. Никто не мешает нам пользоваться старой рабочей версией MkDocs (можно прописать в пайплайне сборки установку стабильной версии MkDocs<2.0; в пакете MkDocs Material это ограничение вроде уже прописано)
2. Существует несколько альтернативных форков MkDocs (например, проект со звучным названием ProperDocs) которые будут продолжать развивать классическое mkdocs-сообщество. Есть тот же самый Zensical, который в своё время дорастёт до полноценного рабочего состояния.
Что же решил я? Я решил продолжить пользоваться MkDocs Material, не обновлять MkDocs до версии 2.0 и ждать, когда в Zensical реализуют модульную систему и добавят все необходимые мне функции.
В общем, конец света откладывается, живём и радуемся нашим прекрасным док.проектам на Material for MkDocs!
#практика #docsascode