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
The current and past members of the MkDocs team.
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 |
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 |
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.
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.
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.
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.
gh-deploy
command on Windows with Python 3 (#722)mkdocs build
and mkdocs serve
(#832)edit_uri
setting.--force
flag to the gh-deploy
command to force the push to the
repository (#973).http://user.github.io/repo
=> https://user.github.io/repo/
(#1029).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 customising themes and Custom themes for creating and distributing new themes
-m
flag. (#706)ancestors
rather than just
the initial one. (#693)--quiet
and --verbose
options to all subcommands. (#579)-a
) to most command line options. (#579)mkdocs serve
is already in use, don't show the
user a full stack trace. (#596)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.
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.
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.
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.
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.
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.
--no-livereload
to mkdocs serve
for a simpler development server. (#511)mkdocs gh-deploy
(#516)docs_dir
. (#254)mkdocs serve
. (#341)mkdocs new
command. (#412)mkdocs build --clean
. (#346)__pycache__
from the package tar. (#196)prettyprint well
CSS classes to all HTML, only add it in
the MkDocs theme. (#183)markdown_extensions
. (#74)mkdocs json
command to output your rendered
documentation as json files. (#128)--clean
switch to build
, json
and gh-deploy
commands to
remove stale files from the output directory. (#157)<ul>
rendering in readthedocs theme. (#171)use_directory_urls
config behaviour. (#63)extra_javascript
and extra_css
in all themes. (#90)extra_javascript
and extra_css
. (#92)