Why MaterialX¶
Since mkdocs-material has entered maintenance mode with no new features planned, and its alternative Zensical remains immature and incompatible with the existing MkDocs plugin ecosystem, this will disrupt the once-thriving ecosystem. For users with stable, fully-featured sites, migrating to Zensical entails high costs and significant stability risks.
So, is there a way to retain the rich ecosystem and stability of mkdocs-material while also gaining the cutting-edge features like Zensical provides?
The answer is MaterialX, which is positioned with the following brand-new vision.
MaterialX Roadmap¶
In my opinion, the beauty of technology lies in enabling more people to effortlessly achieve what was once difficult using the tools you provide.
A great product should strike the perfect balance in feature design, knowing when to stop, instead of overwhelming users with excessive feature options and dazzling configuration items. Let’s be honest, both mkdocs-material and Zensical suffer from over-customization, burdened with overly complex configurations. Who doesn’t end up with hundreds of lines of config? Who hasn’t spent days tinkering with mkdocs-material on their first try?
MaterialX aims to be a zero-fuss solution, allowing users to convert everyday notes and documents into professional websites with minimal setup, facilitating easy sharing and collaboration.
Therefore, MaterialX will adhere to the following goals and principles:
- Goal: Pursue accessibility for everyone. Empowering all users to own their websites, including but not limited to developers, product managers, marketers, and DevOps engineers. Website creation should no longer be exclusive to technical users
- Principle: Extreme ease of use is our top priority. We will simplify configurations and feature sets, provide sensible defaults and automated setup, and minimize the cost of configuration and maintenance for users
- Focus: General-purpose features and visual presentation. Future feature selection will lean more toward general-purpose functionality and visual expression, and we will deliver a wider range of content presentation formats, such as graphs, charts, images, audio and video, to bring your content to life
- Obsession: User experience (UX). We will pay meticulous attention to interactive and visual details, whether it’s an unnoticeable line spacing adjustment or a simple border design ...
Differences from Material¶
| Aspect | mkdocs-material | MaterialX |
|---|---|---|
| Latest Version | mkdocs-material-9.7.1 | mkdocs-materialx-10.x (based on v9.7.1) |
| Current Status | Nearing end-of-maintenance | Active maintenance and updates |
| Feature Updates | None (with legacy bugs) | Bug fixes, new feature additions, UX improvements, etc. See Changelog |
Key Update Highlights of MaterialX
- Added the modern Liquid Glass theme, consistent with Zensical
- Added the next-gen date and author plugin, see documentation: Adding Document Dates and Authors
- Added the recent updates module, see documentation: Adding Recent Updates Module
- Rebuilt the TOC component for mobile devices, enabling seamless NAV and TOC experiences on mobile
- Added indentation guide lines and active link accent colors for TOC; implemented table zebra-striping
- Moved the "back-to-top" button to the bottom, aligning with intuitive proximity-based interaction logic
Differences from Zensical¶
| Aspect | Zensical | MaterialX |
|---|---|---|
| Audience | Technical developers Technical documentation |
All users Markdown notes & documents |
| Direction | Increasingly feature-heavy and complex | Prioritizes extreme ease of use, stays increasingly lightweight |
| Language | Rust | Python |
| Stage | Early-stage | Mature and stable |
| Ecosystem | Non-existent, uncertain future | Rich, open, and vibrant |
Zensical is impressive, but I cannot find a compelling reason to adopt it.