0.17.0

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

• Add "edit Link" support to MkDocs theme (#1129)
• Open files with utf-8-sig to account for BOM (#1186)
• Symbolic links are now followed consistently (#1134)
• Support for keyboard navigation shortcuts added to included themes (#1095)
• Some refactoring and improvements to config_options (#1296)
• Officially added support for Python 3.6 (#1296)
• 404 Error page added to readthedocs theme (#1296))
• Internal refactor of Markdown processing (#713)
• Removed special error message for mkdocs-bootstrap and mkdocs-bootswatch
  themes (#1168)
• The legacy pages config is no longer supported (#1168)
• The deprecated json command has been removed (#481)
• Support for Python 2.6 has been dropped (#165)
• File permissions are no longer copied during build (#1292)
• Support query and fragment strings in edit_uri (#1224 & #1273)