配置文件

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


简介

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

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

项目信息

site_name

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

site_name: Marshmallow Generator

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

site_url

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

默认值null

repo_url

置后,在每个页面上提供指向您的存储库(GitHub,Bitbucket,GitLab,...)的链接。

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_urledit_uri,并附加页面的输入路径。

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

edit_uri支持查询('?')和片段('#')字符。 对于使用查询或片段访问文件的存储库主机,可以按如下方式设置edit_uri。 (注意URI中的# ...)

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

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

# Query string example
edit_uri: root/path/docs/

注意:

在一些已知的主机(特别是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/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

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

默认值null

google_analytics

设置Google Analytics跟踪配置。

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

文档布局

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

nav:
    - 'Introduction': 'index.md'
    - 'User Guide': 'user-guide.md'
    - 'About': 'about.md'

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

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

nav:
    - Home: index.md
    - User Guide: user-guide.md
    - Bug 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文件的字母数字排序的嵌套列表。如果没有找到它将是[](空列表)。

构建目录

theme

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

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

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

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

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

name:

已知安装主题的字符串名称。 有关可用主题的列表,请访问[样式化您的文档]。

custom_dir:

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

如果您想要调整现有主题,请参阅样式化您的文档了解详细信息。

如果您想从头开始构建自己的主题,请参阅[自定义主题]。

static_templates:

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

主题特定关键字

还可以定义主题支持的任何其他关键字。 有关详细信息,请参阅您正在使用的主题的文档。

默认值'mkdocs'

docs_dir

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

默认值'docs'

site_dir

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

默认值'site'

注意:

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

site/

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

extra_css

设置主题中包含到docs_dir中的CSS文件列表。 例如,以下示例将在[docs_dir](#docs_dir)的css子目录中包含extra.css文件。

extra_css:
    - css/extra.css
    - 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构造,将传递给模板。 这在创建自定义主题时具有很大的灵活性。

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

extra:
    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默认使用的扩展名列表(metatoctablesfenced_code)。

例如,要启用SmartyPants排版扩展,请使用:

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

延申阅读:

Python-Markdown文档提供了扩展名列表,它们是开箱即用的。有关给定扩展可用的配置选项列表,请参阅该扩展的文档。

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

默认值[] (an empty list).

plugins

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

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

plugins:
    - search
    - your_other_plugin

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

plugins: []

默认值['search'] ,MkDocs内置了该'search'插件(“搜索”).

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

separator

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

plugins:
    - search:
        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

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

警告:

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

注意:

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

默认值['en']

prebuild_index

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

预建索引有两种选择:

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

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

注意:

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

默认值False