内置离线插件¶

¥Built-in offline plugin¶

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

¥MkDocs is one of the few frameworks that supports building offline-capable documentation that can be directly viewed by the user – no server needed. With the offline plugin, you can distribute the site directory as a downloadable .zip file while retaining most interactive functionality.

客观的¶

¥Objective¶

工作原理¶

¥How it works¶

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

¥After building your project, switch to the site directory and open index.html in your browser – you're now viewing your documentation from your local file system! Most browsers will denote this by showing file:// in the address bar. However, you'll realize that the site search is gone.

Material for MkDocs 提供了许多交互功能，但由于现代浏览器的限制，其中一些功能无法在本地文件系统中使用。更具体地说，从技术角度来说，所有对Fetch API 的调用都会出错，并显示如下消息：

¥Material for MkDocs offers many interactive features, some of which will not work from the local file system due to the restrictions of modern browsers. More specifically and technically, all calls to the Fetch API will error with a message like:

Cross origin requests are only supported for protocol schemes: http, [...]

虽然浏览器出于安全原因施加了这些限制，但这会降低项目的交互性。离线插件通过将搜索索引移至 JavaScript 文件，并利用@squidfunk的iframe-worker shim，确保站点搜索持续正常工作。

¥While browsers impose those restriction for security reasons, it reduces the interactivity of your project. The offline plugin makes sure that site search keeps working by moving the search index to a JavaScript file, and leveraging @squidfunk's iframe-worker shim.

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

¥Additionally, the plugin automatically disables the use_directory_urls setting, ensuring that users can open your documentation directly from the local file system.

有一些限制。

¥There are some limitations.

何时使用¶

¥When to use it¶

顾名思义，该插件仅应在构建离线分发项目时使用。此外，该离线插件可以与以下其他插件完美兼容，从而帮助您创建更出色的离线文档：

¥As the name already indicates, the plugin should only be used when you're building your project for offline distribution. It's also good to know, that the offline plugin plays nicely with the following other plugins, helping to create even better offline-capable documentation:

内置隐私插件隐私插件让您在构建离线使用版本时轻松使用外部资源，因为它会自动下载这些资源并将其与您的文档一起分发。您的文档无需连接互联网即可运行。
内置优化插件优化插件会使用压缩和转换技术自动识别并优化您在项目中引用的所有媒体文件。您的文档可以以较小的 .zip 文件格式下载。

配置¶

¥Configuration¶

9.0.0离线 – 内置

¥ Built-in privacy plugin

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

¥The privacy plugin makes it easy to use external assets when building for offline usage, as it automatically downloads them for distribution with your documentation.

plugins:
  - offline

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

¥Your documentation can work without connectivity to the internet¹

一般的¶

¥General¶

可用的设置如下：

¥ Built-in optimize plugin

`enabled`¶

¥enabled¶

9.0.0真

¥The optimize plugin automatically identifies and optimizes all media files that you reference in your project by using compression and conversion techniques.

使用此设置在构建项目时启用或禁用插件。如果您想构建在线和离线文档，最好使用环境变量：

¥Your documentation can be distributed as a smaller .zip download

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

限制¶

¥Limitations¶

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

¥9.0.0 offline – built-in

您可能想知道，为什么需要隐私插件才能使用离线插件构建真正支持离线的文档。虽然离线插件当然也可以添加下载外部资源的支持，但此功能已在隐私插件中完全实现，并且是其存在的意义所在。Material for MkDocs 的插件系统采用模块化方法——许多插件可以完美协作并相互增强功能，只需几行配置即可解决复杂问题。↩