Material for MkDocs 9.7.0：Insiders 全部特性面向所有人免费开放与维护模式全解读

Material for MkDocs 9.7.0：Insiders 全部特性面向所有人免费开放与维护模式全解读

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

本文围绕 Material for MkDocs 官方公告（docs/blog/posts/insiders-now-free-for-everyone.md）展开，系统梳理 9.7.0 这个"最终功能版本"中 20 项此前仅限赞助者使用的 Insiders 特性如何面向全员免费开放，并完整说明升级路径、从 Insiders 仓库迁移到社区版的具体步骤、以及项目进入维护模式后的弃用清单与依赖策略调整。读完本文，你将掌握从旧版本或 Insiders 版本平滑切换到社区版 9.7.x 的完整实操方案，并理解每个新开放特性的配置入口与底层实现。

9.7.0：最后一个功能版本，Insiders 正式向所有人开放

2025 年 11 月 11 日，Material for MkDocs 发布了9.7.0——这是项目进入维护模式前的最后一个新功能版本。从这一版本开始，所有此前仅向 GitHub Sponsors 赞助者开放的 Insiders 付费版特性，全部合并进社区版，任何人无需赞助即可免费使用。

这一决定源于项目方向的转变：开发团队将精力转向 Zensical——一个从零构建、旨在突破 MkDocs 技术限制的下一代静态站点生成器。Material for MkDocs 随之进入维护模式：至少在接下来的 12 个月内，团队会继续修复关键 bug 与安全漏洞，但不再新增任何功能。

作为佐证，本仓库 docs/changelog/index.md 的 9.7.0 条目明确写道："This release includes all features that were previously exclusive to the Insiders edition. These features are now freely available to everyone."（本版本包含所有此前专属于 Insiders 版本的特性，现在对所有人免费开放。），并同步标注了维护模式警告。

同时，官方也宣布终止 sponsorware（赞助者先行）商业模式，正式告别 GitHub Sponsors 赞助计划。过去几年通过赞助支持过该项目的个人与组织，其订阅均已自动取消。

全部 20 项 Insiders 特性清单与配置入口

赞助者们长期独享的以下 20 项高级特性，现已在社区版中全部开放。它们覆盖博客、导航、搜索、标签、社交卡片、隐私合规、代码块与插件系统等多个维度：

• 博客体系：Blog plugin: pinned posts（置顶文章）、Blog plugin: author profiles（作者档案页）、Blog plugin: advanced settings（高级设置）
• 导航与浏览：Navigation path（面包屑导航）、Instant previews（即时预览）、Instant prefetching（即时预取）、Stay on page when switching languages（切换语言时保持页面位置）
• 标签体系：Tags plugin: advanced settings（高级设置）、Tags plugin: nested tags（嵌套标签）、Tags plugin: shadow tags（影子标签）
• 社交卡片：Social plugin: custom layouts（自定义布局）、Social plugin: background images（背景图片）
• 代码体验：Code range selection（代码范围选择）、Code annotations: custom selectors（自定义标注选择器）、Footnote tooltips（脚注悬停提示）
• 隐私与性能：Privacy plugin: advanced settings（高级设置）、Privacy plugin: external links（外部链接处理）、Optimize plugin（图片自动优化）
• 多站点：Projects plugin（多项目构建）
• 排版：Typeset plugin（排版插件）

公告中附带提示：mkdocstrings 的 Insiders 版本也随之免费开放——Timothée 加入 Zensical 团队后，宣布此前保留给其赞助者的 mkdocstrings Insiders 特性同样全部免费。

从源码看这些特性如何落地

上述特性并非停留在文档层面，而是全部有真实的配置实现与源码支撑，可直接在本仓库对应插件目录中验证：

• 博客高级特性：material/plugins/blog/config.py 中的BlogConfig定义了完整的博客配置面：置顶文章通过pinned配置启用；作者档案由authors_profiles（默认False）、authors_profiles_name、authors_profiles_url_format等字段控制；分页行为由pagination_per_page（默认 10）、pagination_url_format（默认page/{page}）与pagination_format（默认~2~）调节；分类排序则由categories_sort_by、categories_sort_reverse控制。
• 标签嵌套与影子标签：material/plugins/tags/config.py 的TagsConfig中，tags_hierarchy（默认False）与tags_hierarchy_separator（默认/）共同实现嵌套标签；shadow（默认False）、shadow_on_serve、shadow_tags、shadow_tags_prefix/suffix实现影子标签机制。
• 隐私插件外部链接处理：material/plugins/privacy/config.py 的PrivacyConfig提供links（默认True）、links_attr_map与links_noopener（默认True）等外部链接处理选项，以及log_level（可选error/warn/info/debug）等高级设置。
• 图片优化：material/plugins/optimize/config.py 的OptimizeConfig提供concurrency（默认os.cpu_count() - 1）、PNG/JPEG 优化开关与质量参数（如optimize_jpg_quality默认 60、optimize_png_speed默认 3）、缓存目录cache_dir（默认.cache/plugin/optimize）以及optimize_include/optimize_exclude过滤列表。
• 多项目构建：material/plugins/projects/config.py 的ProjectsConfig定义了projects_dir（默认projects）、projects_config_files（默认*/mkdocs.yml）等扫描规则。
• 社交卡片自定义：material/plugins/social/config.py 中的cards_layout（默认default）、cards_layout_dir（默认layouts）与cards_layout_options是自定义布局与背景图片能力的配置基础。

