发布说明

升级

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

pip install -U mkdocs

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

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

维护团队

MkDocs 团队的现任和前任成员。

版本 1.6.1 (2024-08-30)

修复

修复环境变量 SOURCE_DATE_EPOCH=0 设置时发生的构建错误。 #3795
修复 mkdocs_theme.yml 配置为空时发生的构建错误。 #3700
支持 python -W 和 PYTHONWARNINGS，而不是覆盖配置。 #3809
通过删除 0.0.0.0 开发服务器警告，支持在严格模式下使用 Docker 运行。 #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 有任何特殊行为 - 现在它始终完全从站点中排除列出的文档。

如果您想使用像 exclude_docs 键在 MkDocs 1.5 中那样使用的“草稿”功能，请切换到**新的配置键 draft_docs**。

请参见文档。

其他更改

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

更新页面标题的推断

MkDocs 1.5 在推断页面标题（从第一个标题开始）方面存在行为变化。不幸的是，这会导致在极端情况下，未转义的 HTML 标签或实体出现。

现在，标签始终完全从标题中进行清理。尽管 Page.title 仍然应该包含 HTML 实体，并直接传递给主题。

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

背景：#3564, #3578

主题

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

"readthedocs" 主题

修复："readthedocs" 主题现在可以正确处理深度嵌套的导航配置（超过 2 层深），不会混淆地扩展所有部分并垂直跳跃。 (#3464)
修复："readthedocs" 主题现在即使不是 3 个已知托管服务之一，也会显示一个指向存储库的链接（带有通用徽标）。 (#3435)
"readthedocs" 主题现在在页脚中也有对单词“主题”的翻译，该单词错误地始终保持英文。 (#3613, #3625)

"mkdocs" 主题

"mkdocs" 主题更新到了 Bootstrap 的新版本，这意味着样式略有调整。颜色（最显著的是提醒）具有更好的对比度。

"mkdocs" 主题现在支持深色模式 - 既有自动模式（基于操作系统/浏览器设置），也有手动切换模式。这两种选项默认情况下**未**启用，需要显式配置。
请参见文档中的 color_mode、user_color_mode_toggle。

潜在的破坏性更改

jQuery 不再包含在“mkdocs”主题中。如果您在脚本中依赖它，您需要先将其单独添加（到 mkdocs.yml 中）作为额外的脚本

extra_javascript:
  - https://code.jqueryjs.cn/jquery-3.7.1.min.js

或者，如果脚本文件已复制并包含在您的 docs 目录中，则更好。

背景：#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: 配置中的绝对链接也总是被跳过。现在可以使用 validation.nav.absolute_links 以相同的方式验证它们。尽管这有点不合理，因为这样语法就与没有前导斜杠的语法完全冗余。

锚点

有一个新的配置设置，建议启用它以警告

validation:
  anchors: warn

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

WARNING -  Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.

MkDocs 将检测到以下任何声明锚点的方法

## Heading producing an anchor

## Another heading {#custom-anchor-for-heading-using-attr-list}

<a id="raw-anchor"></a>

[](){#markdown-anchor-using-attr-list}

为了与之兼容，插入锚点的插件和扩展需要作为树处理器开发，这些处理器通过插入 etree 元素来进行操作，而不是使用原始 HTML，因为原始 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)
为“搜索”插件添加了许多新支持的语言 - 将 lunr-languages 更新到 1.12.0 (#3334)
错误修复（1.5.0 中的回归）：在“readthedocs”主题中，嵌套页面的“面包屑导航”样式已损坏 (#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中，但在读取值时，仍然需要确保将其作为str(value)读取，以防它是ExtraScriptValue项。为了查询诸如.type之类的属性，您需要先检查isinstance。静态类型检查将在这方面指导您。（#3324）

请参阅提交日志。

版本 1.5.1 (2023-07-28)

Bug 修复（1.5.0 中的回归）：使将ExtraScriptValue视为路径成为可能。这使得一些插件尽管发生了重大变更，但仍然可以正常工作。
Bug 修复（1.5.0 中的回归）：防止针对具有 3 个冲突文件的特殊设置出现错误，例如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:项，并基于已知项目的大型列表（目录，见下文）进行反向查找。

当然，欢迎您使用“virtualenv”与这样的命令一起使用。还要注意，对于需要稳定性的环境（例如 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 - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean '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 - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...

请参阅文档。上下文：#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               # Excludes e.g. docs/hooks/foo.py
  /requirements.txt  # Excludes 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中预览，只是在顶部有一个“草稿”标记。然后，它们当然会被从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" 主题
- 无障碍性：为首页徽标添加 aria 标签 (#3129) 和搜索输入 (#3046)
- "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: 配置下的列表中多次指定插件，则将创建该插件的 2 个（或更多）实例，每个实例都有自己的配置。

以前，这种情况是无法预见的，因此存在错误。

现在，即使这可以工作，但默认情况下，除非插件添加了一个类变量 supports_multiple_instances = True，否则 MkDocs 仍然会显示警告。
错误修复（1.4.1 中的回归）：插件将普通字符串放入 warnings 时不要出错 (#3016)
错误修复：相对链接将始终以斜杠结尾呈现 (#3022)

以前，在 use_directory_urls 下，从子页面到主索引页的链接呈现为例如 <a href="../..">，即使在所有其他情况下，链接看起来都像 <a href="../../">。这会导致某些 Web 浏览器和服务器组合出现意外行为。现在已删除此特殊情况下的错误。
内置的 "mkdocs" 主题现在还支持挪威语 (#3024)
与插件相关的警告看起来更易读 (#3016)

请参阅提交日志.

版本 1.4.1 (2022-10-15)

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

插件的入口点可以命名为 'sometheme/someplugin'。这将产生以下结果
- 如果当前主题为 'sometheme'，则插件 'sometheme/someplugin' 将始终优先于 'someplugin'。
- 如果当前主题不是 'sometheme'，则使用此插件的唯一方法是指定 plugins: [sometheme/someplugin]。
也可以指定 plugins: ['/someplugin'] 而不是 plugins: ['someplugin']，以绝对避免主题命名空间插件。
Bugfix: mkdocs serve 现在可以正确地处理非 ASCII 路径和重定向 (#3001)
Windows: MkDocs 现在依赖 'colorama'，以确保日志输出的颜色 (#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:  # Error, `foo` might be `None`, need to check first.
            if config.site_url.startswith('http:'):  # Error, MkDocs' `site_url` also might be `None`.
                return markdown + self.config.baz  # Error, no such attribute `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:  # OK, `int < int` is valid.
            if (config.site_url or '').startswith('http:'):  # OK, `str.startswith(str)` is valid.
                return markdown + self.config.bar  # OK, `str + str` is valid.

请查看文档。

还要注意，我们必须明确地将配置属性 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 在标题中。
- 为 Google Analytics 添加了新选项 anonymize_ip。
- 依赖项已升级：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)
错误修复：Python 版本 3.10 在 --version 中显示不正确。 (#2618)

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

版本 1.2.2 (2021-07-18) 

错误修复（1.2 中的回归）：修复了服务包含 Unicode 字符的文件/路径。 (#2464)
错误修复（1.2 中的回归）：将实时重新加载文件监视还原为使用轮询观察器。 (#2477)

必须这样做才能合理地支持跨越虚拟文件系统的用法，例如非本机 Docker 和网络挂载。

这将恢复到轮询方法，与以前始终使用的非常类似，这意味着大部分与延迟和 CPU 使用率相关的相同缺点。
从 1.2 中恢复：删除 site_url 配置的要求以及对 use_directory_urls 的限制。 (#2490)
错误修复（1.2 中的回归）：在 mkdocs serve 服务器中服务目录索引时，不要求 URL 中的尾部斜杠。 (#2507)

不再显示 404 错误，而是检测它是否是目录并重定向到添加了尾部斜杠的路径，就像以前一样。
错误修复：修复了使用当前目录中的配置文件的 gh_deploy。 (#2481)
错误修复：修复了“readthedocs” 主题中的反向面包屑。 (#2179)
允许“mkdocs.yaml”作为文件名，前提是未传递“--config”。 (#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)。

如果 site_url 设置为空字符串，则 use_directory_urls 配置选项将强制设置为 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 配置选项。只要您的 Google 帐户中正确链接了旧的“UA-”ID 和新的“G-”ID，并且您使用的是“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)。
结构文件对象现在具有 remove 方法，以帮助插件开发人员操作文件树。相应的 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）。
错误修复：确保轮子仅限 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）。
错误修复：为 Python 3.8+ 在 Windows 上选择合适的 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 主题（#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 都会被计算一次并存储在 files 集合中。这样可以确保所有内部链接始终被正确计算，而无需考虑配置。这还允许验证所有内部链接，而不仅仅是链接到其他 Markdown 页面。(#842 和 #872）。
一个新的 url 模板过滤器会智能地确保所有 URL 相对于当前页面（#1526）。
添加了一个 on_files 插件事件，可用于包含不在 docs_dir 中的文件、排除文件、重新定义页面 URL（例如实现无扩展名的 URL）或以其他各种方式操作文件。

向后不兼容的更改

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

当 `use_directory_urls` 为 `False` 时，URL 已更改

以前，无论 use_directory_urls 设置如何配置，所有 Markdown 页面的文件名都将被更改为索引页面。但是，路径处理仅在 use_directory_urls 设置为 True（默认值）时才需要。当 use_directory_urls 设置为 False 时，路径处理不再发生，这将导致所有尚未成为索引文件的页面的 URL 不同。由于此行为仅影响非默认配置，并且将选项设置为 False 的最常见用例是针对本地文件系统 (file://) 浏览，因此它不太可能影响大多数用户。但是，如果您将 use_directory_urls 设置为 False 用于托管在 Web 服务器上的 MkDocs 站点，那么您的大多数 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 则没有。这种不一致已在没有任何 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 属性。目前，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 工作器，并提供回退（#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）。
将 MkDocs 版本检查添加到 gh-deploy 脚本中（#640）。
改进 Markdown 扩展错误消息。(#782）。
放弃对 Python 3.3 的官方支持，并设置 tornado>=5.0（#1427）。
添加对 GitLab 编辑链接的支持（#1435）。
从发行说明中链接到 GitHub 问题（#644）。
在 gh-deploy 提交消息中扩展 {sha} 和 {version}（#1410）。
压缩 sitemap.xml（#1130）。
延迟加载 JS 脚本（#1380）。
在搜索输入框中添加一个标题属性 (#1379).
将 RespondJS 更新至最新版本 (#1398).
始终通过 HTTPS 加载 Google Analytics (#1397).
提升滚动帧率 (#1394).
提供更多版本信息。(#1393).
重构 writing-your-docs.md (#1392).
解决 Safari 浏览器在缩放至 < 100% 时出现的错误 (#1389).
移除在 body 上添加 clicky 类和动画。(#1387).
防止搜索插件重新注入 extra_javascript 文件 (#1388).
重构 copy_media_files 实用函数以提升灵活性 (#1370).
移除 PyPI 部署文档 (#1360).
更新至 Python-Markdown 库的链接 (#1360).
文档化如何为 MkDocs 命令生成 manpages (#686).

版本 0.17.5 (2018-07-06)

Bugfix: 修复 Python 3.7 和 PEP 479 不兼容问题 (#1518).

版本 0.17.4 (2018-06-08)

Bugfix: 为 sitemap.xml 添加多级嵌套支持 (#1482).

版本 0.17.3 (2018-03-07)

Bugfix: 由于 5.0 中的变化，设置依赖项 tornado>=4.1,<5.0 (#1428).

版本 0.17.2 (2017-11-15)

Bugfix: 修正 extra_* 配置设置回归问题 (#1335 & #1336).

版本 0.17.1 (2017-10-30)

Bugfix: 支持缺少结尾斜杠的 repo_url。(#1321).
Bugfix: 为 mkdocs.toc.TableOfContext 添加长度支持 (#1325).
Bugfix: 为第三方主题的搜索插件添加一些主题特定设置 (#1316).
Bugfix: 在本地服务器上使用 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 配置文件中的主题配置选项下覆盖这些默认值，该选项现在接受嵌套选项。一个这样的嵌套选项是 custom_dir 选项，它替换了现已弃用的 theme_dir 选项。如果用户之前设置了 theme_dir 选项，则会发出警告，在未来的版本中会引发错误。

如果配置之前像这样定义了 theme_dir

theme: mkdocs
theme_dir: custom

那么配置应该调整如下

theme:
  name: mkdocs
  custom_dir: custom

有关详细信息，请参见主题配置选项文档。

之前已弃用的模板变量已移除。(#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)
不再支持旧版 pages 配置 (#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)
确保导航栏中的首页 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 代替。用户只需将他们自定义的网站图标的副本保存到 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 的修改时间。如果 Markdown 自 HTML 生成后发生更改，则重新构建页面。否则，页面保持原样。这种模式可以在 mkdocs serve 和 mkdocs build 命令中调用。

mkdocs serve --dirtyreload

mkdocs build --dirty

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

更严格的目录验证

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

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

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

版本 0.15.3 (2016-02-18)

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

版本 0.15.2 (2016-02-08)

修复了错误的警告，该警告指出将从 MkDocs 中删除外部主题 will be removed from 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 中。之后，它们可以使用 pip 安装：pip install mkdocs-bootstrap 和 pip install mkdocs-bootswatch

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

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

修复使用指向 Markdown 文件的绝对链接时的问题。 (#628)
弃用对 Python 2.6 的支持，将在 1.0.0 中删除。 (#165)
添加对 Python 版本 3.5 的官方支持。
添加对 site_description 和 site_author 的支持，以便在 ReadTheDocs 主题中使用。 (#631)
将 FontAwesome 更新为 4.5.0。 (#789)
使用 X-UA-Compatible 提高 IE 支持。 (#785)
添加对 Python 的 -m 标志的支持。 (#706)
错误修复：确保自动填充页面的排序一致。 (#638)
错误修复：如果 MkDocs 主题的目录太长而无法容纳在页面中，则滚动目录。 (#204)
错误修复：将所有祖先添加到页面属性 ancestors 中，而不仅仅是最初的祖先。 (#693)
错误修复：再次将 HTML 包含在构建输出中。 (#691)
错误修复：向 Read the Docs 提供文件名。 (#721 和 RTD #1480)
错误修复：静默 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)
错误修复：修复使用空格进行搜索时的 JavaScript 编码问题。 (#586)
错误修复：gh-deploy 现在可以在 mkdocs.yml 不在 Git 存储库根目录的情况下工作。 (#578)
错误修复：在解析 TOC 时处理 (通过而不是删除) HTML 实体。 (#612)
错误修复：将 extra_templates 默认为空列表，不要自动发现它们。 (#616)

版本 0.13.3 (2015-06-02)

错误修复：如果 site_dir 在 docs_dir 内，则将验证错误降级为警告，因为这不会导致构建出现任何问题，但会给多次构建的用户带来不便。 (#580)

版本 0.13.2 (2015-05-30)

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

版本 0.13.1 (2015-05-27)

错误修复：修复仅在 pages 配置中包含路径列表的最小配置出现的问题。 (#562)

版本 0.13.0 (2015-05-26)

版本 0.13.0 的弃用

弃用 JSON 命令

在此版本中，mkdocs json 命令已标记为已弃用，使用该命令时将显示弃用警告。它将在未来的 MkDocs 版本中删除，最迟将在版本 1.0 中删除。mkdocs json 命令为用户提供了一种便捷的方式，可以将文档内容输出为 JSON 文件，但随着 MkDocs 添加了搜索功能，此功能已重复。

在 site_dir 中创建了一个包含 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 主题中。有关将其添加到您自己的主题中的信息，请参阅支持搜索的自定义主题文档。

新的命令行界面

使用 Python 库 Click 重写了 MkDocs 的命令行界面。这意味着 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)
添加一个 extra 配置选项，用于将任意变量传递给模板。 (#510)
向 mkdocs serve 添加 --no-livereload，以创建更简单的开发服务器。 (#511)
向所有主题添加版权显示支持 (#549)
添加对 mkdocs gh-deploy 中自定义提交消息的支持 (#516)
错误修复：修复指向与名为 index.md 的 Markdown 文件位于同一目录中的媒体的链接问题 (#535)
错误修复：修复 Unicode 文件名的错误 (#542).

版本 0.12.2 (2015-04-22)

修复：修复了一个回归问题，如果在 pages 配置中，某些子标题丢失但其他子标题存在，就会出现错误。(#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)
将构建日期和 MkDocs 版本添加到 ReadTheDocs 和 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 Enterprise 中的 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)
修复：修复了由于处理 pages 配置的顺序而导致的子标题问题。(#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)
添加了 --clean 开关到 build、json 和 gh-deploy 命令，用于从输出目录中删除陈旧的文件。(#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)

按键	操作
`?`	打开此帮助
`n`	下一页
`p`	上一页
`s`	搜索

发布说明

升级

维护团队

版本 1.6.1 (2024-08-30)

修复

添加

版本 1.6.0 (2024-04-20)

本地预览

草稿

更新页面标题的推断

主题

"readthedocs" 主题

"mkdocs" 主题

配置

所有插件的新“enabled”设置

验证

页面之间超链接的验证

绝对链接

导航中的绝对链接

锚点

插件开发者升级

插件可以在多个优先级上为同一个事件类型添加多个处理程序

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

钩子和调试

弃用

API 弃用

其他

版本 1.5.3 (2023-09-18)

版本 1.5.2 (2023-08-02)

版本 1.5.1 (2023-07-28)

版本 1.5.0 (2023-07-26)

新命令 mkdocs get-deps

MkDocs 拥有一个官方的插件目录

扩展的链接验证

在 Markdown 中验证链接

在导航中验证链接

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

排除的文档文件

草稿

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

页面标题将从任何风格的标题推断

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

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

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

插件开发人员的升级

主题更新

错误修复

导航中的相对路径可以遍历根目录之上

MkDocs 可以从 stdin 接受配置

新的命令行标志

弃用

版本 1.4.3 (2023-05-02)

版本 1.4.2 (2022-11-01)

版本 1.4.1 (2022-10-15)

版本 1.4.0 (2022-09-27)

功能升级

钩子 (#2978)

edit_uri 灵活性 (#2927)

插件开发者升级

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

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

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

MkDocs 具有类型注解，可以与 mypy 一起使用 (#2941，#2970)

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

将 ConfigOption 架构重构为基于类的 (#2962)

新：config_options.Optional (#2962)

新：config_options.ListOfItems (#2938)

已更新：config_options.SubConfig (#2807)

配置选项的其他更改

主题更新

未来兼容性

对公共 API 的不兼容更改 

其他 

版本 1.3.1 (2022-07-19) 

版本 1.3.0 (2022-03-26) 

功能升级 

错误修复 

其他 

版本 1.2.4 (2022-03-26) 

版本 1.2.3 (2021-10-12) 

所有插件的新“`enabled`”设置

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

新命令 `mkdocs get-deps`

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

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

`edit_uri` 灵活性 (#2927)

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

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

新：`config_options.Optional` (#2962)

新：`config_options.ListOfItems` (#2938)

已更新：`config_options.SubConfig` (#2807)

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

重新设计 `mkdocs serve` 的自动重新加载和 HTTP 服务器 (#2385)

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

添加了 `build_error` 事件 (#2103)

支持 Lunr.py 作为 `prebuild_index` 引擎

`readthedocs` 主题已使用上游更新（#588 和 #1374）

将 `mkdocs` 主题更新至 Bootswatch 4.1.3（#1563）

当 `use_directory_urls` 为 `False` 时，URL 已更改

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

模板变量和 `base_url`

`theme_dir` 配置选项已完全弃用

自动填充 `extra_css` 和 `extra_javascript` 已被弃用。 (#986)