Skip to content

构建优化的网站

默认情况下,MkDocs 的 Material 主题允许构建优化的网站,这些网站在搜索引擎上的排名很高,加载速度快(即使在网络速度慢的情况下也是如此),并且即使没有 JavaScript 也能完美工作。此外,内置优化插件增加了对更多有用的自动优化技术的支持。

配置

内置项目插件

内置的项目插件允许将你的文档分割成多个独立的 MkDocs 项目,并行构建它们一起服务它们。在 mkdocs.yml 中添加以下内容:

plugins:
  - projects

接下来,在你的根目录中创建一个名为 projects 的文件夹,该文件夹将包含所有的项目。例如,如果我们想要构建一个包含两种额外语言的项目,我们可以使用:

.
├─ projects/
  ├─ de/
    ├─ docs/
    └─ mkdocs.yml
  └─ fr/
     ├─ docs/
     └─ mkdocs.yml
└─ mkdocs.yml

如果你现在调用 mkdocs serve 并更改其中一个项目中的文件,项目插件会确保 MkDocs 也会重新加载那些文件。请注意,这些项目目前是完全独立的,这意味着它们会有独立的搜索索引和站点地图。我们很乐意接收关于这个插件的反馈,并了解你的需求以使它变得更好,因为我们计划添加对合并和提升文件的支持。 创建一个讨论来分享你的想法!

项目插件的使用案例

项目插件的理想使用案例是:

  • 构建多语言网站
  • 在你的文档旁边构建一个博客
  • 为了更好的性能分割大型代码库

请注意,该插件目前还处于实验阶段。我们提前发布它,这样我们可以与我们的用户一起改进它,并在我们发现新的使用案例时使它更加强大。

以下配置选项可用:

enabled

默认值:true – 此选项指定在构建你的项目时是否启用插件。如果你想加快本地构建速度,你可以使用环境变量

plugins:
  - projects:
      enabled: !ENV [CI, false]

concurrency

默认值:CPU 数量 – 此选项指定插件在构建项目时允许使用的 CPU 数量。有了更多的 CPU,插件可以在同一时间内做更多的工作,从而更快地完成优化。可以禁用并行处理:

plugins:
  - projects:
      concurrency: 1

项目

以下配置选项可用于项目:

projects

默认值:true – 此选项指定是否构建嵌套项目。如果你想关闭插件,例如,对于本地构建,你可以使用环境变量

plugins:
  - projects:
      projects: !ENV [CI, false]

projects_dir

默认值:projects – 此选项指定插件期望你的项目存储的文件夹的名称。虽然通常不需要更改此选项,但可以用以下方式更改它:

plugins:
  - projects:
      projects_dir: path/to/folder

内置优化插件

内置的优化插件会自动识别并优化所有媒体文件,作为构建过程的一部分,使用压缩和转换技术。在 mkdocs.yml 中添加以下行:

plugins:
  - optimize # (1)!
  1. 请确保已安装所有图像处理的依赖项,否则插件将无法正常工作。

如果你需要能够在有和没有 Insiders 的情况下构建你的文档,请参阅 内置插件 部分,了解如何使用共享配置来实现这一点。

以下配置选项可用:

enabled

默认值:true – 此选项指定在构建你的项目时是否启用插件。如果你想加快本地构建速度,你可以使用环境变量

plugins:
  - optimize:
      enabled: !ENV [CI, false]

concurrency

默认值:CPU 数量 – 此选项指定插件在优化媒体文件时允许使用的 CPU 数量。有了更多的 CPU,插件可以在同一时间内做更多的工作,从而更快地完成优化。可以禁用并行处理:

plugins:
  - optimize:
      concurrency: 1

优化

技术文档通常包括屏幕截图或图表,这两者都是压缩的主要候选对象。内置优化插件允许使用 pngquant(用于 PNG)和 Pillow(用于 JPG)自动压缩图像。

以下配置选项可用于优化:

optimize_png

默认值:true – 此选项指定插件是否应使用 pngquant(必须在系统上安装)优化 PNG 文件。可以禁用 PNG 优化:

plugins:
  - optimize:
      optimize_png: false

optimize_png_speed

默认值:4,范围[1,10] – 此选项指定 pngquant 在压缩时应用的速度/质量折衷。数字越低,优化所花费的时间越多:

较慢

plugins:
  - optimize:
      optimize_png_speed: 1

较快 粗糙

plugins:
  - optimize:
      optimize_png_speed: 10

效率

10 的因子比默认的 4 低 5% 的质量,但是速度快 8 倍。

optimize_png_strip

默认值:true – 此选项指定 pngquant 是否应删除所有在浏览器中渲染图像时不必要的非可选元数据:

plugins:
  - optimize:
      optimize_png_strip: false

optimize_jpg

默认值:true – 此选项指定插件是否应使用 Pillow(一个 Python 图像处理库)优化 JPG 文件。可以禁用 JPG 优化:

plugins:
  - optimize:
      optimize_jpg: false

optimize_jpg_quality

默认值:60,范围[0,100] – 此选项指定 Pillow 在压缩时使用的图像质量。如果图像看起来模糊,调整和更改此设置是个好主意:

plugins:
  - optimize:
      optimize_jpg_quality: 75

optimize_jpg_progressive

默认值:true – 此选项指定 Pillow 在压缩 JPG 时是否应使用 渐进式编码(更快的渲染)。可以禁用渐进式编码:

plugins:
  - optimize:
      optimize_jpg_progressive: false

缓存

内置优化插件 实现了一个智能的缓存机制,确保只有在媒体文件的内容发生变化时,才会将它们推送到优化管道中。如果你更换或更新了图像,插件将检测到并更新优化版本。

以下配置选项可用于缓存:

cache

默认值:true – 此选项指定插件在开始优化作业之前是否查询其缓存中是否存在现有的工件。通常不需要更改此设置,除非是在调试插件本身。可以禁用缓存:

plugins:
  - optimize:
      cache: false

cache_dir

默认值:.cache/plugins/optimize – 此选项指定插件缓存的文件系统位置。通常不需要更改此设置,除非是在调试插件本身。可以更改缓存目录:

plugins:
  - optimize:
      cache_dir: .cache/plugins/optimize

默认情况下,所有实现了缓存的内置插件都会在你的 mkdocs.yml 所在的同一文件夹中创建一个 .cache 目录,并创建子文件夹以避免相互干扰。如果你使用了这个插件的多个实例,可能需要更改此设置。