Conventions#

This section explains several conventions used in this documentation.

Symbols#

This documentation use some symbols for illustration purposes. Before you read on, please make sure you've made yourself familiar with the following list of conventions:

– Version#

The tag symbol in conjunction with a version number denotes when a specific feature or behavior was added. Make sure you're at least on this version if you want to use it.

– Default value#

Some properties in mkdocs.yml have default values for when the author does not explicitly define them. The default value of the property is always included.

– Default value is computed#

Some default values are not set to static values but computed from other values, like the site language, repository provider, or other settings.

– Default value is empty#

Some properties do not contain default values. This means that the functionality that is associated with them is not available unless explicitly enabled.

– Metadata property#

This symbol denotes that the thing described is a metadata property, which can be used in Markdown documents as part of the front matter definition.

– Multiple instances#

This symbol denotes that the plugin supports multiple instances, i.e, that it can be used multiple times in the plugins setting in mkdocs.yml.

– Optional feature#

Most of the features are hidden behind feature flags, which means they must be explicitly enabled via mkdocs.yml. This allows for the existence of potentially orthogonal features.

– Experimental#

Some newer features are still considered experimental, which means they might (although rarely) change at any time, including their complete removal (which hasn't happened yet).

– Plugin#

Several features are implemented through MkDocs excellent plugin architecture, some of which are built-in and distributed with Material for MkDocs, so no installation is required.

– Markdown extension#

This symbol denotes that the thing described is a Markdown extension, which can be enabled in mkdocs.yml and adds additional functionality to the Markdown parser.

– Required value#

Some (very few in fact) properties or settings are required, which means the authors must explicitly define them.

– Customization#

This symbol denotes that the thing described is a customization that must be added by the author.

– Utility#

Besides plugins, there are some utilities that build on top of MkDocs in order to provide extended functionality, like for example support for versioning.