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.14.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

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

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

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)