配置

所有可用配置设置的指南。

---

介绍

项目设置默认通过项目目录中名为 mkdocs.yml 的 YAML 配置文件进行配置。你可以使用 -f/--config-file 选项指定另一个路径（参见 mkdocs build --help）。

至少，此配置文件必须包含 site_name。所有其他设置都是可选的。

项目信息

site_name

这是一个必需的设置，应为一个字符串，用作项目文档的主要标题。例如：

site_name: 棉花糖生成器

在渲染主题时，此设置将作为 site_name 上下文变量传递。

site_url

设置站点的规范 URL。这将为每个 HTML 页面的 head 部分添加一个带有 canonical URL 的 link 标签。如果 MkDocs 站点的“根”位于域的子目录中，请确保在设置中包含该子目录（例如 https://example.com/foo/）。

此设置还用于 mkdocs serve：服务器将挂载到从 URL 的路径组件获取的路径上，例如 some/page.md 将通过 http://127.0.0.1:8000/foo/some/page/ 提供服务，以模拟预期的远程布局。

默认值: null

repo_url

设置后，将在每个页面上提供指向你的仓库（GitHub、Bitbucket、GitLab 等）的链接。

repo_url: https://github.com/example/repository/

默认值: null

repo_name

设置后，将在每个页面上提供指向你的仓库的链接名称。

默认值: 如果 repo_url 匹配这些域名，则为 'GitHub'、'Bitbucket' 或 'GitLab'，否则为 repo_url 中的主机名。

edit_uri

从 repo_url 到文档目录的路径，直接查看页面时，考虑到仓库主机（例如 GitHub、Bitbucket 等）、分支和文档目录本身的特定情况。MkDocs 将 repo_url 和 edit_uri 连接起来，并附加页面的输入路径。

设置后，如果你的主题支持，将直接提供指向源仓库中页面的链接。这使得查找和编辑页面的源代码变得更加容易。如果未设置 repo_url，此选项将被忽略。在某些主题上，设置此选项可能会导致使用编辑链接代替仓库链接。其他主题可能会同时显示这两个链接。

edit_uri 支持查询（'?'）和片段（'#'）字符。对于使用查询或片段访问文件的仓库主机，edit_uri 可以设置如下（注意 URI 中的 ? 和 #）：

# 查询字符串示例
edit_uri: '?query=root/path/docs/'

# 哈希片段示例
edit_uri: '#root/path/docs/'

对于其他仓库主机，只需指定到文档目录的相对路径。

# 查询字符串示例
edit_uri: root/path/docs/

例如，有以下配置：

repo_url: https://example.com/project/repo
edit_uri: blob/main/docs/

意味着名为 'foo/bar.md' 的页面将有一个指向以下地址的编辑链接：
https://example.com/project/repo/blob/main/docs/foo/bar.md

edit_uri 实际上可以只是一个绝对 URL，不一定要相对于 repo_url，因此这可以实现相同的结果：

edit_uri: https://example.com/project/repo/blob/main/docs/

有关更多灵活性，请参见下面的 edit_uri_template。

注意： 在少数已知的主机（特别是 GitHub、Bitbucket 和 GitLab）上，edit_uri 是从 repo_url 派生的，不需要手动设置。只需定义一个 repo_url，就会自动填充 edit_uri 配置设置。

例如，对于托管在 GitHub 或 GitLab 上的仓库，edit_uri 将自动设置为 edit/master/docs/（注意 edit 路径和 master 分支）。

对于托管在 Bitbucket 上的仓库，等效的 edit_uri 将自动设置为 src/default/docs/（注意 src 路径和 default 分支）。

要使用与默认值不同的 URI（例如不同的分支），只需将 edit_uri 设置为你想要的字符串。如果你不希望在页面上显示任何“编辑 URL 链接”，则将 edit_uri 设置为空字符串以禁用自动设置。

警告： 在 GitHub 和 GitLab 上，默认的“edit”路径（edit/master/docs/）会在在线编辑器中打开页面。此功能要求用户拥有并登录到 GitHub/GitLab 帐户。否则，用户将被重定向到登录/注册页面。或者，使用“blob”路径（blob/master/docs/）打开只读视图，支持匿名访问。

默认值: 如果 repo_url 匹配这些域名，则为 GitHub 和 GitLab 仓库的 edit/master/docs/ 或 Bitbucket 仓库的 src/default/docs/，否则为 null

edit_uri_template

