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 0.15.2

Maintenance team

The current and past members of the MkDocs team.

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. 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 configuruation 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 1.0 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 Styling your docs 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)