Material for MkDocs je populární framework pro generování statických webových stránek, resp. dokumentace, postavený na MkDocs. Sám ho používám pro tvorbu tohoto webu a s ergonomií i výsledkem jsem velmi spokojen. Překvapilo mě proto zjištění, že tým okolo Material for MkDocs se rozhodl v dalším vývoji nepokračovat a vytvořit zcela nový nástroj nazvaný Zensical. Ze série jejich článků (viz předchozí odkaz) se však zdá, že se jedná o dlouhodobě plánované a odůvodněné rozhodnutí.
Narazili např. na technické limity knihovny pro vyhledávání na straně klienta Lunr.js, která je navíc dlouhodobě nepodporovaná. K tomu se jim nepodařilo najít dostatečně dobrou alternativu, takže se rozhodli postavit vlastní vyhledávací engine. Dále je zmíněno potenciálně pomalé sestavení dokumentace s MkDocs (klidně 8 i 20 minut) v případě rozsáhlých projektů (což se mě naštěstí netýká).
Daleko větším problémem je však situace okolo samotného projektu MkDocs jakožto klíčové závislosti: projekt se stal dlouhodobě neudržovaný, komunikace ohledně jeho správy byla poněkud nejasná a nová verze MkDocs 2 navíc nemá v plánu podporovat pluginy, které jsou pro fungování Material for MkDocs klíčové. Tým tento projekt proto vyhodnotil jako "supply chain risk".
Nakonec se rozhodli od MkDocs oprostit a vytvořit výše zmíněný Zensical. Ten je napsaný z většiny v Rustu, nicméně je dostupný na pypi.org a dá se nainstalovat třeba pomocí uv:
uv init
uv add --dev zensical
uv run zensical
Mimochodem, přepis funkcionality do Rustu následuje aktuální trend, který reprezentují projekty jako Ruff, již zmíněný uv nebo částečně Pydantic.
Těší mě, že by měla být (z většiny) zajištěna zpětná kompatibilita:
Compatibility with Material for MkDocs is our top priority. We understand that switching to a new static site generator can be challenging, especially for large projects with many customizations. Therefore, we've put significant effort into ensuring that Zensical understands mkdocs.yml configuration files, so that you can build your projects with minimal changes.
-- Zensical – A modern static site generator
Více viz detailní Feature Parity
Material for MkDocs by měl dostávat podporu přibližně do listopadu 2026:
We're aware that transitioning takes time, which is why we commit to supporting Material for MkDocs for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed.
-- Zensical – A modern static site generator
Zensical je k dispozici pod permisivní MIT licencí (stejně jako Material for MkDocs). Zajímavou změnou je odklon od sponsorware modelu (kde některé funkce byly jen pro sponsory) k nabídce pro profesionální použití pomocí Zensical Spark.
Vývoj plánuji dále sledovat a rozhodně jim přeju, ať se tenhle model osvědčí.
Update: Zdá se, že v posledních verzích Material for MkDocs je potřeba explicitně přidat přepínač --livereload. K tomu se od verze 9.7.2 začalo vypisovat varování o nekompatibilitě s MkDocs 2, které lze vypnout nastavením proměnné prostředí NO_MKDOCS_2_WARNING=1. Nově tedy pro spuštění vývojového serveru používám příkaz:
NO_MKDOCS_2_WARNING=1 uv run mkdocs serve --livereload
Nekompatibilita s MkDocs 2 je zároveň od verze 9.7.5 explicitně ošetřena:
We released 9.7.5, which limits the version range of MkDocs to <2. This ensures that your builds will continue to work, even if MkDocs 2.0 is released.
-- What MkDocs 2.0 means for your documentation projects
