MkDocs 插件¶

一个安装，使用和创建MkDocs插件的指南

安装插件¶

在使用插件之前，必须在系统上安装该插件。如果你使用的是MkDocs自带的插件，那么它在你安装MkDocs的时候就已经安装了。但是，要安装第三方插件，您需要确定适当的包名并使用pip安装它:

pip install mkdocs-foo-plugin

一旦插件成功安装，它就可以使用了。它只需要在配置文件中启用。 [MkDocs 插件] wiki页面有一个不断增长的插件列表，您可以安装和使用。

使用插件¶

插件配置选项应该包含在构建网站时使用的插件列表。每个“插件”必须是分配给该插件的字符串名称(请参阅给定插件的文档以确定其“名称”)。这里列出的插件必须已经安装。

plugins:
    - search

一些插件可能提供自己的配置选项。如果你想设置任何配置选项，那么你可以嵌套一个给定插件支持的任何选项的键/值映射(option_name: option value)。注意，插件名后面必须跟着冒号(:)，然后在新行中，选项名和值必须缩进并用冒号分隔。如果你想为一个插件定义多个选项，每个选项必须在单独的行中定义。

plugins:
    - search:
        lang: en
        foo: bar

有关给定插件可用的配置选项的信息，请参阅该插件的文档。

有关默认插件的列表以及如何覆盖它们，请参阅配置文档。

开发插件¶

像MkDocs一样，插件必须用Python编写。尽管可以在同一个模块中定义多个插件，但通常期望每个插件都作为单独的Python模块发布。 MkDocs Plugin至少必须包含一个BasePlugin子类和一个指向它的[入口点]。

BasePlugin¶

mkdocs.plugins.BasePlugin的子类应该定义插件的行为。该类通常由构建过程中对特定事件执行的操作以及插件的配置方案组成。

所有BasePlugin 子类包含以下属性:

config_scheme¶

A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of mkdocs.config.config_options.BaseConfigOption or any of its subclasses.

For example, the following config_scheme defines three configuration options: foo, which accepts a string; bar, which accepts an integer; and baz, which accepts a boolean value.

class MyPlugin(mkdocs.plugins.BasePlugin):
    config_scheme = (
        ('foo', mkdocs.config.config_options.Type(str, default='a default value')),
        ('bar', mkdocs.config.config_options.Type(int, default=0)),
        ('baz', mkdocs.config.config_options.Type(bool, default=True))
    )

New in version 1.4.

Subclassing Config 指定配置模式

为了获得类型安全的好处，如果你只针对MkDocs 1.4+，请将配置模式定义为一个类:

class MyPluginConfig(mkdocs.config.base.Config):
    foo = mkdocs.config.config_options.Type(str, default='a default value')
    bar = mkdocs.config.config_options.Type(int, default=0)
    baz = mkdocs.config.config_options.Type(bool, default=True)

class MyPlugin(mkdocs.plugins.BasePlugin[MyPluginConfig]):
    ...

Examples of config definitions¶

Example

from mkdocs.config import base, config_options as c

class _ValidationOptions(base.Config):
    enable = c.Type(bool, default=True)
    verbose = c.Type(bool, default=False)
    skip_checks = c.ListOfItems(c.Choice(('foo', 'bar', 'baz')), default=[])

class MyPluginConfig(base.Config):
    definition_file = c.File(exists=True)  # required
    checksum_file = c.Optional(c.File(exists=True))  # can be None but must exist if specified
    validation = c.SubConfig(_ValidationOptions)

From the user's point of view SubConfig is similar to Type(dict), it's just that it also retains full ability for validation: you define all valid keys and what each value should adhere to.

And ListOfItems is similar to Type(list), but again, we define the constraint that each value must adhere to.

This accepts a config as follows:

my_plugin:
  definition_file: configs/test.ini  # relative to mkdocs.yml
  validation:
    enable: !ENV [CI, false]
    verbose: true
    skip_checks:
      - foo
      - baz

Example

import numbers
from mkdocs.config import base, config_options as c

class _Rectangle(base.Config):
    width = c.Type(numbers.Real)  # required
    height = c.Type(numbers.Real)  # required

class MyPluginConfig(base.Config):
    add_rectangles = c.ListOfItems(c.SubConfig(_Rectangle))  # required

