MkDocs Material 内置 offline 插件构建无需服务器、可离线分发的文档站点【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 是为数不多能够构建离线可读文档的静态站点框架之一——生成的文档无需 Web 服务器用户解压后直接双击index.html即可浏览。本文围绕内置的 offline 插件讲解其工作原理如何让搜索在file://协议下继续工作、mkdocs.yml中的最小配置与enabled参数、与隐私/优化插件的配合方式以及启用离线构建时必须注意的功能限制帮助你产出可直接以.zip形式分发的离线文档包。Objective为什么需要 offline 插件工作原理从file://到可用交互MkDocs 构建出的site目录本质上是一组纯静态的 HTML、CSS、JS 与资源文件。按照 构建站点 的流程完成mkdocs build后切换到site目录并双击index.html文档即可在本地文件系统中直接打开浏览器地址栏会显示file://前缀。但问题随之而来Material for MkDocs 的许多交互功能依赖 Fetch API 发起网络请求而现代浏览器出于安全考虑禁止从file://页面发起跨源请求通常会抛出类似如下错误Cross origin requests are only supported for protocol schemes: http, [...]站点搜索正是受影响最明显的功能——搜索索引search/search_index.json需要通过 Fetch API 获取一旦走file://协议便会失败搜索框形同虚设。offline 插件正是为解决这一问题而生的。它在构建阶段做了两件事把搜索索引内联为 JavaScript 文件在on_post_build钩子中读取site_dir/search/search_index.json的内容生成同目录下的search_index.js其内容形如var __index {...}让搜索数据不再依赖网络请求。追加 iframe-worker 垫片shim通过squidfunk/iframe-worker项目用隐藏 iframe 模拟 Web Worker 的异步能力使 Lunr.js 搜索逻辑在file://协议下也能正常执行。此外插件在on_config钩子中自动关闭use_directory_urls。目录式 URL如foo/bar/依赖服务器重写才能正确解析而本地文件系统没有这一能力关闭后链接会退化为foo/bar.html形式保证从本地直接打开时所有链接都能正确解析。这两项改动由 src/plugins/offline/plugin.py 中OfflinePlugin的on_config与on_post_build两个钩子完成其中on_post_build被标注为event_priority(-100)确保其在构建流程的末尾、其他插件处理完成之后才执行。何时使用插件的定位非常明确只在为离线分发构建站点时才启用它。也就是说如果你正计划把整个site目录打包成.zip发给用户offline 插件就是关键一环而如果站点始终托管在服务器上则没有必要启用。离线场景下offline 插件还与其他内置插件配合默契能组合出更完整的离线体验内置 privacy 插件离线构建时外部资源字体、CDN 脚本等无法访问privacy 插件会在构建时自动把外部资源下载并内联进产物让你的文档在完全断网的环境下也能正常渲染。内置 optimize 插件自动识别并压缩、转换站点引用的所有媒体文件减小产物体积让最终分发的.zip更小、下载更快。有人可能会问为什么不让 offline 插件顺带实现外部资源下载这是因为该能力已在 privacy 插件中完整实现并成为其存在的核心理由。Material for MkDocs 的插件体系遵循模块化设计——各插件各司其职又相互增强几个简单的配置即可解决复杂问题。Configuration在mkdocs.yml中启用与所有 内置插件 一样offline 插件的启用极其简单。在mkdocs.yml中添加如下配置即可plugins: - offlineoffline 插件随 Material for MkDocs 内置分发无需单独安装。从源码结构看它由 src/plugins/offline/config.py 定义配置项、src/plugins/offline/plugin.py 实现具体逻辑二者对应发布在 material/plugins/offline/ 目录下。Generalenabled参数插件目前唯一的配置项是enabled参数类型默认值说明enabled布尔true是否在构建站点时启用离线处理默认值为true即一旦在plugins中声明offline离线构建能力即生效。若希望一套配置同时产出在线与离线两种产物可借助 环境变量 控制开关——例如默认关闭、仅当设置OFFLINE环境变量时才启用plugins: - offline: enabled: !ENV [OFFLINE, false]使用该方式时普通构建mkdocs build生成的是常规在线站点而在设置OFFLINEtrue的环境下构建则得到可离线分发的产物。从 config.py 的OfflineConfig可以看到enabled通过Type(bool, default True)定义plugin 的两个钩子也都以if not self.config.enabled: return作为守卫关闭时不会产生任何副作用。Limitations必须关闭的功能浏览器的安全限制决定了并非所有交互功能都能在file://下工作。启用 offline 插件后以下依赖 Fetch API 的功能需要显式关闭否则在本地打开时相关请求会报错Instant loading即时加载点击链接时通过 Fetch API 预取并替换页面内容file://下无法跨源请求需关闭navigation.instant。Site analytics站点统计统计脚本需要向后端上报数据离线环境下不存在服务端统计也就失去意义。Versioning版本切换版本选择依赖 Fetch API 动态获取版本列表离线包中无法工作。Comment systems评论系统主流评论方案如 Giscus、Gitalk均需与外部服务通信离线时同样不可用。这些功能的具体开关方式可分别查阅上文链接的 setup 章节。关闭它们之后你的离线文档将保留绝大部分核心交互——尤其是站点搜索——同时不会在本地打开时冒出红字报错。源码视角离线搜索的两条关键链路深入源码可以看到offline 插件与搜索模块的配合构成了完整的离线搜索链路索引加载的分流逻辑位于 src/templates/assets/javascripts/bundle.ts 的fetchSearchIndex函数当location.protocol file:时通过watchScript动态加载插件生成的search/search_index.js并把全局变量__index作为索引数据否则走常规路径用 Fetch API 请求search/search_index.json。这正是移动搜索索引到 JavaScript 文件这一设计的落点。搜索 worker 的 iframe 垫片搜索本身在 Web Worker 中执行以保持 UI 流畅而 Web Worker 从file://页面创建同样受限。搜索模块的 worker/_/index.ts 注释明确指出借助一个轻量的、基于 iframe 的 Web Worker 垫片搜索在file://协议下也能得到支持。插件在on_config中向config.extra[polyfills]追加的https://unpkg.com/iframe-worker/shim见 plugin.py正是这个垫片。此外worker 内的多语言支持在 iframe 环境中需要修正脚本加载路径worker/main/index.ts 通过检测parent上是否存在IFrameWorker来识别垫片环境并依据首个带src的script元素重新推导 lunr 语言包的基础路径。至此离线站点保留的最重要交互——搜索——从索引内联、worker 垫片到链接重写形成了一条完整且可验证的链路这也是 offline 插件价值的核心所在。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考