配置文件

所有可用配置选项的指南。

简介

始终使用名为mkdocs.yml的位于项目目录中的YAML文件来进行设置。

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

项目信息

site_name

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

  1. site_name: Marshmallow Generator

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

site_url

设置站点的规范URL。 这将添加带有规范URL的链接标记到生成的HTML标头。

默认值： null

repo_url

置后，在每个页面上提供指向您的存储库（GitHub，Bitbucket，GitLab，…）的链接。

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

默认值： null

repo_name

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

默认值： 'GitHub', 'Bitbucket' or 'GitLab'， 如果repo_url不能匹配这些域名，则使用来自repo_url的域名。

edit_uri

Path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself. MkDocs concatenates repo_url and edit_uri, and appends the input path of the page. 直接查看页面时从基础repo_url到docs目录的路径，考虑存储库主机（例如GitHub，Bitbucket等），分支和docs目录本身的细节。 MkDocs连接repo_url和edit_uri，并附加页面的输入路径。

设置后，如果您的主题支持它，则直接提供源存储库中页面的链接。 这样可以更轻松地查找和编辑页面的源。 如果未设置repo_url，则忽略此选项。 在某些主题上，设置此选项可能会导致使用编辑链接代替存储库链接。 其他主题可能会显示这两个链接。

edit_uri支持查询（’？’）和片段（’＃’）字符。 对于使用查询或片段访问文件的存储库主机，可以按如下方式设置edit_uri。 （注意URI中的？和# …）

  1. # Query string example
  2. edit_uri: '?query=root/path/docs/'
  1. # Hash fragment example
  2. edit_uri: '#root/path/docs/'

对于其他存储库主机，只需指定docs目录的相对路径即可。

  1. # Query string example
  2. edit_uri: root/path/docs/

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

  1. 例如，对于GitHub或GitLab托管的存储库，`edit_uri`将自动设置为`edit/master/docs/`（注意`edit`路径和`master`分支）。
  3. 对于Bitbucket托管的存储库，等效的`edit_uri`将自动设置为`src/default/docs/`（注意`src`路径和`default`分支）。
  5. 要使用与默认值不同的URI（例如不同的分支），只需将`edit_uri`设置为所需的字符串即可。如果您不希望页面上显示任何“编辑URL链接”，请将`edit_uri`设置为空字符串以禁用自动设置。

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

默认值：edit/master/docs/用于GitHub和GitLab存储库，src/default/docs/用于Bitbucket存储库，如果repo_url匹配那些域，否则为null

site_description

设置站点描述。 这将为生成的HTML标头添加元标记。

默认值： null

site_author

设置作者的姓名。 这将为生成的HTML标头添加元标记。

默认值： null

copyright

设置版权信息以包含在主题的文档中。

默认值： null

google_analytics

设置Google Analytics跟踪配置。

  1. google_analytics: ['UA-36723568-3', 'mkdocs.org']

默认值： null

remote_branch

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

默认值： gh-pages

remote_name

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

默认值： origin

文档布局

nav

此设置用于确定站点的全局导航的格式和布局。 例如，以下内容将创建“Introduction”，“User Guide”和“About”导航项。

  1. nav:
  2.     - 'Introduction': 'index.md'
  3.     - 'User Guide': 'user-guide.md'
  4.     - 'About': 'about.md'

所有路径必须相对于mkdocs.yml配置文件。 有关更详细的细分，请参阅[配置页面和导航]部分，包括如何创建子导航。

导航项目还可能包括指向外部站点的链接。 虽然标题对于内部链接是可选的，但外部链接需要它们。 外部链接可以是完整URL或相对URL。 假定在文件中找不到的任何路径都是外部链接。

  1. nav:
  2.     - Home: index.md
  3.     - User Guide: user-guide.md
  4.     - Bug Tracker: https://example.com/

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

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

  1. site_url: https://example.com/foo/
  3. nav:
  4.     - Home: ../
  5.     - User Guide: user-guide.md
  6.     - Bug Tracker: /bugs/

