Skip to content

Zensical – 由 Material for MkDocs 团队构建的现代静态网站生成器

我们非常高兴地宣布 Zensical，这是我们下一代静态网站生成器，旨在简化构建文档网站的过程。经过十年的经验提炼，Zensical 是我们克服 MkDocs 技术限制的努力，远远超出了其能力。

Zensical 是数千小时工作的结果——从零开始构建，旨在提供现代和舒适的创作体验，同时使开发人员能够通过即将推出的模块系统轻松扩展和自定义 Zensical。我们的目标是支持数万页的文档即代码工作流程，而不妥协性能或可用性。

为了使过渡无缝，兼容性 是第一位的。我们投入了大量精力，确保所有用户能够顺利迁移到 Material for MkDocs。Zensical 可以原生读取 mkdocs.yml，允许您以最小的更改构建现有项目。到目前为止，支持一部分插件，我们正在努力在未来几个月内实现功能平衡。

Zensical 完全开源，采用 MIT 许可证，可以用于任何目的，包括商业用途。我们也告别了赞助软件模型，取而代之的是我们为专业用户提供的新产品：Zensical Spark。这使我们能够保持独立，最大化用户价值，因为我们与您共同塑造 Zensical 的未来。

您可以订阅 我们的新闻通讯 以保持最新信息。

这是四部分系列的第二篇文章：

  1. 转变 Material for MkDocs
  2. Zensical – 由 Material for MkDocs 创作者构建的现代静态网站生成器
  3. Material for MkDocs Insiders – 现在对所有人免费
  4. 再见，GitHub 讨论

为什么选择 Zensical？

自 2016 年首次发布以来，Material for MkDocs 已帮助成千上万的团队发布和维护可靠的文档。然而，近年来，显然我们遇到了核心依赖项 MkDocs 的限制。这些限制由于深植于其架构中而无法克服。

我们在 关于我们基础工作更新 中也提到，MkDocs 必须被视为供应链风险，因为自 2024 年 8 月以来它未得到维护。它在一年多的时间里没有发布任何版本，并且正在积累未解决的问题和拉取请求。这些发展迫使我们切断与 MkDocs 的依赖关系。

为了规划前进的道路，我们回到绘图板，和数十位专业用户交谈，并彻底分析了 MkDocs 生态系统。我们不仅想创建一个 MkDocs 的分支或移植，而是决定从第一原则重新思考静态网站生成。

通过 Zensical，我们正在创建一个现代静态网站生成器，它与您的内容和自定义兼容，并解决 MkDocs 的限制。虽然 Material for MkDocs 是建立在 MkDocs 之上的，Zensical 将这两个项目整合为一个一致的栈，涵盖静态网站生成、主题和自定义。您今天可以期待：

尽管我们尚未达到完全的功能平衡，但您已经可以使用 Zensical 以最小的更改构建现有的 Material for MkDocs 项目。

您可以跳转到 兼容性 部分了解已经支持的内容。

您可以期待什么

坚实的基础

我们在 Zensical 的目标是创建一个一致且现代的栈，垂直整合创作体验（AX）、开发者体验（DX）和用户体验（UX）的所有部分。这使我们在过度依赖第三方框架和依赖的解决方案中拥有显著的竞争优势，帮助我们创建更强大的开源软件。

ZRX，我们新的差异构建引擎，为 Zensical 创建了坚实的基础，并且是一个独立的开源项目。它为构建差异数据流提供了一种新颖的方式，使其易于构建且愉快。大部分工程工作都投入到了 ZRX，因为它构成了 Zensical 的骨干，并将使我们更快地发布功能。

遵循架构提升的原则，我们将基本的、可重用的功能移入 ZRX，这使我们能够保持 Zensical 的核心简单，并专注于静态网站生成。ZRX 处理繁重的工作——差异构建、缓存和数据流编排。

随着即将推出的 模块系统 和 组件系统，这两者都在我们的公开 路线图 上，Zensical 在未来几个月将获得更多的自由度，使您能够以以前在 MkDocs 中不可能的方式扩展和自定义 Zensical。

现代设计

Zensical 带来了新鲜、现代的设计，突破了材料设计的美学，创建了一个更易于品牌化和适应不同用例的视觉基础。新设计优先考虑清晰性、简单性和可用性，同时具有更专业的外观：

Zensical Zensical