如何升级到 9.7.0 及以上版本

升级操作非常简单，使用 pip 强制重装即可获取全部特性：

pip install --upgrade --force-reinstall mkdocs-material

--force-reinstall确保覆盖任何历史遗留的本地安装，--upgrade则将包提升到最新版本。升级后可用以下命令确认版本：

pip show mkdocs-material

本仓库当前源码中，material/init.py 维护的版本号为9.7.6，即 9.7.x 系列仍在持续迭代，建议定期检查更新以获得关键 bug 修复与安全补丁。

从 Insiders 切换回社区版

如果你是 Insiders 用户，官方强烈建议尽快切回社区版——因为社区版现在已包含 Insiders 的全部功能，且切换后无需再为第三方贡献处理个人访问令牌（Personal Access Token），协作门槛显著降低。

版本策略重要变化：从今往后，Material for MkDocs 的bug 修复将只发布到社区版；安全漏洞则在两个版本中都会修复。

需要调整两个文件：requirements.txt与 GitHub Actions 工作流。将原先通过GH_TOKEN拉取 Insiders 私有仓库的安装指令，替换为直接安装 PyPI 社区包：

- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders. git + pip install mkdocs-material

Insiders 仓库退役时间表

Insiders 仓库本身还会保留 6 个月，期间使用 Insiders 构建项目时会看到一条指向本公告的提示信息。此后按如下节奏逐步退役：

• 2026 年 2 月 1 日：提示信息升级为警告；
• 2026 年 5 月 1 日：Insiders 仓库被彻底删除。

因此，任何仍依赖 Insiders 私有仓库的 CI/CD 流水线都应在此之前完成迁移。

维护模式下的变更与弃用

正式弃用：Projects 插件与 Typeset 插件

在向公众释放全部特性的同时，Projects plugin 与 Typeset plugin 因可维护性问题被正式弃用，此后不再接收任何更新，包括 bug 修复。弃用原因是两者为了兼容 MkDocs 依赖了过多 workaround，也正是它们推动了 Zensical 的诞生。如果这两个插件在你的场景下工作正常，可以继续使用，但应评估长期风险。Zensical 将原生提供更完善的子项目支持、国际化与版本管理能力。

依赖策略：从 semver 切换到 minimal version ranges

此前 Material for MkDocs 对依赖使用语义化版本（semver）范围以保证兼容性。从 9.7.0 起，官方改用最小版本范围（minimal version ranges）策略，为依赖解析提供更大灵活性——具体来说，允许用户使用包含重要 bug 修复或安全补丁的更新版本依赖。

安全与所有权承诺

官方明确不会将 Material for MkDocs 仓库所有权转移给任何个人或组织：仓库与 PyPI 包将继续由 @squidfunk 持有，以维持用户所依赖的可信供应链。如果你希望接手维护工作，官方建议直接创建 fork。

展望：Zensical 与对社区的承诺

可持续性新路径：Zensical Spark

Material for MkDocs 依赖 sponsorware 模式，而 Zensical 采用全新思路确保面向企业级复杂文档需求持续演进。Zensical Spark 是一个协作空间，专业用户可通过结构化设计流程直接参与 Zensical 的功能规划——识别机会、验证方案、确定优先级，把真实的文档建设痛点转化为惠及整个社区的功能。

对现有用户的承诺

如果你正在使用 Material for MkDocs，无需仓促迁移。官方承诺在接下来 12 个月内持续保障其安全与可用，同时全力投入 Zensical 建设。9.7.0 标志着一次重大转变：每一个 Insiders 特性都无需任何赞助即可使用；而 Zensical 完全免费开源，且保持与 Material for MkDocs 的兼容性，可视为对现有项目理念的自然延续与升级。在本仓库中，你可以通过 docs/blog/posts/zensical.md 了解 Zensical 的完整定位，通过 docs/blog/posts/transforming-material-for-mkdocs.md、docs/blog/posts/goodbye-github-discussions.md 与 docs/blog/posts/mkdocs-2.0.md 回顾整个系列的前因后果。

总结

对于 Material for MkDocs 的所有用户而言，9.7.0 是一个里程碑式版本：20 项此前付费独享的高级特性全部免费开放，覆盖博客、导航、标签、社交卡片、隐私合规、代码块、图片优化与多项目构建等核心能力；同时项目正式进入维护模式，仅接受关键 bug 修复与安全更新，并明确了 Projects/Typeset 插件的弃用与依赖策略调整。建议所有用户立即执行pip install --upgrade --force-reinstall mkdocs-material完成升级，Insiders 用户则应按上述 diff 切换回社区版，并在 2026 年 5 月 1 日前彻底脱离 Insiders 私有仓库依赖。若你的团队正在规划长期演进路线，可关注 Zensical 的兼容性进展，以最小的改造成本完成下一代迁移。

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material