在上面的示例中，使用了两种不同风格的外部链接。 首先请注意，site_url表示MkDocs站点托管在域的/foo/子目录中。 因此，“Home”导航项是一个相对链接，它将一个级别提升到服务器根目录并有效地指向“https:// example.com/”。 “Bug Tracker”项使用来自服务器根目录的绝对路径，并有效地指向“https://example.com/bugs/”。 当然，“User Guide”指向本地MkDocs页面。

默认值：默认情况下，nav将包含在docs_dir及其子目录中找到的所有Markdown文件的字母数字排序的嵌套列表。如果没有找到它将是[]（空列表）。

构建目录

theme

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

如果是字符串，则必须是已知安装主题的字符串名称。 有关可用主题的列表，请访问[样式化您的文档]。

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

  1. theme:
  2.     name: mkdocs
  3.     custom_dir: my_theme_customizations/
  4.     static_templates:
  5.         - sitemap.html
  6.     include_sidebar: false

如果是一组键/值对，则可以定义以下嵌套键：

!!! block “”

  1. #### name:
  3. 已知安装主题的字符串名称。 有关可用主题的列表，请访问[样式化您的文档]。
  5. #### custom_dir:
  7. 包含自定义主题的目录。 这可以是相对目录，在这种情况下，它相对于包含配置文件的目录进行解析，或者它可以是来自本地文件系统根目录的绝对目录路径。
  9. 如果您想要调整现有主题，请参阅[样式化您的文档][theme_dir]了解详细信息。
  11. 如果您想从头开始构建自己的主题，请参阅[自定义主题]。
  13. #### static_templates:
  15. 要呈现为静态页面的模板列表。 模板必须位于主题的模板目录中或主题配置中定义的`custom_dir`中。
  17. #### 主题特定关键字
  19. 还可以定义主题支持的任何其他关键字。 有关详细信息，请参阅您正在使用的主题的文档。

默认值： 'mkdocs'

docs_dir

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

默认值： 'docs'

site_dir

为输出HTML和其他文件而创建的目录。 这可以是相对目录，在这种情况下，它相对于包含配置文件的目录进行解析，或者它可以是来自本地文件系统根目录的绝对目录路径。

默认值： 'site'

!!! note “注意：” 如果您使用的是源代码控制，通常需要确保输出文件未提交到存储库中，并且只保留源文件在版本控制下。 例如，如果使用git，您可以将以下行添加到.gitignore文件中：

  1.     site/
  3. 如果您正在使用其他源代码控制工具，则需要查看有关如何忽略特定目录的文档。

extra_css

设置主题中包含到docs_dir中的CSS文件列表。 例如，以下示例将在[docs_dir]（＃docs_dir）的css子目录中包含extra.css文件。

  1. extra_css:
  2.     - css/extra.css
  3.     - css/second_extra.css

默认值： [] (an empty list).

extra_javascript

设置要包含到主题中的docs_dir中的JavaScript文件列表。请参阅extra_css中的示例以了解用法。

默认值： [] (an empty list).

extra_templates

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

默认值： [] (an empty list).

extra

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

例如，如果您使用的主题支持显示项目版本，则可以将其传递给主题，如下所示：

  1. extra:
  2.     version: 1.0

默认值： 默认情况下，“extra”将是一个空键值映射。

预览控制

use_directory_urls

此设置控制用于链接的样式。

下表演示了将“use_directory_urls”设置为“true”或“false”时网站上显示的URL的不同之处。

源文件 use_directory_urls: true use_directory_urls: false
index.md / /index.html
api-guide.md /api-guide/ /api-guide.html
about/license.md /about/license/ /about/license.html

use_directory_urls：true的默认样式创建了更多用户友好的URL，通常是您想要使用的。

如果您希望在直接从文件系统打开页面时保持文档正确链接，则备用样式有时会很有用，因为它会创建直接指向目标文件而非目标目录的链接。

默认值： true

strict

确定警告的处理方式。 设置为“true”以在发出警告时停止处理。 设置为“false”以打印警告并继续处理。

默认值： false

dev_addr

