• Officially support Python 3.11 (#3020)

  Note: Simply upgrading to Python 3.11 can cut off 10-15% of your site's build time.

• Support multiple instances of the same plugin (#3027)

  If a plugin is specified multiple times in the list under the plugins: config, that will create 2 (or more) instances of the plugin with their own config each.

  Previously this case was unforeseen and, as such, bugged.

  Now even though this works, by default a warning will appear from MkDocs anyway, unless the plugin adds a class variable supports_multiple_instances = True.

• Bugfix (regression in 1.4.1): Don't error when a plugin puts a plain string into warnings (#3016)

• Bugfix: Relative links will always render with a trailing slash (#3022)

  Previously under use_directory_urls, links from a sub-page to the main index page rendered as e.g. <a href="../.."> even though in all other cases the links look like <a href="../../">. This caused unwanted behavior on some combinations of Web browsers and servers. Now this special-case bug was removed.

• Built-in "mkdocs" theme now also supports Norwegian language (#3024)

• Plugin-related warnings look more readable (#3016)

See commit log.

• Support theme-namespaced plugin loading (#2998)

  Plugins' entry points can be named as 'sometheme/someplugin'. That will have the following outcome:

  • If the current theme is 'sometheme', the plugin 'sometheme/someplugin' will always be preferred over 'someplugin'.
  • If the current theme isn't 'sometheme', the only way to use this plugin is by specifying plugins: [sometheme/someplugin].

  One can also specify plugins: ['/someplugin'] instead of plugins: ['someplugin'] to definitely avoid the theme-namespaced plugin.

• Bugfix: mkdocs serve will work correctly with non-ASCII paths and redirects (#3001)

• Windows: 'colorama' is now a dependency of MkDocs, to ensure colorful log output (#2987)

• Plugin-related config options have more reliable validation and error reporting (#2997)

• Translation sub-commands of setup.py were completely dropped. See documentation [1] [2] for their new replacements (#2990)

• The 'mkdocs' package (wheel and source) is now produced by Hatch build system and pyproject.toml instead of setup.py (#2988)

Other small improvements; see commit log.

Feature upgrades

Hooks (#2978)

The new hooks: config allows you to add plugin-like event handlers from local Python files, without needing to set up and install an actual plugin.

See documentation.

edit_uri flexibility (#2927)

There is a new edit_uri_template: config.
It works like edit_uri but more generally covers ways to construct an edit URL.
See documentation.

Additionally, the edit_uri functionality will now fully work even if repo_url is omitted (#2928)

Upgrades for plugin developers

Note: this release has big changes to the implementation of plugins and their configs. But, the intention is to have zero breaking changes in all reasonably common use cases. Or at the very least if a code fix is required, there should always be a way to stay compatible with older MkDocs versions. Please report if this release breaks something.

Customize event order for plugin event handlers (#2973)

Plugins can now choose to set a priority value for their event handlers. This can override the old behavior where for each event type, the handlers are called in the order that their plugins appear in the plugins config.

If this is set, 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.

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.

See documentation.

New events that persist across builds in mkdocs serve (#2972)

The new events are on_startup and on_shutdown. They run at the very beginning and very end of an mkdocs invocation.
on_startup also receives information on how mkdocs was invoked (e.g. serve --dirtyreload).

See documentation.

Replace File.src_path to not deal with backslashes (#2930)

The property src_path uses backslashes on Windows, which doesn't make sense as it's a virtual path.
To not make a breaking change, there's no change to how this property is used, but now you should:

• Use File.src_uri instead of File.src_path
• and File.dest_uri instead of File.dest_path.

These consistently use forward slashes, and are now the definitive source that MkDocs itself uses.

See source code.

As a related tip: you should also stop using os.path.* or pathlib.Path() to deal with these paths, and instead use posixpath.* or pathlib.PurePosixPath()

MkDocs is type-annotated, ready for use with mypy (#2941, #2970)

Type annotations for event handler methods (#2931)

MkDocs' plugin event methods now have type annotations. You might have been adding annotations to events already, but now they will be validated to match the original.

See source code and documentation.

One big update is that now you should annotate method parameters more specifically as config: defaults.MkDocsConfig instead of config: base.Config. This not only makes it clear that it is the main config of MkDocs itself, but also provides type-safe access through attributes of the object (see next section).

See source code and documentation.

Rework ConfigOption schemas as class-based (#2962)

When developing a plugin, the settings that it accepts used to be specified in the config_scheme variable on the plugin class.
This approach is now soft-deprecated, and instead you should specify the config in a sub-class of base.Config.

Old example:

from mkdocs import plugins
from mkdocs.config import base, config_options

class MyPlugin(plugins.BasePlugin):
    config_scheme = (
        ('foo', config_options.Type(int)),
        ('bar', config_options.Type(str, default='')),
    )

    def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
        if self.config['foo'] < 5:
            if config['site_url'].startswith('http:'):
                return markdown + self.config['baz']

This code snippet actually has many mistakes but it will pass all type checks and silently run and even succeed in some cases.

So, on to the new equivalent example, changed to new-style schema and attribute-based access:
(Complaints from "mypy" added inline)

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

class MyPluginConfig(base.Config):
    foo = c.Optional(c.Type(int))
    bar = c.Type(str, default='')

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: base.MkDocsConfig, **kwargs):
        if self.config.foo < 5:  # Error, `foo` might be `None`, need to check first.
            if config.site_url.startswith('http:'):  # Error, MkDocs' `site_url` also might be `None`.
                return markdown + self.config.baz  # Error, no such attribute `baz`!

This lets you notice the errors from a static type checker before running the code and fix them as such:

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: base.MkDocsConfig, **kwargs):
        if self.config.foo is not None and self.config.foo < 5:  # OK, `int < int` is valid.
            if (config.site_url or '').startswith('http:'):  # OK, `str.startswith(str)` is valid.
                return markdown + self.config.bar  # OK, `str + str` is valid.

See documentation.

Also notice that we had to explicitly mark the config attribute foo as Optional.
The new-style config has all attributes marked as required by default, and specifying required=False or required=True is not allowed!

New: config_options.Optional (#2962)

Wrapping something into Optional is conceptually similar to "I want the default to be None" -- and you have to express it like that, because writing default=None doesn't actually work.

Breaking change: the method BaseConfigOption.is_required() was removed. Use .required instead. (#2938)
And even the required property should be mostly unused now.
For class-based configs, there's a new definition for whether an option is "required":

• It has no default, and
• It is not wrapped into config_options.Optional.

New: config_options.ListOfItems (#2938)

Defines a list of items that each must adhere to the same constraint. Kind of like a validated Type(list)

Examples how to express a list of integers (with from mkdocs.config import config_options as c):

Description | Code entry ----------- | ---------- Required to specify | foo = c.ListOfItems(c.Type(int)) Optional, default is [] | foo = c.ListOfItems(c.Type(int), default=[]) Optional, default is None | foo = c.Optional(c.ListOfItems(c.Type(int)))

See more examples in documentation.

Updated: config_options.SubConfig (#2807)

SubConfig used to silently ignore all validation of its config options. Now you should pass validate=True to it or just use new class-based configs where this became the default.

So, it can be used to validate a nested sub-dict with all keys pre-defined and value types strictly validated.

See examples in documentation.

Other changes to config options

URL's default is now None instead of ''. This can still be checked for truthiness in the same way - if config.some_url: (#2962)

FilesystemObject is no longer abstract and can be used directly, standing for "file or directory" with optional existence checking (#2938)

Bug fixes:

• Fix SubConfig, ConfigItems, MarkdownExtensions to not leak values across different instances (#2916, #2290)
• SubConfig raises the correct kind of validation error without a stack trace (#2938)
• Fix dot-separated redirect in config_options.Deprecated(moved_to) (#2963)

Tweaked logic for handling ConfigOption.default (#2938)

Deprecated config option classes: ConfigItems (#2983), OptionallyRequired (#2962), RepoURL (#2927)

Theme updates

• Styles of admonitions in "MkDocs" theme (#2981):

  • Update colors to increase contrast
  • Apply admonition styles also to <details> tag, to support Markdown extensions that provide it (pymdownx.details, callouts)

• Built-in themes now also support these languages:

  • Russian (#2976)
  • Turkish (Turkey) (#2946)
  • Ukrainian (#2980)

Future compatibility

• extra_css: and extra_javascript: warn if a backslash \ is passed to them. (#2930, #2984)

• Show DeprecationWarnings as INFO messages. (#2907)

  If any plugin or extension that you use relies on deprecated functionality of other libraries, it is at risk of breaking in the near future. Plugin developers should address these in a timely manner.

• Avoid a dependency on importlib_metadata starting from Python 3.10 (#2959)

• Drop support for Python 3.6 (#2948)

Incompatible changes to public APIs

• mkdocs.utils:
  • create_media_urls and normalize_url warn if a backslash \ is passed to them. (#2930)
  • is_markdown_file stops accepting case-insensitive variants such as .MD, which is how MkDocs build was already operating. (#2912)
  • Hard-deprecated: modified_time, reduce_list, get_html_path, get_url_path, is_html_file, is_template_file. (#2912)

Miscellaneous

• If a plugin adds paths to watch in LiveReloadServer, it can now unwatch them. (#2777)

• Bugfix (regression in 1.2): Support listening on an IPv6 address in mkdocs serve. (#2951)

Other small improvements; see commit log.

• Pin Python-Markdown version to <3.4, thus excluding its latest release that breaks too many external extensions (#2893)

• When a Markdown extension fails to load, print its name and traceback (#2894)

• Bugfix for "readthedocs" theme (regression in 1.3.0): add missing space in breadcrumbs (#2810)

• Bugfix: don't complain when a file "readme.md" (lowercase) exists, it's not recognized otherwise (#2852)

• Built-in themes now also support these languages:

  • Italian (#2860)

Other small improvements; see commit log.

Feature upgrades

• ReadTheDocs theme updated from v0.4.1 to v1.0.0 according to upstream (#2585)

  The most notable changes:

  • New option logo: Rather than displaying the site_name in the title, one can specify a path to an image to display instead.
  • New option anonymize_ip for Google Analytics.
  • Dependencies were upgraded: jQuery upgraded to 3.6.0, Modernizr.js dropped, and others.

  See documentation of config options for the theme

• Built-in themes now also support these languages:

  • German (#2633)
  • Persian (Farsi) (#2787)

• Support custom directories to watch when running mkdocs serve (#2642)

  MkDocs by default watches the docs directory and the config file. Now there is a way to add more directories to watch for changes, either via the YAML watch key or the command line flag --watch.

  Normally MkDocs never reaches into any other directories (so this feature shouldn't be necessary), but some plugins and extensions may do so.

  See documentation.

• New --no-history option for gh_deploy (#2594)

  Allows to discard the history of commits when deploying, and instead replace it with one root commit

Bug fixes

• An XSS vulnerability when using the search function in built-in themes was fixed (#2791)

• Setting the edit_uri option no longer erroneously adds a trailing slash to repo_url (#2733)

Miscellaneous

• Breaking change: the pages config option that was deprecated for a very long time now causes an error when used (#2652)

  To fix the error, just change from pages to nav.

• Performance optimization: during startup of MkDocs, code and dependencies of other commands will not be imported (#2714)

  The most visible effect of this is that dependencies of mkdocs serve will not be imported when mkdocs build is used.

• Recursively validate nav (#2680)

  Validation of the nested nav structure has been reworked to report errors early and reliably. Some edge cases have been declared invalid.

Other small improvements; see commit log.

• Compatibility with Jinja2 3.1.0 (#2800)

  Due to a breaking change in Jinja2, MkDocs would crash with the message AttributeError: module 'jinja2' has no attribute 'contextfilter'

MkDocs 1.2.3 is a bugfix release for MkDocs 1.2.

Aside: MkDocs has a new chat room on Gitter/Matrix. More details.

Improvements:

• Built-in themes now also support these languages:

  • Simplified Chinese (#2497)
  • Japanese (#2525)
  • Brazilian Portuguese (#2535)
  • Spanish (#2545, previously #2396)

• Third-party plugins will take precedence over built-in plugins with the same name (#2591)

• Bugfix: Fix ability to load translations for some languages: core support (#2565) and search plugin support with fallbacks (#2602)

• Bugfix (regression in 1.2): Prevent directory traversal in the dev server (#2604)

• Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a build failure in strict mode (#2607)

• Bugfix: Correctly print colorful messages in the terminal on Windows (#2606)

• Bugfix: Python version 3.10 was displayed incorrectly in --version (#2618)

Other small improvements; see commit log.

MkDocs 1.2.2 is a bugfix release for MkDocs 1.2 -- make sure you've seen the "major" release notes as well.

• Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters (#2464)

• Bugfix (regression in 1.2): Revert livereload file watching to use polling observer (#2477)

  This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts.

  This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage.

• Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls (#2490)

• Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server (#2507)

  Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before.

• Bugfix: Fix gh_deploy with config-file in the current directory (#2481)

• Bugfix: Fix reversed breadcrumbs in "readthedocs" theme (#2179)

• Allow "mkdocs.yaml" as the file name when '--config' is not passed (#2478)

• Stop treating ";" as a special character in URLs: urlparse -> urlsplit (#2502)

• Improve build performance for sites with many pages (partly already done in 1.2) (#2407)