发布说明

---

升级

要升级 MkDocs 到最新版本，请使用 pip：

pip install -U mkdocs

你可以使用 mkdocs --version 确定当前安装的版本：

$ mkdocs --version
mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10)

维护团队

MkDocs 团队的当前和过去成员。

• @tomchristie
• @d0ugal
• @waylan
• @oprypin
• @ultrabug

版本 1.6.1（2024-08-30）

修复

• 修复当环境变量 SOURCE_DATE_EPOCH=0 设置时构建错误。#3795
• 修复当 mkdocs_theme.yml 配置为空时构建错误。#3700
• 支持 python -W 和 PYTHONWARNINGS 而不是覆盖配置。#3809
• 支持在严格模式下使用 Docker 运行，通过移除 0.0.0.0 开发服务器警告。#3784
• 从 sitemap.xml 中移除不必要的 changefreq。#3629
• 修复关闭菜单下拉时 JavaScript 控制台错误。#3774
• 修复重复点击时出现的 JavaScript 控制台错误。#3730
• 修复下拉选择时可能出现的 JavaScript 控制台错误。#3694

新增

• 新增荷兰语翻译。#3804
• 新增和更新简体中文翻译。#3684

版本 1.6.0（2024-04-20）

本地预览

• mkdocs serve 在打开超过 5 个标签页时不再锁定浏览器。这是通过在标签页变为非活动状态时关闭轮询连接实现的。后台标签页也不会自动重新加载，而是在再次打开标签页时重新加载。上下文：#3391

• 新增标志 serve --open 以在浏览器中打开站点。
  在首次构建完成后，此标志将导致默认操作系统 Web 浏览器在本地站点的首页打开。
  上下文：#3500

草稿

警告：从版本 1.5 更改。

exclude_docs 配置被拆分为两个独立的概念。

exclude_docs 配置不再对 mkdocs serve 有任何特殊行为——它现在总是完全排除列出的文档。

如果你希望使用 MkDocs 1.5 中 exclude_docs 键所做的“草稿”功能，请切换到 新的配置键 draft_docs。

参见 文档。

其他更改：

• 当“草稿”页面链接到不存在的文件时，降低警告级别。上下文：#3449

页面标题推导更新

MkDocs 1.5 在从第一个标题推导页面标题时改变了行为。不幸的是，这可能会导致在边缘情况下出现未转义的 HTML 标签或实体。

现在标签总是从标题中完全净化。尽管 Page.title 仍然预期包含 HTML 实体，并直接传递给主题。

图像（特别是某些扩展中的表情符号）仅通过其 alt 属性的值保留在标题中。

上下文：#3564, #3578

主题

• 内置主题现在也支持波兰语 (#3613)

"readthedocs" 主题

• 修复：“readthedocs”主题现在可以正确处理深度嵌套的导航配置（超过 2 层深度），而不会混淆地展开所有部分并在垂直方向上跳转。(#3464)

• 修复：“readthedocs”主题现在在没有一个已知的托管方时也会显示指向仓库的链接（带有通用图标）。(#3435)

• “readthedocs”主题现在也在页脚中为单词“theme”添加了翻译，该单词之前总是保留为英文。(#3613, #3625)

"mkdocs" 主题

“mkdocs”主题进行了重大更新，升级到更新版本的 Bootstrap，这意味着样式略有改版。颜色（特别是提示框的颜色）对比度更好。

“mkdocs”主题现在支持暗模式——自动（基于操作系统/浏览器设置）和手动切换。这两个选项默认不启用，需要显式配置。
参见 color_mode, user_color_mode_toggle 在 文档。

警告：可能的破坏性更改。

jQuery 不再包含在“mkdocs”主题中。如果你依赖于在你的脚本中使用它，你需要首先单独添加它（到 mkdocs.yml 中）作为一个额外的脚本：

extra_javascript:
  - https://code.jquery.com/jquery-3.7.1.min.js

或者更好的是，如果脚本文件是从你的文档目录中复制并包含的。

上下文：#3493, #3649

配置

所有插件的新 "enabled" 设置

你可能已经看到一些插件采用了 enabled: false 设置（或通常通过环境变量控制）来使插件不执行任何操作。 现在每个插件都有这个设置。插件仍然可以选择自行实现此配置并决定其行为（除非它们放弃对旧版本 MkDocs 的支持，否则它们现在仍然应该这样做），但现在每个插件都有一个回退机制。

参见文档。上下文：#3395

验证

页面间超链接的验证

绝对链接

历史上，在 Markdown 中，MkDocs 只识别指向另一个物理 *.md 文档（或媒体文件）的相对链接。这是一个很好的惯例，因为这样源页面在没有 MkDocs 的情况下也可以自由浏览，例如在 GitHub 上。而绝对链接则保持不变（这通常会导致它们无法按预期工作，或者最近被警告）。

如果你不喜欢总是使用相对链接，现在你可以选择使用绝对链接并使其正常工作。

如果你将设置 validation.links.absolute_links 设置为新值 relative_to_docs，所有以 / 开头的 Markdown 链接将被理解为相对于 docs_dir 根目录。然后，这些链接将根据 MkDocs 先前版本中已对相对链接生效的所有其他规则进行正确性验证。对于 HTML 输出，这些链接仍将被转换为相对链接，以确保站点仍然可靠地工作。

因此，现在任何文档（例如 "dir1/foo.md"）都可以链接到文档 "dir2/bar.md"，如 [link](/dir2/bar.md)，而不仅仅是之前唯一正确的方式 [link](../dir2/bar.md)。

不过，你需要启用此设置。默认情况下，仍然只是跳过对这些链接的任何处理。

参见文档。上下文：#3485

nav 中的绝对链接

nav: 配置中的绝对链接也总是被跳过。现在可以通过 validation.nav.absolute_links 以相同的方式验证它们。尽管这样做意义不大，因为语法只是与不带前导斜杠的语法重复。

锚点

有一个新的配置设置建议启用警告：

validation:
  anchors: warn

此设置可能产生的警告示例：

WARNING - 文档文件 'foo/example.md' 包含链接 '../bar.md#some-heading'，但文档 'foo/bar.md' 不包含锚点 '#some-heading'。

MkDocs 将检测以下任何一种声明锚点的方法：

## 产生锚点的标题

## 另一个标题 {#使用 attr-list 的自定义锚点}

<a id="原始锚点"></a>

[](){#使用 attr-list 的 Markdown 锚点}

为了与此兼容，插入锚点的插件和扩展需要开发为插入 etree 元素的 treeprocessors，而不是无法检测的原始 HTML。

如果你作为用户遇到误报的缺失锚点且无法解决此问题，你可以选择通过将此选项设置为 ignore 来禁用这些消息（默认情况下它们处于 INFO 级别）。

参见文档。上下文：#3463

其他更改：

• 当 nav 配置完全没有指定时，not_in_nav 设置（最初在 1.5.0 中添加）获得了一个额外的行为：由 not_in_nav 覆盖的文档将不包含在自动推导的导航中。上下文：#3443

• 修复：markdown_extensions 的 !relative YAML 标签（最初在 1.5.0 中添加）——它在许多典型用例中被破坏了。

  参见文档。上下文：#3466

• 配置验证现在在第一个错误时退出，以避免显示奇怪的次要错误。上下文：#3437

• MkDocs 过去会缩短意外错误的错误消息，例如“文件未找到”，但现在不再如此，完整的错误消息和堆栈跟踪将可以查看（当然，除非错误有适当的处理程序）。上下文：#3445

插件开发者的升级

插件可以为同一事件类型添加多个处理程序，并设置多个优先级

参见 mkdocs.plugins.CombinedEvent 在 文档。上下文：#3448

启用真正的生成文件并扩展 File API

参见 文档。

• 有一对新的属性 File.content_string/content_bytes，它们成为获取文件内容的官方 API，并由 MkDocs 本身使用。 这取代了旧的方法，即必须手动读取位于 File.abs_src_path 的文件，尽管这些新属性在底层仍然主要执行这一操作。

• File 的内容可以由一个字符串支持，不再必须是 abs_src_path 中实际存在的文件。

  可以设置属性 File.content_string 或 File.content_bytes，它将优先于 abs_src_path。

  此外，abs_src_path 不再保证存在，可以为 None。MkDocs 本身在所有情况下仍然使用物理文件，但最终会出现不填充此属性的插件。

• 有一个新的构造函数 File.generated()，插件应使用它而不是 File() 构造函数。它更加方便，因为不需要手动查找 docs_dir 和 use_directory_urls 等值。其签名如下：

  f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
  f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)

  这样，现在从钩子中添加虚拟文件变得非常容易：

  def on_files(files: Files, config: MkDocsConfig):
      files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))

  对于大量内容，仍然最好使用物理文件，但不再需要通过提供一个未使用的假 docs_dir 来操作路径。

• 有一个新的属性 File.generated_by，这是通过约定产生的——对于生成的文件，应将其设置为生成该文件的插件名称（plugins: 集合中的键）。使用 File.generated() 构造函数时，此属性会自动填充。

• 可以设置 File 的 edit_uri 属性，例如从插件或钩子中设置，使其与默认值（等于 src_uri）不同，这将在文档的编辑链接中反映出来。这很有用，因为有些页面不是由真实文件支持的，而是从其他源文件或脚本动态创建的。因此，钩子可以将 edit_uri 设置为相应的源文件或脚本。

• File 对象现在将其原始的 src_dir、dest_dir、use_directory_urls 值作为属性存储。

• File 的字段按需计算但会被缓存。只有上述三个属性是主要的，部分还包括 dest_uri。这样，例如可以覆盖 File 的 dest_uri，并且 abs_dest_path 将基于它计算。但是你需要先使用 del f.abs_dest_path 清除该属性，因为值会被缓存。

• File 实例现在是可哈希的（可以用作 dict 的键）。除非是同一个 File 实例，否则两个文件不再被视为“相等”。

其他变化：

• Files 对象内部存储 File 对象的方式已经重新设计，因此任何选择访问 Files._files 的插件都会收到弃用警告。

• 在自动推断 nav 时，Files 集合中 File 对象的顺序不再重要。它们会根据默认的字母顺序强制排序。

上下文：#3451, #3463

钩子和调试

• 钩子文件现在可以使用 import 语句导入相邻的 *.py 文件。以前只能通过 sys.path 变通方法实现。参见 文档 中的新提及。上下文：#3568

• 详细 -v 日志更详细地显示了插件事件的顺序——逐个显示每个调用的插件，而不仅仅是事件类型。上下文：#3444

弃用

• 不再支持 Python 3.7，正式支持 Python 3.12。上下文：#3429

• 主题配置文件 mkdocs_theme.yml 不再执行 YAML 标签。上下文：#3465

• 插件事件 on_page_read_source 被软弃用，因为总是有更好的替代方案（参见新的 File API 或仅 on_page_markdown，取决于所需的交互）。

  当多个插件/钩子应用此事件处理程序时，它们会相互覆盖，因此现在在这种情况下会有警告。

  参见 文档。上下文：#3503

API 弃用

• 不再允许将 File.page 设置为 Page 或其子类以外的类型。上下文：#3443 - 遵循 1.5.3 版本中的弃用和 #3381。

• Theme._vars 已弃用 - 请使用 theme['foo'] 而不是 theme._vars['foo']

• utils: 移除了 modified_time(), get_html_path(), get_url_path(), is_html_file(), is_template_file()。path_to_url() 已被弃用。

• LiveReloadServer.watch() 不再接受自定义回调。

上下文: #3429

杂项

• sitemap.xml.gz 文件的可重复性略有提高，不再在每次构建时更改，而是每天仅在日期更改时更新一次。上下文: #3460

其他小改进；参见 提交日志。

版本 1.5.3 (2023-09-18)

• 修复 mkdocs serve 在快速导航时有时会锁定所有浏览器标签的问题 (#3390)

• 为 "search" 插件添加了许多新的支持语言 - 更新 lunr-languages 至 1.12.0 (#3334)

• 错误修复 (1.5.0 中的回归): 在 "readthedocs" 主题中，嵌套页面的 "breadcrumb navigation" 样式被破坏 (#3383)

• 内置主题现在也支持繁体中文（台湾）语言 (#3154)

• 插件现在可以将 File.page 设置为自己的 Page 子类。如果 File.page 被设置为 Page 的严格子类以外的任何内容，现在也会发出警告。(#3367, #3381)

  请注意，仅实例化一个 Page 会自动设置文件，因此需要小心不要创建不必要的 Page。

其他小改进；参见 提交日志。

版本 1.5.2 (2023-08-02)

• 错误修复 (1.5.0 中的回归): 恢复 --no-livereload 的功能。(#3320)

• 错误修复 (1.5.0 中的回归): 新的页面标题检测有时无法删除锚链接 - 修复此问题。(#3325)

• 部分恢复 1.5 之前的 API: extra_javascript 项将再次主要是字符串，只有在使用额外的 script 功能时才会是 ExtraScriptValue。

  插件可以自由地将字符串附加到 config.extra_javascript，但在读取值时，仍必须确保在值为 ExtraScriptValue 项时读取为 str(value)。对于查询诸如 .type 之类的属性，您需要首先检查 isinstance。静态类型检查将引导您完成此操作。(#3324)

参见 提交日志。

版本 1.5.1 (2023-07-28)

• 错误修复 (1.5.0 中的回归): 使 ExtraScriptValue 可以作为路径处理。这使得一些插件尽管有破坏性更改仍能正常工作。

• 错误修复 (1.5.0 中的回归): 防止特殊设置出现错误，例如 index.html、index.md 和 README.md 三个冲突文件 (#3314)

参见 提交日志。

版本 1.5.0 (2023-07-26)

新命令 mkdocs get-deps

此命令猜测 MkDocs 站点构建所需的 Python 依赖项。它仅打印需要安装的 PyPI 包。在终端中，它可以与安装命令直接组合如下：

pip install $(mkdocs get-deps)

这个想法是，在运行此命令后，您可以直接继续执行 mkdocs build，它几乎总是“直接工作”，无需考虑要安装哪些依赖项。

它的工作原理是通过扫描 mkdocs.yml 中的 themes:、plugins:、markdown_extensions: 项，并根据一个大型已知项目列表（目录，见下文）进行反向查找。

当然，欢迎您使用这样的命令与“虚拟环境”结合使用。另请注意，对于需要稳定性的环境（例如 CI），直接以这种方式安装依赖项并不是非常可靠的方法，因为它排除了依赖项固定。

该命令允许覆盖使用的配置文件（而不是当前目录中的 mkdocs.yml）以及使用的项目目录（而不是从默认位置下载）。参见 mkdocs get-deps --help。

上下文: #3205

MkDocs 有一个官方插件目录

查看 https://github.com/mkdocs/catalog 并添加您的所有通用插件、主题和扩展，以便可以通过 mkdocs get-deps 查找它们。

此目录从“best-of-mkdocs”重命名并进行了重大更新。除了 pip 安装命令外，页面现在还显示了添加插件所需的基本配置样板。

扩展链接验证

Markdown 中的验证链接

如您所知，在 Markdown 中，MkDocs 实际上只识别指向另一个物理 *.md 文档（或媒体文件）的相对链接。这是一个很好的惯例，因为源页面在没有 MkDocs 的情况下也可以自由浏览，例如在 GitHub 上。MkDocs 知道在输出中应将这些 *.md 链接适当地转换为 *.html，并且如果这样的链接实际上没有指向现有文件，它也会始终告知您。 然而，链接的检查实际上非常宽松，存在许多妥协。例如，以 / 开头的链接（“绝对”链接）和以 / 结尾的链接被原样保留，且未显示任何警告，这使得这些非常脆弱的链接得以潜入站点源码：这些链接目前恰好有效，但未经过验证，并且在启用 use_directory_urls 时，需要额外增加一层 ..，这令人困惑。

现在，除了验证相对链接外，MkDocs 还会对未识别类型的链接（包括绝对链接）打印 INFO 消息。它们看起来像这样：

INFO - 文档文件 'example.md' 包含一个绝对链接 '/foo/bar/'，它被原样保留。你是否意指 'foo/bar.md'？

如果你不希望有任何更改，甚至不希望显示 INFO 消息，并且希望恢复到 MkDocs 1.4 的静默状态，请在 mkdocs.yml 中添加以下配置（不推荐）：

validation:
  absolute_links: ignore
  unrecognized_links: ignore

相反，如果你希望这些链接打印 WARNING 消息并导致 mkdocs build --strict 失败，建议你将这些配置为 warn。

有关实际推荐的设置和更多详细信息，请参阅文档。上下文：#3283

导航中的链接验证

nav 配置中的文档链接现在也可以进行可配置的验证，尽管默认设置没有变化。

欢迎你为那些被遗忘并排除在导航之外的文件开启验证。例如：

validation:
  nav:
    omitted_files: warn
    absolute_links: warn

这可以使以下消息以 WARNING 级别出现（与之前仅有的 INFO 选项相反），从而被 mkdocs --strict 捕获：

INFO - 以下页面存在于文档目录中，但未包含在 "nav" 配置中：...

参见文档。上下文：#3283, #1755

将文档标记为有意“不在导航中”

新增了一个配置 not_in_nav。通过它，你可以将特定模式的文件标记为免于上述 omitted_files 警告类型；这些文件将不再打印任何消息。（作为推论，将此配置设置为 * 与完全忽略 omitted_files 效果相同。）

如果你通常喜欢这些关于导航中被遗忘文件的警告，但仍有一些页面是你有意排除在导航之外，并且只想构建和复制它们，这将非常有用。

not_in_nav 配置是一组类似 gitignore 的模式。有关另一个此类配置的解释，请参见下一节。

参见文档。上下文：#3224, #1888

排除的文档文件

新增了一个配置 exclude_docs，它告诉 MkDocs 忽略 docs_dir 下的某些文件，并且不将它们作为构建的一部分复制到生成的 site 目录中。

历史上，MkDocs 总是忽略以点开头的文件名，仅此而已。现在，这一切都是可配置的：你可以取消忽略这些文件，或者忽略更多模式的文件。

exclude_docs 配置遵循 .gitignore 模式格式，并以多行 YAML 字符串形式指定。例如：

exclude_docs: |
  *.py               # 排除例如 docs/hooks/foo.py
  /requirements.txt  # 排除 docs/requirements.txt

链接的验证（如上所述）也会受到 exclude_docs 的影响。在 mkdocs serve 期间，消息会解释这种交互，而在 mkdocs build 期间，被排除的文件如同不存在一样。

作为一项额外的相关更改，如果你需要在目录中同时拥有 README.md 和 index.md 文件，但只想发布其中一个，你现在可以使用此功能显式忽略其中一个，从而避免警告。

参见文档。上下文：#3224

草稿

警告：从版本 1.6 中移除：

exclude_docs 配置不再适用于 mkdocs serve 的“草稿”功能。此功能已重命名为 draft_docs。

exclude_docs 配置还有另一个行为：所有被排除的 Markdown 页面仍然可以在 mkdocs serve 中预览，只是在顶部会有一个“DRAFT”标记。当然，它们会在 mkdocs build 或 gh-deploy 中被排除。

如果你不希望 mkdocs serve 有任何特殊行为，而是希望它执行完全正常的构建，请使用新的标志 mkdocs serve --clean。

参见文档。上下文：#3224

mkdocs serve 不再在构建错误后退出

如果在站点重新构建期间发生错误（来自配置或插件），mkdocs serve 过去会在打印堆栈跟踪后退出。现在，它将简单地冻结服务器，直到作者编辑文件以解决问题，然后将继续重新加载。 但是首次构建时的错误仍然会导致 mkdocs serve 像以前一样退出。

上下文: #3255

页面标题将根据任何样式的标题推断

MkDocs 一直具备根据文档的第一行推断页面标题的能力（如果未在 nav 中指定），前提是该行包含一个必须以字符 # 开头的 <h1> 标题。现在，任何样式的 Markdown 标题都能被理解（#1886）。由于之前的解析过于简单，也无法在第一个标题中使用 attr_list 属性（#3136）。现在这个问题也得到了修复。

Markdown 扩展可以使用相对于当前文档的路径

这主要针对 pymdownx.snippets 或 markdown_include.include 等扩展：现在可以指定它们的包含路径相对于当前渲染的 Markdown 文档，或相对于 docs_dir。其他任何扩展当然也可以利用新的 !relative YAML 标签。

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative

参见 文档。上下文: #2154, #3258

<script> 标签可以指定 type="module" 和其他属性

在 extra_javascript 中，如果你使用 .mjs 文件扩展名或显式指定 type: module 键，脚本将以 type="module" 属性添加。defer: true 和 async: true 键也可用。

参见 extra_javascript 的 更新文档。

首先，这仅在内置主题中支持，其他主题需要跟进，见下文。

上下文: #3237

主题开发者变更（需要采取行动！）

使用构造 {% for script in extra_javascript %} 现已完全过时，因为它无法允许自定义 <script> 标签的属性。它将继续工作，但会阻止 MkDocs 的一些功能。

相反，你现在需要使用 config.extra_javascript（这已经有一段时间了），并结合新的 script_tag 过滤器：

    {%- for script in config.extra_javascript %}
      {{ script | script_tag }}
    {%- endfor %}

参见 文档。

插件开发者升级

• 重大变更：config.extra_javascript 不再是一个简单的字符串列表，而是一个 ExtraScriptValue 项的列表。因此，你不能再将列表值视为字符串。如果你想保持与旧版本的兼容性，只需始终将项引用为 str(item)。如果你愿意，仍然可以向列表中追加普通字符串。参见上述关于 <script> 标签的信息。上下文: #3237

• File 新增了一个属性 inclusion。其值根据 exclude_docs 和 not_in_nav 配置计算，并实现它们的行为。插件可以读取此值或写入它。默认情况下，新 File 实例遵循配置的指示，但插件可以选择为每个文件明确做出此决定。

• 创建 File 时，现在可以直接设置 dest_uri，而不必在创建后更新它（及其他依赖属性）。上下文

• 新增了一个配置选项 DictOfItems。与 ListOfItems 类似，它验证所有具有相同类型的配置选项映射。键是任意的，但始终是字符串。上下文: #3242

• 新增了一个函数 get_plugin_logger。为了选择一种标准化的方式让插件记录消息，请使用以下惯用法：

  log = mkdocs.plugins.get_plugin_logger(__name__)
  ...
  log.info("Hello, world")

  上下文: #3245

• SubConfig 配置选项可以方便地通过指定特定类型的配置进行子类化。例如，class ExtraScript(SubConfig[ExtraScriptValue]):。要了解这有何用处，请在代码中搜索此类。上下文

• 修复：SubConfig 存在一个错误，即路径（来自 FilesystemObject 选项）未按预期相对于主配置文件进行处理，因为 config_file_path 未正确继承到其中。现已修复。上下文: #3265

• Config 成员现在有一种避免与 Python 保留字冲突的方法。这是通过从每个成员名称中去除尾随的下划线来实现的。

  例如，添加一个 async 布尔选项，用户可以设置为 async: true，并以编程方式读取为 config.async_：

  class ExampleConfig(Config):
      async_ = Type(bool, default=False)

  以前，使用新样式模式无法创建具有保留名称的配置键。上下文 * Theme 已正确声明其属性，并新增了 theme.locale 和 theme.custom_dir 属性。

• 一些类型注解变得更加精确。例如：

  • context 参数获得了类型 TemplateContext (TypedDict)。上下文
  • Page、Section、Link 类现在有了一个共同的基类 StructureItem。上下文
  • 一些方法不再接受 Config，只接受原本预期的 MkDocsConfig。上下文
  • config.mdx_configs 获得了适当的类型。上下文：#3229

主题更新

• 内置主题大多不再依赖 <script defer>。这可能会影响 extra_javascript 的一些使用，主要是移除了对“页面是否完全加载”的自定义处理需求。上下文：#3237

• “mkdocs” 主题现在为 > 引用块添加了样式，之前它们完全没有区别。上下文：#3291

• “readthedocs” 主题根据上游更新至 v1.2.0，改进了 <kbd> 和面包屑导航的样式。上下文：#3058

• 两个内置主题的 highlight.js 版本更新至 11.8.0，jQuery 更新至 3.6.0。

错误修复

导航中的相对路径可以穿越根目录

1.2 版本中的回归问题 - 导航中的相对路径不再能够穿越站点根目录，并且被截断至根目录。尽管这种穿越不推荐并会产生警告，但这是一个已记录的行为。现在该行为已恢复。

上下文：#2752, #3010

MkDocs 可以接受来自 stdin 的配置

这可以用于动态配置覆盖。请参阅 配置继承 底部更新的部分。

使用此功能的命令是 mkdocs build -f -。在之前的版本中这样做会导致错误。

上下文

新的命令行标志

• mkdocs --no-color build 禁用颜色输出和行换行。此选项也可通过环境变量 NO_COLOR=true 实现。上下文：#3282
• mkdocs build --no-strict 将 strict 配置覆盖为 false。上下文：#3254
• mkdocs build -f -（如上所述）。
• mkdocs serve --clean（如上所述）。
• mkdocs serve --dirty 是 mkdocs serve --dirtyreload 的新名称。

弃用

• extra_javascript 经历了一次可能导致插件在罕见情况下中断的更改，主题开发者需要注意。请参阅上述相关条目。

• Python-Markdown 从 <3.4 中解绑。该版本已知会移除功能。如果你受到这些移除的影响，你仍然可以选择为自己固定版本：Markdown <3.4。上下文：#3222, #2892

• mkdocs.utils.warning_filter 现在显示关于弃用的警告。自 MkDocs 1.2 以来它没有任何作用。请考虑使用 get_plugin_logger 或在 mkdocs.plugins.* 下直接记录。上下文：#3008

• 访问 Theme 的 _vars 属性已被弃用 - 直接访问键即可。

• 访问 Config 的 user_configs 属性已被弃用。注意：请使用新的属性 config.theme.custom_dir 代替 config.user_configs[*]['theme']['custom_dir']。

其他小改进；请参阅 提交日志。

版本 1.4.3 (2023-05-02)

• 错误修复：对于 hooks 功能，模块在使用某些高级 Python 特性（如数据类）时不再加载失败 (#3193)

• 错误修复：如果页面没有填充的 URL，则不会创建 None 的站点地图条目 - 影响从导航中排除某些文件的站点 (07a297b)

• “readthedocs” 主题：

  • 可访问性：为 Home 标志 (#3129) 和搜索输入 (#3046) 添加 aria 标签
  • “readthedocs” 主题现在支持 hljs_style: 配置，与 “mkdocs” 主题相同 (#3199)

• 翻译：

  • 内置主题现在也支持印度尼西亚语 (#3154)
  • 修复了 zh_CN 翻译 (#3125)
  • tr_TR 翻译变为 tr - 使用应不受影响 (#3195)

请参阅 提交日志。

版本 1.4.2 (2022-11-01)

• 正式支持 Python 3.11 (#3020)

  提示： 只需升级到 Python 3.11 即可减少 10-15% 的站点构建时间。

• 支持同一插件的多个实例 (#3027)

  如果在 plugins: 配置下的列表中多次指定同一插件，这将创建两个（或更多）具有各自配置的插件实例。

  之前这种情况未被预见，因此存在错误。 现在，尽管这种方式有效，但默认情况下 MkDocs 仍会显示警告，除非插件添加了一个类变量 supports_multiple_instances = True。

• Bug修复（1.4.1 版本中的回归问题）：当插件将普通字符串放入 warnings 时不会出错 (#3016)

• Bug修复：相对链接始终会渲染为带有尾部斜杠的形式 (#3022)

  之前在 use_directory_urls 下，从子页面到主索引页的链接会渲染为例如 <a href="../..">，尽管在所有其他情况下链接看起来像 <a href="../../">。这导致了一些网页浏览器和服务器组合下的不期望行为。现在这个特殊情况错误已被移除。

• 内置的 "mkdocs" 主题现在也支持挪威语 (#3024)

• 与插件相关的警告看起来更易读 (#3016)

查看 提交日志。

版本 1.4.1 (2022-10-15)

• 支持主题命名空间插件加载 (#2998)

  插件的入口点可以命名为 'sometheme/someplugin'。这将产生以下结果：

  • 如果当前主题是 'sometheme'，插件 'sometheme/someplugin' 将始终优先于 'someplugin'。
  • 如果当前主题不是 'sometheme'，使用此插件的唯一方式是指定 plugins: [sometheme/someplugin]。

  也可以指定 plugins: ['/someplugin'] 而不是 plugins: ['someplugin']，以明确避免使用主题命名空间插件。

• Bug修复：mkdocs serve 在非 ASCII 路径和重定向下能正确工作 (#3001)

• Windows：'colorama' 现在是 MkDocs 的依赖项，以确保彩色日志输出 (#2987)

• 与插件相关的配置选项具有更可靠的验证和错误报告 (#2997)

• setup.py 的翻译子命令已被完全移除。请参阅文档 [1] [2] 了解其新的替代方式 (#2990)

• 'mkdocs' 包（wheel 和源码）现在由 Hatch 构建系统和 pyproject.toml 生成，而不是 setup.py (#2988)

其他小改进；查看 提交日志。

版本 1.4.0 (2022-09-27)

功能升级

钩子 (#2978)

新的 hooks: 配置允许你从本地 Python 文件中添加类似插件的事件处理器，而无需设置和安装实际的插件。

查看 文档。

edit_uri 灵活性 (#2927)

新增了 edit_uri_template: 配置。
它的工作方式类似于 edit_uri，但更普遍地涵盖了构建编辑 URL 的方式。
查看 文档。

此外，即使省略了 repo_url，edit_uri 功能现在也能完全正常工作 (#2928)

插件开发者升级

注意：此版本对插件及其配置的实现进行了重大更改。但目的是在所有合理常见的情况下不引入任何破坏性变化。或者至少如果需要代码修复，应该始终有一种方法可以与旧版本的 MkDocs 保持兼容。请报告此版本是否破坏了某些内容。

自定义插件事件处理器的执行顺序 (#2973)

插件现在可以选择为其事件处理器设置优先级值。这可以覆盖旧的行为，即对于每种事件类型，处理器按照它们在 plugins 配置 中出现的顺序被调用。

如果设置了此项，优先级较高的事件会先被调用。没有选择优先级的事件默认值为 0。具有相同优先级的事件按照它们在配置中出现的顺序排列。

推荐的优先级值：100 "最先"，50 "早期"，0 "默认"，-50 "晚期"，-100 "最后"。
随着不同的插件发现彼此之间更精确的关系，这些值应进一步调整。

查看 文档。

在 mkdocs serve 中跨构建持续的新事件 (#2972)

新增的事件是 on_startup 和 on_shutdown。它们在 mkdocs 调用的最开始和最后运行。
on_startup 还会接收有关 mkdocs 如何被调用的信息（例如 serve --dirtyreload）。

查看 文档。

替换 File.src_path 以避免处理反斜杠 (#2930)

属性 src_path 在 Windows 上使用反斜杠，这在虚拟路径中没有意义。
为了避免破坏性更改，此属性的使用方式没有变化，但现在你应该：

• 使用 File.src_uri 而不是 File.src_path
• 以及 File.dest_uri 而不是 File.dest_path。

这些一致地使用正斜杠，并且现在是 MkDocs 自身使用的确定性来源。 参见 源代码。

相关提示：您也应该停止使用 os.path.* 或 pathlib.Path() 来处理这些路径，而应改用 posixpath.* 或 pathlib.PurePosixPath()。

MkDocs 已类型注解，可与 mypy 配合使用 (#2941, #2970)

事件处理方法的类型注解 (#2931)

MkDocs 的插件事件方法现在具有类型注解。您可能已经为事件添加了注解，但现在它们将被验证以匹配原始定义。

参见 源代码 和 文档。

一个重大更新是，现在您应该更具体地注解方法参数为 config: defaults.MkDocsConfig 而不是 config: base.Config。这不仅明确了它是 MkDocs 自身的主配置，还通过对象属性提供了类型安全的访问（参见下一节）。

参见 源代码 和 文档。

重构 ConfigOption 模式为基于类的 (#2962)

在开发插件时，它接受的设置过去是在插件类的 config_scheme 变量中指定的。
现在这种方法已被软弃用，您应该在 base.Config 的子类中指定配置。

旧示例：

from mkdocs import plugins
from mkdocs.config import base, config_options

class MyPlugin(plugins.BasePlugin):
    config_scheme = (
        ('foo', config_options.Type(int)),
        ('bar', config_options.Type(str, default='')),
    )

    def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
        if self.config['foo'] < 5:
            if config['site_url'].startswith('http:'):
                return markdown + self.config['baz']

这段代码实际上有很多错误，但它会通过所有类型检查，静默运行，甚至在某些情况下成功。

因此，接下来是新的等效示例，改为新样式模式和基于属性的访问：
（添加了 "mypy" 的抱怨）

from mkdocs import plugins
from mkdocs.config import base, config_options as c

class MyPluginConfig(base.Config):
    foo = c.Optional(c.Type(int))
    bar = c.Type(str, default='')

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo < 5:  # 错误，`foo` 可能是 `None`，需要先检查。
            if config.site_url.startswith('http:'):  # 错误，MkDocs 的 `site_url` 也可能是 `None`。
                return markdown + self.config.baz  # 错误，没有这样的属性 `baz`！

这使您在运行代码之前就能注意到静态类型检查器发现的错误并修复它们：

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo is not None and self.config.foo < 5:  # 正确，`int < int` 是有效的。
            if (config.site_url or '').startswith('http:'):  # 正确，`str.startswith(str)` 是有效的。
                return markdown + self.config.bar  # 正确，`str + str` 是有效的。

参见 文档。

还要注意，我们必须显式地将配置属性 foo 标记为 Optional。
新样式的配置默认将所有属性标记为必需，并且不允许指定 required=False 或 required=True！

新增：config_options.Optional (#2962)

将某些内容包装到 Optional 中，概念上类似于“我希望默认值为 None”——而且您必须这样表达，因为写 default=None 实际上不起作用。

重大变更：移除了方法 BaseConfigOption.is_required()。请改用 .required。(#2938)
甚至 required 属性现在也应该很少使用。
对于基于类的配置，有一个新的定义来确定选项是否“必需”：

• 它没有默认值，并且
• 它没有被包装到 config_options.Optional 中。

新增：config_options.ListOfItems (#2938)

定义一个列表，其中的每个项目都必须符合相同的约束条件。有点像经过验证的 Type(list)。

如何表达整数列表的示例（使用 from mkdocs.config import config_options as c）：

描述	代码条目
必须指定	foo = c.ListOfItems(c.Type(int))
可选，默认值为 []	foo = c.ListOfItems(c.Type(int), default=[])
可选，默认值为 None	foo = c.Optional(c.ListOfItems(c.Type(int)))

参见更多 文档 中的示例。

更新：config_options.SubConfig (#2807)

SubConfig 过去会静默忽略其配置选项的所有验证。现在你应该向其传递 validate=True，或者直接使用新的基于类的配置，其中这已成为默认设置。

因此，它可以用于验证预定义了所有键且值类型严格验证的嵌套子字典。

参见 文档 中的示例。

其他配置选项的更改

URL 的默认值现在是 None 而不是 ''。这仍然可以通过相同的方式进行真值检查 - if config.some_url: (#2962)

FilesystemObject 不再是抽象的，可以直接使用，表示“文件或目录”，并可选地进行存在性检查 (#2938)

错误修复：

• 修复 SubConfig、ConfigItems、MarkdownExtensions 在不同实例之间泄漏值的问题 (#2916, #2290)
• SubConfig 在没有堆栈跟踪的情况下引发正确的验证错误类型 (#2938)
• 修复 config_options.Deprecated(moved_to) 中的点分隔重定向 (#2963)

调整了处理 ConfigOption.default 的逻辑 (#2938)

已弃用的配置选项类：ConfigItems (#2983)、OptionallyRequired (#2962)、RepoURL (#2927)

主题更新

• "MkDocs" 主题中的提示样式 (#2981)：

  • 更新颜色以增加对比度
  • 将提示样式也应用于 <details> 标签，以支持提供此功能的 Markdown 扩展（pymdownx.details、callouts）

• 内置主题现在还支持以下语言：

  • 俄语 (#2976)
  • 土耳其语（土耳其） (#2946)
  • 乌克兰语 (#2980)

未来兼容性

• extra_css: 和 extra_javascript: 警告如果传递了反斜杠 \。(#2930, #2984)

• 将 DeprecationWarning 显示为 INFO 消息。(#2907)

  如果你使用的插件或扩展依赖于其他库的已弃用功能，它在未来可能会面临破坏的风险。插件开发者应及时解决这些问题。

• 从 Python 3.10 开始避免依赖 importlib_metadata (#2959)

• 放弃对 Python 3.6 的支持 (#2948)

对公共 API 的不兼容更改

• mkdocs.utils：
  • create_media_urls 和 normalize_url 警告如果传递了反斜杠 \。(#2930)
  • is_markdown_file 停止接受大小写不敏感的变体，如 .MD，这是 MkDocs 构建已经操作的方式。(#2912)
  • 硬弃用：modified_time、reduce_list、get_html_path、get_url_path、is_html_file、is_template_file。(#2912)

其他

• 如果插件在 LiveReloadServer 中添加了路径到 watch，现在可以 unwatch 它们。(#2777)

• 错误修复（1.2 中的回归）：在 mkdocs serve 中支持监听 IPv6 地址。(#2951)

其他小改进；参见 提交日志。

版本 1.3.1 (2022-07-19)

• 将 Python-Markdown 版本固定为 <3.4，从而排除其最新版本，该版本破坏了太多外部扩展 (#2893)

• 当 Markdown 扩展加载失败时，打印其名称和回溯 (#2894)

• 修复 "readthedocs" 主题的错误（1.3.0 中的回归）：在面包屑中添加缺失的空格 (#2810)

• 错误修复：当存在文件 "readme.md"（小写）时不报错，否则不会被识别 (#2852)

• 内置主题现在还支持以下语言：

  • 意大利语 (#2860)

其他小改进；参见 提交日志。

版本 1.3.0 (2022-03-26)

功能升级

• 根据上游更新 ReadTheDocs 主题，从 v0.4.1 到 v1.0.0 (#2585)

  最显著的变化：

  • 新选项 logo：不再在标题中显示 site_name，而是可以指定一个图像路径来显示。
  • 新选项 anonymize_ip 用于 Google Analytics。
  • 依赖项升级：jQuery 升级到 3.6.0，Modernizr.js 被移除，以及其他。

  参见 主题配置选项的文档

• 内置主题现在还支持以下语言：

  • 德语 (#2633)
  • 波斯语（波斯语） (#2787)

• 支持在运行 mkdocs serve 时监视自定义目录 (#2642)

  MkDocs 默认监视 docs 目录和配置文件。现在有一种方法可以添加更多目录来监视更改，可以通过 YAML watch 键或命令行标志 --watch 来实现。

  通常 MkDocs 不会进入任何其他目录（因此这个功能应该不是必需的），但某些插件和扩展可能会这样做。

  参见 文档。

• gh_deploy 的新选项 --no-history (#2594)

  允许在部署时丢弃提交历史，并用一个根提交替换它

错误修复

• 修复了在使用内置主题的搜索功能时的XSS漏洞 (#2791)

• 设置 edit_uri 选项不再错误地在 repo_url 后添加尾部斜杠 (#2733)

杂项

• 重大变更：长期弃用的 pages 配置选项现在在使用时会导致错误 (#2652)

  要修复此错误，只需将 pages 更改为 nav。

• 性能优化：在 MkDocs 启动期间，不会导入其他命令的代码和依赖项 (#2714)

  最明显的效果是，使用 mkdocs build 时不会导入 mkdocs serve 的依赖项。

• 递归验证 nav (#2680)

  嵌套的 nav 结构的验证已重新设计，以尽早可靠地报告错误。一些边缘情况已被声明为无效。

其他小改进；请参阅提交日志。

版本 1.2.4 (2022-03-26)

• 兼容 Jinja2 3.1.0 (#2800)

  由于 Jinja2 中的重大变更，MkDocs 会崩溃并显示消息 AttributeError: module 'jinja2' has no attribute 'contextfilter'

版本 1.2.3 (2021-10-12)

• 内置主题现在也支持以下语言：

  • 简体中文 (#2497)
  • 日语 (#2525)
  • 巴西葡萄牙语 (#2535)
  • 西班牙语 (#2545, 之前 #2396)

• 第三方插件将优先于同名的内置插件 (#2591)

• 错误修复：修复加载某些语言翻译的能力：核心支持 (#2565) 和搜索插件支持与回退 (#2602)

• 错误修复（1.2 中的回归）：防止开发服务器中的目录遍历 (#2604)

• 错误修复（1.2 中的回归）：防止在严格模式下将 Web 服务器警告视为构建失败 (#2607)

• 错误修复：在 Windows 终端中正确打印彩色消息 (#2606)

• 错误修复：在 --version 中错误显示 Python 版本 3.10 (#2618)

其他小改进；请参阅提交日志。

版本 1.2.2 (2021-07-18)

• 错误修复（1.2 中的回归）：修复提供包含 Unicode 字符的文件/路径 (#2464)

• 错误修复（1.2 中的回归）：恢复使用轮询观察器进行 livereload 文件监视 (#2477)

  这是为了合理支持跨越虚拟文件系统的使用情况，例如非本机 Docker 和网络挂载。

  这回到了轮询方法，与之前一直使用的方法非常相似，意味着大多数相同的延迟和 CPU 使用率的缺点。

• 恢复 1.2 中的更改：移除对 site_url 配置的要求和对 use_directory_urls 的限制 (#2490)

• 错误修复（1.2 中的回归）：在 mkdocs serve 服务器中提供目录索引时，不再要求 URL 末尾有斜杠 (#2507)

  不再显示 404 错误，而是检测它是否是目录并重定向到添加了尾部斜杠的路径，就像之前一样。

• 错误修复：修复当前目录中配置文件的 gh_deploy (#2481)

• 错误修复：修复 "readthedocs" 主题中的面包屑顺序 (#2179)

• 当未传递 '--config' 时，允许使用 "mkdocs.yaml" 作为文件名 (#2478)

• 停止将 ";" 视为 URL 中的特殊字符：urlparse -> urlsplit (#2502)

• 提高包含许多页面的站点的构建性能（部分已在 1.2 中完成）(#2407)

版本 1.2.1 (2021-06-09)

• 错误修复（1.2 中的回归）：确保 'gh-deploy' 始终推送。

版本 1.2 (2021-06-04)

版本 1.2 的主要新增功能

增加了对主题本地化的支持 (#2299)

mkdocs 和 readthedocs 主题现在支持使用 theme.locale 参数进行语言本地化，默认值为 en（英语）。此版本中唯一支持的其他语言是 fr（法语）和 es（西班牙语）。有关使用提供的翻译的详细信息，请参阅用户指南。请注意，翻译不会默认发生。用户必须首先使用以下命令安装必要的依赖项：

pip install 'mkdocs[i18n]'

欢迎贡献翻译，详细信息请参阅翻译指南。

第三方主题的开发者可能希望查看主题开发指南的相关部分。

更新内置主题模板的贡献者应查看贡献指南。

search 插件的 lang 设置现在默认使用 theme.locale 中指定的语言。

增加了对配置文件中环境变量的支持 (#1954)

现在可以在配置文件中指定环境变量。 !ENV 标签。变量的值将由 YAML 解析器解析并转换为适当类型。

somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']

有关详细信息，请参阅配置文档中的环境变量。

配置继承支持已添加 (#2218)

配置文件现在可以继承自父配置文件。在主文件中，将 INHERIT 键设置为父文件的相对路径。

INHERIT: path/to/base.yml

然后，这两个文件将被深度合并。有关详细信息，请参阅配置继承。

更新 gh-deploy 命令 (#2170)

已将嵌入（并修改）的 ghp_import 副本替换为对上游库的依赖。从 1.0.0 版本开始，ghp-import 包含一个 Python API，可以直接调用。

MkDocs 现在可以受益于最近的错误修复和新功能，包括以下内容：

• 部署到 GitHub Pages 时会自动包含一个 .nojekyll 文件。
• 现在可以使用 --shell 标志，据报道在 Windows 上效果更好。
• 应尊重 Git 作者和提交者环境变量 (#1383)。

重构 mkdocs serve 的自动重载和 HTTP 服务器 (#2385)

mkdocs serve 现在使用基于标准库 http.server 和 watchdog 的新底层服务器 + 文件监视器实现。它提供了与之前使用的 livereload 库类似的功能（现在已从依赖项中删除，连同 tornado）。

这使得重载在响应时间和一致性方面更加灵敏。多个快速文件更改不再导致站点反复重建（问题 #2061）。

服务器的几乎每个方面都略有不同，但实际可见的变化很小。日志输出仅与旧的相似。预期不会出现行为退化，如果发现，应报告。

根据 site_url 的子路径偏移本地站点根目录 (#2424)

当使用 mkdocs serve 并将 site_url 指定为例如 http://example.org/sub/path/ 时，现在本地服务的站点根目录变为 http://127.0.0.1:8000/sub/path/，所有文档路径也相应偏移。

添加了 build_error 事件 (#2103)

插件开发者现在可以使用 on_build_error 钩子在构建站点时发生异常时执行代码。

有关详细信息，请参阅插件文档中的 on_build_error。

三个新异常：BuildError、PluginError 和 Abort (#2103)

MkDocs 现在在 mkdocs.exceptions 中定义了三个新异常：BuildError、PluginError 和 Abort：

• PluginError 可以从插件中引发，以停止构建并记录错误消息 而不显示回溯。
• BuildError 不应由第三方插件开发者使用，仅保留供内部使用。
• Abort 用于内部中止构建并显示错误而不显示回溯。

有关详细信息，请参阅插件文档中的 处理错误。

搜索索引策略配置

用户现在可以指定在为其站点建立索引时希望使用的策略。用户可以在以下选项中进行选择：

• full ：将页面标题、章节标题和全文添加到搜索索引中。
• sections ：仅将页面标题和章节标题添加到搜索索引中。
• titles ：仅将页面标题添加到搜索索引中。

有关详细信息，请参阅配置文档中的 搜索索引。

1.2 中的向后不兼容更改

• site_url 配置选项现在必需。如果未设置，将发出警告。在未来的版本中将引发错误 (#2189)。

  use_directory_urls 配置选项将在 site_url 设置为空字符串时强制为 false。在这种情况下，如果 use_directory_urls 未显式设置为 false，将发出警告 (#2189)。

  注意：这在 1.2.2 版本中已恢复

• google_analytics 配置选项已弃用，因为 Google 似乎正在逐步淘汰它，转而支持其新的 Google Analytics 4 属性。请参阅主题文档以获取替代方案，这些替代方案可以作为主题配置的一部分进行配置。例如，mkdocs 和 readthedocs 主题各自添加了一个新的 theme.analytics.gtag 配置选项，该选项使用新的 Google Analytics 4 属性。请参阅 Google 的文档，了解如何 升级到 Google Analytics 4 属性。然后，将 theme.analytics.gtag 设置为 "G-" ID，并删除包含 "UA-" ID 的 google_analytics 配置选项。只要旧的 "UA-" ID 和新的 "G-" ID 在您的 Google 账户中正确关联，并且您使用的是 "G-" ID，Google Analytics 就会将数据以旧格式和新格式提供。详见 #2252。

• 在使用 --livereload 服务器时，主题文件现在默认被排除在监视文件列表之外。这一新的默认行为是大多数用户所需要的，并且在编辑站点内容时提供了更好的性能。主题开发者可以使用 --watch-theme 选项启用旧行为。（#2092）

• mkdocs 主题现在在打印页面时移除侧边栏。这为更好地渲染表格等内容释放了水平空间（#2193）。

• mkdocs.config.DEFAULT_SCHEMA 全局变量已被替换为函数 mkdocs.config.defaults.get_schema()，以确保每个配置实例都是唯一的（#2289）。

• mkdocs.utils.warning_filter 已被弃用，现在没有任何作用。插件应删除对其的任何引用，因为它可能在未来的版本中被删除。为了确保任何警告被计数，只需将其记录到 mkdocs 日志中（即：mkdocs.plugins.pluginname）。

• on_serve 事件（接收 server 对象和 builder 函数）受到服务器重写的影响。server 现在是一个 mkdocs.livereload.LiveReloadServer，而不是 livereload.server.Server。插件通常可以对这些对象执行的操作是调用 server.watch(some_dir, builder)，这基本上是将该目录添加到监视目录中，导致站点在文件更改时重建。这仍然有效，但将任何其他函数传递给 watch 已被弃用并显示警告。第二个参数已经是可选的，并且只会接受这个确切的 builder 函数以保持兼容性。

• plugins.search.prebuild_index 配置选项的 python 方法自版本 1.2 起已待弃用。预计在版本 1.3 中使用时会发出警告，在版本 1.4 中会引发错误。建议用户使用其他方法生成搜索的预构建索引。

• lunr 和 lunr[languages] 依赖项不再默认安装。这些依赖项仅对那些预构建搜索索引并使用 python 选项的罕见用户需要，而该选项现已待弃用。如果您使用此功能，则需要手动安装 lunr 和 lunr[languages]。如果需要这些依赖项但未安装，则会发出警告。

版本 1.2 的其他更改和新增内容

• 修复：在过滤章节时，正确处理 _get_by_type 中的导航子项（#2203）。
• 正式支持 Python 3.9，并放弃对 Python 3.5 的支持。
• 修复：修复了在 ReadTheDocs 主题中导航项部分截断的问题（#2297）。
• Structure Files 对象现在有一个 remove 方法，以帮助插件开发者操作 Files 树。相应的 src_paths 已成为一个属性，以适应这种可能的动态行为。详见 #2305。
• 将 highlight.js 更新至 10.5.0。详见 #2313。
• 修复：搜索插件现在支持日语。详见 #2178。
• 文档已重构（#1629）。
• 恢复 readthedocs 主题中表格的样式（#2028）。
• 确保 site_url 以斜杠结尾（#1785）。
• 修正 pages 模板上下文变量的文档（#1736）。
• 将 lunr 依赖项更新至 0.5.9，并将 lunr.js 更新至相应的 2.3.9 版本（#2306）。
• 日志消息现在使用颜色来区分错误、警告和调试消息。
• 修复：当 use_directory_urls 为 False 时识别主页（#2362）。

版本 1.1.2 (2020-05-14)

• 修复：规范化 IP 地址并将不支持的地址错误更改为警告（#2108）。

版本 1.1.1 (2020-05-12)

• 修复：通过支持 SOURCE_DATE_EPOCH 环境变量，使压缩的站点地图具有确定性（#2100）。
• 修复：即使 use_directory_urls 为 false，也使用 README.md 作为 index.html（#2081）。
• 修复：忽略以反斜杠开头的链接（#1680）。
• 修复：将 builder 传递给 on_serve 事件，以便插件可以将其传递给 server.watch（#1952）。
• 错误修复：使用 lunr[languages]==0.5.8 以避免 nltk 不兼容问题 (#2062)。
• 错误修复：确保 wheel 仅适用于 Python 3 (#2021)。
• 错误修复：清理 dev_addr 验证并禁止使用 0.0.0.0 (#2022)。
• 添加对搜索插件的 min_search_length 参数的支持 (#2014)。
• 错误修复：readthedocs 主题的 code 颜色 (#2027)。

版本 1.1 (2020-02-22)

版本 1.1 的主要新增功能

支持 Lunr.py 作为 prebuild_index 引擎

Mkdocs 现在支持使用 Lunr.py 预构建索引，Lunr.py 是 Lunr.js 的纯 Python 实现，允许用户在需要时避免安装 NodeJS 环境。更多信息请阅读 prebuild_index 文档。

readthedocs 主题更新至上游版本 (#588 和 #1374)

readthedocs 主题现在更接近 [上游] Sphinx 主题（版本 0.4.1）。添加了许多新的主题配置设置，这些设置反映了上游的配置选项。详情请参阅 主题文档。

更新 mkdocs 主题至 Bootswatch 4.1.3 (#1563)

mkdocs 主题现在支持 Bootswatch 4.1 的所有功能。此外，在此更新中更改了 2 个文件名。如果您使用的是继承自 mkdocs 主题的主题，主题开发者可能需要按如下方式更新这些文件名。

css/bootstrap-custom.min.css => css/bootstrap.min.css
js/bootstrap-3.0.3.min.js => js/bootstrap.min.js

改进了命令行上的配置支持 (#1401)

build、serve 和 gh-deploy 子命令现在支持控制是否创建 目录 URL 的标志：--use-directory-urls / --no-directory-urls。此外，gh-deploy 子命令现在支持 build 和 serve 的所有配置选项，添加了 --strict、--theme、--theme-dir 和 --site-dir。

更新了 lunr-languages 支持 (#1729)

lunr-languages 插件已更新至 1.4.0，添加了对阿拉伯语 (ar) 和越南语 (vi) 的支持。此外，荷兰语和日语的语言代码已更改为标准值：nl 和 ja。旧的语言代码 (du 和 jp) 仍作为别名保留，但可能会在 MkDocs 的未来版本中移除。

版本 1.1 的其他更改和新增功能

• 错误修复：确保主题中的嵌套点文件被忽略并记录行为 (#1981)。
• 更新最低依赖至 Markdown 3.2.1。
• 更新最低依赖至 Jinja 2.10.1 以解决安全问题 (#1780)。
• 更新至 lunr.js 2.3.8 (#1989)。
• 添加对 Python 3.8 的支持。
• 放弃对 Python 3.4 的支持。
• 放弃对 Python 2.7 的支持。MkDocs 现在仅支持 PY3 (#1926)。
• 错误修复：在 Windows 上为 Python 3.8+ 选择适当的 asyncio 事件循环 (#1885)。
• 错误修复：确保嵌套的索引页面不会被识别为主页 (#1919)。
• 错误修复：正确识别部署版本 (#1879)。
• 错误修复：正确构建 custom_dir 的 ValidationError 消息 (#1849)。
• 错误修复：从主题中排除 Markdown 文件和 README 文件 (#1766)。
• 错误修复：考虑编码的 URL (#1670)。
• 错误修复：确保主题文件不会覆盖 docs_dir 文件 (#1671)。
• 错误修复：不要规范化 URL 片段 (#1655)。
• 错误修复：在 sitemap.xml 中跳过外部 URL (#1742)。
• 错误修复：确保主题文件不会在 Windows 上覆盖 docs_dir 文件 (#1876)。
• 在 readthedocs 主题中添加 canonical 标签 (#1669)。
• 改进了 git 不可用时的错误消息。
• 添加对 mkdocs 主题的 nav_style 主题选项的支持 (#1930)。
• 错误修复：mkdocs 主题中的长/嵌套下拉菜单现在行为更加一致 (#1234)。
• 错误修复：mkdocs 主题中的多行导航标题不再遮挡文档内容 (#716)。
• 添加对 mkdocs 主题的 navigation_depth 主题选项的支持 (#1970)。
• page.toc 项目中的 level 属性现在是 1 索引的，以匹配 <hN> 标签中的级别 (#1970)。

版本 1.0.4 (2018-09-07)

• 错误修复：忽略 Markdown 中的绝对链接 (#1621)。

版本 1.0.3 (2018-08-29)

• 错误修复：在导航中警告相对路径 (#1604)。
• 错误修复：正确处理空的 theme_config.yml 文件 (#1602)。

版本 1.0.2 (2018-08-22)

• 错误修复：为错误模板提供绝对的 base_url (#1598)。

版本 1.0.1 (2018-08-13)

• 错误修复：在搜索框中按下 [Enter] 时防止页面重新加载 (#1589)。
• 错误修复：在所有资产准备就绪之前避免调用 search (#1584)。
• 错误修复：如果存在 index.md，则排除 README.md (#1580)。
• 错误修复：修复 readthedocs 主题中主页的导航错误 (#1576)。

版本 1.0（2018-08-03）

版本 1.0 的主要新增内容

页面、文件和导航的内部重构

页面、文件和导航的内部处理已完全重构。重构中包含的更改总结如下。

• 支持隐藏页面。所有 Markdown 页面现在都会被包含在构建中，无论它们是否包含在导航配置中（#699）。
• 导航现在可以包含指向外部站点的链接（#989 #1373 & #1406）。
• 在渲染任何页面之前，所有页面的页面数据（包括标题）都已正确确定（#1347）。
• 自动填充的导航现在将索引页面排在顶部。换句话说，索引页面将作为目录的第一个子项列出，而所有其他文档在索引页面之后按文件名按字母数字顺序排序（#73 & #1042）。
• 现在，README.md 文件在目录中被视为索引文件，并将被渲染为 index.html（#608）。
• 所有文件的 URL 都被计算一次并存储在文件集合中。这确保所有内部链接始终正确计算，无论配置如何。这也允许验证所有内部链接，而不仅仅是其他 Markdown 页面的链接（#842 & #872）。
• 新增了一个 url 模板过滤器，智能地确保所有 URL 相对于当前页面（#1526）。
• 新增了一个 on_files 插件事件，可用于包含不在 docs_dir 中的文件、排除文件、重新定义页面 URL（即实现无扩展名 URL），或以其他各种方式操作文件。

向后不兼容的更改

作为内部重构的一部分，引入了一些向后不兼容的更改，总结如下。

当 use_directory_urls 为 False 时，URL 已更改

以前，所有 Markdown 页面都会被修改文件名以成为索引页面，无论 use_directory_urls 设置如何配置。然而，路径修改仅在 use_directory_urls 设置为 True（默认）时需要。当 use_directory_urls 设置为 False 时，路径修改不再发生，这将导致所有非索引文件的 URL 不同。由于此行为仅影响非默认配置，并且设置选项为 False 的最常见用户案例是用于本地文件系统（file://）浏览，因此不太可能影响大多数用户。但是，如果您在托管在 Web 服务器上的 MkDocs 站点中将 use_directory_urls 设置为 False，那么您的大多数 URL 现在都会失效。如您所见，新 URL 更加合理。

Markdown 文件	旧 URL	新 URL
index.md	index.html	index.html
foo.md	foo/index.html	foo.html
foo/bar.md	foo/bar/index.html	foo/bar.html

请注意，当 use_directory_urls 设置为 True（默认）时，URL 或文件路径没有变化，除了 MkDocs 在所有内部生成的 URL 上更一致地包含一个结尾斜杠。

pages 配置设置已重命名为 nav

pages 配置设置已被弃用，如果在配置文件中设置，将发出警告。该设置已重命名为 nav。要更新您的配置，只需将设置重命名为 nav。换句话说，如果您的配置如下所示：

pages:
  - Home: index.md
  - User Guide: user-guide.md

只需按如下方式编辑配置：

nav:
  - Home: index.md
  - User Guide: user-guide.md

在当前版本中，任何包含 pages 设置但没有 nav 设置的配置，pages 配置将被复制到 nav，并发出警告。然而，在未来的版本中，这可能不再发生。如果同时定义了 pages 和 nav，pages 设置将被忽略。

模板变量和 base_url

在 MkDocs 的早期版本中，一些 URL 期望 base_url 模板变量被添加到 URL 前面，而其他则不需要。这种不一致性已被移除，所有 URL 在添加到模板上下文之前都不会被修改。

例如，主题模板可能以前包含一个指向 site_name 的链接，如下所示：

<a href="{{ nav.homepage.url }}">{{ config.site_name }}</a>

MkDocs 会神奇地返回一个相对于当前页面的主页 URL。这种“魔法”已被移除，应使用 url 模板过滤器：

<a href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>

此更改适用于任何导航项和页面，以及 page.next_page 和 page.previous_page 属性。目前，这些属性仍将返回相对于当前页面的 URL，但建议使用 url 过滤器以确保未来兼容性。

extra_javascript 和 extra_css 变量继续像以前一样工作（不使用 url 模板过滤器），但它们已被弃用，相应的配置值（config.extra_javascript 和 config.extra_css）应改为使用过滤器。

{% for path in config.extra_css %}
    <link href="{{ path|url }}" rel="stylesheet">
{% endfor %}

请注意，导航现在可以包含指向外部站点的链接。显然，base_url 不应添加到这些项目中。然而，url 模板过滤器足够智能，能够识别 URL 是绝对的，并且不会对其进行更改。因此，所有导航项目都可以传递给过滤器，只有那些需要更改的项目才会被修改。

{% for nav_item in nav %}
    <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
{% endfor %}

基于路径的设置相对于配置文件 (#543)

以前，各种配置选项中的任何相对路径都是相对于当前工作目录解析的。现在，它们相对于配置文件解析。由于文档一直鼓励从包含配置文件的目录（项目根目录）运行各种 MkDocs 命令，这一更改不会影响大多数用户。然而，这将使实现自动化构建或从项目根目录以外的位置运行命令变得更加容易。

只需使用 -f/--config-file 选项并指向配置文件：

mkdocs build --config-file /path/to/my/config/file.yml

与之前一样，如果没有指定文件，MkDocs 会在当前工作目录中查找名为 mkdocs.yml 的文件。

添加对 YAML 元数据的支持 (#1542)

以前，MkDocs 仅支持 MultiMarkdown 风格的元数据，这种元数据不识别不同的数据类型，并且相当有限。现在，MkDocs 还支持 Markdown 文档中的 YAML 风格元数据。MkDocs 依赖于分隔符（--- 或 ...）的存在或不存在来确定是使用 YAML 风格元数据还是 MultiMarkdown 风格元数据。

以前，MkDocs 会在分隔符之间识别 MultiMarkdown 风格的元数据。现在，如果检测到分隔符，但分隔符之间的内容不是有效的 YAML 元数据，MkDocs 不会尝试将内容解析为 MultiMarkdown 风格的元数据。因此，MultiMarkdown 风格的元数据不得包含分隔符。有关详细信息，请参阅 MultiMarkdown 风格元数据文档。

在 0.17 版本之前，MkDocs 将所有元数据值作为字符串列表返回（即使只有一行也会返回一个包含一个字符串的列表）。在 0.17 版本中，该行为被更改为返回每个值作为一个字符串（多行被连接），一些用户发现这有限制（参见 #1471）。当前版本中，MultiMarkdown 风格的元数据继续保持这种行为。然而，YAML 风格的元数据支持全范围的“安全”YAML 数据类型。因此，建议任何复杂的元数据使用 YAML 风格（有关详细信息，请参阅 YAML 风格元数据文档）。事实上，未来的 MkDocs 版本可能会弃用对 MultiMarkdown 风格元数据的支持。

重构搜索插件

搜索插件已完全重构，以支持以下功能：

• 在浏览器中使用 Web Worker，并提供回退 (#1396)。
• 可选地在本地预构建搜索索引 (#859 & #1061)。
• 升级到 lunr.js 2.x (#1319)。
• 支持除英语以外的语言的搜索 (#826)。
• 允许用户定义单词分隔符 (#867)。
• 仅对长度 > 2 的查询运行搜索 (#1127)。
• 移除对 require.js 的依赖 (#1218)。
• 压缩搜索索引 (#1128)。

用户可以查看可用的 配置选项，主题作者应查看 [搜索和主题] 如何交互。

theme_dir 配置选项完全弃用

从 0.17 版本开始，custom_dir 选项取代了已弃用的 theme_dir 选项。如果用户设置了 theme_dir 选项，MkDocs 0.17 版本会将值复制到 theme.custom_dir 选项，并发出警告。从 1.0 版本开始，该值不再复制，并会引发错误。

版本 1.0 的其他更改和新增内容

• 键盘快捷键更改以避免与常用辅助功能快捷键冲突 (#1502)。
• 用户友好的 YAML 解析错误 (#1543)。
• 正式支持 Python 3.7。
• 缺少主题配置文件现在会引发错误。
• 空的 extra_css 和 extra_javascript 设置不再引发警告。
• 在内置主题中添加 highlight.js 配置设置（#1284）。
• 选择结果时关闭搜索模态框（#1527）。
• 为 AnchorLinks 添加 level 属性（#1272）。
• 在 gh-deploy 脚本中添加 MkDocs 版本检查（#640）。
• 改进 Markdown 扩展错误消息（#782）。
• 放弃对 Python 3.3 的官方支持，并设置 tornado>=5.0（#1427）。
• 添加对 GitLab 编辑链接的支持（#1435）。
• 在发布说明中链接到 GitHub 问题（#644）。
• 在 gh-deploy 提交消息中扩展 {sha} 和 {version}（#1410）。
• 压缩 sitemap.xml（#1130）。
• 延迟加载 JS 脚本（#1380）。
• 为搜索输入添加 title 属性（#1379）。
• 将 RespondJS 更新到最新版本（#1398）。
• 始终通过 HTTPS 加载 Google Analytics（#1397）。
• 提高滚动帧率（#1394）。
• 提供更多版本信息（#1393）。
• 重构 writing-your-docs.md（#1392）。
• 解决 Safari 缩放到小于 100% 时的 bug（#1389）。
• 移除向 body 添加 clicky 类和动画（#1387）。
• 防止搜索插件重新注入 extra_javascript 文件（#1388）。
• 重构 copy_media_files 实用函数以提高灵活性（#1370）。
• 移除 PyPI 部署文档（#1360）。
• 更新 Python-Markdown 库的链接（#1360）。
• 记录如何为 MkDocs 命令生成手册页（#686）。

版本 0.17.5（2018-07-06）

• 错误修复：修复 Python 3.7 和 PEP 479 不兼容问题（#1518）。

版本 0.17.4（2018-06-08）

• 错误修复：为 sitemap.xml 添加多级嵌套支持（#1482）。

版本 0.17.3（2018-03-07）

• 错误修复：设置依赖 tornado>=4.1,<5.0，由于 5.0 版本的变化（#1428）。

版本 0.17.2（2017-11-15）

• 错误修复：修正 extra_* 配置设置的回归问题（#1335 和 #1336）。

版本 0.17.1（2017-10-30）

• 错误修复：支持缺少结尾斜杠的 repo_url（#1321）。
• 错误修复：为 mkdocs.toc.TableOfContext 添加长度支持（#1325）。
• 错误修复：为第三方主题的搜索插件添加一些主题特定设置（#1316）。
• 错误修复：在本地服务器上使用 dev_addr 覆盖 site_url（#1317）。

版本 0.17.0（2017-10-19）

版本 0.17.0 的主要新增功能

插件 API（#206）

MkDocs 新增了一个 插件 API，允许用户定义自己的自定义行为。请参阅包含的文档以获取 API 的完整解释。

之前内置的搜索功能已被移除，并封装在一个名为 "search" 的插件中，行为保持不变。当 MkDocs 构建时，搜索索引现在被写入 search/search_index.json 而不是 mkdocs/search_index.json。如果在配置中未定义插件设置，则默认包含 search 插件。请参阅 配置 文档以了解如何覆盖默认设置。

主题自定义（#1164）

已添加对主题特定自定义的支持。主题作者可以定义默认选项，如 主题配置 中所述。主题现在可以从另一个主题继承，定义要渲染的各种静态模板，并定义任意默认变量以控制模板中的行为。主题配置在名为 mkdocs_theme.yml 的配置文件中定义，该文件应放置在模板文件的根目录中。如果未找到配置文件，将发出警告，并在未来的版本中引发错误。

用户可以在其 mkdocs.yml 配置文件的 theme 配置选项下覆盖这些默认值，该选项现在接受嵌套选项。其中一个嵌套选项是 custom_dir 选项，它取代了现已弃用的 theme_dir 选项。如果用户之前设置了 theme_dir 选项，将发出警告，并预计在未来的版本中引发错误。

如果配置之前定义了如下 theme_dir：

theme: mkdocs
theme_dir: custom

则配置应调整为：

theme:
  name: mkdocs
  custom_dir: custom

请参阅 theme 配置选项文档以获取详细信息。

已移除的已弃用模板变量（#1168）

页面模板

页面模板的主要入口点已从 base.html 更改为 main.html。这允许 base.html 继续存在，同时允许用户覆盖 main.html 并扩展 base.html。在版本 0.16 中，如果没有 main.html 模板，base.html 仍然有效，但会引发弃用警告。在版本 1.0 中，如果没有 main.html 模板，构建将失败。

上下文变量

模板上下文中的页面特定变量名称已根据 自定义主题 中的定义进行了重构。 旧变量名在0.16版本中发出警告，但在1.0版本中已被移除。

以下任何旧页面变量都应在用户创建和第三方模板中更新为新变量：

旧变量名	新变量名
current_page	page
page_title	page.title
content	page.content
toc	page.toc
meta	page.meta
canonical_url	page.canonical_url
previous_page	page.previous_page
next_page	page.next_page

此外，许多全局变量已被更改和/或移除，用户创建和第三方模板应按如下所述进行更新：

旧变量名	新变量名或表达式
current_page	page
include_nav	nav|length>1
include_next_prev	(page.next_page or page.previous_page)
site_name	config.site_name
site_author	config.site_author
page_description	config.site_description
repo_url	config.repo_url
repo_name	config.repo_name
site_url	config.site_url
copyright	config.copyright
google_analytics	config.google_analytics
homepage_url	nav.homepage.url
favicon	{{ base_url }}/img/favicon.ico

自动填充的 extra_css 和 extra_javascript 完全弃用。(#986)

在 MkDocs 的早期版本中，如果 extra_css 或 extra_javascript 配置设置为空，MkDocs 会扫描 docs_dir 并自动填充每个设置中找到的所有 CSS 和 JavaScript 文件。在 0.16 版本中，此行为已被弃用并发出警告。在 0.17 中，任何未列出的 CSS 和 JavaScript 文件将不会包含在 HTML 模板中，但会发出警告。换句话说，它们仍将被复制到 site-dir，但如果未明确列出，它们将不会对主题产生任何影响。

从现在开始，docs_dir 中的所有 CSS 和 JavaScript 文件都应明确列在 extra_css 或 extra_javascript 配置设置中。

其他对 0.17.0 版本的更改和添加

• 在 MkDocs 主题中添加“编辑链接”支持 (#1129)
• 使用 utf-8-sig 打开文件以处理 BOM (#1186)
• 符号链接现在一致地被跟随 (#1134)
• 在包含的主题中添加了对键盘导航快捷键的支持 (#1095)
• 对 config_options 进行了一些重构和改进 (#1296)
• 正式添加了对 Python 3.6 的支持 (#1296)
• 在 readthedocs 主题中添加了 404 错误页面 (#1296)
• 对 Markdown 处理进行了内部重构 (#713)
• 移除了对 mkdocs-bootstrap 和 mkdocs-bootswatch 主题的特殊错误消息 (#1168)
• 不再支持旧版页面配置 (#1168)
• 已移除已弃用的 json 命令 (#481)
• 已移除对 Python 2.6 的支持 (#165)
• 构建期间不再复制文件权限 (#1292)
• 在 edit_uri 中支持查询和片段字符串 (#1224 & #1273)

版本 0.16.3 (2017-04-04)

• 修复了 readthedocs 主题中自动滚动引起的错误 (#1177)
• 修复了一些文档拼写错误 (#1181 & #1185)
• 修复了 0.16.2 中引入的 livereload 服务器的回归问题 (#1174)

版本 0.16.2 (2017-03-13)

• 系统根目录 (/) 不是 site_dir 或 docs_dir 的有效路径 (#1161)
• 重构 readthedocs 主题导航 (#1155 & #1156)
• 添加了对开发服务器提供自定义错误页面的支持 (#1040)
• 确保错误页面上的 nav.homepage.url 不为空 (#1131)
• 将 livereload 依赖性增加到 2.5.1 (#1106)

版本 0.16.1 (2016-12-22)

• 确保滚动监听行为不影响导航栏 (#1094)
• 仅在用户明确请求时“加载”主题 (#1105)

版本 0.16 (2016-11-04)

0.16.0 版本的主要添加

模板变量重构。(#874)

页面上下文

模板上下文中的页面特定变量名已按 自定义主题 中定义进行重构。旧变量名将发出警告，但在 0.16 版本中仍将继续工作，但在未来版本中可能会被移除。

以下任何旧页面变量都应在用户创建和第三方模板中更新为新变量：

旧变量名	新变量名
current_page	page
page_title	page.title
content	page.content
toc	page.toc
meta	page.meta
canonical_url	page.canonical_url
previous_page	page.previous_page
next_page	page.next_page

全局上下文

此外，许多全局变量已被更改和/或弃用，用户创建和第三方模板应按如下所述进行更新：

以前，全局变量 include_nav 是根据导航中的页面数量以编程方式更改的。该变量将发出警告，但 继续为版本0.16工作，但在未来的版本中可能会被移除。请改用{% if nav|length>1 %}。

以前，全局变量include_next_prev会根据导航中的页面数量以编程方式进行更改。该变量将发出警告，但将继续在版本0.16中工作，但在未来的版本中可能会被移除。请改用{% if page.next_page or page.previous_page %}。

以前，全局变量page_description会根据当前页面是否为主页以编程方式进行更改。现在它直接映射到config['site_description']。请在模板中使用{% if page.is_homepage %}来有条件地更改描述。

全局变量homepage_url直接映射到nav.homepage.url，并且正在被弃用。该变量将发出警告，但将继续在版本0.16中工作，但在未来的版本中可能会被移除。请改用nav.homepage.url。

全局变量favicon映射到配置设置site_favicon。模板变量和配置设置都在被弃用，并将发出警告，但将继续在版本0.16中工作，并在未来的版本中可能会被移除。请在模板中使用{{ base_url }}/img/favicon.ico。用户只需将其自定义favicon图标保存到docs_dir或theme_dir中的img/favicon.ico即可。

许多变量直接映射到config中同名的变量。这些变量正在被弃用，并将发出警告，但将继续在版本0.16中工作，但在未来的版本中可能会被移除。请改用config.var_name，其中var_name是配置变量之一。

以下是全局上下文中所有更改的摘要：

旧变量名	新变量名或表达式
current_page	page
include_nav	nav|length>1
include_next_prev	(page.next_page or page.previous_page)
site_name	config.site_name
site_author	config.site_author
page_description	config.site_description
repo_url	config.repo_url
repo_name	config.repo_name
site_url	config.site_url
copyright	config.copyright
google_analytics	config.google_analytics
homepage_url	nav.homepage.url
favicon	{{ base_url }}/img/favicon.ico

增加了模板自定义功能。（#607）

内置主题已更新，将其各个部分包装在模板块中，允许使用theme_dir配置设置轻松覆盖每个单独的块。无需任何新设置，您可以使用不同的分析服务、替换默认搜索功能或更改导航行为等。有关更多详细信息，请参阅相关文档。

为了启用此功能，页面模板的主要入口点已从base.html更改为main.html。这允许base.html继续存在，同时允许用户覆盖main.html并扩展base.html。对于版本0.16，如果没有main.html模板，base.html将继续工作，但已被弃用并会发出警告。在版本1.0中，如果没有main.html模板，构建将失败。任何自定义和第三方模板都应相应更新。

第三方主题最简单的更新方式是简单地添加一个仅包含以下内容的main.html文件：

{% extends "base.html" %}

这样，主题包含main.html入口点，并且还支持以与内置主题相同的方式覆盖块。鼓励第三方主题将其模板中的各个部分包装在块中，以支持此类自定义。

自动填充的extra_css和extra_javascript已弃用。（#986）

在MkDocs的早期版本中，如果extra_css或extra_javascript配置设置为空，MkDocs会扫描docs_dir并自动填充每个设置中找到的所有CSS和JavaScript文件。此行为已被弃用，并将发出警告。在下一个版本中，自动填充功能将停止工作，任何未列出的CSS和JavaScript文件将不会包含在HTML模板中。换句话说，它们仍将被复制到site-dir，但如果未明确列出，它们将不会对主题产生任何影响。

docs_dir中的所有CSS和JavaScript文件应从现在开始在extra_css或extra_javascript配置设置中明确列出。

支持脏构建。（#990）

对于大型站点，创建页面所需的构建时间可能会变得有问题，因此创建了“脏”构建模式。此模式仅比较修改时间 生成的 HTML 和源 Markdown 文件。如果自 HTML 生成以来 Markdown 文件发生了变化，则页面会重新构建。否则，页面保持不变。此模式可以在 mkdocs serve 和 mkdocs build 命令中调用：

mkdocs serve --dirtyreload

mkdocs build --dirty

需要注意的是，这种构建页面的方法仅适用于内容的开发，因为导航和其他链接不会在其他页面上更新。

更严格的目录验证

以前，如果 site_dir 是 docs_dir 的子目录，则会发出警告。现在这会引发错误。此外，如果 docs_dir 被设置为包含配置文件的目录而不是其子目录，现在也会引发错误。您需要重新调整目录结构，以更好地符合文档化的 布局。

版本 0.16.0 的其他更改和新增内容

• 修复：在 Windows 上使用 Python 3 支持 gh-deploy 命令 (#722)
• 修复：在 Python 包构建中包含 .woff2 字体文件 (#894)
• 对文档首页/教程进行了各种更新和改进 (#870)
• 修复：支持配置文件更改的 livereload (#735)
• 修复：非媒体模板文件不再与媒体文件一起复制 (#807)
• 添加标志 (-e/--theme-dir)，以在 mkdocs build 和 mkdocs serve 命令中指定主题目录 (#832)
• 修复了在 Windows 和 Python 2 下 Unicode 文件名的问题 (#833)
• 改进了 MkDocs 主题中内联代码的样式 (#718)
• 修复：将变量转换为 JSON 传递给 JavaScript (#850)
• 更新了 ReadTheDocs 主题，以更接近上游字体大小和颜色 (#857)
• 修复了当鼠标远离它们时永久链接标记显示的问题 (#843)
• 修复：在自动创建页面配置时处理目录名称中的句点 (#728)
• 更新搜索到 Lunr 0.7，为较大文档带来了一些性能提升 (#859)
• 修复：支持 SOURCE_DATE_EPOCH 环境变量以实现“可重现”构建 (#938)
• 在复制媒体文件时遵循链接 (#869)
• 将“编辑于...”链接更改为直接指向源仓库中的文件，而不是仓库的根目录 (#975)，可通过新的 edit_uri 设置进行配置。
• 修复：如果未在 CLI 上指定，则不覆盖严格模式的配置值 (#738)
• 为 gh-deploy 命令添加 --force 标志，以强制推送到仓库 (#973)
• 改进了 readthedocs 主题中当前选定菜单项的对齐方式 (#888)
• http://user.github.io/repo => https://user.github.io/repo/ (#1029)
• 改进了安装说明 (#1028)
• 考虑宽表格并一致地包裹内联代码段 (#834)
• 修复：在错误模板中使用绝对 URL 进行导航和媒体链接 (#77)

版本 0.15.3 (2016-02-18)

• 改进了当给定主题无法找到时的错误消息。
• 修复了相对符号链接的问题 (#639)

版本 0.15.2 (2016-02-08)

• 修复了不正确的警告，该警告指出外部主题 将从 MkDocs 中移除。

版本 0.15.1 (2016-01-30)

• 将最低支持的 Click 版本降低到 3.3，以适应包维护者 (#763)

版本 0.15.0 (2016-01-21)

版本 0.15.0 的主要新增内容

添加对可安装主题的支持

MkDocs 现在支持通过 Python 包分发的主题。随着这一功能的加入，Bootstrap 和 Bootswatch 主题已移至外部 git 仓库和 Python 包中。有关这些特定主题的更多详细信息，请参阅各自的文档。

• MkDocs Bootstrap
• MkDocs Bootswatch

它们将默认包含在 MkDocs 中，直到未来的某个版本。之后，它们将可以通过 pip 安装：pip install mkdocs-bootstrap 和 pip install mkdocs-bootswatch

有关使用和自定义主题的更多信息，请参阅 自定义您的主题 文档，以及有关创建和分发新主题的 自定义主题 文档。

版本 0.15.0 的其他更改和新增内容

• 修复了使用绝对链接指向 Markdown 文件时的问题 (#628)
• 弃用对 Python 2.6 的支持，计划在 1.0.0 版本中移除 (#165)
• 正式支持 Python 3.5 版本
• 为 ReadTheDocs 主题添加对 site_description 和 site_author 的支持 (#631)
• 将 FontAwesome 更新到 4.5.0 版本 (#789)
• 通过 X-UA-Compatible 增加了对 IE 的支持 (#785)
• 添加了对 Python 的 -m 标志的支持 (#706)

• 修复：确保自动填充页面的顺序一致 (#638)

• Bugfix: 如果MkDocs主题的目录表太长以至于页面无法容纳，则滚动目录表。(#204)

• Bugfix: 将所有祖先添加到页面属性 ancestors 中，而不仅仅是初始的一个。(#693)
• Bugfix: 再次在构建输出中包含HTML。(#691)
• Bugfix: 向Read the Docs提供文件名。(#721 和 RTD#1480)
• Bugfix: 静默Click的unicode_literals警告。(#708)

版本 0.14.0 (2015-06-09)

• 通过确保所有配置字符串都作为Unicode加载来改进Unicode处理。(#592)
• 移除对six库的依赖。(#583)
• 移除对ghp-import库的依赖。(#547)
• 为所有子命令添加 --quiet 和 --verbose 选项。(#579)
• 为大多数命令行选项添加短选项 (-a)。(#579)
• 为readthedocs主题添加版权页脚。(#568)
• 如果 mkdocs serve 请求的端口已被使用，不要向用户显示完整的堆栈跟踪。(#596)
• Bugfix: 修复搜索时带有空格的JavaScript编码问题。(#586)
• Bugfix: 如果mkdocs.yml不在git仓库根目录中，gh-deploy现在也能正常工作。(#578)
• Bugfix: 在解析目录时处理（传递而不是丢弃）HTML实体。(#612)
• Bugfix: 默认将extra_templates设置为空列表，不要自动发现它们。(#616)

版本 0.13.3 (2015-06-02)

• Bugfix: 如果site_dir在docs_dir内，则将验证错误减少为警告，因为这不会导致构建问题，但会给用户带来多次构建的不便。(#580)

版本 0.13.2 (2015-05-30)

• Bugfix: 确保在退出前记录所有错误和警告。(#536)
• Bugfix: 修复与ReadTheDocs的兼容性问题。(#554)

版本 0.13.1 (2015-05-27)

• Bugfix: 修复最小配置中仅包含页面配置中的路径列表的问题。(#562)

版本 0.13.0 (2015-05-26)

版本 0.13.0 的弃用

弃用JSON命令

在此版本中，mkdocs json 命令已被标记为弃用，并且在使用时将显示弃用警告。它将在MkDocs的[未来版本]中被移除，最迟在版本1.0中移除。mkdocs json 命令为用户提供了一种方便的方式来将文档内容输出为JSON文件，但由于MkDocs中添加了搜索功能，此功能被重复了。

在MkDocs构建中创建了一个包含所有内容的新索引，因此使用 site_dir 的默认值，可以在 site/mkdocs/search_index.json 中找到它。

每次MkDocs构建（使用 mkdocs build）时都会创建此新文件，无需配置即可启用它。

更改页面配置

提供了一种[新方式]来在mkdocs.yml文件中定义页面，特别是嵌套页面，并弃用现有的方法，支持将在MkDocs 1.0中移除。

警告用户内置主题的移除

在MkDocs的未来版本中，除mkdocs和readthedocs之外的所有主题都将移至外部包中。这将使它们更容易得到支持，并在MkDocs发布之外进行更新。

版本 0.13.0 的主要新增功能

搜索

MkDocs现已添加了对搜索的支持。这是基于JavaScript库lunr.js。它已添加到 mkdocs 和 readthedocs 主题中。请参阅自定义主题文档中的[支持搜索]，以将其添加到您自己的主题中。

新的命令行界面

MkDocs的命令行界面已使用Python库Click重新编写。这意味着MkDocs现在具有更易于使用的界面和更好的帮助输出。

此更改部分向后不兼容，因为虽然未记录，但可以将任何配置选项传递给不同的命令。现在只有一小部分配置选项可以传递给命令。要全面查看命令及其可用参数，请使用 mkdocs --help 和 mkdocs build --help 来显示它们。

支持额外的HTML和XML文件

类似于extra_javascript和extra_css配置选项，添加了一个名为extra_templates的新选项。这将自动填充项目文档目录中的任何 .html 或 .xml 文件。

用户可以放置静态HTML和XML文件，它们将被复制过来，或者他们也可以使用Jinja2语法并利用全局变量。

默认情况下，MkDocs将使用此方法为文档创建站点地图。

版本 0.13.0 的其他更改和新增内容

• 添加对 Markdown 扩展配置选项 的支持。(#435)
• MkDocs 现在提供 Python wheels。(#486)
• 仅在首页包含构建日期和 MkDocs 版本。(#490)
• 为文档构建生成站点地图。(#436)
• 在配置中添加更清晰的方式来定义嵌套页面。(#482)
• 添加 额外配置 选项，用于将任意变量传递给模板。(#510)
• 为 mkdocs serve 添加 --no-livereload，以获得更简单的开发服务器。(#511)
• 在所有主题中添加版权显示支持 (#549)
• 在 mkdocs gh-deploy 中添加对自定义提交消息的支持 (#516)
• 错误修复：修复链接到与名为 index.md 的 Markdown 文件在同一目录中的媒体 (#535)
• 错误修复：修复 Unicode 文件名导致的错误 (#542)。

版本 0.12.2 (2015-04-22)

• 错误修复：修复一个回归问题，即如果在页面配置中某些子标题缺失但其他子标题存在时会出现错误。(#464)

版本 0.12.1 (2015-04-14)

• 错误修复：修复某些浏览器中目录底部项目不可点击的 CSS 错误。

版本 0.12.0 (2015-04-14)

• 在 CLI 输出中显示当前 MkDocs 版本。(#258)
• 使用 gh-deploy 时检查 CNAME 文件。(#285)
• 在所有主题中将首页添加回导航。(#271)
• 为本地链接检查添加严格模式。(#279)
• 在所有主题中添加 Google Analytics 支持。(#333)
• 在 ReadTheDocs 和 MkDocs 主题输出中添加构建日期和 MkDocs 版本。(#382)
• 标准化所有主题的语法高亮并添加缺失的语言。(#387)
• 添加详细标志 (-v) 以显示构建的更多详细信息。(#147)
• 添加在部署到 GitHub 时指定远程分支的选项。这使得可以在个人和仓库站点上部署到 GitHub Pages。(#354)
• 在 ReadTheDocs 主题 HTML 中添加 favicon 支持。(#422)
• 编辑文件时自动刷新浏览器。(#163)
• 错误修复：永远不要在代码块中重写 URL。(#240)
• 错误修复：从 docs_dir 复制媒体时不要复制点文件。(#254)
• 错误修复：修复 ReadTheDocs 主题中表格的渲染。(#106)
• 错误修复：为所有 bootstrap 主题添加底部填充。(#255)
• 错误修复：修复嵌套 Markdown 页面和自动页面配置的问题。(#276)
• 错误修复：修复 GitHub 企业版 URL 解析错误。(#284)
• 错误修复：如果 mkdocs.yml 完全为空，不要报错。(#288)
• 错误修复：修复相对 URL 和 Markdown 文件的许多问题。(#292)
• 错误修复：如果找不到页面，不要停止构建，继续处理其他页面。(#150)
• 错误修复：从页面标题中删除 site_name，这需要手动添加。(#299)
• 错误修复：修复目录截断 Markdown 的问题。(#294)
• 错误修复：修复 BitBucket 的主机名。(#339)
• 错误修复：确保所有链接以斜杠结尾。(#344)
• 错误修复：修复 readthedocs 主题中的仓库链接。(#365)
• 错误修复：本地包含 jQuery 以避免离线使用 MkDocs 时的问题。(#143)
• 错误修复：不允许 docs_dir 在 site_dir 中或反之。(#384)
• 错误修复：删除 ReadTheDocs 主题中的内联 CSS。(#393)
• 错误修复：修复由于页面配置处理顺序导致的子标题问题。(#395)
• 错误修复：在主题不存在时不要在实时重载期间报错。(#373)
• 错误修复：修复 Meta 扩展可能不存在时的问题。(#398)
• 错误修复：包装长行内代码，否则它们会超出屏幕。(#313)
• 错误修复：删除 HTML 解析正则表达式，并使用 HTMLParser 解析以修复标题中包含代码的问题。(#367)
• 错误修复：修复滚动到锚点导致标题隐藏在导航下的问题。(#7)
• 错误修复：为 bootswatch 主题中的 HTML 表格添加更美观的 CSS 类。(#295)
• 错误修复：在使用 mkdocs serve 时传递特定配置文件时不要报错。(#341)
• 错误修复：在使用 mkdocs new 命令时不要覆盖 index.md 文件。(#412)
• 错误修复：在 ReadTheDocs 主题中删除代码中的粗体和斜体。(#411)
• 错误修复：在 MkDocs 主题中内联显示图像。(#415)
• 错误修复：修复 ReadTheDocs 主题中的 no-highlight 问题。(#319)
• 错误修复：在使用 mkdocs build --clean 时不要删除隐藏文件。(#346)
• 错误修复：在 Python >= 2.7 上不要阻止 Python-markdown 的更新版本。(#376)
• 错误修复：修复跨平台打开文件时的编码问题。(#428)

版本 0.11.1 (2014-11-20)

• 错误修复：修复 ReadTheDocs 主题中代码高亮时的 CSS 换行问题。(#233)

版本 0.11.0（2014-11-18）

• 如果当前主题存在 404.html 文件，则渲染该文件。（#194）
• 错误修复：修复 MkDocs 和 ReadTheDocs 主题中的长导航栏、表格渲染和代码高亮问题。（#225）
• 错误修复：修复 google_analytics 代码的问题。（#219）
• 错误修复：从包 tar 中移除 __pycache__。（#196）
• 错误修复：修复指向当前页面锚点的 Markdown 链接。（#197）
• 错误修复：不要将 prettyprint well CSS 类添加到所有 HTML，仅在 MkDocs 主题中添加。（#183）
• 错误修复：在 ReadTheDocs 主题中显示章节标题。（#175）
• 错误修复：在 watchdog 中使用轮询观察器，以便在没有 inotify 的文件系统上重建工作。（#184）
• 错误修复：改进常见配置相关错误的错误输出。（#176）

版本 0.10.0（2014-10-29）

• 增加了对 Python 3.3 和 3.4 的支持。（#103）
• 通过 markdown_extensions 配置设置支持可配置的 Python-Markdown 扩展。（#74）
• 添加了 mkdocs json 命令，以将渲染的文档输出为 json 文件。（#128）
• 在 build、json 和 gh-deploy 命令中添加了 --clean 开关，以从输出目录中移除过时的文件。（#157）
• 支持多个主题目录，以允许替换单个模板而不是复制整个主题。（#129）
• 错误修复：修复 readthedocs 主题中的 <ul> 渲染。（#171）
• 错误修复：改进 readthedocs 主题在小屏幕上的显示效果。（#168）
• 错误修复：放宽了必需的 Python 包版本，以避免冲突。（#104）
• 错误修复：修复某些配置下渲染目录的问题。（#146）
• 错误修复：修复子页面中嵌入图像的路径。（#138）
• 错误修复：修复 use_directory_urls 配置行为。（#63）
• 错误修复：在所有主题中支持 extra_javascript 和 extra_css。（#90）
• 错误修复：修复 Windows 下的路径处理。（#121）
• 错误修复：修复 readthedocs 主题中的菜单生成。（#110）
• 错误修复：修复 Windows 下的 mkdocs 命令创建。（#122）
• 错误修复：正确处理外部的 extra_javascript 和 extra_css。（#92）
• 错误修复：修复了 favicon 支持。（#87）