内置离线插件¶

MkDocs 是为数不多的支持构建可离线查看文档的框架之一，用户可以直接查看，无需服务器。通过离线插件，您可以将 site 目录 分发为可下载的 .zip 文件，同时保留大部分交互功能。

目标¶

工作原理¶

在 构建您的项目 后，切换到 site 目录 并在浏览器中打开 index.html —— 您现在正在从本地文件系统查看文档！大多数浏览器会在地址栏中显示 file:// 来表示这一点。然而，您会发现站点搜索功能消失了。

Material for MkDocs 提供了许多交互功能，其中一些由于现代浏览器的限制而无法从本地文件系统正常工作。更具体和技术性地说，所有对 Fetch API 的调用都会出现如下错误信息：

跨源请求仅支持协议方案：http，[…]

虽然浏览器出于安全原因施加了这些限制，但这减少了您项目的交互性。离线插件确保站点搜索继续工作，通过将搜索索引移动到 JavaScript 文件中，并利用 @squidfunk 的 iframe-worker 补丁。

此外，该插件会自动禁用 use_directory_urls 设置，确保用户可以直接从本地文件系统打开您的文档。

存在一些 限制。

何时使用¶

正如名称所示，插件仅应在您为离线分发 构建您的项目 时使用。值得注意的是，离线插件与以下其他插件兼容良好，有助于创建更好的离线文档：

配置¶

9.0.0 offline – built-in

与所有 内置插件 一样，使用离线插件非常简单。只需将以下行添加到 mkdocs.yml 中，然后开始构建可离线查看的文档：

plugins:
  - offline

离线插件内置于 Material for MkDocs 中，无需单独安装。

一般设置¶

以下设置可用：

enabled¶

9.0.0 true

使用此设置在 构建您的项目 时启用或禁用插件。如果您希望同时构建在线和离线可用的文档，使用 环境变量 是个好主意：

plugins:
  - offline:
      enabled: !ENV [OFFLINE, false]

限制¶

启用离线插件时，请确保禁用以下设置，因为它们使用 Fetch API，在从本地文件系统调用时会出错：

• 即时加载
• 站点分析
• 版本控制
• 评论系统