Built-in plugins¶
Material for MkDocs started out as a theme for MkDocs, but has since evolved into a full-fledged framework for building and maintaining documentation. The theme is still the core of the project, but it's now accompanied by a growing number of complementary built-in plugins.
We strive to make those plugins as modular and generic as possible, so that they can be used in a wide variety of projects and use cases. By providing useful default settings, we also try to make them as easy to use as possible, so that you can get started quickly, tweaking their settings later on. When developing built-in plugins, we always adhere to the following design principles:
-
Modularity: Built-in plugins are designed to be modular, so that they can be easily combined to implement sophisticated pipelines. For example, the offline, optimize and privacy plugins can be used together to build truly offline-capable documentation.
-
Interoperability: Built-in plugins are designed to be as compatible as possible, so they can be used in combination with other plugins, including third-party plugins. We strive to make it simple to integrate with the vast ecosystem that has evolved around MkDocs.
-
Performance: Built-in plugins are designed to be as fast and memory-efficient as possible, so that they don't unnecessarily slow down builds. This is particularly important for large documentation projects with thousands of pages.
Categories¶
Management¶
The following plugins greatly improve the authoring experience when working on documentation projects by providing better management capabilities, from the management of plugins, multiple projects, and metadata, to the creation of minimal reproductions for bug reports:
-
The group plugin allows to group plugins into logical units to conditionally enable or disable them for specific environments with the use of environment variables.
Optimal management of plugins when building in different environments
-
The meta plugin makes it easy to manage metadata (front matter) for all pages in a folder, so a certain subset of pages uses specific tags or a custom template.
Simpler organization, categorization and management of metadata
-
The projects plugin allows to split your main project into multiple distinct projects, build them concurrently and preview them together as one.
Connect multiple projects together, and build them separately or as one
-
The info plugin is a small and useful utility that helps to create self-contained minimal reproductions, so we maintainers can fix reported bugs more quickly.
Your bug reports are of the highest quality, so we can fix them as fast as possible
Optimization¶
The following plugins are designed to help you build optimized documentation, making it more accessible to your users through faster loading times, better search engine rankings, beautiful preview images on social media, and GDPR compliance with a few lines of configuration:
-
The social plugin automatically generates beautiful and customizable social cards for each page of your documentation, showing as previews on social media.
Links to your site render beautiful social cards when shared on social media
-
The optimize plugin automatically identifies and optimizes all media files that you reference in your project by using compression and conversion techniques.
Your site loads faster as smaller images are served to your users
-
The privacy plugin downloads external assets automatically for easy self-hosting, allowing for GDPR compliance with a single line of configuration.
Your documentation can be made GDPR compliant with minimal effort
-
The offline plugin adds support for building offline-capable documentation, so you can distribute the
sitedirectory as a.zipfile that can be downloaded.
Your documentation can work without connectivity to the internet
Content¶
The following plugins are designed to help you set up a blog, provide search functionality to your users, add tags to pages and posts, and use the same typesetting capabilities in specific parts of the documentation exactly as in the main content:
-
The blog plugin adds first-class support for blogging to Material for MkDocs, either as a sidecar to your documentation or as a standalone installation.
Your blog is built with the same powerful engine as your documentation
-
The search plugin adds a search bar to the header, allowing users to search the entire documentation, so it's easier for them to find what they're looking for.
Your documentation is searchable without any external services, even offline
-
The tags plugin adds first-class support for categorizing pages with tags, adding the ability to group related pages to improve the discovery of related content.
Your pages are categorized with tags, yielding additional context
-
The typeset plugin allows to preserve the enriched presentation of titles and headlines within the navigation and table of contents.
Sidebars preserve the same formatting as section titles in pages
Architecture¶
Multiple instances¶
Several built-in plugins have support for multiple instances, which means that they can be used multiple times in the same configuration file, allowing to fine-tune behavior for separate sections of your project. Currently, the following plugins have support for multiple instances: