使用 Zensical 替代 Mkdocs

本文文本由人类撰写，部分资料由 AI 收集。

在很长一段时间里，Material for Mkdocs 是在文档领域的优选框架。有很多技术文档使用这个框架进行编写，比如 FastAPI、hummingbot。

但是，在2025年11月，Material 主题的作者宣布将该主题变为维护模式，即提供关键漏洞和安全更新，不再添加新功能，并将中心转移到一个名为 Zensical 的框架里。他们建议用户在 Zensical 框架能提供所需功能之后迁移到 Zensical 上。

0 Mkdocs 介绍

先给对 Mkdocs 还没那么熟悉的同学介绍一下它。

0.1 Mkdocs 是什么

用专业一点的定义，Mkdocs 是一个静态站点生成器。通俗一点说，Mkdocs 可以把我们写的 Markdown 文档变成网页，便于查看，可以在 Github Pages 之类的托管服务里或者自己的服务器上部署。

0.2 它和其他同类产品有什么区别

使用静态站点生成技术把 Markdown 文件变成网页的产品主要面向两类应用：博客和文档，Mkdocs 属于后者。博客主要按时间线排布，而文档则有一个比较严密的组织逻辑。

在文档生成器里，Mkdocs 和 VitePress 属于两个用得比较多的框架。VitePress 在 Node.js 上运行，基于 Vite，可以嵌入 Vue 组件。而 Mkdocs 在 Python 上运行，主要在 Markdown 上做扩展。

0.3 Material for Mkdocs 和 Mkdocs 是什么关系

简单来讲，Material for Mkdocs 是一个基于 Mkdocs 的一个文档框架。它的底层是 Mkdocs，但是它扩展了很多功能，比如搜索、提示、代码块的优化，以及标签页、图表、图标的支持等。

可以简单把 Material 理解为一个主题，但是它其实已经不止是一个主题了。

1 为什么要选择 Zensical

访问Mkdocs的仓库，我们不难发现，从 2024 年 8 月以来，Mkdocs 的维护者就没有发布过新的 release 了。而在对应的时间点之后，仓库中也只有5条提交记录。截至发稿时，仓库中已经有 117 条未关闭的 issue 和 65 条未合并的 Pull Requests 了。用 Material 团队的话说，这应该被视为供应链风险。其中一些问题已经影响到了终端用户，比如 Mkdocs 的依赖库更新之后，使用 mkdocs serve 命令进行预览时，更新文件无法触发自动刷新。

在 2025 年 10 月，Mkdocs 的最初作者创建了 Mkdocs 2.0 的仓库，并在 2026 年 1 月发布了预览版。根据 Material 团队的测试和解读，Mkdocs 2.0 将引入一些破坏性变更，导致 Material 框架无法继续适配它。同时，Mkdocs 2.0 对于社区成员的贡献不是非常开放，这和 Material 团队的价值观不符。因此，Material 团队决定开发一个新的底层框架，名为 Zensical。

Zensical 的目标是完全兼容 Material for Mkdocs。同时它也引入了一些新特性，比如在兼容yaml配置文件的同时，使用toml而不是yaml作为新项目的推荐方案。Zensical 项目的愿景是：Adaptive systems for evolving ideas – Zensical creates scalable Open Source systems for technical writing that always keep you in the flow.。

2 如何使用 Zensical

对于使用过 Material for Mkdocs 的同学来说，Zensical 使用起来很简单，基本上只需要把命令里面的 mkdocs 变成 zensical 就行了。

2.1 安装

Zensical 作者建议使用 Python 虚拟环境进行安装。

如果你没有安装其他环境管理软件，可以使用 Python 自带的 Venv 工具，在想建立项目的文件夹里输入以下命令：

python -m venv .venv  
.venv\Scripts\activate
pip install zensical

如果你使用 uv，则可以用它进行环境管理。（已经完成上面那步的话就不需要完成这一步了）关于 uv 的使用可以看看这篇文章

uv init
uv add --dev zensical
uv run zensical

之后，在文件夹里输入

