Material for MkDocs 9.7.0Insiders 全部特性面向所有人免费开放与维护模式全解读【免费下载链接】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 githttps://${GH_TOKEN}github.com/squidfunk/mkdocs-material-insiders. git pip install mkdocs-materialInsiders 仓库退役时间表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 SparkMaterial 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考