In this example we define a list of complex items, and that's achieved by passing a concrete SubConfig to ListOfItems.

This accepts a config as follows:

my_plugin:
  add_rectangles:
    - width: 5
      height: 7
    - width: 12
      height: 2

When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes provided in mkdocs.config.config_options or a third party subclass defined in the plugin.

Any settings provided by the user which fail validation or are not defined in the config_scheme will raise a mkdocs.config.base.ValidationError.

config¶

A dictionary of configuration options for the plugin, which is populated by the load_config method after configuration validation has completed. Use this attribute to access options provided by the user.

def on_pre_build(self, config, **kwargs):
    if self.config['baz']:
        # implement "baz" functionality here...

New in version 1.4

Safe attribute-based access¶

To get type safety benefits, if you're targeting only MkDocs 1.4+, access options as attributes instead:

def on_pre_build(self, config, **kwargs):
    if self.config.baz:
        print(self.config.bar ** 2)  # OK, `int ** 2` is valid.

All BasePlugin subclasses contain the following method(s):

load_config(options)¶

Loads configuration from a dictionary of options. Returns a tuple of (errors, warnings). This method is called by MkDocs during configuration validation and should not need to be called by the plugin.

on_<event_name>()¶

Optional methods which define the behavior for specific events. The plugin should define its behavior within these methods. Replace <event_name> with the actual name of the event. For example, the pre_build event would be defined in the on_pre_build method.

Most events accept one positional argument and various keyword arguments. It is generally expected that the positional argument would be modified (or replaced) by the plugin and returned. If nothing is returned (the method returns None), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as **kwargs. In the event that additional keywords are provided to an event in a future version of MkDocs, there will be no need to alter your plugin.

For example, the following event would add an additional static_template to the theme config:

class MyPlugin(BasePlugin):
    def on_config(self, config, **kwargs):
        config['theme'].static_templates.add('my_template.html')
        return config

New in version 1.4

To get type safety benefits, if you're targeting only MkDocs 1.4+, access config options as attributes instead:

def on_config(self, config: MkDocsConfig):
    config.theme.static_templates.add('my_template.html')
        return config

Events¶

There are three kinds of events: Global Events, Page Events and Template Events.

See a diagram with relations between all the plugin events

The events themselves are shown in yellow, with their parameters.
Arrows show the flow of arguments and outputs of each event. Sometimes they're omitted.
The events are chronologically ordered from top to bottom.
Dotted lines appear at splits from global events to per-page events.
Click the events' titles to jump to their description.

One-time Events¶

One-time events run once per mkdocs invocation. The only case where these tangibly differ from global events is for mkdocs serve: global events, unlike these, will run multiple times -- once per build.

on_startup¶

The startup event runs once at the very beginning of an mkdocs invocation.

New in MkDocs 1.4.

The presence of an on_startup method (even if empty) migrates the plugin to the new system where the plugin object is kept across builds within one mkdocs serve.

Note that for initializing variables, the __init__ method is still preferred. For initializing per-build variables (and whenever in doubt), use the on_config event.

Parameters:

command (Literal[build, gh-deploy, serve]) –
the command that MkDocs was invoked with, e.g. "serve" for mkdocs serve.
dirty (bool) –
whether --dirtyreload or --dirty flags were passed.

on_shutdown¶

The shutdown event runs once at the very end of an mkdocs invocation, before exiting.

This event is relevant only for support of mkdocs serve, otherwise within a single build it's undistinguishable from on_post_build.

New in MkDocs 1.4.

The presence of an on_shutdown method (even if empty) migrates the plugin to the new system where the plugin object is kept across builds within one mkdocs serve.

Note the on_post_build method is still preferred for cleanups, when possible, as it has a much higher chance of actually triggering. on_shutdown is "best effort" because it relies on detecting a graceful shutdown of MkDocs.

on_serve¶

The serve event is only called when the serve command is used during development. It runs only once, after the first build finishes. It is passed the Server instance which can be modified before it is activated. For example, additional files or directories could be added to the list of "watched" files for auto-reloading.

Parameters:

server (LiveReloadServer) –
livereload.Server instance
config (MkDocsConfig) –
global configuration object
builder (Callable) –
a callable which gets passed to each call to server.watch

Returns:

Optional[LiveReloadServer] –
livereload.Server instance

Global Events¶

Global events are called once per build at either the beginning or end of the build process. Any changes made in these events will have a global effect on the entire site.

on_config¶

The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here.

Parameters:

config (MkDocsConfig) –
global configuration object

Returns:

Optional[Config] –
global configuration object

on_pre_build¶

The pre_build event does not alter any variables. Use this event to call pre-build scripts.

Parameters:

config (MkDocsConfig) –
global configuration object

on_files¶

The files event is called after the files collection is populated from the docs_dir. Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data.

Parameters:

files (Files) –
global files collection
config (MkDocsConfig) –
global configuration object

Returns:

Optional[Files] –
global files collection

on_nav¶

The nav event is called after the site navigation is created and can be used to alter the site navigation.

Parameters:

nav (Navigation) –
global navigation object
config (MkDocsConfig) –
global configuration object
files (Files) –
global files collection

Returns:

Optional[Navigation] –
global navigation object

on_env¶

The env event is called after the Jinja template environment is created and can be used to alter the Jinja environment.

Parameters:

env (jinja2.Environment) –
global Jinja environment
config (MkDocsConfig) –
global configuration object
files (Files) –
global files collection

Returns:

Optional[jinja2.Environment] –
global Jinja Environment

on_post_build¶

The post_build event does not alter any variables. Use this event to call post-build scripts.

Parameters:

config (MkDocsConfig) –
global configuration object

on_build_error¶

The build_error event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See Handling Errors for more details.

Parameters:

error (Exception) –
exception raised

Template Events¶

Template events are called once for each non-page template. Each template event will be called for each template defined in the extra_templates config setting as well as any static_templates defined in the theme. All template events are called after the env event and before any page events.

on_pre_template¶

The pre_template event is called immediately after the subject template is loaded and can be used to alter the template.

Parameters:

template (jinja2.Template) –
a Jinja2 Template object
template_name (str) –
string filename of template
config (MkDocsConfig) –
global configuration object

Returns:

Optional[jinja2.Template] –
a Jinja2 Template object

on_template_context¶

The template_context event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only.

Parameters:

context (Dict[str, Any]) –
dict of template context variables
template_name (str) –
string filename of template
config (MkDocsConfig) –
global configuration object

Returns:

Optional[Dict[str, Any]] –
dict of template context variables

on_post_template¶

The post_template event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc.

Parameters:

output_content (str) –
output of rendered template as string
template_name (str) –
string filename of template
config (MkDocsConfig) –
global configuration object

Returns:

Optional[str] –
output of rendered template as string

Page Events¶

Page events are called once for each Markdown page included in the site. All page events are called after the post_template event and before the post_build event.

on_pre_page¶

The pre_page event is called before any actions are taken on the subject page and can be used to alter the Page instance.

Parameters:

page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object
files (Files) –
global files collection

Returns:

Optional[Page] –
mkdocs.nav.Page instance

on_page_read_source¶

The on_page_read_source event can replace the default mechanism to read the contents of a page's source from the filesystem.

Parameters:

page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object

Returns:

Optional[str] –
The raw source for a page as unicode string. If None is returned, the default loading from a file will be performed.

on_page_markdown¶

The page_markdown event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as page.meta at this point.

Parameters:

markdown (str) –
Markdown source text of page as string
page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object
files (Files) –
global files collection

Returns:

Optional[str] –
Markdown source text of page as string

on_page_content¶

The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page.

Parameters:

html (str) –
HTML rendered from Markdown source as string
page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object
files (Files) –
global files collection

Returns:

Optional[str] –
HTML rendered from Markdown source as string

on_page_context¶

The page_context event is called after the context for a page is created and can be used to alter the context for that specific page only.

Parameters:

context (Dict[str, Any]) –
dict of template context variables
page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object
nav (Navigation) –
global navigation object

Returns:

Optional[Dict[str, Any]] –
dict of template context variables

on_post_page¶

The post_page event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc.

Parameters:

output (str) –
output of rendered template as string
page (Page) –
mkdocs.nav.Page instance
config (MkDocsConfig) –
global configuration object

Returns:

Optional[str] –
output of rendered template as string

Event Priorities¶

For each event type, corresponding methods of plugins are called in the order that the plugins appear in the plugins config.

Since MkDocs 1.4, plugins can choose to set a priority value for their events. Events with higher priority are called first. Events without a chosen priority get a default of 0. Events that have the same priority are ordered as they appear in the config.

`mkdocs.plugins.event_priority(priority: float) -> Callable[[T], T]` ¶

A decorator to set an event priority for an event handler method.

Recommended priority values: 100 "first", 50 "early", 0 "default", -50 "late", -100 "last". As different plugins discover more precise relations to each other, the values should be further tweaked.

@plugins.event_priority(-100)  # Wishing to run this after all other plugins' `on_files` events.
def on_files(self, files, config, **kwargs):
    ...

New in MkDocs 1.4. Recommended shim for backwards compatibility:

try:
    from mkdocs.plugins import event_priority
except ImportError:
    event_priority = lambda priority: lambda f: f  # No-op fallback

Handling Errors¶

MkDocs defines four error types:

`mkdocs.exceptions.MkDocsException` ¶

Bases: ClickException

The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead.

`mkdocs.exceptions.ConfigurationError` ¶

Bases: MkDocsException

This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's config_scheme.

`mkdocs.exceptions.BuildError` ¶

Bases: MkDocsException

This error may be raised by MkDocs during the build process. Plugins should not raise this error.

`mkdocs.exceptions.PluginError` ¶

Bases: BuildError

A subclass of [mkdocs.exceptions.BuildError][] which can be raised by plugin events.

Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error message. Therefore, MkDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user.

Therefore, you might want to catch any exceptions within your plugin and raise a PluginError, passing in your own custom-crafted message, so that the build process is aborted with a helpful message.

The on_build_error event will be triggered for any exception.

For example:

from mkdocs.exceptions import PluginError
from mkdocs.plugins import BasePlugin


class MyPlugin(BasePlugin):
    def on_post_page(self, output, page, config, **kwargs):
        try:
            # some code that could throw a KeyError
            ...
        except KeyError as error:
            raise PluginError(str(error))

    def on_build_error(self, error, **kwargs):
        # some code to clean things up
        ...

Entry Point¶

Plugins need to be packaged as Python libraries (distributed on PyPI separate from MkDocs) and each must register as a Plugin via a setuptools entry_points. Add the following to your setup.py script:

entry_points={
    'mkdocs.plugins': [
        'pluginname = path.to.some_plugin:SomePluginClass',
    ]
}

The pluginname would be the name used by users (in the config file) and path.to.some_plugin:SomePluginClass would be the importable plugin itself (from path.to.some_plugin import SomePluginClass) where SomePluginClass is a subclass of BasePlugin which defines the plugin behavior. Naturally, multiple Plugin classes could exist in the same module. Simply define each as a separate entry point.

entry_points={
    'mkdocs.plugins': [
        'featureA = path.to.my_plugins:PluginA',
        'featureB = path.to.my_plugins:PluginB'
    ]
}

Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config.

MkDocs 插件¶

安装插件¶

使用插件¶

开发插件¶

BasePlugin¶

config_scheme¶

Examples of config definitions¶

config¶

Safe attribute-based access¶

load_config(options)¶

on_<event_name>()¶

Events¶

One-time Events¶

on_startup¶

on_shutdown¶

on_serve¶

Global Events¶

on_config¶

on_pre_build¶

on_files¶

on_nav¶

on_env¶

on_post_build¶

on_build_error¶

Template Events¶

on_pre_template¶

on_template_context¶

on_post_template¶

Page Events¶

on_pre_page¶

on_page_read_source¶

on_page_markdown¶

on_page_content¶

on_page_context¶

on_post_page¶

Event Priorities¶

mkdocs.plugins.event_priority(priority: float) -> Callable[[T], T] ¶

Handling Errors¶

mkdocs.exceptions.MkDocsException ¶

mkdocs.exceptions.ConfigurationError ¶

mkdocs.exceptions.BuildError ¶

mkdocs.exceptions.PluginError ¶

Entry Point¶

`mkdocs.plugins.event_priority(priority: float) -> Callable[[T], T]` ¶

`mkdocs.exceptions.MkDocsException` ¶

`mkdocs.exceptions.ConfigurationError` ¶

`mkdocs.exceptions.BuildError` ¶

`mkdocs.exceptions.PluginError` ¶