跳转至

下一代主题插件 MaterialX

MaterialX for MkDocs，下一代 mkdocs-material，让你继续用熟悉的方式构建漂亮站点。基于 mkdocs-material-9.7.1 衍生，取名为 X，提供持续的维护与更新。

为什么选择 MaterialX ?

由于 MkDocs 原作者的个人问题，MkDocs 项目即将走向尽头。他已停止更新 MkDocs，并打算发布一个全新的 2.0 版本作为替代。可是，这个新版本与现有生态系统完全不兼容，它是一个完全独立的项目，只是沿用了 MkDocs 这个名称，一旦你不小心升级了，将导致毁灭性的破坏。

所以，为了摆脱对 MkDocs 的依赖，原流行主题框架 mkdocs-material 团队停止了对 mkdocs-material 的维护，转而去开发了一个全新的同类项目 Zensical，优点是现代架构，缺点是不兼容原来的 MkDocs 生态（无插件），有着较高的迁移成本（所有配置项都需要从头重建），且目前很多基础功能还不完善。

为了让原有的 MkDocs 生态和项目持续且稳定的运行下去，MkDocs 有了新的社区继任者 ProperDocs (基于 MkDocs 1.6.1)，会提供持续的更新维护且无缝兼容原来的 MkDocs 生态。

同样 mkdocs-material 也迎来了新的继任者 MaterialX (基于 mkdocs-material 9.7.1)，也会提供持续的更新维护，且无缝兼容原有的生态，零迁移成本。

MaterialX 既维持了 mkdocs-material 项目的 丰富功能 和 稳定性，又拥有了 新特性 和 兼容性，并将拥有以下全新愿景和定位。

MaterialX 路线图

MaterialX 旨在成为 极简易用傻瓜式 的静态站点生成器，用户只需要简单且少量的配置，就能轻松把平时的笔记和文档转成专业站点，方便传播分享与交流。

为什么强调极简易用 ?

在我看来，技术的魅力在于让更多的人利用你提供的工具轻而易举就实现了他原来很难做到的事。

一个好的产品，在功能设计上，应该是恰到好处，适可而止，而不是提供更多的功能选择和眼花缭乱的配置项。说实话，无论是 mkdocs-material 还是 Zensical，都有点个性化过度了，配置项太多太复杂了，谁的配置项最后不是动辄几百行？哪个初次用 mkdocs-material 的人没折腾上好几天？

所以，MaterialX 将遵循以下目标和原则：

  • 目标：追求人人可用，人人都可拥有自己的网站，包括但不限于开发者、产品经理、运营人员、运维人员等，不再是技术人员的专利
  • 原则：以极简易用为首要原则，化繁为简，未来会简化配置和功能项，提供更合理的默认配置和自动化配置，减少用户的配置和使用成本
  • 侧重：通用型功能和可视化呈现，未来在功能选择上会更多偏向通用型和可视化表达型功能，将为大家提供更丰富的内容呈现形式，如图形、图表、图像、音视频等，让内容动起来
  • 偏执：用户体验，会更注重交互细节和视觉细节，会花很多时间去关注这些，可能是一个毫不起眼的行间距，也可能是一根简单的线条 ...

差异

与 mkdocs-material

差异 mkdocs-material MaterialX
最后版本 mkdocs-material-9.7.1 mkdocs-materialx-10.x
(基于 mkdocs-material-9.7.1 衍生)
使用方式 mkdocs.yml + 主题名 material mkdocs.yml + 新主题名 materialx
其他一切都和使用 material 时一样
当前状态 停止了更新 持续维护与更新
功能更新 无（有遗留 bug） bug 修复、新功能添加、用户体验优化等
具体见 Changelog

与 Zensical

差异 Zensical MaterialX
功能定位 技术开发者、技术文档 任何 Markdown 用户、Markdown 笔记及文档
开发语言 Rust + Python Python
发展阶段 诞生几个月，初期，bug多，基础功能不完善 诞生超十年，成熟稳定，功能丰富完善
使用方式 采用 TOML 全新配置格式
所有配置项需用新格式从头再来一遍		 延用 YAML 格式
0 迁移成本
生态环境 完全从 0 构建的新工具
不兼容原 MkDocs 周边与生态		 基于 mkdocs-material-9.7.1 构建
无缝兼容原技术生态
扩展延展 底层不支持，不够开放，无插件 开源开放，插件丰富
侧重方向 以个性化和多样性为出发点，易引起配置堆积，使用将越来越复杂 以极简易用为首要原则，将提供更合理的自动化配置以减少使用成本，将会越来越轻量化

MaterialX 更新要点

  • 新增了下一代日期作者插件，参见：document-dates-zh
    • 它比 git-revision-date-localized 和 git-authors 快 20-500 倍，并可在任何环境（无 Git、Git 环境、Docker、所有 CI/CD 构建系统等）下运行
    • 彻底解决了基于日期时间的基建问题，让项目有了自动化日期的能力，再也无需为任何功能手动设置日期，包括：页面日期展示、blog 日期展示、blog 日期分类、blog 列表排序、sitemap.xml (lastmod - SEO 增强)、RSS feed、最近更新模块、搜索排序等
  • 添加了最新更新模块，参见：recently-updated-zh
    • 按更新时间倒序展示最近更新的文档，列表项动态更新
    • 提供了丰富的页面展示形态 (列表、详情、网格)
    • 智能提取文档摘要 (无需手动设置)
    • 智能预估阅读时长，支持所有语言（中日韩 & 空格分隔型语言）
  • 重构了移动端 TOC 组件，在移动设备上实现无缝 NAV 和 TOC 体验 (Zensical 在移动端无 TOC 功能)
  • 完美修复了在移动设备上当侧边栏抽屉处于激活时，轻扫会穿透抽屉的历史遗留 bug (很影响用户体验，容易引起误操作，Zensical & Material 未能修复)
  • 大幅改进了在移动端的使用体验和细节
    • 将 "返回顶部" 容器移至底部，更符合就近操作的交互逻辑
    • 优化了 "返回顶部" 容器的显示与隐藏的灵敏度
    • 为 TOC 添加了缩进引导线和活动链接强调色
  • 添加了 Liquid Glass 现代主题，允许在 Liquid Glass 主题中设置顶栏背景颜色，以支持不同配色方案的背景，参见 Topbar style
  • 更多见 Changelog


快速开始

安装:

pip install mkdocs-materialx

配置 materialx 主题到 mkdocs.yml:

theme:
  name: materialx

注意：主题名字是 materialx，不是 material，其他一切都和使用 material 时一样

使用以下命令启动实时预览，自动开启和自动热重载：

mkdocs serve --livereload -o

properdocs serve -o

更新日志

Changelog


Chat Group

Discord: https://discord.gg/cvTfge4AUy

Wechat: