跳转至

第三方插件规划(与 MkDocs 插件对应)

对应官方:Plugins

Zensical 基于对 GitHub 上使用 Material for MkDocs 的 Top 1000 仓库及插件目录的定量分析,将需要迁移的 MkDocs 插件分为两级优先级,全部放入官方 Backlog。

支持策略

  • 兼容方式:在 mkdocs.ymlzensical.tomlproject 域中,把原插件配置映射到 Zensical 正在开发的模块(modules),用户无需修改配置或内容即可构建。
  • Tier 1(最高优先级):确保无缝迁移的核心插件。
  • Tier 2(次高优先级):次高优先级插件。

MkDocs 插件对应清单

MkDocs 插件 分类 Zensical 对应 Backlog
mkdocstrings Tier 1 映射为 Zensical 模块(文档指向 /docs/setup/extensions/mkdocstrings #4
macros(mkdocs-macros-plugin) Tier 1 对应模块开发中 #16
minify(mkdocs-minify-plugin) Tier 1 对应模块 #15
mike Tier 1 对应模块 #14
awesome-nav(mkdocs-awesome-nav) Tier 1 对应模块 #12
static-i18n(mkdocs-static-i18n) Tier 2 对应模块 #1
git-authors Tier 2 对应模块 #19
git-committers Tier 2 对应模块 #17
git-revision-date-localized Tier 2 对应模块 #18

git 泛指上述三个 git-* 插件,Zensical 将其全数纳入 Tier 2 支持。

当前限制与未来开放

  1. 当前限制:Zensical 先以自带模块替代上表中的 MkDocs 插件,用于测试模块系统;目前暂未发布公共 API,刻意暂缓第三方接入以免破坏变更。
  2. 未来开放:待 API 稳定后,在 Zensical Spark 中发布公共 API,并邀请关键生态维护者参与,培育第三方模块生态。
  3. 开发优势:第三方开发者只需写业务逻辑,运行时负责编排、并行化、缓存;模块可用 Rust 编写(Python 支持也在推进)。
  4. 替换自由:即使官方提供默认模块,用户仍可用第三方模块替换,保持灵活性。

功能重构提示

  • literate-navawesome-nav(Tier 1)当前为兼容而映射,但 Phase 4 后 Zensical 将用模块化导航原生支持"导航即内容",超越原插件约束。
  • typeset 等因 MkDocs 设计局限产生的插件在 Zensical 中已废弃(不在上表)。

与本站内置插件的关系

本站已覆盖 Zensical 的内置插件:博客(博客系统完全指南)、搜索(搜索功能配置)、标签(标签插件)、RSS(RSS 插件)。上表所列是未来以模块形式替代的 MkDocs 第三方插件,目前尚在 Backlog 中。

官方链接Plugins