Release Notes

Upgrading

To upgrade MkDocs to the latest version, use pip:

pip install -U mkdocs

You can determine your currently installed version using mkdocs --version:

$ mkdocs --version
mkdocs, version 1.0 from /path/to/mkdocs (Python 3.6)

Maintenance team

The current and past members of the MkDocs team.

Version 1.2 (Under development)

Major Additions to Version 1.2

Support added for Environment Variables in the configuration file (#1954)

Environments variables may now be specified in the configuration file with the !ENV tag. The value of the variable will be parsed by the YAML parser and converted to the appropriate type.

somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']

See Environment Variables in the Configuration documentation for details.

Update gh-deploy command (#2170)

The vendored (and modified) copy of ghp_import has been replaced with a dependency on the upstream library. As of version 1.0.0, [ghp_import] includes a Python API which makes it possible to call directly.

MkDocs can now benefit from recent bug fixes and new features, including the following:

A build_error event was added (#2103)

Plugin developers can now use the on_build_error hook to execute code when an exception is raised while building the site.

See on_build_error in the Plugins documentation for details.

Three new exceptions: BuildError PluginError and Abort (#2103)

MkDocs now has tree new exceptions defined in mkdocs.exceptions: BuildError, PluginError, and Abort:

See Handling errors in the Plugins documentation for details.

Search Indexing Strategy configuration

Users can now specify which strategy they wish to use when indexing their site for search. A user can select between the following options:

See Search Indexing in the configuration documentation for details.

Backward Incompatible Changes in 1.2

A theme's files are now excluded from the list of watched files by default when using the --livereload server. This new default behavior is what most users need and provides better performance when editing site content. Theme developers can enable the old behavior with the --watch-theme option. (#2092).

The mkdocs theme now removes the sidebar when printing a page. This frees up horizontal space for better rendering of content like tables (#2193).

The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema(), which ensures that each instance of the configuration is unique (#2289).

The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e: mkdocs.plugins.pluginname).

Other Changes and Additions to Version 1.2

Version 1.1.2 (2020-05-14)

Version 1.1.1 (2020-05-12)

Version 1.1 (2020-02-22)

Major Additions to Version 1.1

Support for Lunr.py as prebuild_index engine

Mkdocs now supports prebuilding indices using Lunr.py, a pure Python implementation of Lunr.js, allowing the user to avoid installing a NodeJS environment if so desired. For more information please read the prebuild_index documentation.

readthedocs theme updated with upstream (#588 and #1374)

The readthedocs theme now more closely matches the upstream Sphinx theme (version 0.4.1). A number of new theme configuration settings were added which mirror the upstream configuration options. See the theme documentation for details.

Update mkdocs theme to Bootswatch 4.1.3 (#1563)

The mkdocs theme now supports all the features of Bootswatch 4.1. Additionaly, 2 filenames were changed in this update. If you are using a theme which inherits from the mkdocs theme, the theme developer may need to update these filenames as follows.

css/bootstrap-custom.min.css => css/bootstrap.min.css
js/bootstrap-3.0.3.min.js => js/bootstrap.min.js

Improved configuration support on the command line (#1401)

The build, serve, and gh-deploy subcommands now support flags to control whether directory URLs should be created: --use-directory-urls / --no-directory-urls. In addition, the gh-deploy subcommand now supports all the configuration options that build and serve do, adding --strict, --theme, --theme-dir, and --site-dir.

Updated lunr-languages support (#1729)

The lunr-languages plugin has been updated to 1.4.0, adding support for Arabic (ar) and Vietnamese (vi) languages. In addition, the Dutch and Japanese language codes have been changed to their standard values: nl and ja, respectively. The old language codes (du and jp) remain as aliases but may be removed in a future version of MkDocs.

Other Changes and Additions to Version 1.1

Version 1.0.4 (2018-09-07)

Version 1.0.3 (2018-08-29)

Version 1.0.2 (2018-08-22)

Version 1.0.1 (2018-08-13)

Version 1.0 (2018-08-03)

Major Additions to Version 1.0

Internal Refactor of Pages, Files, and Navigation

Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below.

Backward Incompatible Changes

As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below.

URLS have changed when use_directory_urls is False

Previously, all Markdown pages would be have their filenames altered to be index pages regardless of how the use_directory_urls setting was configured. However, the path munging is only needed when use_directory_urls is set to True (the default). The path mungling no longer happens when use_directory_urls is set to False, which will result in different URLs for all pages that were not already index files. As this behavior only effects a non-default configuration, and the most common user-case for setting the option to False is for local file system (file://) browsing, its not likely to effect most users. However, if you have use_directory_urls set to False for a MkDocs site hosted on a web server, most of your URLs will now be broken. As you can see below, the new URLs are much more sensible.

Markdown file Old URL New URL
index.md index.html index.html
foo.md foo/index.html foo.html
foo/bar.md foo/bar/index.html foo/bar.html

Note that there has been no change to URLs or file paths when use_directory_urls is set to True (the default), except that MkDocs more consistently includes an ending slash on all internally generated URLs.

The pages configuration setting has been renamed to nav

The pages configuration setting is deprecated and will issue a warning if set in the configuration file. The setting has been renamed nav. To update your configuration, simply rename the setting to nav. In other words, if your configuration looked like this:

pages:
    - Home: index.md
    - User Guide: user-guide.md

Simply edit the configuration as follows:

nav:
    - Home: index.md
    - User Guide: user-guide.md

In the current release, any configuration which includes a pages setting, but no nav setting, the pages configuration will be copied to nav and a warning will be issued. However, in a future release, that may no longer happen. If both pages and nav are defined, the pages setting will be ignored.

Template variables and base_url

In previous versions of MkDocs some URLs expected the base_url template variable to be prepended to the URL and others did not. That inconsistency has been removed in that no URLs are modified before being added to the template context.

For example, a theme template might have previously included a link to the site_name as:

<a href="{{ nav.homepage.url }}">{{ config.site_name }}</a>

And MkDocs would magically return a URL for the homepage which was relative to the current page. That "magic" has been removed and the url template filter should be used:

<a href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>

This change applies to any navigation items and pages, as well as the page.next_page and page.previous_page attributes. For the time being, the extra_javascript and extra_css variables continue to work as previously (without the url template filter), but they have been deprecated and the corresponding configuration values (config.extra_javascript and config.extra_css respectively) should be used with the filter instead.

{% for path in config['extra_css'] %}
    <link href="{{ path|url }}" rel="stylesheet">
{% endfor %}

Note that navigation can now include links to external sites. Obviously, the base_url should not be prepended to these items. However, the url template filter is smart enough to recognize the URL is absolute and does not alter it. Therefore, all navigation items can be passed to the filter and only those that need to will be altered.

{% for nav_item in nav %}
    <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
{% endfor %}

Path Based Settings are Relative to Configuration File (#543)

Previously any relative paths in the various configuration options were resolved relative to the current working directory. They are now resolved relative to the configuration file. As the documentation has always encouraged running the various MkDocs commands from the directory that contains the configuration file (project root), this change will not affect most users. However, it will make it much easier to implement automated builds or otherwise run commands from a location other than the project root.

Simply use the -f/--config-file option and point it at the configuration file:

mkdocs build --config-file /path/to/my/config/file.yml

As previously, if no file is specified, MkDocs looks for a file named mkdocs.yml in the current working directory.

Added support for YAML Meta-Data (#1542)

Previously, MkDocs only supported MultiMarkdown style meta-data, which does not recognize different data types and is rather limited. MkDocs now also supports YAML style meta-data in Markdown documents. MkDocs relies on the the presence or absence of the deliminators (--- or ...) to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used.

Previously MkDocs would recognize MultiMarkdown style meta-data between the deliminators. Now, if the deliminators are detected, but the content between the deliminators is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data. Therefore, MultiMarkdowns style meta-data must not include the deliminators. See the MultiMarkdown style meta-data documentation for details.

Prior to version 0.17, MkDocs returned all meta-data values as a list of strings (even a single line would return a list of one string). In version 0.17, that behavior was changed to return each value as a single string (multiple lines were joined), which some users found limiting (see #1471). That behavior continues for MultiMarkdown style meta-data in the current version. However, YAML style meta-data supports the full range of "safe" YAML data types. Therefore, it is recommended that any complex meta-data make use of the YAML style (see the YAML style meta-data documentation for details). In fact, a future version of MkDocs may deprecate support for MultiMarkdown style meta-data.

Refactor Search Plugin

The search plugin has been completely refactored to include support for the following features:

Users can review the configuration options available and theme authors should review how search and themes interact.

theme_dir Configuration Option fully Deprecated

As of version 0.17, the custom_dir option replaced the deprecated theme_dir option. If users had set the theme_dir option, MkDocs version 0.17 copied the value to the theme.custom_dir option and a warning was issued. As of version 1.0, the value is no longer copied and an error is raised.

Other Changes and Additions to Version 1.0

Version 0.17.5 (2018-07-06)

Version 0.17.4 (2018-06-08)

Version 0.17.3 (2018-03-07)

Version 0.17.2 (2017-11-15)

Version 0.17.1 (2017-10-30)

Version 0.17.0 (2017-10-19)

Major Additions to Version 0.17.0

Plugin API. (#206)

A new Plugin API has been added to MkDocs which allows users to define their own custom behaviors. See the included documentation for a full explanation of the API.

The previously built-in search functionality has been removed and wrapped in a plugin (named "search") with no changes in behavior. When MkDocs builds, the search index is now written to search/search_index.json instead of mkdocs/search_index.json. If no plugins setting is defined in the config, then the search plugin will be included by default. See the configuration documentation for information on overriding the default.

Theme Customization. (#1164)

Support had been added to provide theme specific customizations. Theme authors can define default options as documented in Theme Configuration. A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. The theme configuration is defined in a configuration file named mkdocs_theme.yml which should be placed at the root of your template files. A warning will be raised if no configuration file is found and an error will be raised in a future release.

Users can override those defaults under the theme configuration option of their mkdocs.yml configuration file, which now accepts nested options. One such nested option is the custom_dir option, which replaces the now deprecated theme_dir option. If users had previously set the theme_dir option, a warning will be issued, with an error expected in a future release.

If a configuration previously defined a theme_dir like this:

theme: mkdocs
theme_dir: custom

Then the configuration should be adjusted as follows:

theme:
    name: mkdocs
    custom_dir: custom

See the theme configuration option documentation for details.

Previously deprecated Template variables removed. (#1168)

Page Template

The primary entry point for page templates has been changed from base.html to main.html. This allows base.html to continue to exist while allowing users to override main.html and extend base.html. For version 0.16, base.html continued to work if no main.html template existed, but it raised a deprecation warning. In version 1.0, a build will fail if no main.html template exists.

Context Variables

Page specific variable names in the template context have been refactored as defined in Custom Themes. The old variable names issued a warning in version 0.16, but have been removed in version 1.0.

Any of the following old page variables should be updated to the new ones in user created and third-party templates:

Old Variable Name New Variable Name
current_page page
page_title page.title
content page.content
toc page.toc
meta page.meta
canonical_url page.canonical_url
previous_page page.previous_page
next_page page.next_page

Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below:

Old Variable Name New Variable Name or Expression
current_page page
include_nav nav|length>1
include_next_prev (page.next_page or page.previous_page)
site_name config.site_name
site_author config.site_author
page_description config.site_description
repo_url config.repo_url
repo_name config.repo_name
site_url config.site_url
copyright config.copyright
google_analytics config.google_analytics
homepage_url nav.homepage.url
favicon {{ base_url }}/img/favicon.ico

Auto-Populated extra_css and extra_javascript Fully Deprecated. (#986)

In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. On version 0.16 this behavior was deprecated and a warning was issued. In 0.17 any unlisted CSS and JavaScript files will not be included in the HTML templates, however, a warning will be issued. In other words, they will still be copied to the site-dir, but they will not have any effect on the theme if they are not explicitly listed.

All CSS and javaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.

Other Changes and Additions to Version 0.17.0

Version 0.16.3 (2017-04-04)

Version 0.16.2 (2017-03-13)

Version 0.16.1 (2016-12-22)

Version 0.16 (2016-11-04)

Major Additions to Version 0.16.0

Template variables refactored. (#874)

Page Context

Page specific variable names in the template context have been refactored as defined in Custom Themes. The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version.

Any of the following old page variables should be updated to the new ones in user created and third-party templates:

Old Variable Name New Variable Name
current_page page
page_title page.title
content page.content
toc page.toc
meta page.meta
canonical_url page.canonical_url
previous_page page.previous_page
next_page page.next_page
Global Context

Additionally, a number of global variables have been altered and/or deprecated and user created and third-party templates should be updated as outlined below:

Previously, the global variable include_nav was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if nav|length>1 %} instead.

Previously, the global variable include_next_prev was altered programmatically based on the number of pages in the nav. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use {% if page.next_page or page.previous_page %} instead.

Previously the global variable page_description was altered programmatically based on whether the current page was the homepage. Now it simply maps to config['site_description']. Use {% if page.is_homepage %} in the template to conditionally change the description.

The global variable homepage_url maps directly to nav.homepage.url and is being deprecated. The variable will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use nav.homepage.url instead.

The global variable favicon maps to the configuration setting site_favicon. Both the template variable and the configuration setting are being deprecated and will issue a warning but continue to work for version 0.16, and may be removed in a future version. Use {{ base_url }}/img/favicon.ico in your template instead. Users can simply save a copy of their custom favicon icon to img/favicon.ico in either their docs_dir or theme_dir.

A number of variables map directly to similarly named variables in the config. Those variables are being deprecated and will issue a warning but continue to work for version 0.16, but may be removed in a future version. Use config.var_name instead, where var_name is the name of one of the configuration variables.

Below is a summary of all of the changes made to the global context:

Old Variable Name New Variable Name or Expression
current_page page
include_nav nav|length>1
include_next_prev (page.next_page or page.previous_page)
site_name config.site_name
site_author config.site_author
page_description config.site_description
repo_url config.repo_url
repo_name config.repo_name
site_url config.site_url
copyright config.copyright
google_analytics config.google_analytics
homepage_url nav.homepage.url
favicon {{ base_url }}/img/favicon.ico

Increased Template Customization. (#607)

The built-in themes have been updated by having each of their many parts wrapped in template blocks which allow each individual block to be easily overridden using the theme_dir config setting. Without any new settings, you can use a different analytics service, replace the default search function, or alter the behavior of the navigation, among other things. See the relevant documentation for more details.

To enable this feature, the primary entry point for page templates has been changed from base.html to main.html. This allows base.html to continue to exist while allowing users to override main.html and extend base.html. For version 0.16, base.html will continue to work if no main.html template exists, but it is deprecated and will raise a warning. In version 1.0, a build will fail if no main.html template exists. Any custom and third party templates should be updated accordingly.

The easiest way for a third party theme to be updated would be to simply add a main.html file which only contains the following line:

{% extends "base.html" %}

That way, the theme contains the main.html entry point, and also supports overriding blocks in the same manner as the built-in themes. Third party themes are encouraged to wrap the various pieces of their templates in blocks in order to support such customization.

Auto-Populated extra_css and extra_javascript Deprecated. (#986)

In previous versions of MkDocs, if the extra_css or extra_javascript config settings were empty, MkDocs would scan the docs_dir and auto-populate each setting with all of the CSS and JavaScript files found. This behavior is deprecated and a warning will be issued. In the next release, the auto-populate feature will stop working and any unlisted CSS and JavaScript files will not be included in the HTML templates. In other words, they will still be copied to the site-dir, but they will not have any effect on the theme if they are not explicitly listed.

All CSS and javaScript files in the docs_dir should be explicitly listed in the extra_css or extra_javascript config settings going forward.

Support for dirty builds. (#990)

For large sites the build time required to create the pages can become problematic, thus a "dirty" build mode was created. This mode simply compares the modified time of the generated HTML and source markdown. If the markdown has changed since the HTML then the page is re-constructed. Otherwise, the page remains as is. This mode may be invoked in both the mkdocs serve and mkdocs build commands:

mkdocs serve --dirtyreload

mkdocs build --dirty

It is important to note that this method for building the pages is for development of content only, since the navigation and other links do not get updated on other pages.

Stricter Directory Validation

Previously, a warning was issued if the site_dir was a child directory of the docs_dir. This now raises an error. Additionally, an error is now raised if the docs_dir is set to the directory which contains your config file rather than a child directory. You will need to rearrange you directory structure to better conform with the documented layout.

Other Changes and Additions to Version 0.16.0

Version 0.15.3 (2016-02-18)

Version 0.15.2 (2016-02-08)

Version 0.15.1 (2016-01-30)

Version 0.15.0 (2016-01-21)

Major Additions to Version 0.15.0

Add support for installable themes

MkDocs now supports themes that are distributed via Python packages. With this addition, the Bootstrap and Bootswatch themes have been moved to external git repositories and python packages. See their individual documentation for more details about these specific themes.

They will be included with MkDocs by default until a future release. After that they will be installable with pip: pip install mkdocs-bootstrap and pip install mkdocs-bootswatch

See the documentation for Customizing Your Theme for more information about using and customizing themes and Custom themes for creating and distributing new themes

Other Changes and Additions to Version 0.15.0

Version 0.14.0 (2015-06-09)

Version 0.13.3 (2015-06-02)

Version 0.13.2 (2015-05-30)

Version 0.13.1 (2015-05-27)

Version 0.13.0 (2015-05-26)

Deprecations to Version 0.13.0

Deprecate the JSON command

In this release the mkdocs json command has been marked as deprecated and when used a deprecation warning will be shown. It will be removed in a future release of MkDocs, version 1.0 at the latest. The mkdocs json command provided a convenient way for users to output the documentation contents as JSON files but with the additions of search to MkDocs this functionality is duplicated.

A new index with all the contents from a MkDocs build is created in the site_dir, so with the default value for the site_dir It can be found in site/mkdocs/search_index.json.

This new file is created on every MkDocs build (with mkdocs build) and no configuration is needed to enable it.

Change the pages configuration

Provide a new way to define pages, and specifically nested pages, in the mkdocs.yml file and deprecate the existing approach, support will be removed with MkDocs 1.0.

Warn users about the removal of builtin themes

All themes other than mkdocs and readthedocs will be moved into external packages in a future release of MkDocs. This will enable them to be more easily supported and updates outside MkDocs releases.

Major Additions to Version 0.13.0

Support for search has now been added to MkDocs. This is based on the JavaScript library lunr.js. It has been added to both the mkdocs and readthedocs themes. See the custom theme documentation on supporting search for adding it to your own themes.

New Command Line Interface

The command line interface for MkDocs has been re-written with the Python library Click. This means that MkDocs now has an easier to use interface with better help output.

This change is partially backwards incompatible as while undocumented it was possible to pass any configuration option to the different commands. Now only a small subset of the configuration options can be passed to the commands. To see in full commands and available arguments use mkdocs --help and mkdocs build --help to have them displayed.

Support Extra HTML and XML files

Like the extra_javascript and extra_css configuration options, a new option named extra_templates has been added. This will automatically be populated with any .html or .xml files in the project docs directory.

Users can place static HTML and XML files and they will be copied over, or they can also use Jinja2 syntax and take advantage of the global variables.

By default MkDocs will use this approach to create a sitemap for the documentation.

Other Changes and Additions to Version 0.13.0

Version 0.12.2 (2015-04-22)

Version 0.12.1 (2015-04-14)

Version 0.12.0 (2015-04-14)

Version 0.11.1 (2014-11-20)

Version 0.11.0 (2014-11-18)

Version 0.10.0 (2014-10-29)