zensical new .

或者是

uv run zensical new .

就会在当前文件夹下创建需要的文件。

2.2 目录结构

.
├─ .github/workflows
│  └─ docs.yml
├─ docs/
│  ├─ index.md
│  └─ markdown.md
└─ zensical.toml

这是最初的目录结构。.github/ 目录下放置的是 Github Action 用到的文件，将代码上传至 Github 之后可以直接生成 Github Pages。docs/ 目录下存放的就是我们自己写的 Markdown 文件，Zensical 提供了 index 和 markdown 两个示例，如不需要可以直接删去。zensical.toml 是整个项目的配置文件，具体可参考 Setup 和 Authoring 两个页面。

2.3 撰写文章

要往站点里添加内容非常简单，只需要在 docs/ 文件夹里新建一个 .md 后缀的文件即可。如果文章比较多，也可以在这里新建文件夹以更清晰地组织页面。

2.4 导航

正如前面所说，Zensical 适合手册/文档类的内容。默认情况下，它会根据 doc/ 文件夹下文件的排列方式建立导航，让文章在侧栏中显示。

如果想更好地控制导航结构，可以通过 zensical.toml 设置显式导航。比如模板里的两个文章索引可以写为：

[project]
nav = [
  "index.md",
  "about.md"
]

同时，显式导航支持更改文章在侧栏中的标题，比如：

[project]
nav = [
  {"Home" = "index.md"},
  {"About" = "about.md"}
]

2.5 预览

在发布站点之前，我们可以启用一个本地服务器进行预览。在项目的虚拟环境中执行：

zensical serve

之后，我们就可以在输出的地址（默认是 http://localhost:8000）进行预览。

2.6 发布

模板中已经写好了 Github Actions 所需的文件，可以直接在 Github 上新建一个仓库，将代码上传，之后在仓库的设置里将 Pages 的 Source 改成 Github Actions 即可。

如果需要手动部署，可以运行

zensical build

Zensical 将会在项目设置中的 site_dir 路径下生成对应的网页文件，将文件复制到 Web 服务器对应目录下即可。

3 将原有的 Mkdocs 站点迁移至 Zensical

3.1 Zensical 的兼容性

Zensical 团队在 Feature parity 页面详细地写了当前 Zensical 与 Material for Mkdocs 的功能一致性。可以看到，当前 Zensical 已经实现了 Material for Mkdocs 支持的绝大多数功能。

3.2 如何迁移

lz没有尝试过迁移。二者的文件目录结构兼容，理论上只要在原目录下直接按照本文 2.1 中的说明进行安装即可。

3.3 一些顾虑

Zensical 团队在 faqs 页面中进行了一些解答。这里做一些搬运。

3.3.1 在什么时候可以从 Material for Mkdocs 迁移到 Zensical 呢

当 Zensical 已经完成对你站点用到的功能的支持后，你就可以迁移到 Zensical 了。

Zensical 团队列出了命令行选项、模板、第三方插件等的支持或修改情况，可以前往对应 faq 页面查看。

3.3.2 是否应该将 mkdocs.yml 转换成 zensical.toml

Zensical 团队不建议将已有的 mkdocs.yml 转换成 zensical.toml。如果今后需要更改格式，Zensical 团队承诺会提供转换工具。

3.3.3 会对 mkdocs.yml 支持多长时间

无限期。Zensical 团队计划今后将对 Mkdocs 的兼容功能放到一个专门的兼容包中，用户可以自行选择是否使用。

3.4 Zensical Spark 相关

Zensical 为商业团队提供了名为 Zensical Spark 的付费订阅项目。订阅后可以抢先体验新功能、提供迁移支持和直接联系 Zensical 团队。但是他们承诺，Zensical 项目本身是开源项目，可以免费且自由地使用。Zensical Spark 使他们能够保持对 Zensical 的开发进度。

4 收个尾

感谢你的阅读，看到这里的人应该不是很多（笑）。写技术类的文章算是我的一点点小爱好。欢迎一起讨论呀。