我们的公开 路线图，由 Zensical 构建

目前，Zensical 的布局和网站结构与 Material for MkDocs 非常接近，因为我们专注于确保最大兼容性。一旦我们完成即将推出的 组件系统 的工作，我们将提供一个更加灵活和可适应的替代方案，更容易根据不同的用例和品牌需求进行定制。

您也可以通过一行配置保持 Material for MkDocs 的外观和感觉。

闪电般快速的搜索

客户端搜索不是妥协——对于绝大多数静态网站来说，这是最佳解决方案，因为它更快，不需要维护，也不需要您为服务付费。

如 本系列的第一部分 中详细介绍的，Material for MkDocs 中当前的搜索实现存在严重限制，并且基于一个现在不再维护的库，这就是我们决定从头开始构建一个新的搜索引擎的原因。它基于与 Zensical 本身相同的目标：性能、灵活性和可扩展性。

Disco，我们的模块化和闪电般快速的客户端搜索引擎，仅在 Zensical 中可用。当您使用 Zensical 构建网站时，您的用户将立即受益于 Disco 的改进排名算法，以及其过滤和聚合能力：

Zensical Zensical

Disco 在 zensical.org 上

在 2026 年初，我们将以独立的开源项目形式发布 Disco。通过 Zensical Spark 中专业用户的反馈，我们将不断改进搜索体验，使 Disco 成为一个高度可配置和可定制的搜索引擎，以适应您的需求。

您可以订阅 我们的新闻通讯 以接收有关 Disco 的最新消息。

创作体验

在编写文档时，缓慢的反馈循环可能是一个主要痛点。几乎所有人都知道等待静态网站生成器完成构建网站的感觉，只是为了在输出中看到一个小的更改。通过 Zensical，我们终于解决了这个问题。

重要的是要理解，我们尚未充分利用 ZRX 的差异能力，因为目前我们被迫做出几个妥协，以确保与 Material for MkDocs 的最大 兼容性。Markdown 渲染需要通过 Python Markdown，这迫使我们支付额外的编组成本。

虽然初始构建有时可能比 MkDocs 更慢，但重复构建——特别是在提供网站时——已经快 4 到 5 倍，因为只有更改的文件需要重新构建。

我们还在基于用 Rust 编写的 CommonMark 兼容解析器的新 Markdown 工具链上工作，这将使 Markdown 处理显著更快。我们将在即将推出的 组件系统 中解决这个问题，我们将在 2026 年初开始工作。一旦我们的新 Markdown 工具链准备就绪，我们将提供自动化工具，以在 Python Markdown 和 CommonMark 之间进行转换，因此您不需要手动迁移内容。

最大兼容性

与 Material for MkDocs 的兼容性 是我们的首要任务。我们理解，切换到新的静态网站生成器可能是具有挑战性的，特别是对于具有许多自定义的大型项目。因此，我们投入了大量精力，确保 Zensical 理解 mkdocs.yml 配置文件，以便您可以以最小的更改构建项目。

这意味着您现有的 Markdown 文件、模板覆盖、CSS 和 JavaScript 扩展不需要被触及，主要是因为我们没有更改生成的 HTML，并依赖 Python Markdown 来处理您的内容。

然而，插件是另一回事。在 MkDocs 中，几乎所有插件都有副作用，这使得并行构建变得不可能。我们从第一原则出发，问道：现代静态网站生成器的可扩展性应该是什么样子？ 我们的答案是即将推出的 模块系统，它基于四个核心原则采取根本不同的方法：

  • 模块可以注入、扩展和重新定义功能
  • 模块通过拓扑排序是确定性的
  • 模块促进可重用性，可以重新组合
  • 模块可以通过明确定义的合同进行合作

我们正在努力将 MkDocs 插件提供的基本功能作为内置模块发布。在 2026 年初，我们将向第三方开发者开放模块系统，以便他们可以开始构建自己的模块，因为我们认为 Zensical 是一个繁荣生态系统的核心。

Zensical Spark

Zensical Spark，我们的专业用户产品，是与 Material for MkDocs 的专业用户进行无数次通话的结果。从初创企业到大型企业，我们使组织能够在不同环境中实现复杂项目。为此，我们创建了 Zensical Spark 作为一个协作空间。如果您是专业用户，Zensical Spark 适合您，因为：

  • 您可以确信 Zensical 将继续作为一组相互关联和可持续的 OSI 合规开源项目进行长期开发和维护。

  • 您可以获得成功使用、配置和自定义 Zensical 所需的支持，获得来自 Zensical 团队的一流支持。

  • 您可以通过参与 我们新的方法 来影响 Zensical 的未来发展，帮助我们构建您所需的确切功能。

让我们谈谈！如果您在专业环境中工作，请通过 contact@zensical.org 联系我们以安排通话，了解 Zensical Spark 如何帮助您的团队顺利过渡到 Zensical，并在其持续发展中发声。

您还应该考虑加入 候补名单，因为名额有限。

我们正在壮大团队

我们也很高兴地宣布，我们正在壮大 我们的团队：

Timothée Mazzucotelli，也被称为 @pawamoy，正在加入 Zensical！

在 Zensical，Tim 专注于提供与 mkdocstrings 一样无缝的 API 参考文档生成体验（通过文档字符串）。凭借他的专业知识和 Zensical 的新栈，我们将推动 API 参考文档的可能性。

再见，GitHub 赞助

谢谢您！感谢所有通过 GitHub Sponsors 多年来支持我们的人——我们对您的支持感激不已。它在帮助我们构建、维护和发展 Material for MkDocs 方面是无价的，没有您我们无法做到。真的，非常感谢！

Material for MkDocs 给了我们无价的东西：为成千上万的用户构建的经验，以及围绕开源软件构建团队的机会。它让我们看到，从开源中谋生不仅是可能的——我们将其发展成为 GitHub 上最大的赞助软件项目之一，并激励其他人追求类似的道路。

现在我们正在开辟新天地。Zensical 是我们的下一个篇章，我们正在专业化我们对开源开发的方式。我们的愿景是让 Zensical 对每个人免费使用，同时围绕它建立一个可持续的商业模式，通过 我们新的方法。

这一过渡意味着告别 GitHub Sponsors。它为我们提供了极大的帮助，但随着我们专业化和扩展，我们正在从个人项目转变为公司——建立一个能够满足专业用户日益增长需求的业务和团队，同时保持我们的价值观。

我们将加倍努力支持开源，为每个人开发软件。

如果您想继续支持我们的工作，请订阅 我们的新闻通讯。在接下来的几个月里，我们将提供新的支持我们的方法，可能会获得独家福利。

展望未来

Material for MkDocs 在一个最终变得太小的容器中有机生长。通过 Zensical，我们正在建立坚实的基础，旨在与我们共同成长——以及与您共同成长。

Material for MkDocs 现在处于维护模式

我们希望对继续使用 Material for MkDocs 的风险保持透明。由于 MkDocs 不再维护并面临基本的供应链问题，我们无法保证 Material for MkDocs 将在未来继续可靠地工作。我们意识到过渡需要时间，这就是为什么我们承诺至少在接下来的 12 个月内支持它，修复关键错误和安全漏洞，但前进的道路是 Zensical。

如果文档在您的组织中发挥着关键作用，并且您担心这可能会影响您的业务，请考虑加入 Zensical Spark，或者随时通过 contact@zensical.org 安排通话。

12 个月后的我们

在接下来的 12 个月中，按照我们的 分阶段过渡策略，我们将达到第二和第三阶段——推出我们的 模块系统 和 组件系统，以及 CommonMark 支持。通过用基于 Rust 的 Markdown 解析器替换 Python Markdown，我们将解锁性能改进和灵活模板所需的模块化。这是 Zensical 真正开始展现其能力的地方。

Zensical 已经在实际项目中发挥作用，得益于与 Material for MkDocs 的广泛 兼容性。我们正在积极努力缩小差距，以实现完全的 功能平衡。

您可以 立即安装 Zensical，并使用它构建现有的 Material for MkDocs 项目。如果您遇到错误，请随时 提交问题——我们在这里帮助您。

与我们联系

如果您有我们未解决的问题，请通过 contact@zensical.org 联系我们。我们目前正在收集社区关于 Zensical 的问题，并将在接下来的几周内在我们的文档中以 FAQ 部分的形式进行解答。

我们非常感谢您迄今为止成为我们旅程的一部分。通过 Zensical，我们正在开启新的篇章，我们对与您共同前行感到无比兴奋。

您可以订阅 我们的新闻通讯 以保持最新信息。