edit_uri 的更灵活变体。这两个是等效的：

edit_uri: 'blob/main/docs/'
edit_uri_template: 'blob/main/docs/{path}'

(它们也是互斥的——不要同时指定两者).

从这里开始，你可以改变路径的定位或格式，以防默认的附加路径行为不够用。

edit_uri_template 的内容是普通的 Python 格式字符串，只有以下字段可用：

• {path}，例如 foo/bar.md
• {path_noext}，例如 foo/bar

并且可以使用转换标志 !q 对字段进行百分号编码：

• {path!q}，例如 foo%2Fbar.md

? 注意：建议的有用配置：

• GitHub Wiki:
  (例如 https://github.com/project/repo/wiki/foo/bar/_edit)

  repo_url: 'https://github.com/project/repo/wiki'
  edit_uri_template: '{path_noext}/_edit'

• BitBucket 编辑器:
  (例如 https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit)

  repo_url: 'https://bitbucket.org/project/repo/'
  edit_uri_template: 'src/master/docs/{path}?mode=edit'

• GitLab 静态站点编辑器:
  (例如 https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md)

  repo_url: 'https://gitlab.com/project/repo'
  edit_uri_template: '-/sse/master/docs%2F{path!q}'

• GitLab Web IDE:
  (例如 https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md)

  edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'

默认值: null

site_description

设置站点描述。这将在生成的 HTML 头部添加一个 meta 标签。

默认值: null

site_author

设置作者的名称。这将在生成的 HTML 头部添加一个 meta 标签。

默认值: null

copyright

设置主题中包含的版权信息。

默认值: null

remote_branch

在使用 gh-deploy 部署到 GitHub Pages 时，设置要提交到的远程分支。此选项可以通过 gh-deploy 中的命令行选项覆盖。

默认值: gh-pages

remote_name

在使用 gh-deploy 部署到 GitHub Pages 时，设置要推送到的远程名称。此选项可以通过 gh-deploy 中的命令行选项覆盖。

默认值: origin

文档布局

nav

此设置用于确定站点全局导航的格式和布局。一个最小的导航配置可能如下所示：

nav:
  - 'index.md'
  - 'about.md'

导航配置中的所有路径必须相对于 docs_dir 配置选项。有关更详细的分解，包括如何创建子部分，请参阅[配置页面和导航]部分。

导航项也可以包括指向外部站点的链接。虽然内部链接的标题是可选的，但外部链接的标题是必需的。外部链接可以是完整的 URL 或相对 URL。任何在文件中找不到的路径都被假定为外部链接。有关 MkDocs 如何确定文档页面标题的信息，请参阅[元数据]部分。

nav:
  - Introduction: 'index.md'
  - 'about.md'
  - 'Issue Tracker': 'https://example.com/'

在上面的示例中，前两个项目指向本地文件，而第三个项目指向外部站点。

然而，有时 MkDocs 站点托管在项目站点的子目录中，你可能希望链接到同一站点的其他部分而不包含完整的域名。在这种情况下，你可以使用适当的相对 URL。

site_url: https://example.com/foo/

nav:
  - Home: '../'
  - 'User Guide': 'user-guide.md'
  - 'Bug Tracker': '/bugs/'

在上面的示例中，使用了两种不同风格的外部链接。首先，请注意 site_url 表明 MkDocs 站点托管在域的 /foo/ 子目录中。因此，Home 导航项是一个相对链接，向上跳转一级到服务器根目录，实际上指向 https://example.com/。Bug Tracker 项使用从服务器根目录开始的绝对路径，实际上指向 https://example.com/bugs/。当然，User Guide 指向本地 MkDocs 页面。

默认值: 默认情况下，nav 将包含按字母数字顺序排序的、嵌套的所有在 docs_dir 及其子目录中找到的 Markdown 文件列表。索引文件将始终在子部分中首先列出。

exclude_docs

新增: 新增于版本 1.5。

警告: 在版本 1.6 中更改：

此配置不再适用于 mkdocs serve 的“草稿”功能。如果你有希望在“serve”中可用而在“build”中不可用的草稿文档，请将 exclude_docs 替换为新的 draft_docs 配置选项。

此配置定义了在构建站点时不会被包含的文件模式（位于 docs_dir 下）。

示例:

exclude_docs: |
  api-config.json    # 任何位置的此文件名。
  /requirements.txt  # 顶层的 "docs/requirements.txt"。
  *.py               # 任何位置的此扩展名的文件。
  !/foo/example.py   # 但保留此特定文件。

这遵循了 .gitignore 模式格式。

以下默认值总是隐式地前置——以排除点文件（及目录）以及顶层的 templates 目录：

exclude_docs: |
  .*
  /templates/

因此，为了真正从头开始配置此设置，您需要首先指定这些条目的否定版本。

否则，您可以选择仅将某些点文件重新纳入站点：

exclude_docs: |
  !.assets  # 尽管排除了所有其他 '.*'，但不排除 '.assets'

draft_docs

新功能： 版本 1.6 新增。

此配置定义了文件模式（位于 docs_dir 下），这些文件将被视为草稿。草稿文件在 mkdocs serve 期间可用，并带有“DRAFT”标记，但不会包含在构建中。要防止此效果并使“serve”行为与“build”相同，您可以运行 mkdocs serve --clean。

示例：

draft_docs: |
  drafts/               # 任何位置的 "drafts" 目录。
  _unpublished.md       # 以 _unpublished.md 结尾的 md 文件
  !/foo_unpublished.md  # 但保留此特定文件。

这遵循了 .gitignore 模式格式。

not_in_nav

新功能： 版本 1.5 新增。

新功能： 版本 1.6 新增：

如果未指定 nav 配置，此配置中指定的页面现在将从推断的导航中排除。

如果您想将某些文档包含在站点中但有意将其从导航中排除，通常 MkDocs 会对此发出警告。

将此类文件模式（相对于 docs_dir）添加到 not_in_nav 配置中将防止此类警告。

示例：

nav:
  - Foo: foo.md
  - Bar: bar.md

not_in_nav: |
  /private.md

与前一个选项一样，这遵循了 .gitignore 模式格式。

注意： 将给定文件添加到 exclude_docs 优先于并隐含 not_in_nav。

validation

新功能： 版本 1.5 新增。

配置 MkDocs 在验证文档链接时的诊断消息的严格程度。

这是一个配置树，每个配置的值可以是以下三种之一：warn、info、ignore。这些值会导致生成相应严重级别的日志消息。当然，warn 级别旨在与 mkdocs build --strict 一起使用（此时它会成为错误），您可以在持续测试中使用它。

配置 validation.links.absolute_links 还额外有一个特殊值 relative_to_docs，用于 绝对链接的验证。

示例： 截至 MkDocs 1.6 的此配置默认值：

validation:
  nav:
    omitted_files: info
    not_found: warn
    absolute_links: info
  links:
    not_found: warn
    anchors: info
    absolute_links: info
    unrecognized_links: info

（注意：您不应复制整个示例，因为它只是重复了默认值。只有不同的个别项目才应设置。）

某些行为的默认值已经与 MkDocs 1.4 及以下版本不同——它们之前是被忽略的。

示例： 配置 MkDocs 1.6 以像 MkDocs 1.4 及以下版本一样运行（降低严格性）：

validation:
  absolute_links: ignore
  unrecognized_links: ignore
  anchors: ignore

示例： 大多数站点的推荐设置（最大严格性）：

validation:
  omitted_files: warn
  absolute_links: warn  # 或 'relative_to_docs' - MkDocs 1.6 新增
  unrecognized_links: warn
  anchors: warn  # MkDocs 1.6 新增

请注意，在上面的示例中我们省略了 'nav' 和 'links' 键。这里的 absolute_links: 意味着同时设置 nav: absolute_links: 和 links: absolute_links:。

完整值列表及它们可以隐藏或突出显示的日志消息示例：

• validation.nav.omitted_files

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

• validation.nav.not_found

  • 'nav' 配置中包含对 'foo/bar.md' 的引用，但在文档文件中未找到。

  • 'nav' 配置中包含对 'foo/bar.md' 的引用，但此文件被排除在构建站点之外。

• validation.nav.absolute_links

  • 'nav' 配置中包含对 '/foo/bar.html' 的绝对路径引用，这可能指向外部资源。

• validation.links.not_found

  • 文档文件 'example.md' 包含链接 '../foo/bar.md'，但目标文件在文档文件中未找到。

  • 文档文件 'example.md' 包含指向 'foo/bar.md' 的链接，但此文件被排除在构建站点之外。

• validation.links.anchors

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

  • 文档文件 'example.md' 包含一个链接 '#some-heading'，但本页没有这样的锚点。

• validation.links.absolute_links

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

• validation.links.unrecognized_links

  • 文档文件 'example.md' 包含一个无法识别的相对链接 '../foo/bar/'，它被保留原样。你是指 'foo/bar.md' 吗？

  • 文档文件 'example.md' 包含一个无法识别的相对链接 'mail@example.com'，它被保留原样。你是指 'mailto:mail@example.com' 吗？

绝对链接的验证

新增: 此功能在版本 1.6 中新增。

历史上，在 Markdown 中，MkDocs 只识别指向另一个物理 *.md 文档（或媒体文件）的相对链接。遵循这一惯例是好的，因为这样源页面也可以在没有 MkDocs 的情况下自由浏览，例如在 GitHub 上。而绝对链接则被保留原样（使其通常无法按预期工作），或者更近期的版本中，会发出警告。如果你不喜欢总是使用相对链接，现在你可以选择使用绝对链接并让它们正确工作。

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

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

不过，你需要启用该设置。默认情况下，链接仍会被跳过。

示例: 设置以识别绝对链接并验证它们:

validation:
  links:
    absolute_links: relative_to_docs
    anchors: warn
    unrecognized_links: warn

构建目录

theme

设置文档站点的主题和主题特定配置。可以是字符串或键值对集合。

如果是字符串，它必须是已安装主题的字符串名称。有关可用主题的列表，请访问 [选择你的主题]。

一组键值对的示例可能如下所示：

theme:
  name: mkdocs
  locale: en
  custom_dir: my_theme_customizations/
  static_templates:
    - sitemap.html
  include_sidebar: false

如果是键值对集合，可以定义以下嵌套键：

区块:

name

已安装主题的字符串名称。有关可用主题的列表，请访问 [选择你的主题]。

locale

表示网站语言的代码。详情请参阅 [本地化你的主题]。

custom_dir

包含自定义主题的目录。可以是相对目录，在这种情况下，它相对于包含配置文件的目录解析，也可以是本地文件系统根目录的绝对目录路径。

如果你想调整现有主题，请参阅 自定义你的主题 了解详情。

如果你想从头开始构建自己的主题，请参阅 [主题开发者指南]。

static_templates

要渲染为静态页面的模板列表。模板必须位于主题的模板目录或主题配置中定义的 custom_dir 中。

(主题特定关键词)

主题支持的任何其他关键词也可以定义。有关详情，请参阅你正在使用的主题的文档。

默认: 'mkdocs'

docs_dir

包含文档源 Markdown 文件的目录。可以是相对目录，在这种情况下，它相对于包含配置文件的目录解析，也可以是本地文件系统根目录的绝对目录路径。

默认: 'docs'

site_dir

输出 HTML 和其他文件的目录。可以是相对目录，在这种情况下，它相对于包含配置文件的目录解析，也可以是本地文件系统根目录的绝对目录路径。

默认: 'site'

注意: 如果你使用源代码控制，通常你会希望确保你的构建输出文件不被提交到仓库中，而只保留源文件在版本控制下。例如，如果使用 git，你可以在 .gitignore 文件中添加以下行：

site/

如果你使用其他源代码控制工具，请查阅其文档了解如何忽略特定目录。

extra_css

设置一组CSS文件（相对于docs_dir），主题将包含这些文件，通常作为<link>标签。

示例：

extra_css:
  - css/extra.css
  - css/second_extra.css

默认值: []（空列表）。

extra_javascript

设置docs_dir中的JavaScript文件列表，主题将包含这些文件，作为<script>标签。

新功能: 在版本1.5中更改:

旧版本的MkDocs仅支持简单的字符串列表，但现在支持多个额外的配置键：type、async、defer。

查看示例及其生成内容：

extra_javascript:
  - some_plain_javascript.js       # <script src="some_plain_javascript.js"></script>
        # MkDocs 1.5 中的新行为:
  - implicitly_as_module.mjs       # <script src="implicitly_as_module.mjs" type="module"></script>
        # 仅在 MkDocs 1.5 及之后版本支持的配置键:
  - path: explicitly_as_module.mjs # <script src="explicitly_as_module.mjs" type="module"></script>
    type: module
  - path: deferred_plain.js        # <script src="deferred_plain.js" defer></script>
    defer: true
  - path: scripts/async_module.mjs # <script src="scripts/async_module.mjs" type="module" async></script>
    type: module
    async: true

因此，每个项目可以是：

• 一个简单的字符串，或
• 一个映射，包含必需的path键和三个可选键type（字符串）、async（布尔值）、defer（布尔值）。

只有简单的字符串变体可以检测.mjs扩展名并添加type="module"，否则无论扩展名如何，都必须写出type: module。

默认值: []（空列表）。

注意：*.js和*.css文件，就像任何其他类型的文件一样，总是从docs_dir复制到站点的部署副本中，无论它们是否通过上述配置链接到页面。

extra_templates

设置docs_dir中的模板列表，MkDocs将构建这些模板。要了解更多关于为MkDocs编写模板的信息，请阅读关于[自定义主题]的文档，特别是关于[可用变量]的部分。请参阅[extra_css]中的示例以了解用法。

默认值: []（空列表）。

extra

一组键值对，其中值可以是任何有效的YAML结构，这些值将被传递给模板。这允许在创建自定义主题时具有很大的灵活性。

例如，如果你使用的主题支持显示项目版本，你可以这样传递版本信息给主题：

extra:
  version: 1.0

默认值: 默认情况下，extra将是一个空的键值映射。

预览控制

实时重载

watch

确定在运行mkdocs serve时监视的额外目录。配置是一个YAML列表。

watch:
  - directory_a
  - directory_b

允许在不每次通过-w/--watch选项传递时设置自定义默认值。

注意： 通过配置文件提供的路径是相对于配置文件的。

通过-w/--watch CLI参数提供的路径则不是。

use_directory_urls

此设置控制生成的文档的目录结构，从而控制用于链接页面的URL格式。

下表展示了当将use_directory_urls设置为true或false时，目录结构和站点上使用的URL有何不同。

use_directory_urls: false

当文档托管在无法通过URL X访问文件X/index.html的系统上时，需要此设置。当设置为false时，不会创建额外的X目录，文件仅存储为X.html。链接直接指向目标文件，而不是目标目录。

源文件	生成的文件	URL格式
index.md	index.html	/index.html
api-guide.md	api-guide.html	/api-guide.html
about/license.md	about/license.html	/about/license.html

例如，当：

• 直接从文件系统打开页面
• 将文档发布到静态S3网站时

需要将此设置为false。

use_directory_urls: true

默认的use_directory_urls: true样式创建更用户友好的URL，通常是你想要使用的。

源文件	生成的文件	URL格式
index.md	/index.html	/
api-guide.md	/api-guide/index.html	/api-guide/
about/license.md	/about/license/index.html	/about/license

默认值: true

strict

确定如何处理警告。设置为true以在出现警告时停止处理。设置为false以打印警告并继续处理。

这也可以作为命令行标志使用：--strict。

默认值: false

dev_addr

确定运行mkdocs serve时使用的地址。必须是IP:PORT格式。 允许在不每次调用 mkdocs serve 命令时通过 --dev-addr 选项传递的情况下设置自定义默认值。

默认值: '127.0.0.1:8000'

另请参阅: site_url.

格式化选项

markdown_extensions

MkDocs 使用 [Python Markdown][pymkd] 库将 Markdown 文件转换为 HTML。Python Markdown 支持多种 [扩展][pymdk-extensions]，这些扩展可以自定义页面的格式。此设置允许您启用 MkDocs 默认使用的扩展（meta、toc、tables 和 fenced_code）之外的扩展列表。

例如，要启用 [SmartyPants 排版扩展][smarty]，请使用：

markdown_extensions:
  - smarty

一些扩展提供了自己的配置选项。如果您想设置任何配置选项，则可以为给定扩展支持的任何选项嵌套键/值映射（option_name: option value）。请参阅您正在使用的扩展的文档，以确定它们支持哪些选项。

例如，要在（包含的）toc 扩展中启用永久链接，请使用：

markdown_extensions:
  - toc:
      permalink: true

请注意，冒号 (:) 必须跟随扩展名 (toc)，然后在新的行上，选项名称和值必须缩进并用冒号分隔。如果您想为单个扩展定义多个选项，则每个选项必须在单独的行上定义：

markdown_extensions:
  - toc:
      permalink: true
      separator: "_"

为每个扩展添加一个额外的列表项。如果您对特定扩展没有要设置的配置选项，则只需省略该扩展的选项：

markdown_extensions:
  - smarty
  - toc:
      permalink: true
  - sane_lists

注意: 动态配置值。

要动态配置扩展，您可以从 环境变量 或 获取当前渲染的 Markdown 文件或整个 MkDocs 站点的路径 中获取配置值。

在上面的示例中，每个扩展都是一个列表项（以 - 开头）。作为替代方案，可以使用键/值对。然而，在这种情况下，必须为没有定义选项的扩展提供空值。因此，上面的最后一个示例也可以定义如下：

markdown_extensions:
  smarty: {}
  toc:
    permalink: true
  sane_lists: {}

如果您打算通过 [继承] 覆盖某些选项，则需要此替代语法。

注意: 更多扩展。

Python-Markdown 文档提供了一个 [扩展列表][exts]，这些扩展是开箱即用的。有关给定扩展可用的配置选项列表，请参阅该扩展的文档。

您还可以安装和使用各种第三方扩展（[Python-Markdown wiki]、[MkDocs 项目目录][catalog]）。请参阅这些扩展提供的文档以获取安装说明和可用的配置选项。

默认值: []（空列表）。

hooks

新功能: 在版本 1.4 中新增。

一个路径列表，指向 Python 脚本（相对于 mkdocs.yml），这些脚本被加载并作为 插件 实例使用。

例如：

hooks:
  - my_hooks.py

然后，文件 my_hooks.py 可以包含任何 插件事件处理程序（不带 self），例如：

def on_page_markdown(markdown, **kwargs):
    return markdown.replace('a', 'z')

? 示例: 高级示例:

这会根据 Markdown 内容生成警告（并且在 严格 模式下警告是致命的）：

import logging, re
import mkdocs.plugins

log = logging.getLogger('mkdocs')

@mkdocs.plugins.event_priority(-50)
def on_page_markdown(markdown, page, **kwargs):
    path = page.file.src_uri
    for m in re.finditer(r'\bhttp://[^) ]+', markdown):
        log.warning(f"文档文件 '{path}' 包含非 HTTPS 链接: {m[0]}")

与 [插件][] 相比，这不会启用任何新功能，它只是简化了单次使用的情况，因为这些不需要像插件那样 安装。

请注意，对于 mkdocs serve，钩子模块在每次构建时 不会 重新加载。

您可能已经在 mkdocs-simple-hooks 插件 中看到了此功能。如果使用标准方法名称，则可以直接替换，例如：

-plugins:
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: 'my_hooks:on_page_markdown'
+hooks:
+  - my_hooks.py

新功能: 在 MkDocs 1.6 中新增。

如果钩子文件旁边有一个名为 foo.py 的文件，它可以使用正常的 Python 语法 import foo 来访问其函数。

在 MkDocs 的旧版本中，需要一个变通方法才能使其工作——将路径添加到 sys.path。

plugins

插件允许您在构建文档时扩展 MkDocs 的功能。MkDocs 带有一些内置插件，您也可以安装和使用第三方插件。

插件的配置方式与 markdown_extensions 类似。您可以启用一个插件列表，并为每个插件设置配置选项。

例如，要启用 search 插件并设置其 lang 选项，请使用：

plugins:
  - search:
      lang: ['en', 'fr']

如果您对特定插件没有要设置的配置选项，则只需省略该插件的选项：

plugins:
  - search
  - awesome-plugin

注意: 更多插件。

MkDocs 文档提供了一个 插件列表，这些插件是开箱即用的。有关给定插件可用的配置选项列表，请参阅该插件的文档。

您还可以安装和使用各种第三方插件（[MkDocs 项目目录][catalog]）。请参阅这些插件提供的文档以获取安装说明和可用的配置选项。

默认值: []（空列表）。 构建站点时要使用的插件列表（带有可选的配置设置）。有关详细信息，请参阅[插件]文档。

默认值: ['search']（MkDocs 自带的 "search" 插件）。

如果在 mkdocs.yml 配置文件中定义了 plugins 配置项，那么任何默认插件（如 search）都会被忽略，你需要显式地重新启用这些默认插件，如果你想继续使用它们的话：

plugins:
  - search
  - your_other_plugin

要为某个插件定义选项，请使用一组嵌套的键/值对：

plugins:
  - search
  - your_other_plugin:
      option1: value
      option2: other value

要完全禁用所有插件，包括任何默认插件，请将 plugins 设置为空列表：

plugins: []

enabled 选项

新增: MkDocs 1.6 新增。

每个插件都有自己的选项键。然而，MkDocs 还确保每个插件都有一个 enabled 布尔选项。这可以用于有条件地启用某个插件，如下例所示：

plugins:
  - search
  - code-validator:
      enabled: !ENV [LINT, false]

参见: 环境变量

替代语法

在上面的示例中，每个插件都是一个列表项（以 - 开头）。作为替代，可以使用键/值对。然而，在这种情况下，必须为没有定义选项的插件提供一个空值。因此，上面的最后一个示例也可以定义如下：

plugins:
  search: {}
  your_other_plugin:
    option1: value
    option2: other value

如果你想通过[继承]覆盖某些选项，则需要使用这种替代语法。

搜索

MkDocs 默认提供了一个使用 [lunr.js] 作为搜索引擎的搜索插件。以下配置选项可用于改变搜索插件的行为：

separator

一个正则表达式，匹配用于构建索引时的单词分隔符。默认情况下，使用空格和连字符 (-)。要添加点 (.) 作为单词分隔符，你可以这样做：

plugins:
  - search:
      separator: '[\s\-\.]+'

默认值: '[\s\-]+'

min_search_length

一个整数值，定义搜索查询的最小长度。默认情况下，长度小于 3 个字符的搜索会被忽略，因为短搜索词的搜索结果质量较差。然而，对于某些用例（例如关于消息队列的文档，可能会生成对 'MQ' 的搜索），可能更倾向于设置一个较短的限制。

plugins:
  - search:
      min_search_length: 2

默认值: 3

lang

在构建搜索索引时要使用的语言列表，通过它们的 [ISO 639-1] 语言代码标识。使用 [Lunr Languages]，支持以下语言：

• ar: 阿拉伯语
• da: 丹麦语
• nl: 荷兰语
• en: 英语
• fi: 芬兰语
• fr: 法语
• de: 德语
• hu: 匈牙利语
• it: 意大利语
• ja: 日语
• no: 挪威语
• pt: 葡萄牙语
• ro: 罗马尼亚语
• ru: 俄语
• es: 西班牙语
• sv: 瑞典语
• th: 泰语
• tr: 土耳其语
• vi: 越南语

你可以[贡献额外的语言]。

警告: 虽然搜索支持同时使用多种语言，但最好不要添加额外的语言，除非你真的需要它们。每种额外的语言都会显著增加带宽需求并占用更多浏览器资源。通常，最好将 MkDocs 的每个实例保持为单一语言。

注意: Lunr Languages 目前不包括对中文或其他亚洲语言的支持。然而，一些用户报告说使用日语效果不错。

默认值: 如果设置了 theme.locale，则为该值，否则为 [en]。

prebuild_index

可选地生成所有页面的预构建索引，这为较大的站点提供了一些性能改进。在启用之前，请确认你使用的主题明确支持使用预构建索引（内置主题支持）。设置为 true 以启用。

警告: 此选项要求安装 [Node.js] 并且 node 命令在系统路径中。如果调用 node 失败，则会发出警告并且构建继续不受影响。你可以使用 --strict 标志进行构建，以使此类失败引发错误。

注意: 对于较小的站点，不建议使用预构建索引，因为它会显著增加带宽需求，而对用户的改进几乎不明显。然而，对于较大的站点（数百页），带宽增加相对较小，而用户会注意到搜索性能的显著提升。

默认值: False

indexing

配置搜索索引器在为你的页面构建索引时使用的策略。如果你的项目规模较大，索引占用了大量磁盘空间，此属性特别有用。

plugins:
  - search:
      indexing: 'full'

选项

选项	描述
full	索引每个页面的标题、章节标题和全文。
sections	索引每个页面的标题和章节标题。
titles	仅索引每个页面的标题。

默认值: full

特殊 YAML 标签

环境变量

在大多数情况下，配置选项的值直接在配置文件中设置。然而，作为一种选择，配置选项的值可以设置为环境变量的值，使用 !ENV 标签。例如，要将 site_name 选项的值设置为变量 SITE_NAME 的值，YAML 文件可能包含以下内容：

site_name: !ENV SITE_NAME

如果环境变量未定义，则配置设置将被分配一个 null（或在 Python 中为 None）值。可以定义一个默认值作为列表中的最后一个值。像这样：

site_name: !ENV [SITE_NAME, 'My default site name']

也可以使用多个回退变量。请注意，最后一个值不是一个环境变量，但如果未定义指定的环境变量，则必须使用该值作为默认值。

site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name']

在环境变量中定义的简单类型，如字符串、布尔值、整数、浮点数、日期戳和空值，会被解析为直接在 YAML 文件中定义的值，这意味着该值将被转换为适当的类型。然而，复杂类型，如列表和键/值对，不能在单个环境变量中定义。

有关更多详细信息，请参阅 pyyaml_env_tag 项目。

相对于当前文件或站点的路径

新功能: 在版本 1.5 中新增。

一些 Markdown 扩展可以从知道当前正在处理的 Markdown 文件的路径或当前站点的根路径中受益。为此，可以在配置文件的大多数上下文中使用特殊标签 !relative，尽管目前唯一已知的用例是在 markdown_extensions 中。

可能的值示例如下：

- !relative  # 相对于当前 Markdown 文件的目录
- !relative $docs_dir  # docs_dir 的路径
- !relative $config_dir  # 包含主 mkdocs.yml 的目录的路径
- !relative $config_dir/some/child/dir  # 根配置目录的某个子目录

（这里，$docs_dir 和 $config_dir 是目前唯一被识别的特殊前缀。）

示例：

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative  # 相对于当前 Markdown 文件

这允许 [pymdownx.snippets] 扩展包含相对于当前 Markdown 文件的文件，否则它将无法知道这些路径。

注意：即使对于默认情况，任何扩展的基路径在技术上都是当前工作目录，尽管假设它是包含 mkdocs.yml 的目录。因此，即使你不希望路径是相对的，为了改进默认行为，始终首选使用此惯用法：

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative $config_dir  # 相对于包含 mkdocs.yml 的根目录

配置继承

通常，一个文件会包含站点的整个配置。然而，一些组织可能会维护多个站点，这些站点共享一个通用的配置。与其为每个站点维护单独的配置，不如在父配置文件中定义通用配置选项，每个站点的主要配置文件继承该配置。

要定义配置文件的父级，请将 INHERIT（全大写）键设置为父文件的路径。该路径必须相对于主要文件的位置。

要与父配置合并的配置选项必须定义为键/值对。具体来说，[markdown_extensions] 和 plugins 选项必须使用不使用列表项（以 - 开头的行）的替代语法。

例如，假设通用（父）配置在 base.yml 中定义：

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  toc:
    permalink: true
  admonition: {}

然后，对于“foo”站点，主要配置文件将在 foo/mkdocs.yml 中定义：

INHERIT: ../base.yml
site_name: Foo Project
site_url: https://example.com/foo

当运行 mkdocs build 时，foo/mkdocs.yml 文件将作为配置文件传递。MkDocs 将解析该文件，检索并解析父文件 base.yml，并将两者深度合并。这将导致 MkDocs 接收到以下合并的配置：

站点名称: Foo 项目
站点网址: https://example.com/foo

主题:
  名称: mkdocs
  语言环境: 英语
  highlightjs: 启用

Markdown 扩展:
  toc:
    永久链接: 启用
  警告提示: {}

深度合并允许你在主配置文件中添加和/或覆盖各种值。例如，假设你希望为一个站点添加对定义列表的支持，使用不同的符号作为永久链接，并定义一个不同的分隔符。在该站点的主配置文件中，你可以这样做：

INHERIT: ../base.yml
site_name: Bar Project
site_url: https://example.com/bar

markdown_extensions:
  def_list: {}
  toc:
    permalink: 
    separator: "_"

在这种情况下，上述配置将与 base.yml 进行深度合并，并生成以下配置：

site_name: Bar Project
site_url: https://example.com/bar

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  def_list: {}
  toc:
    permalink: 
    separator: "_"
  admonition: {}

注意，admonition 扩展从父配置中保留了下来，def_list 扩展被添加，toc.permalink 的值被替换，而 toc.separator 的值被添加。

你可以替换或合并任何键的值。然而，任何非键的值总是被替换。因此，你不能向列表中追加项目。你必须重新定义整个列表。

由于 [nav] 配置由嵌套列表组成，这意味着你不能合并导航项。当然，你可以用一个新的配置替换整个 nav 配置。然而，通常期望项目的整个导航在主配置文件中定义。

警告： 提醒一下，所有基于路径的配置选项必须相对于主配置文件，并且在合并时 MkDocs 不会更改路径。因此，在父文件中定义路径，该文件被多个不同站点继承，可能不会按预期工作。通常最好只在主配置文件中定义基于路径的选项。

继承也可以作为一种快速方式在命令行上覆盖键——通过使用标准输入作为配置文件。例如：

echo '{INHERIT: mkdocs.yml, site_name: "Renamed site"}' | mkdocs build -f -