配置¶

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

介绍¶

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

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

项目信息¶

site_name¶

This is a required setting, and should be a string that is used as the main title for the project documentation. For example:

site_name: Marshmallow Generator

When rendering the theme this setting will be passed as the site_name context variable.

site_url¶

Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting (https://example.com/foo/).

This setting is also used for mkdocs serve: the server will be mounted onto a path taken from the path component of the URL, e.g. some/page.md will be served from http://127.0.0.1:8000/foo/some/page/ to mimic the expected remote layout.

default: null

repo_url¶

When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page.

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

default: null

repo_name¶

When set, provides the name for the link to your repository on each page.

default: 'GitHub', 'Bitbucket' or 'GitLab' if the repo_url matches those domains, otherwise the hostname from the repo_url.

edit_uri¶

The 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.

When set, and if your theme supports it, provides a link directly to the page in your source repository. This makes it easier to find and edit the source for the page. If repo_url is not set, this option is ignored. On some themes, setting this option may cause an edit link to be used in place of a repository link. Other themes may show both links.

The edit_uri supports query ('?') and fragment ('#') characters. For repository hosts that use a query or a fragment to access the files, the edit_uri might be set as follows. (Note the ? and # in the URI...)

# Query string example
edit_uri: "?query=root/path/docs/"

# Hash fragment example
edit_uri: "#root/path/docs/"

For other repository hosts, simply specify the relative path to the docs directory.

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

For example, having this config:

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

means that a page named 'foo/bar.md' will have its edit link lead to:
https://example.com/project/repo/blob/main/docs/foo/bar.md

edit_uri can actually be just an absolute URL, not necessarily relative to repo_url, so this can achieve the same result:

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

For more flexibility, see edit_uri_template below.

default: edit/master/docs/ for GitHub and GitLab repos or src/default/docs/ for a Bitbucket repo, if repo_url matches those domains, otherwise null

edit_uri_template¶

The more flexible variant of edit_uri. These two are equivalent:

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

(they are also mutually exclusive -- don't specify both).

Starting from here, you can change the positioning or formatting of the path, in case the default behavior of appending the path isn't enough.

The contents of edit_uri_template are normal Python format strings, with only these fields available:

• {path}, e.g. foo/bar.md
• {path_noext}, e.g. foo/bar

And the conversion flag !q is available, to percent-encode the field:

• {path!q}, e.g. foo%2Fbar.md

? NOTE: Suggested useful configurations:

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

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

• BitBucket editor:
  (e.g. 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 Static Site Editor:
  (e.g. 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:
  (e.g. 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}"

default: null

site_description¶

Set the site description. This will add a meta tag to the generated HTML header.

default: null

site_author¶

Set the name of the author. This will add a meta tag to the generated HTML header.

default: null

copyright¶

Set the copyright information to be included in the documentation by the theme.

default: null

remote_branch¶

Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy.

default: gh-pages

remote_name¶

Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy.

default: origin

文档导航¶

nav¶

此设置用于确定站点全局导航的格式和布局。 一个最小的导航配置应该是这样的:

nav:
    - "index.md"
    - "about.md"

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

导航项也可以包括到外部站点的链接。 虽然标题对于内部链接是可选的，但是对于外部链接是必需的。 外部链接可以是完整 URL，也可以是相对 URL。 在文件中没有找到的任何路径都被认为是外部链接。 关于 MkDocs 如何确定文档的页面标题，请参阅[Meta-Data]部分。

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 页面。

default: 默认情况下，nav 将包含在docs_dir及其子目录中找到的所有 Markdown 文件的字母数字排序嵌套列表。 索引文件总是在子节中列在前面。

建立目录¶

theme¶

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

如果是字符串，则必须是已知已安装主题的字符串名称。 如需可用主题列表，请访问选择您的主题。

一个键/值对的例子可能是这样的:

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

If a set of key/value pairs, the following nested keys can be defined:

default: 'mkdocs'

docs_dir¶

The directory containing the documentation source markdown files. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path from the root of your local file system.

default: 'docs'

site_dir¶

The directory where the output HTML and other files are created. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path from the root of your local file system.

default: 'site'

site/

extra_css¶

Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir.

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

default: [] (an empty list).

extra_javascript¶

Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage.

default: [] (an empty list).

extra_templates¶

Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage.

default: [] (an empty list).

extra¶

A set of key-value pairs, where the values can be any valid YAML construct, that will be passed to the template. This allows for great flexibility when creating custom themes.

For example, if you are using a theme that supports displaying the project version, you can pass it to the theme like this:

extra:
    version: 1.0

default: By default extra will be an empty key-value mapping.

预览控件¶

现场重装¶

watch¶

Determines additional directories to watch when running mkdocs serve. Configuration is a YAML list.

watch:
    - directory_a
    - directory_b

Allows a custom default to be set without the need to pass it through the -w/--watch option every time the mkdocs serve command is called.

use_directory_urls¶

This setting controls the style used for linking to pages within the documentation.

The following table demonstrates how the URLs used on the site differ when setting use_directory_urls to true or false.

The default style of use_directory_urls: true creates more user friendly URLs, and is usually what you'll want to use.

The alternate style can be useful if you want your documentation to remain properly linked when opening pages directly from the file system, because it creates links that point directly to the target file rather than the target directory.

default: true

strict¶

Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing.

This is also available as a command line flag: --strict.

default: false

dev_addr¶

Determines the address used when running mkdocs serve. Must be of the format IP:PORT.

Allows a custom default to be set without the need to pass it through the --dev-addr option every time the mkdocs serve command is called.

default: '127.0.0.1:8000'

See also: site_url.

格式选项¶

markdown_extensions¶

MkDocs uses the Python Markdown library to translate Markdown files into HTML. Python Markdown supports a variety of extensions that customize how pages are formatted. This setting lets you enable a list of extensions beyond the ones that MkDocs uses by default (meta, toc, tables, and fenced_code).

For example, to enable the SmartyPants typography extension, use:

markdown_extensions:
    - smarty

Some extensions provide configuration options of their own. If you would like to set any configuration options, then you can nest a key/value mapping (option_name: option value) of any options that a given extension supports. See the documentation for the extension you are using to determine what options they support.

For example, to enable permalinks in the (included) toc extension, use:

markdown_extensions:
    - toc:
          permalink: True

Note that a colon (:) must follow the extension name (toc) and then on a new line the option name and value must be indented and separated by a colon. If you would like to define multiple options for a single extension, each option must be defined on a separate line:

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

Add an additional item to the list for each extension. If you have no configuration options to set for a specific extension, then simply omit options for that extension:

markdown_extensions:
    - smarty
    - toc:
          permalink: True
    - sane_lists

In the above examples, each extension is a list item (starts with a -). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for extensions for which no options are defined. Therefore, the last example above could also be defined as follows:

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

This alternative syntax is required if you intend to override some options via inheritance.

default: [] (an empty list).

hooks¶

A list of paths to Python scripts (relative to mkdocs.yml) that are loaded and used as plugin instances.

For example:

hooks:
    - my_hooks.py

Then the file my_hooks.py can contain any plugin event handlers (without self), e.g.:

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

? EXAMPLE: Advanced example:

This produces warnings based on the Markdown content (and warnings are fatal in strict mode):

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"Documentation file '{path}' contains a non-HTTPS link: {m[0]}")

This does not enable any new abilities compared to plugins, it only simplifies one-off usages, as these don't need to be installed like plugins do.

Note that for mkdocs serve the hook module will not be reloaded on each build.

You might have seen this feature in the mkdocs-simple-hooks plugin. If using standard method names, it can be directly replaced, e.g.:

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

plugins¶

A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details.

If the plugins config setting is defined in the mkdocs.yml config file, then any defaults (such as search) are ignored and you need to explicitly re-enable the defaults if you would like to continue using them:

plugins:
    - search
    - your_other_plugin

To define options for a given plugin, use a nested set of key/value pairs:

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

In the above examples, each plugin is a list item (starts with a -). As an alternative, key/value pairs can be used instead. However, in that case an empty value must be provided for plugins for which no options are defined. Therefore, the last example above could also be defined as follows:

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

This alternative syntax is required if you intend to override some options via inheritance.

To completely disable all plugins, including any defaults, set the plugins setting to an empty list:

plugins: []

default: ['search'] (the "search" plugin included with MkDocs).

Search¶

A search plugin is provided by default with MkDocs which uses lunr.js as a search engine. The following config options are available to alter the behavior of the search plugin:

separator¶

A regular expression which matches the characters used as word separators when building the index. By default whitespace and the hyphen (-) are used. To add the dot (.) as a word separator you might do this:

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

default: '[\s\-]+'

min_search_length¶

An integer value that defines the minimum length for a search query. By default searches shorter than 3 chars in length are ignored as search result quality with short search terms are poor. However, for some use cases (such as documentation about Message Queues which might generate searches for 'MQ') it may be preferable to set a shorter limit.

plugins:
    - search:
          min_search_length: 2

default: 3

lang¶

A list of languages to use when building the search index as identified by their ISO 639-1 language codes. With Lunr Languages, the following languages are supported:

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

You may contribute additional languages.

default: The value of theme.locale if set, otherwise [en].

prebuild_index¶

Optionally generates a pre-built index of all pages, which provides some performance improvements for larger sites. Before enabling, confirm that the theme you are using explicitly supports using a prebuilt index (the builtin themes do). Set to true to enable.

default: False

indexing¶

Configures what strategy the search indexer will use when building the index for your pages. This property is particularly useful if your project is large in scale, and the index takes up an enormous amount of disk space.

plugins:
    - search:
          indexing: "full"

Options¶

default: full ＃＃ 环境变量

In most cases, the value of a configuration option is set directly in the configuration file. However, as an option, the value of a configuration option may be set to the value of an environment variable using the !ENV tag. For example, to set the value of the site_name option to the value of the variable SITE_NAME the YAML file may contain the following:

site_name: !ENV SITE_NAME

If the environment variable is not defined, then the configuration setting would be assigned a null (or None in Python) value. A default value can be defined as the last value in a list. Like this:

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

Multiple fallback variables can be used as well. Note that the last value is not an environment variable, but must be a value to use as a default if none of the specified environment variables are defined.

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

Simple types defined within an environment variable such as string, bool, integer, float, datestamp and null are parsed as if they were defined directly in the YAML file, which means that the value will be converted to the appropriate type. However, complex types such as lists and key/value pairs cannot be defined within a single environment variable.

For more details, see the pyyaml_env_tag project.

配置继承¶

通常，单个文件将保存站点的整个配置。 然而，一些组织可能维护多个站点，这些站点之间共享一个公共配置。 公共配置选项可以在父配置文件中定义，每个站点的主配置文件将继承该配置文件，而不是为每个站点维护单独的配置。

要为配置文件定义父文件，请将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 收到以下合并配置:

site_name: Foo Project
site_url: https://example.com/foo

theme:
    name: mkdocs
    locale: en
    highlightjs: true

markdown_extensions:
    toc:
        permalink: true
    admonition: {}

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

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配置替换为一个新的。但是，通常期望整个导航将在项目的主配置文件中定义。