docs/about/release-notes.md
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.5.0 from /path/to/mkdocs (Python 3.10)
The current and past members of the MkDocs team.
SOURCE_DATE_EPOCH=0 is set. #3795mkdocs_theme.yml config is empty. #3700python -W and PYTHONWARNINGS instead of overriding the configuration. #38090.0.0.0 dev server warning. #3784changefreq from sitemap.xml. #3629mkdocs serve no longer locks up the browser when more than 5 tabs are open. This is achieved by closing the polling connection whenever a tab becomes inactive. Background tabs will no longer auto-reload either - that will instead happen as soon the tab is opened again. Context: #3391
New flag serve --open to open the site in a browser.
After the first build is finished, this flag will cause the default OS Web browser to be opened at the home page of the local site.
Context: #3500
DANGER: Changed from version 1.5.
The exclude_docs config was split up into two separate concepts.
The exclude_docs config no longer has any special behavior for mkdocs serve - it now always completely excludes the listed documents from the site.
If you wish to use the "drafts" functionality like the exclude_docs key used to do in MkDocs 1.5, please switch to the new config key draft_docs.
See documentation.
Other changes:
MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.
Now tags are always fully sanitized from the title. Though it still remains the case that [Page.title][mkdocs.structure.pages.Page.title] is expected to contain HTML entities and is passed directly to the themes.
Images (notably, emojis in some extensions) get preserved in the title only through their alt attribute's value.
Context: #3564, #3578
Fix: "readthedocs" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. (#3464)
Fix: "readthedocs" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. (#3435)
"readthedocs" theme now also has translation for the word "theme" in the footer that mistakenly always remained in English. (#3613, #3625)
The "mkdocs" theme got a big update to a newer version of Bootstrap, meaning a slight overhaul of styles. Colors (most notably of admonitions) have much better contrast.
The "mkdocs" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are not enabled by default and need to be configured explicitly.
See color_mode, user_color_mode_toggle in documentation.
WARNING: Possible breaking change.
jQuery is no longer included into the "mkdocs" theme. If you were relying on it in your scripts, you will need to separately add it first (into mkdocs.yml) as an extra script:
yamlextra_javascript: - https://code.jquery.com/jquery-3.7.1.min.jsOr even better if the script file is copied and included from your docs dir.
Context: #3493, #3649
enabled" setting for all pluginsYou may have seen some plugins take up the convention of having a setting enabled: false (or usually controlled through an environment variable) to make the plugin do nothing.
Now every plugin has this setting. Plugins can still choose to implement this config themselves and decide how it behaves (and unless they drop older versions of MkDocs, they still should for now), but now there's always a fallback for every plugin.
See documentation. Context: #3395
Historically, within Markdown, MkDocs only recognized relative links that lead to another physical
*.mddocument (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against).
If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.
If you set the setting validation.links.absolute_links to the new value relative_to_docs, all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.
So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as [link](/dir2/bar.md), in addition to the previously only correct way [link](../dir2/bar.md).
You have to enable the setting, though. The default is still to just skip any processing of such links.
See documentation. Context: #3485
Absolute links within the nav: config were also always skipped. It is now possible to also validate them in the same way with validation.nav.absolute_links. Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash.
There is a new config setting that is recommended to enable warnings for:
validation:
anchors: warn
Example of a warning that this can produce:
WARNING - Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.
Any of the below methods of declaring an anchor will be detected by MkDocs:
## Heading producing an anchor
## Another heading {#custom-anchor-for-heading-using-attr-list}
<a id="raw-anchor"></a>
[](){#markdown-anchor-using-attr-list}
Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert etree elements as their mode of operation, rather than raw HTML which is undetectable for this purpose.
If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to ignore (and they are at INFO level by default anyway).
See documentation. Context: #3463
Other changes:
When the nav config is not specified at all, the not_in_nav setting (originally added in 1.5.0) gains an additional behavior: documents covered by not_in_nav will not be part of the automatically deduced navigation. Context: #3443
Fix: the !relative YAML tag for markdown_extensions (originally added in 1.5.0) - it was broken in many typical use cases.
See documentation. Context: #3466
Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437
MkDocs used to shorten error messages for unexpected errors such as "file not found", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: #3445
See [mkdocs.plugins.CombinedEvent][] in documentation. Context: #3448
File][mkdocs.structure.files.File] APISee [documentation][mkdocs.structure.files.File].
There is a new pair of attributes [File.content_string][mkdocs.structure.files.File.content_string]/[content_bytes][mkdocs.structure.files.File.content_bytes] that becomes the official API for obtaining the content of a file and is used by MkDocs itself.
This replaces the old approach where one had to manually read the file located at [File.abs_src_path][mkdocs.structure.files.File.abs_src_path], although that is still the primary action that these new attributes do under the hood.
The content of a File can be backed by a string and no longer has to be a real existing file at abs_src_path.
It is possible to set the attribute File.content_string or File.content_bytes and it will take precedence over abs_src_path.
Further, abs_src_path is no longer guaranteed to be present and can be None instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute.
There is a new constructor [File.generated()][mkdocs.structure.files.File.generated] that should be used by plugins instead of the File() constructor. It is much more convenient because one doesn't need to manually look up the values such as docs_dir and use_directory_urls. Its signature is one of:
f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)
This way, it is now extremely easy to add a virtual file even from a hook:
def on_files(files: Files, config: MkDocsConfig):
files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))
For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused docs_dir.
There is a new attribute [File.generated_by][mkdocs.structure.files.File.generated_by] that arose by convention - for generated files it should be set to the name of the plugin (the key in the plugins: collection) that produced this file. This attribute is populated automatically when using the File.generated() constructor.
It is possible to set the [edit_uri][mkdocs.structure.files.File.edit_uri] attribute of a File, for example from a plugin or hook, to make it different from the default (equal to src_uri), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the edit_uri to that source file or script accordingly.
The File object now stores its original src_dir, dest_dir, use_directory_urls values as attributes.
Fields of File are computed on demand but cached. Only the three above attributes are primary ones, and partly also [dest_uri][mkdocs.structure.files.File.dest_uri]. This way, it is possible to, for example, overwrite dest_uri of a File, and abs_dest_path will be calculated based on it. However you need to clear the attribute first using del f.abs_dest_path, because the values are cached.
File instances are now hashable (can be used as keys of a dict). Two files can no longer be considered "equal" unless it's the exact same instance of File.
Other changes:
The internal storage of File objects inside a Files object has been reworked, so any plugins that choose to access Files._files will get a deprecation warning.
The order of File objects inside a Files collection is no longer significant when automatically inferring the nav. They get forcibly sorted according to the default alphabetic order.
Context: #3451, #3463
Hook files can now import adjacent *.py files using the import statement. Previously this was possible to achieve only through a sys.path workaround. See the new mention in documentation. Context: #3568
Verbose -v log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444
Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429
The theme config file mkdocs_theme.yml no longer executes YAML tags. Context: #3465
The plugin event on_page_read_source is soft-deprecated because there is always a better alternative to it (see the new File API or just on_page_markdown, depending on the desired interaction).
When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.
See documentation. Context: #3503
It is no longer allowed to set File.page to a type other than Page or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381.
Theme._vars is deprecated - use theme['foo'] instead of theme._vars['foo']
utils: modified_time(), get_html_path(), get_url_path(), is_html_file(), is_template_file() are removed. path_to_url() is deprecated.
LiveReloadServer.watch() no longer accepts a custom callback.
Context: #3429
sitemap.xml.gz file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460Other small improvements; see commit log.
Fix mkdocs serve sometimes locking up all browser tabs when navigating quickly (#3390)
Add many new supported languages for "search" plugin - update lunr-languages to 1.12.0 (#3334)
Bugfix (regression in 1.5.0): In "readthedocs" theme the styling of "breadcrumb navigation" was broken for nested pages (#3383)
Built-in themes now also support Chinese (Traditional, Taiwan) language (#3154)
Plugins can now set File.page to their own subclass of Page. There is also now a warning if File.page is set to anything other than a strict subclass of Page. (#3367, #3381)
Note that just instantiating a Page sets the file automatically, so care needs to be taken not to create an unneeded Page.
Other small improvements; see commit log.
Bugfix (regression in 1.5.0): Restore functionality of --no-livereload. (#3320)
Bugfix (regression in 1.5.0): The new page title detection would sometimes be unable to drop anchorlinks - fix that. (#3325)
Partly bring back pre-1.5 API: extra_javascript items will once again be mostly strings, and only sometimes ExtraScriptValue (when the extra script functionality is used).
Plugins should be free to append strings to config.extra_javascript, but when reading the values, they must still make sure to read it as str(value) in case it is an ExtraScriptValue item. For querying the attributes such as .type you need to check isinstance first. Static type checking will guide you in that. (#3324)
See commit log.
Bugfix (regression in 1.5.0): Make it possible to treat ExtraScriptValue as a path. This lets some plugins still work despite the breaking change.
Bugfix (regression in 1.5.0): Prevent errors for special setups that have 3 conflicting files, such as index.html, index.md and README.md (#3314)
See commit log.
mkdocs get-depsThis command guesses the Python dependencies that a MkDocs site requires in order to build. It simply prints the PyPI packages that need to be installed. In the terminal it can be combined directly with an installation command as follows:
pip install $(mkdocs get-deps)
The idea is that right after running this command, you can directly follow it up with mkdocs build and it will almost always "just work", without needing to think which dependencies to install.
The way it works is by scanning mkdocs.yml for themes:, plugins:, markdown_extensions: items and doing a reverse lookup based on a large list of known projects (catalog, see below).
Of course, you're welcome to use a "virtualenv" with such a command. Also note that for environments that require stability (for example CI) directly installing deps in this way is not a very reliable approach as it precludes dependency pinning.
The command allows overriding which config file is used (instead of mkdocs.yml in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See mkdocs get-deps --help.
Context: #3205
Check out https://github.com/mkdocs/catalog and add all your general-purpose plugins, themes and extensions there, so that they can be looked up through mkdocs get-deps.
This was renamed from "best-of-mkdocs" and received significant updates. In addition to pip installation commands, the page now shows the config boilerplate needed to add a plugin.
As you may know, within Markdown, MkDocs really only recognizes relative links that lead to another physical
*.mddocument (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. MkDocs knows that in the output it should turn those*.mdlinks into*.htmlas appropriate, and it would also always tell you if such a link doesn't actually lead to an existing file.
However, the checks for links were really loose and had many concessions. For example, links that started with / ("absolute") and links that ended with / were left as is and no warning was shown, which allowed such very fragile links to sneak into site sources: links that happen to work right now but get no validation and links that confusingly need an extra level of .. with use_directory_urls enabled.
Now, in addition to validating relative links, MkDocs will print INFO messages for unrecognized types of links (including absolute links). They look like this:
INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?
If you don't want any changes, not even the INFO messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to mkdocs.yml (not recommended):
validation:
absolute_links: ignore
unrecognized_links: ignore
If, on the opposite end, you want these to print WARNING messages and cause mkdocs build --strict to fail, you are recommended to configure these to warn instead.
See documentation for actual recommended settings and more details. Context: #3283
Links to documents in the nav configuration now also have configurable validation, though with no changes to the defaults.
You are welcomed to turn on validation for files that were forgotten and excluded from the nav. Example:
validation:
nav:
omitted_files: warn
absolute_links: warn
This can make the following message appear with the WARNING level (as opposed to INFO as the only option previously), thus being caught by mkdocs --strict:
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...
See documentation. Context: #3283, #1755
There is a new config not_in_nav. With it, you can mark particular patterns of files as exempt from the above omitted_files warning type; no messages will be printed for them anymore. (As a corollary, setting this config to * is the same as ignoring omitted_files altogether.)
This is useful if you generally like these warnings about files that were forgotten from the nav, but still have some pages that you knowingly excluded from the nav and just want to build and copy them.
The not_in_nav config is a set of gitignore-like patterns. See the next section for an explanation of another such config.
See documentation. Context: #3224, #1888
There is a new config exclude_docs that tells MkDocs to ignore certain files under docs_dir and not copy them to the built site as part of the build.
Historically MkDocs would always ignore file names starting with a dot, and that's all. Now this is all configurable: you can un-ignore these and/or ignore more patterns of files.
The exclude_docs config follows the .gitignore pattern format and is specified as a multiline YAML string. For example:
exclude_docs: |
*.py # Excludes e.g. docs/hooks/foo.py
/requirements.txt # Excludes docs/requirements.txt
Validation of links (described above) is also affected by exclude_docs. During mkdocs serve the messages explain the interaction, whereas during mkdocs build excluded files are as good as nonexistent.
As an additional related change, if you have a need to have both README.md and index.md files in a directory but publish only one of them, you can now use this feature to explicitly ignore one of them and avoid warnings.
See documentation. Context: #3224
DANGER: Dropped from version 1.6:
The
exclude_docsconfig no longer applies the "drafts" functionality formkdocs serve. This was renamed todraft_docs.
The exclude_docs config has another behavior: all excluded Markdown pages will still be previewable in mkdocs serve only, just with a "DRAFT" marker on top. Then they will of course be excluded from mkdocs build or gh-deploy.
If you don't want mkdocs serve to have any special behaviors and instead want it to perform completely normal builds, use the new flag mkdocs serve --clean.
See documentation. Context: #3224
mkdocs serve no longer exits after build errorsIf there was an error (from the config or a plugin) during a site re-build, mkdocs serve used to exit after printing a stack trace. Now it will simply freeze the server until the author edits the files to fix the problem, and then will keep reloading.
But errors on the first build still cause mkdocs serve to exit, as before.
Context: #3255
MkDocs always had the ability to infer the title of a page (if it's not specified in the nav) based on the first line of the document, if it had a <h1> heading that had to written starting with the exact character #. Now any style of Markdown heading is understood (#1886). Due to the previous simplistic parsing, it was also impossible to use attr_list attributes in that first heading (#3136). Now that is also fixed.
This is aimed at extensions such as pymdownx.snippets or markdown_include.include: you can now specify their include paths to be relative to the currently rendered Markdown document, or relative to the docs_dir. Any other extension can of course also make use of the new !relative YAML tag.
markdown_extensions:
- pymdownx.snippets:
base_path: !relative
See documentation. Context: #2154, #3258
<script> tags can specify type="module" and other attributesIn extra_javascript, if you use the .mjs file extension or explicitly specify a type: module key, the script will be added with the type="module" attribute. defer: true and async: true keys are also available.
See updated documentation for extra_javascript.
At first this is only supported in built-in themes, other themes need to follow up, see below.
Context: #3237
Using the construct {% for script in extra_javascript %} is now fully obsolete because it cannot allow customizing the attributes of the <script> tag. It will keep working but blocks some of MkDocs' features.
Instead, you now need to use config.extra_javascript (which was already the case for a while) and couple it with the new script_tag filter:
{%- for script in config.extra_javascript %}
{{ script | script_tag }}
{%- endfor %}
See documentation.
Breaking change: config.extra_javascript is no longer a plain list of strings, but instead a list of ExtraScriptValue items. So you can no longer treat the list values as strings. If you want to keep compatibility with old versions, just always reference the items as str(item) instead. And you can still append plain strings to the list if you wish. See information about <script> tags above. Context: #3237
File has a new attribute inclusion. Its value is calculated from both the exclude_docs and not_in_nav configs, and implements their behavior. Plugins can read this value or write to it. New File instances by default follow whatever the configs say, but plugins can choose to make this decision explicitly, per file.
When creating a File, one can now set a dest_uri directly, rather than having to update it (and other dependent attributes) after creation. Context
A new config option was added - DictOfItems. Similarly to ListOfItems, it validates a mapping of config options that all have the same type. Keys are arbitrary but always strings. Context: #3242
A new function get_plugin_logger was added. In order to opt into a standardized way for plugins to log messages, please use the idiom:
log = mkdocs.plugins.get_plugin_logger(__name__)
...
log.info("Hello, world")
Context: #3245
SubConfig config option can be conveniently subclassed with a particular type of config specified. For example, class ExtraScript(SubConfig[ExtraScriptValue]):. To see how this is useful, search for this class in code. Context
Bugfix: SubConfig had a bug where paths (from FilesystemObject options) were not made relative to the main config file as intended, because config_file_path was not properly inherited to it. This is now fixed. Context: #3265
Config members now have a way to avoid clashing with Python's reserved words. This is achieved by stripping a trailing underscore from each member's name.
Example of adding an async boolean option that can be set by the user as async: true and read programmatically as config.async_:
class ExampleConfig(Config):
async_ = Type(bool, default=False)
Previously making a config key with a reserved name was impossible with new-style schemas. Context
Theme has its attributes properly declared and gained new attributes theme.locale, theme.custom_dir.
Some type annotations were made more precise. For example:
context parameter has gained the type TemplateContext (TypedDict). ContextPage, Section, Link now have a common base class StructureItem. ContextConfig and only accept MkDocsConfig as was originally intended. Contextconfig.mdx_configs got a proper type. Context: #3229Built-in themes mostly stopped relying on <script defer>. This may affect some usages of extra_javascript, mainly remove the need for custom handling of "has the page fully loaded yet". Context: #3237
"mkdocs" theme now has a styling for > blockquotes, previously they were not distinguished at all. Context: #3291
"readthedocs" theme was updated to v1.2.0 according to upstream, with improved styles for <kbd> and breadcrumb navigation. Context: #3058
Both built-in themes had their version of highlight.js updated to 11.8.0, and jQuery updated to 3.6.0.
Regression in 1.2 - relative paths in the nav could no longer traverse above the site's root and were truncated to the root. Although such traversal is discouraged and produces a warning, this was a documented behavior. The behavior is now restored.
Context: #2752, #3010
This can be used for config overrides on the fly. See updated section at the bottom of Configuration Inheritance.
The command to use this is mkdocs build -f -. In previous versions doing this led to an error.
mkdocs --no-color build disables color output and line wrapping. This option is also available through an environment variable NO_COLOR=true. Context: #3282mkdocs build --no-strict overrides the strict config to false. Context: #3254mkdocs build -f - (described directly above).mkdocs serve --clean (described above).mkdocs serve --dirty is the new name of mkdocs serve --dirtyreload.extra_javascript underwent a change that can break plugins in rare cases, and it requires attention from theme developers. See respective entries above.
Python-Markdown was unpinned from <3.4. That version is known to remove functionality. If you are affected by those removals, you can still choose to pin the version for yourself: Markdown <3.4. Context: #3222, #2892
mkdocs.utils.warning_filter now shows a warning about being deprecated. It does nothing since MkDocs 1.2. Consider get_plugin_logger or just logging under mkdocs.plugins.* instead. Context: #3008
Accessing the _vars attribute of a Theme is deprecated - just access the keys directly.
Accessing the user_configs attribute of a Config is deprecated. Note: instead of config.user_configs[*]['theme']['custom_dir'], please use the new attribute config.theme.custom_dir.
Other small improvements; see commit log.
Bugfix: for the hooks feature, modules no longer fail to load if using some advanced Python features like dataclasses (#3193)
Bugfix: Don't create None sitemap entries if the page has no populated URL - affects sites that exclude some files from navigation (07a297b)
"readthedocs" theme:
hljs_style: config, same as "mkdocs" theme (#3199)Translations:
zh_CN translation (#3125)tr_TR translation becomes just tr - usage should remain unaffected (#3195)See commit log.
Officially support Python 3.11 (#3020)
NEW: Tip: Simply upgrading to Python 3.11 can cut off 10-15% of your site's build time.
Support multiple instances of the same plugin (#3027)
If a plugin is specified multiple times in the list under the plugins: config, that will create 2 (or more) instances of the plugin with their own config each.
Previously this case was unforeseen and, as such, bugged.
Now even though this works, by default a warning will appear from MkDocs anyway, unless the plugin adds a class variable supports_multiple_instances = True.
Bugfix (regression in 1.4.1): Don't error when a plugin puts a plain string into warnings (#3016)
Bugfix: Relative links will always render with a trailing slash (#3022)
Previously under use_directory_urls, links from a sub-page to the main index page rendered as e.g. <a href="../.."> even though in all other cases the links look like <a href="../../">. This caused unwanted behavior on some combinations of Web browsers and servers. Now this special-case bug was removed.
Built-in "mkdocs" theme now also supports Norwegian language (#3024)
Plugin-related warnings look more readable (#3016)
See commit log.
Support theme-namespaced plugin loading (#2998)
Plugins' entry points can be named as 'sometheme/someplugin'. That will have the following outcome:
plugins: [sometheme/someplugin].One can also specify plugins: ['/someplugin'] instead of plugins: ['someplugin'] to definitely avoid the theme-namespaced plugin.
Bugfix: mkdocs serve will work correctly with non-ASCII paths and redirects (#3001)
Windows: 'colorama' is now a dependency of MkDocs, to ensure colorful log output (#2987)
Plugin-related config options have more reliable validation and error reporting (#2997)
Translation sub-commands of setup.py were completely dropped. See documentation [1] [2] for their new replacements (#2990)
The 'mkdocs' package (wheel and source) is now produced by Hatch build system and pyproject.toml instead of setup.py (#2988)
Other small improvements; see commit log.
The new hooks: config allows you to add plugin-like event handlers from local Python files, without needing to set up and install an actual plugin.
See documentation.
edit_uri flexibility (#2927)There is a new edit_uri_template: config.
It works like edit_uri but more generally covers ways to construct an edit URL.
See documentation.
Additionally, the edit_uri functionality will now fully work even if repo_url is omitted (#2928)
NOTE: This release has big changes to the implementation of plugins and their configs. But, the intention is to have zero breaking changes in all reasonably common use cases. Or at the very least if a code fix is required, there should always be a way to stay compatible with older MkDocs versions. Please report if this release breaks something.
Plugins can now choose to set a priority value for their event handlers. This can override the old behavior where for each event type, the handlers are called in the order that their plugins appear in the plugins config.
If this is set, events with higher priority are called first. Events without a chosen priority get a default of 0. Events that have the same priority are ordered as they appear in the config.
Recommended priority values: 100 "first", 50 "early", 0 "default", -50 "late", -100 "last".
As different plugins discover more precise relations to each other, the values should be further tweaked.
See documentation.
mkdocs serve (#2972)The new events are on_startup and on_shutdown. They run at the very beginning and very end of an mkdocs invocation.
on_startup also receives information on how mkdocs was invoked (e.g. serve --dirtyreload).
See documentation.
File.src_path to not deal with backslashes (#2930)The property src_path uses backslashes on Windows, which doesn't make sense as it's a virtual path.
To not make a breaking change, there's no change to how this property is used, but now you should:
File.src_uri instead of File.src_pathFile.dest_uri instead of File.dest_path.These consistently use forward slashes, and are now the definitive source that MkDocs itself uses.
See source code.
As a related tip: you should also stop using os.path.* or pathlib.Path() to deal with these paths, and instead use posixpath.* or pathlib.PurePosixPath()
MkDocs' plugin event methods now have type annotations. You might have been adding annotations to events already, but now they will be validated to match the original.
See source code and documentation.
One big update is that now you should annotate method parameters more specifically as config: defaults.MkDocsConfig instead of config: base.Config. This not only makes it clear that it is the main config of MkDocs itself, but also provides type-safe access through attributes of the object (see next section).
See source code and documentation.
When developing a plugin, the settings that it accepts used to be specified in the config_scheme variable on the plugin class.
This approach is now soft-deprecated, and instead you should specify the config in a sub-class of base.Config.
Old example:
from mkdocs import plugins
from mkdocs.config import base, config_options
class MyPlugin(plugins.BasePlugin):
config_scheme = (
('foo', config_options.Type(int)),
('bar', config_options.Type(str, default='')),
)
def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
if self.config['foo'] < 5:
if config['site_url'].startswith('http:'):
return markdown + self.config['baz']
This code snippet actually has many mistakes but it will pass all type checks and silently run and even succeed in some cases.
So, on to the new equivalent example, changed to new-style schema and attribute-based access:
(Complaints from "mypy" added inline)
from mkdocs import plugins
from mkdocs.config import base, config_options as c
class MyPluginConfig(base.Config):
foo = c.Optional(c.Type(int))
bar = c.Type(str, default='')
class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
if self.config.foo < 5: # Error, `foo` might be `None`, need to check first.
if config.site_url.startswith('http:'): # Error, MkDocs' `site_url` also might be `None`.
return markdown + self.config.baz # Error, no such attribute `baz`!
This lets you notice the errors from a static type checker before running the code and fix them as such:
class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
if self.config.foo is not None and self.config.foo < 5: # OK, `int < int` is valid.
if (config.site_url or '').startswith('http:'): # OK, `str.startswith(str)` is valid.
return markdown + self.config.bar # OK, `str + str` is valid.
See documentation.
Also notice that we had to explicitly mark the config attribute foo as Optional.
The new-style config has all attributes marked as required by default, and specifying required=False or required=True is not allowed!
config_options.Optional (#2962)Wrapping something into Optional is conceptually similar to "I want the default to be None" -- and you have to express it like that, because writing default=None doesn't actually work.
Breaking change: the method BaseConfigOption.is_required() was removed. Use .required instead. (#2938)
And even the required property should be mostly unused now.
For class-based configs, there's a new definition for whether an option is "required":
config_options.Optional.config_options.ListOfItems (#2938)Defines a list of items that each must adhere to the same constraint. Kind of like a validated Type(list)
Examples how to express a list of integers (with from mkdocs.config import config_options as c):
| Description | Code entry |
|---|---|
| Required to specify | foo = c.ListOfItems(c.Type(int)) |
| Optional, default is [] | foo = c.ListOfItems(c.Type(int), default=[]) |
| Optional, default is None | foo = c.Optional(c.ListOfItems(c.Type(int))) |
See more examples in documentation.
config_options.SubConfig (#2807)SubConfig used to silently ignore all validation of its config options. Now you should pass validate=True to it or just use new class-based configs where this became the default.
So, it can be used to validate a nested sub-dict with all keys pre-defined and value types strictly validated.
See examples in documentation.
URL's default is now None instead of ''. This can still be checked for truthiness in the same way - if config.some_url: (#2962)
FilesystemObject is no longer abstract and can be used directly, standing for "file or directory" with optional existence checking (#2938)
Bug fixes:
SubConfig, ConfigItems, MarkdownExtensions to not leak values across different instances (#2916, #2290)SubConfig raises the correct kind of validation error without a stack trace (#2938)config_options.Deprecated(moved_to) (#2963)Tweaked logic for handling ConfigOption.default (#2938)
Deprecated config option classes: ConfigItems (#2983), OptionallyRequired (#2962), RepoURL (#2927)
Styles of admonitions in "MkDocs" theme (#2981):
<details> tag, to support Markdown extensions that provide it (pymdownx.details, callouts)Built-in themes now also support these languages:
extra_css: and extra_javascript: warn if a backslash \ is passed to them. (#2930, #2984)
Show DeprecationWarnings as INFO messages. (#2907)
If any plugin or extension that you use relies on deprecated functionality of other libraries, it is at risk of breaking in the near future. Plugin developers should address these in a timely manner.
Avoid a dependency on importlib_metadata starting from Python 3.10 (#2959)
Drop support for Python 3.6 (#2948)
mkdocs.utils:
create_media_urls and normalize_url warn if a backslash \ is passed to them. (#2930)is_markdown_file stops accepting case-insensitive variants such as .MD, which is how MkDocs build was already operating. (#2912)modified_time, reduce_list, get_html_path, get_url_path, is_html_file, is_template_file. (#2912)If a plugin adds paths to watch in LiveReloadServer, it can now unwatch them. (#2777)
Bugfix (regression in 1.2): Support listening on an IPv6 address in mkdocs serve. (#2951)
Other small improvements; see commit log.
Pin Python-Markdown version to <3.4, thus excluding its latest release that breaks too many external extensions (#2893)
When a Markdown extension fails to load, print its name and traceback (#2894)
Bugfix for "readthedocs" theme (regression in 1.3.0): add missing space in breadcrumbs (#2810)
Bugfix: don't complain when a file "readme.md" (lowercase) exists, it's not recognized otherwise (#2852)
Built-in themes now also support these languages:
Other small improvements; see commit log.
ReadTheDocs theme updated from v0.4.1 to v1.0.0 according to upstream (#2585)
The most notable changes:
logo: Rather than displaying the site_name in the title, one can specify a path to an image to display instead.anonymize_ip for Google Analytics.Built-in themes now also support these languages:
Support custom directories to watch when running mkdocs serve (#2642)
MkDocs by default watches the docs directory and the config file. Now there is a way to add more directories to watch for changes, either via the YAML watch key or the command line flag --watch.
Normally MkDocs never reaches into any other directories (so this feature shouldn't be necessary), but some plugins and extensions may do so.
See documentation.
New --no-history option for gh_deploy (#2594)
Allows to discard the history of commits when deploying, and instead replace it with one root commit
An XSS vulnerability when using the search function in built-in themes was fixed (#2791)
Setting the edit_uri option no longer erroneously adds a trailing slash to repo_url (#2733)
Breaking change: the pages config option that was deprecated for a very long time now causes an error when used (#2652)
To fix the error, just change from pages to nav.
Performance optimization: during startup of MkDocs, code and dependencies of other commands will not be imported (#2714)
The most visible effect of this is that dependencies of mkdocs serve will not be imported when mkdocs build is used.
Recursively validate nav (#2680)
Validation of the nested nav structure has been reworked to report errors early and reliably. Some edge cases have been declared invalid.
Other small improvements; see commit log.
Compatibility with Jinja2 3.1.0 (#2800)
Due to a breaking change in Jinja2, MkDocs would crash with the message
AttributeError: module 'jinja2' has no attribute 'contextfilter'
Built-in themes now also support these languages:
Third-party plugins will take precedence over built-in plugins with the same name (#2591)
Bugfix: Fix ability to load translations for some languages: core support (#2565) and search plugin support with fallbacks (#2602)
Bugfix (regression in 1.2): Prevent directory traversal in the dev server (#2604)
Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a build failure in strict mode (#2607)
Bugfix: Correctly print colorful messages in the terminal on Windows (#2606)
Bugfix: Python version 3.10 was displayed incorrectly in --version (#2618)
Other small improvements; see commit log.
Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters (#2464)
Bugfix (regression in 1.2): Revert livereload file watching to use polling observer (#2477)
This had to be done to reasonably support usages that span virtual filesystems such as non-native Docker and network mounts.
This goes back to the polling approach, very similar to that was always used prior, meaning most of the same downsides with latency and CPU usage.
Revert from 1.2: Remove the requirement of a site_url config and the restriction on use_directory_urls (#2490)
Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving a directory index in mkdocs serve server (#2507)
Instead of showing a 404 error, detect if it's a directory and redirect to a path with a trailing slash added, like before.
Bugfix: Fix gh_deploy with config-file in the current directory (#2481)
Bugfix: Fix reversed breadcrumbs in "readthedocs" theme (#2179)
Allow "mkdocs.yaml" as the file name when '--config' is not passed (#2478)
Stop treating ";" as a special character in URLs: urlparse -> urlsplit (#2502)
Improve build performance for sites with many pages (partly already done in 1.2) (#2407)
The mkdocs and readthedocs themes now support language localization using
the theme.locale parameter, which defaults to en (English). The only other
supported languages in this release are fr (French) and es (Spanish). For
details on using the provided translations, see the user
guide. Note that translation will not
happen by default. Users must first install the necessary dependencies with
the following command:
pip install 'mkdocs[i18n]'
Translation contributions are welcome and detailed in the Translation Guide.
Developers of third party themes may want to review the relevant section of the Theme Development Guide.
Contributors who are updating the templates to the built-in themes should review the Contributing Guide.
The lang setting of the search plugin now defaults to the language
specified in theme.locale.
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.
A configuration file may now inherit from a parent configuration file. In the
primary file set the INHERIT key to the relative path of the parent file.
INHERIT: path/to/base.yml
The two files will then be deep merged. See Configuration Inheritance for details.
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:
.nojekyll file is automatically included when deploying to GitHub Pages.--shell flag is now available, which reportedly works better on Windows.mkdocs serve (#2385)mkdocs serve now uses a new underlying server + file watcher implementation,
based on http.server from standard library and watchdog. It provides similar
functionality to the previously used livereload library (which is now dropped
from dependencies, along with tornado).
This makes reloads more responsive and consistent in terms of timing. Multiple rapid file changes no longer cause the site to repeatedly rebuild (issue #2061).
Almost every aspect of the server is slightly different, but actual visible changes are minor. The logging outputs are only similar to the old ones. Degradations in behavior are not expected, and should be reported if found.
site_url (#2424)When using mkdocs serve and having the site_url specified as e.g.
http://example.org/sub/path/, now the root of the locally served site
becomes http://127.0.0.1:8000/sub/path/ and all document paths are offset
accordingly.
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.
MkDocs now has tree new exceptions defined in mkdocs.exceptions:
BuildError, PluginError, and Abort:
PluginError can be raised from a plugin to stop the build and log an error message without traceback.BuildError should not be used by third-party plugins developers and is reserved for internal use only.Abort is used internally to abort the build and display an error without a traceback.See Handling errors
in the Plugins documentation for details.
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.
The site_url configuration option is now required. If it is not set, a warning will be issued. In a future release an error will be raised (#2189).
The use_directory_urls
configuration option will be forced to false if
site_url is set to an empty
string. In that case, if use_directory_urls is not explicitly set to
false, a warning will be issued (#2189).
NOTE: This was reverted in release 1.2.2
The google_analytics configuration option is deprecated as Google appears to
be phasing it out in favor of its new Google Analytics 4 property. See the
documentation for your theme for alternatives which can be configured as part
of your theme configuration. For example, the mkdocs and
readthedocs themes have each added a new theme.analytics.gtag
configuration option which uses the new Google Analytics 4 property. See
Google's documentation on how to Upgrade to a Google Analytics 4
property. Then set theme.analytics.gtag to the "G-" ID and delete the
google_analytics configuration option which contains a "UA-" ID. So long
as the old "UA-" ID and new "G-" ID are properly linked in your Google
account, and you are using the "G-" ID, the data will be made available in
both the old and new formats by Google Analytics. See #2252.
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).
The on_serve event (which receives the server object and the builder
function) is affected by the server rewrite. server is now a
mkdocs.livereload.LiveReloadServer instead of livereload.server.Server.
The typical action that plugins can do with these is to call
server.watch(some_dir, builder), which basically adds that directory to
watched directories, causing the site to be rebuilt on file changes. That
still works, but passing any other function to watch is deprecated and shows
a warning. This 2nd parameter is already optional, and will accept only this
exact builder function just for compatibility.
The python method of the plugins.search.prebuild_index configuration
option is pending deprecation as of version 1.2. It is expected that in
version 1.3 it will raise a warning if used and in version 1.4 it will raise
an error. Users are encouraged to use an alternate method to generate a
prebuilt index for search.
The lunr and lunr[languages] dependencies are no longer installed by
default. The dependencies are only needed for the rare user who pre-builds the
search index and uses the python option, which is now pending deprecation.
If you use this feature, then you will need to manually install lunr and
lunr[languages]. A warning is issued if the dependencies are needed but not
installed.
_get_by_type when filtering for sections (#2203).remove method to help plugin developers manipulate the Files tree. The corresponding src_paths has become a property to accommodate this possible dynamic behavior. See #2305.readthedocs theme (#2028).site_url ends with a slash (#1785).pages template context variable (#1736).lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding 2.3.9 version (#2306).use_directory_urls is False (#2362).SOURCE_DATE_EPOCH environment variable (#2100).README.md as index.html even if use_directory_urls is false (#2081).builder to the on_serve event so that it can be passed to server.watch by plugins (#1952).lunr[languages]==0.5.8 to avoid nltk incompatibilities (#2062).dev_addr validation and disallow 0.0.0.0 (#2022).min_search_length parameter for search plugin (#2014).readthedocs theme code colors (#2027).prebuild_index engineMkdocs now supports pre-building 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.
mkdocs theme to Bootswatch 4.1.3 (#1563)The mkdocs theme now supports all the features of Bootswatch 4.1.
Additionally, 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
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.
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.
ValidationError message for custom_dir (#1849).docs_dir files (#1671).readthedocs theme (#1669).git is not available.nav_style theme option for the mkdocs theme (#1930).mkdocs theme (#1234).mkdocs theme no longer obscure the document content (#716).navigation_depth theme option for the mkdocs theme (#1970).level attribute in page.toc items is now 1-indexed to match the level in <hN> tags (#1970).theme_config.yml files correctly (#1602).base_url to error templates (#1598).search until all assets are ready (#1584).README.md if index.md is present (#1580).readthedocs theme navigation bug with homepage (#1576).Internal handling of pages, files and navigation has been completely refactored. The changes included in the refactor are summarized below.
README.md file is now treated as an index file within a directory and
will be rendered to index.html (#608).docs_dir, exclude files, redefine page URLs (i.e.
implement extensionless URLs), or to manipulate files in various other ways.As part of the internal refactor, a number of backward incompatible changes have been introduced, which are summarized below.
use_directory_urls is FalsePreviously, 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 mangling 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.
pages configuration setting has been renamed to navThe 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.
base_urlIn 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 %}
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.
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, MultiMarkdown's 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.
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 DeprecatedAs 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.
extra_css and extra_javascript settings no longer raise a warning.tornado>=5.0 (#1427).sitemap.xml (#1130).writing-your-docs.md (#1392).clicky class to body and animations. (#1387).extra_javascript files (#1388).copy_media_files util function for more flexibility (#1370).tornado>=4.1,<5.0 due to changes in 5.0 (#1428).extra_* config setting regressions (#1335 & #1336).repo_url with missing ending slash. (#1321).mkdocs.toc.TableOfContext (#1325).site_url with dev_addr on local server (#1317).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.
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.
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.
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 |
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.
utf-8-sig to account for BOM (#1186)json command has been removed (#481)edit_uri (#1224 & #1273)/) is not a valid path for site_dir or docs_dir (#1161)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 Customizing Your Theme for more information about using and customizing 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 sub-commands. (#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 behavior. (#63)extra_javascript and extra_css in all themes. (#90)extra_javascript and extra_css. (#92)