确定运行mkdocs serve时使用的地址。 必须是“IP:PORT”格式。

允许设置自定义默认值，而无需在每次调用mkdocs serve命令时通过--dev-addr选项传递它。

默认值： '127.0.0.1:8000'

格式化选项

markdown_extensions

MkDocs使用Python Markdown库将Markdown文件翻译成HTML。 Python Markdown支持各种扩展，可以自定义页面的格式。 此设置允许您启用超出MkDocs默认使用的扩展名列表（meta，toc，tables和fenced_code）。

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

  1. markdown_extensions:
  2.     - smarty

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

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

  1. markdown_extensions:
  2.     - toc:
  3.         permalink: True

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

  1. markdown_extensions:
  2.     - toc:
  3.         permalink: True
  4.         separator: "_"

为每个扩展名添加一个附加项目到列表中。 如果没有为特定扩展设置的配置选项，则只需省略该扩展的选项：

  1. markdown_extensions:
  2.     - smarty
  3.     - toc:
  4.         permalink: True
  5.     - sane_lists

!!! note “延申阅读：” Python-Markdown文档提供了扩展名列表，它们是开箱即用的。有关给定扩展可用的配置选项列表，请参阅该扩展的文档。

  1. 您也可以安装和使用各种[第三方扩展][3rd]。 有关安装说明和可用配置选项，请参阅这些扩展提供的文档。

默认值： [] (an empty list).

plugins

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

如果plugins配置设置在mkdocs.yml配置文件中定义，则忽略任何默认值（例如search），如果要继续使用它们，则需要显式重新启用默认值：

  1. plugins:
  2.     - search
  3.     - your_other_plugin

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

  1. plugins: []

默认值： ['search'] ，MkDocs内置了该’search’插件（“搜索”）.

Search

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

separator

一个正则表达式，它与构建索引时用作单词分隔符的字符相匹配。 默认情况下使用空格和连字符（-）。 要将点（.）添加为单词分隔符，您可以执行以下操作：

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

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

lang

构建由ISO 639-1语言代码标识的搜索索引时使用的语言列表。 使用Lunr Languages，支持以下语言：

  • da: Danish
  • du: Dutch
  • en: English
  • fi: Finnish
  • fr: French
  • de: German
  • hu: Hungarian
  • it: Italian
  • jp: Japanese
  • no: Norwegian
  • pt: Portuguese
  • ro: Romanian
  • ru: Russian
  • es: Spanish
  • sv: Swedish
  • th: Thai
  • tr: Turkish

您也可以[贡献其他语言]。

!!! Warning “警告：”

  1. 虽然搜索支持同时使用多种语言，但最好不要添加其他语言，除非您确实需要它们。 每种附加语言都会增加大量带宽需求并使用更多浏览器资源。一般来说，最好将MkDoc的每个实例保持为单一语言。

!!! Note “注意：”

  1. Lunr Languages目前不包括对中文或其他亚洲语言的支持。 但是，一些用户使用日语报告了不错的结果。

默认值： ['en']

prebuild_index

（可选）生成所有页面的预构建索引，从而为较大的站点提供一些性能改进。在启用之前，请检查您使用的主题是否明确支持使用预建索引（内置主题可以）。

预建索引有两种选择：

使用Node.js将prebuild_index设置为True或node。 此选项要求安装Node.js并且命令node在系统路径上。 如果启用此功能并因任何原因失败，则会发出警告。 在构建时可以使用--strict标志来导致这样的失败而不是引发错误。

使用Lunr.py设置prebuild_index到python。Lunr.py作为mkdocs的一部分安装，并保证与Lunr.js的兼容性，即使在英语以外的语言上也是如此。 如果您发现实质性的不一致或问题，请在Lunr.py’s issues上报告，然后再回到Node.js版本。

!!! Note “注意：”

  1. 在较小的站点上，不建议使用预先构建的索引，因为它会造成带宽显著增加，而对用户几乎没有明显改善。但是，对于较大的站点（数百页），带宽增加相对较小，您的用户会注意到搜索性能的显着提高。

默认值： False