1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-13 00:01:17 +01:00
mkdocs-material/docs/plugins/index.md
2023-10-03 16:13:01 +02:00

7.4 KiB

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:

  • :material-format-list-group:   Built-in group plugin


    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][mkdocs.env].


    Optimal management of plugins when building in different environments

  • :material-file-tree:   Built-in meta plugin


    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

  • :material-folder-open:   Built-in projects plugin


    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

  • :material-information:   Built-in info plugin


    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:

  • :material-share-circle:   Built-in social plugin


    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

  • :material-rabbit:   Built-in optimize plugin


    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

  • :material-shield-account:   Built-in privacy plugin


    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

  • :material-connection:   Built-in offline plugin


    The offline plugin adds support for building offline-capable documentation, so you can distribute the [site directory][mkdocs.site_dir] as a .zip file 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:

  • :material-newspaper-variant-outline:   Built-in blog plugin


    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

  • :material-magnify:   Built-in search plugin


    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

  • :material-tag-text:   Built-in tags plugin


    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

  • :material-format-title:   Built-in typeset plugin


    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: