Plugins - MkDocs
MkDocs
Home
Getting Started
User Guide
User Guide
Installation
Writing Your Docs
Choosing Your Theme
Customizing Your Theme
Localizing Your Theme
Configuration
Command Line Interface
Deploying Your Docs
Developer Guide
Developer Guide
Themes
Translations
Plugins
API Reference
About
Release Notes
Contributing
License
Search
Previous
Next
Edit on GitHub
MkDocs Plugins
Installing Plugins
Using Plugins
Developing Plugins
MkDocs Plugins
A Guide to installing, using and creating MkDocs Plugins
Installing Plugins
Before a plugin can be used, it must be installed on the system. If you are
using a plugin which comes with MkDocs, then it was installed when you installed
MkDocs. However, to install third party plugins, you need to determine the
appropriate package name and install it using pip:
pip install mkdocs-foo-plugin
Warning
Installing an MkDocs plugin means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.
Once a plugin has been successfully installed, it is ready to use. It just needs
to be enabled in the configuration file. The Catalog
repository has a large ranked list of plugins that you can install and use.
Using Plugins
The plugins configuration option should contain a list of plugins to
use when building the site. Each "plugin" must be a string name assigned to the
plugin (see the documentation for a given plugin to determine its "name"). A
plugin listed here must already be installed.
plugins:
- search
Some plugins may 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 plugin supports. Note
that a colon (:) must follow the plugin name 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 plugin, each option must be defined on a
separate line.
plugins:
- search:
lang: en
foo: bar
For information regarding the configuration options available for a given plugin,
see that plugin's documentation.
For a list of default plugins and how to override them, see the
configuration documentation.
Developing Plugins
Like MkDocs, plugins must be written in Python. It is generally expected that
each plugin would be distributed as a separate Python module, although it is
possible to define multiple plugins in the same module. At a minimum, a MkDocs
Plugin must consist of a BasePlugin subclass and an entry point which
points to it.
BasePlugin
A subclass of mkdocs.plugins.BasePlugin should define the behavior of the plugin.
The class generally consists of actions to perform on specific events in the build
process as well as a configuration scheme for the plugin.
All BasePlugin subclasses contain the following attributes:
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 to specify the config schema
To get type safety benefits, if you're targeting only MkDocs 1.4+, define the config schema as a class instead:
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):
enabled = 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:
enabled: !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.
MkDocs
cluster_on_startup
on_startup
cluster_build
build
cluster_on_config
on_config
cluster_on_pre_build
on_pre_build
cluster_on_files
on_files
cluster_on_nav
on_nav
cluster_populate_page
populate_page
cluster_on_pre_page
on_pre_page
cluster_on_page_read_source
on_page_read_source
cluster_on_page_markdown
on_page_markdown
cluster_on_page_content
on_page_content
cluster_on_env
on_env
cluster_populate_page_2
populate_page
cluster_populate_page_3
populate_page
cluster_build_page
build_page
cluster_on_page_context
on_page_context
cluster_on_post_page
on_post_page
cluster_build_page_2
build_page
cluster_build_page_3
build_page
cluster_on_post_build
on_post_build
cluster_on_serve
on_serve
cluster_on_shutdown
on_shutdown
on_startup
command
dirty
load_config
load_config
on_config
config
on_pre_build
config
on_config:s->on_pre_build:n
get_files
get_files
on_config:s->get_files
on_files
files
config
on_nav
nav
config
files
on_files:s->on_nav:n
get_nav
get_nav
on_files:s->get_nav
render_p
render
pages_point_a
on_nav:s->pages_point_a
get_context
get_context
on_nav:s->get_context
load_config->on_config:n
get_files->on_files:n
get_nav->on_nav:n
on_pre_page
page
config
files
on_page_read_source
page
config
on_pre_page:s->on_page_read_source:n
on_page_markdown
markdown
page
config
files
on_page_read_source:s->on_page_markdown:n
on_page_markdown:s->render_p
on_page_content
html
page
config
files
pages_point_b
on_page_content:s->pages_point_b
on_env
env
config
files
render_p->on_page_content:n
pages_point_a->on_pre_page:n
pages_point_a->render_p
placeholder_cluster_populate_page_2
...
pages_point_a->placeholder_cluster_populate_page_2:n
placeholder_cluster_populate_page_3
...
pages_point_a->placeholder_cluster_populate_page_3:n
placeholder_cluster_populate_page_2:s->pages_point_b
pages_point_b->on_env:n
pages_point_c
pages_point_b->pages_point_c
placeholder_cluster_populate_page_3:s->pages_point_b
on_env:s->get_context
on_page_context
context
page
config
nav
pages_point_c->on_page_context:n
placeholder_cluster_build_page_2
...
pages_point_c->placeholder_cluster_build_page_2:n
placeholder_cluster_build_page_3
...
pages_point_c->placeholder_cluster_build_page_3:n
render
render
on_page_context:s->render
on_post_page
output
page
config
write_file
write_file
on_post_page:s->write_file
get_context->on_page_context:n
render->on_post_page:n
get_template
get_template
get_template->render
on_post_build
config
on_serve
server
config
on_shutdown
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 --dirty flag was 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:
LiveReloadServer | None
–
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:
MkDocsConfig | None
–
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:
Files | None
–
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:
Navigation | None
–
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
(Environment)
–
global Jinja environment
config
(MkDocsConfig)
–
global configuration object
files
(Files)
–
global files collection
Returns:
Environment | None
–
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
(Template)
–
a Jinja2 Template object
template_name
(str)
–
string filename of template
config
(MkDocsConfig)
–
global configuration object
Returns:
Template | None
–
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
(TemplateContext)
–
dict of template context variables
template_name
(str)
–
string filename of template
config
(MkDocsConfig)
–
global configuration object
Returns:
TemplateContext | None
–
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:
str | None
–
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.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
files
(Files)
–
global files collection
Returns:
Page | None
–
mkdocs.structure.pages.Page instance
on_page_read_source
Deprecated
Instead of this event, prefer one of these alternatives:
Since MkDocs 1.6, instead set content_bytes/content_string of a File inside on_files.
Usually (although it's not an exact alternative), on_page_markdown can serve the same purpose.
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.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
Returns:
str | None
–
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.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
files
(Files)
–
global files collection
Returns:
str | None
–
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.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
files
(Files)
–
global files collection
Returns:
str | None
–
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
(TemplateContext)
–
dict of template context variables
page
(Page)
–
mkdocs.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
nav
(Navigation)
–
global navigation object
Returns:
TemplateContext | None
–
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.structure.pages.Page instance
config
(MkDocsConfig)
–
global configuration object
Returns:
str | None
–
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.
Usage example:
@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
New in version 1.6
There may also arise a need to register a handler for the same event at multiple different priorities.
CombinedEvent makes this possible.
mkdocs.plugins.CombinedEvent

Bases: Generic[P, T]
A descriptor that allows defining multiple event handlers and declaring them under one event's name.
Usage example:
@plugins.event_priority(100)
def _on_page_markdown_1(self, markdown: str, **kwargs):
...
@plugins.event_priority(-50)
def _on_page_markdown_2(self, markdown: str, **kwargs):
...
on_page_markdown = plugins.CombinedEvent(_on_page_markdown_1, _on_page_markdown_2)
Note
The names of the sub-methods can't start with on_;
instead they can start with _on_ like in the the above example, or anything else.
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(f"Failed to find the item by key: '{error}'")
def on_build_error(self, error, **kwargs):
# some code to clean things up
...
Logging in plugins
To ensure that your plugins' log messages adhere with MkDocs' formatting and --verbose/--debug flags, please write the logs to a logger under the mkdocs.plugins. namespace.
Example
import logging
log = logging.getLogger(f"mkdocs.plugins.{__name__}")
log.warning("File '%s' not found. Breaks the build if --strict is passed", my_file_name)
log.info("Shown normally")
log.debug("Shown only with `--verbose`")
if log.getEffectiveLevel() <= logging.DEBUG:
log.debug("Very expensive calculation only for debugging: %s", get_my_diagnostics())
log.error() is another logging level that is differentiated by its look, but in all other ways it functions the same as warning, so it's strange to use it. If your plugin encounters an actual error, it is best to just interrupt the build by raising mkdocs.exceptions.PluginError (which will also log an ERROR message).
New in version 1.5
MkDocs now provides a get_plugin_logger() convenience function that returns a logger like the above that is also prefixed with the plugin's name.
mkdocs.plugins.get_plugin_logger(name: str) -> PrefixedLogger

Return a logger for plugins.
Parameters:
name
(str)
–
The name to use with logging.getLogger.
Returns:
PrefixedLogger
–
A logger configured to work well in MkDocs,
prefixing each message with the plugin package name.
Example
from mkdocs.plugins import get_plugin_logger
log = get_plugin_logger(__name__)
log.info("My plugin message")
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.
Publishing a Plugin
You should publish a package on PyPI, then add it to the Catalog for discoverability. Plugins are strongly recommended to have a unique plugin name (entry point name) according to the catalog.
Copyright © 2014 Tom Christie, Maintained by the MkDocs Team.
Documentation built with MkDocs.
Search
×Close
From here you can search these documents. Enter your search terms below.
Keyboard Shortcuts
×Close
Keys
Action
?
Open this help
n
Next page
p
Previous page
s
Search