Future of MkDocs

[Blacksmoke16]

https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/

So as recently announced, Material for MkDocs announced their own new modern static site generator Zensical, in which they also announced the deprecation of the current material project that this repo is currently using. I wanted to create this as a more formal location to discuss what we want to do about it.

Of which, we have a few options:

1. Stay on MkDocs for the time being - simple, nothing to do, but the project is essentially on maintenance mode
2. Migrate to Zensical - might just work out of the box, but likely not due to our plugin usage
3. Migrate to some other static site generator - larger effort, but probably doable

[straight-shoota]

For the time being, MkDocs material should be fine. But eventually migrating to Zensical sounds like a reasonable progression.
It still seems a bit fresh, hasn't reached feature parity yet. So we might want to hold off a bit.
I suppose it wouldn't hurt to start evaluating the capabilities and figure out if our setup requires bigger changes.

[crysbot]

This issue has been mentioned on Crystal Forum. There might be relevant details there:

https://forum.crystal-lang.org/t/zensical-a-modern-static-site-generator-built-by-the-material-for-mkdocs-team/8534/5

[Blacksmoke16]

Yea I don't think it's anything we have to rush into. Will likely be at least a year before Zensical is more fleshed out, and Material also has a 1 years support window.

The biggest gotcha is going to be plugins. Based on what I read they're planning to support some of the built-in MkDocs plugins, and select third-party ones. However ones like code-validator will probably need ported into their new module system that won't be released until early next year. Then at some point would also need to migrate to their toml configuration file.

But yea, I'm cool just sitting on this until next year sometime and can go from there. Just at least wanted to have a tracking ticket for it.

[straight-shoota]

Yeah but code-validator is actually not necessary for building the site (I think?). It's a linting plugin. It doesn't even need to be part of the site generator.
It could just be an external tool. And that would even be more useful because it is a universal feature that works for any Markdown content, not specific to mkdocs.