` must be set to an identifier for associating authors
+ with posts, e.g., a GitHub username like `squidfunk`. This identifier can
+ then be used in the [`authors`][meta.authors] metadata property of
+ a post. Multiple authors are supported. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
+
+### Drafts
+
+The following settings are available for drafts:
+
+---
+
+####
+
+
+
+
+Rendering [draft posts][meta.draft] can be useful in deploy previews. Use this
+setting to specify whether the plugin should include posts marked as drafts when
+[building your project]:
+
+=== "Render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: true
+ ```
+
+=== "Don't render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: false
+ ```
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should include posts marked as
+drafts when [previewing your site]. If you don't wish to include draft posts
+when previewing, use:
+
+``` yaml
+plugins:
+ - blog:
+ draft_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+####
+
+
+
+
+The plugin can automatically mark posts with future dates as drafts. When the
+date is past today, the post is automatically included when
+[building your project], unless explicitly marked as draft:
+
+``` yaml
+plugins:
+ - blog:
+ draft_if_future_date: true
+```
+
+## Usage
+
+### Metadata
+
+Posts can define a handful of metadata properties that specify how the plugin
+renders them, in which views they are integrated, and how they are linked to
+each other. The metadata of each post is validated against a schema to allow for
+a quicker discovery of syntax errors.
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a post with [authors] by providing a list of
+identifiers as defined in the [`authors_file`][config.authors_file]. If an
+author can't be resolved, the plugin will terminate with an error:
+
+``` yaml
+---
+authors:
+ - squidfunk # (1)!
+---
+
+# Post title
+...
+```
+
+1. Authors are linked by using their identifiers. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [authors]: #authors
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a post with one or more [categories][category],
+making the post a part of the generated category page. Categories are defined
+as a list of strings (whitespaces are allowed):
+
+``` yaml
+---
+categories:
+ - Search
+ - Performance
+---
+
+# Post title
+...
+```
+
+If you want to prevent accidental typos assigning categories to posts, you
+can set a predefined list of allowed categories in `mkdocs.yml` by using
+the [`categories_allowed`][config.categories_allowed] setting.
+
+---
+
+####
+
+
+
+
+
+Use this property to specify a post's date. Note that this property is required,
+which means the build fails when it's not set. Additional dates can be set by
+using a slightly different syntax:
+
+=== "Date"
+
+ ``` yaml
+ ---
+ date: 2023-01-31
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Update date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2023-01-31 # (1)!
+ updated: 2023-02-01
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. Each post must have a creation date set.
+
+=== "Custom date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2023-01-31
+ my_custom_date: 2023-02-01 # (1)!
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. The blog plugin validates all dates and allows to format them with
+ [babel]'s [pattern syntax] in templates. When using theme extension,
+ authors can add custom dates to templates.
+
+ This was first requested in #5733.
+
+The following date formats are supported:
+
+- `2023-01-31`
+- `2023-01-31T12:00:00`
+
+---
+
+####
+
+
+
+
+
+Use this property to mark a post as draft. The plugin allows to include or
+exclude posts marked as drafts when [building your project] using the
+[`draft`][config.draft] setting. Mark a post as draft with:
+
+``` yaml
+---
+draft: true
+---
+
+# Post title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+
+Use this property to define a list of links that are rendered in the sidebar of
+a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
+`mkdocs.yml`, supporting sections and even anchors:
+
+=== "Links"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - insiders/index.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with sections"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - Insiders:
+ - insiders/index.md
+ - insiders/getting-started.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with anchors"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md#built-in-search-plugin # (1)!
+ - Insiders:
+ - insiders/index.md#how-to-become-a-sponsor
+ - insiders/getting-started.md#requirements
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. If a link defines an anchor, the plugin resolves the anchor from the
+ linked page and sets the anchor title as a [subtitle].
+
+All relative links are resolved from the [`docs` directory][mkdocs.docs_dir].
+
+ [subtitle]: ../reference/index.md#setting-the-page-subtitle
+
+---
+
+####
+
+
+
+
+
+Use this property to explicitly set the reading time of a post in minutes. When
+[`post_readtime`][config.post_readtime] is enabled, the plugin computes the
+reading time of a post, which can be overridden with:
+
+``` yaml
+---
+readtime: 15
+---
+
+# Post title
+...
+```
+
+---
+
+####
+
+
+
+
+
+Use this property to explicitly set the slug of a post. By default, the slug of
+a post is automatically computed by the [`post_slugify`][config.post_slugify]
+function from the post's title, which can be overridden with:
+
+``` yaml
+---
+slug: help-im-trapped-in-a-universe-factory
+---
+
+# Post title
+...
+```
+
+Slugs are passed to [`post_url_format`][config.post_url_format].
+
+---
+
+!!! question "Missing something?"
+
+ When setting up your blog or migrating from another blog framework, you
+ might discover that you're missing specific functionality – we're happy to
+ consider adding it to the plugin! You can [open a discussion] to
+ ask a question, or create a [change request] on our [issue tracker], so we
+ can find out if it might be a good fit for the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/docs/plugins/group.md b/docs/plugins/group.md
new file mode 100644
index 000000000..37b41e11d
--- /dev/null
+++ b/docs/plugins/group.md
@@ -0,0 +1,121 @@
+---
+title: Built-in group plugin
+icon: 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], e.g., to only enable a subset of
+plugins when [building your project] during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin conditionally and lazily loads all plugins that are part of a group
+if and only if the group is enabled, which means that the plugin doesn't add any
+overhead when the group is disabled. It also means that the grouped plugins
+only need to be installed when the group is enabled.
+
+The plugins that are part of the group are executed in the same order as if
+they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
+Thus, order is preserved and deterministic.
+
+### When to use it
+
+Whenever you're using multiple plugins that are only required in specific
+environments, e.g., when building your project during continuous integration
+(CI), the plugin is the perfect utility for making configuration simpler, as it
+removes the need for splitting configuration into multiple files.
+
+It can be used with any built-in or third-party plugin.
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the group plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+splitting plugins into logical units:
+
+``` yaml
+plugins:
+ - group
+```
+
+The group plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [group]: group.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+The plugin behaves differently than all other built-in plugins – __it is
+disabled by default__. To enable a group, use:
+
+``` yaml
+plugins:
+ - group:
+ enabled: !ENV CI # (1)!
+```
+
+1. If you only want to use the group plugin for better organization and
+ always want to enable the plugins that are part of it, use:
+
+ ``` yaml
+ plugins:
+ - group:
+ enabled: true
+ ```
+
+The decision to disable the plugin by default was made to simplify the usage
+of environment variables, as it removes the need to provide a default value for
+an environment variable.
+
+Now, when [building your project], you can enable a group by setting the
+[environment variable][mkdocs.env]:
+
+``` sh
+CI=true mkdocs build
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+Use this setting to list the plugins that are part of the group. The syntax is
+exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
+simply copy the list of plugins that you want to group, e.g:
+
+``` yaml
+plugins:
+ - group:
+ plugins:
+ - optimize
+ - minify
+```
+
+The plugins mentioned here are just used for illustration purposes.
diff --git a/docs/plugins/index.md b/docs/plugins/index.md
new file mode 100644
index 000000000..892441890
--- /dev/null
+++ b/docs/plugins/index.md
@@ -0,0 +1,246 @@
+# Built-in plugins
+
+Material for MkDocs started out as a theme for [MkDocs][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][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.
+
+ [mkdocs]: https://www.mkdocs.org/
+ [design principles]: ../design-principles.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## 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][group]__
+
+ ---
+
+ 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][meta]__
+
+ ---
+
+ 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][projects]__
+
+ ---
+
+ 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][info]__
+
+ ---
+
+ 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__
+
+
+
+
+ [group]: group.md
+ [info]: info.md
+ [meta]: meta.md
+ [projects]: meta.md
+
+### 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][social]__
+
+ ---
+
+ 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][optimize]__
+
+ ---
+
+ 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][privacy]__
+
+ ---
+
+ 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][offline]__
+
+ ---
+
+ 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__
+
+
+
+ [offline]: offline.md
+ [optimize]: optimize.md
+ [privacy]: privacy.md
+ [social]: social.md
+
+### 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][blog]__
+
+ ---
+
+ 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][search]__
+
+ ---
+
+ 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][tags]__
+
+ ---
+
+ 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][typeset]__
+
+ ---
+
+ 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__
+
+
+
+ [blog]: blog.md
+ [search]: search.md
+ [tags]: tags.md
+ [typeset]: typeset.md
+
+## 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:
+
+
+
+- [Built-in blog plugin][blog]
+- [Built-in group plugin][group]
+- [Built-in optimize plugin][optimize]
+- [Built-in privacy plugin][privacy]
+- [Built-in social plugin][social]
+
+
diff --git a/docs/plugins/info.md b/docs/plugins/info.md
new file mode 100644
index 000000000..b422daa71
--- /dev/null
+++ b/docs/plugins/info.md
@@ -0,0 +1,155 @@
+---
+title: Built-in info plugin
+icon: material/information
+---
+
+# Built-in info plugin
+
+The info plugin is a utility that is solely intended to create self-contained
+[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
+[change requests], making communication between us maintainers and you much
+easier, as we have a common ground to work on.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
+ [reporting bugs]: ../contributing/reporting-a-bug.md
+ [change requests]: ../contributing/requesting-a-change.md
+
+## Objective
+
+### How it works
+
+The plugin helps you to prepare a minimal reproduction by collecting the
+necessary information about the environment and configuration of your project.
+This makes it easier for us to fix bugs, as it requires that you
+[upgrade to the latest version] and [remove your customizations].
+
+When following these principles, you can be confident that you don't report a
+bug that has already been fixed in a subsequent release, or which is caused by
+one of your customizations. Even more importantly, you actively help
+us to fix the bug as quickly as possible.
+
+The output of the plugin is a `.zip` file that you can share with us maintainers.
+
+ [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+ [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
+
+
+### When to use it
+
+Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
+like a question or [change request][change requests], you should attach
+a small, self-contained minimal reproduction. Runnable examples help to make
+communication much more efficient, giving us maintainers more time to benefit
+more users by pushing the project forward. Minimal reproductions are mandatory
+for bug reports.
+
+## Configuration
+
+
+
+
+In order to get started with the built-in info plugin, just add the following
+lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
+with us maintainers:
+
+``` yaml
+plugins:
+ - info
+```
+
+The info plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [info]: info.md
+ [create a minimal reproduction]: ../guides/creating-a-reproduction.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should be enabled when
+[previewing your site]. It's normally not necessary to specify this setting,
+but if you want to change this behavior, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled_on_serve: true
+```
+
+This setting streamlines the process of creating and inspecting minimal
+reproductions, as it allows to quickly iterate on the reproduction without
+having to disable the plugin first.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+### Archive
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should create a `.zip` file
+from the project or exit after the version check. This setting is solely
+intended for debugging the plugin itself:
+
+``` yaml
+plugins:
+ - info:
+ archive: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should stop creating the `.zip`
+file when one of the [requirements] is not satisfied. This setting must only be
+used when [reporting a bug][reporting bugs] that is related to a customization
+[explicitly mentioned in our documentation]. You can change it with:
+
+``` yaml
+plugins:
+ - info:
+ archive_stop_on_violation: false
+```
+
+If you're using this setting when [reporting a bug][reporting bugs], please
+explain why you think it is necessary to include customizations. If you're
+unsure, please ask us first by [creating a discussion].
+
+ [requirements]: #how-it-works
+ [explicitly mentioned in our documentation]: ?q=%22extends+base%22
+ [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/docs/plugins/meta.md b/docs/plugins/meta.md
new file mode 100644
index 000000000..c754e0010
--- /dev/null
+++ b/docs/plugins/meta.md
@@ -0,0 +1,195 @@
+---
+title: Built-in meta plugin
+icon: material/file-tree
+---
+
+# Built-in meta plugin
+
+The meta plugin solves the problem of setting metadata (front matter) for all
+pages in a folder, i.e., a subsection of your project, which is particularly
+useful to ensure that a certain subset of pages features specific tags, uses a
+custom template, or is attributed to an author.
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
+and recursively merges the contents of those files with the metadata (front
+matter) of all pages that are contained in the same folder and all subfolders.
+For example, if you want to add the tag Example to
+multiple pages, use:
+
+``` yaml title=".meta.yml"
+tags:
+ - Example
+```
+
+Now, given the following directory layout, if you store the file in the folder
+named `example`, all pages in that folder receive the tag, while all pages
+outside of the folder remain unaffected:
+
+``` { .sh .no-copy hl_lines="4-8" }
+.
+├─ docs/
+│ ├─ ...
+│ ├─ example/
+│ │ ├─ .meta.yml
+│ │ ├─ a.md
+│ │ ├─ ...
+│ │ └─ z.md
+│ └─ ...
+└─ mkdocs.yml
+```
+
+When combining metadata, lists and dictionaries are recursively merged, which
+means you can append values to a list and add or set specific properties in a
+dictionary on arbitrary levels.
+
+### When to use it
+
+While the plugin itself doesn't offer much functionality beyond adding and
+merging metadata, it is a perfect companion for many of the other built-in
+plugins that Material for MkDocs offers. Some of the most powerful combinations
+of the meta plugin and other built-in plugins are:
+
+
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The meta plugin can be used to [change the layout] for social cards or
+ [change specific layout options] like [background] or [color]
+ for a subset of pages.
+
+ ``` yaml title=".meta.yml"
+ social:
+ cards_layout: default/variant
+ ```
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The meta plugin allows to automatically associate blog posts with specific
+ [authors] and [categories], ensuring that blog posts are always correctly
+ annotated.
+
+ ``` yaml title=".meta.yml"
+ authors:
+ - squidfunk
+ ```
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags], so they can't be forgotten when
+ adding pages.
+
+ ``` yaml title=".meta.yml"
+ tags:
+ - Example
+ ```
+
+- :material-magnify: __[Built-in search plugin][search]__
+
+ ---
+
+ The meta plugin makes it easy to [boost] specific sections in search results
+ or to [exclude] them entirely from being indexed, giving more granular
+ control over search.
+
+ ``` yaml title=".meta.yml"
+ search:
+ exclude: true
+ ```
+
+
+
+ [social]: social.md
+ [change the layout]: social.md#meta.social.cards_layout
+ [change specific layout options]: social.md#meta.social.cards_layout_options
+ [background]: social.md#option.background_color
+ [color]: social.md#option.color
+ [blog]: blog.md
+ [authors]: blog.md#meta.authors
+ [categories]: blog.md#meta.categories
+ [tags]: tags.md
+ [specific tags]: tags.md#meta.tags
+ [search]: search.md
+ [exclude]: search.md#meta.search.exclude
+ [boost]: search.md#meta.search.boost
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the meta plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+applying metadata for multiple pages at once:
+
+``` yaml
+plugins:
+ - meta
+```
+
+The meta plugin is included with Material for MkDocs and doesn't need to be
+installed.
+
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - meta:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Meta file
+
+The following settings are available for meta files:
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the file the plugin will look for when scanning
+the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to change
+this setting, but if you want to change it, use:
+
+``` yaml
+plugins:
+ - meta:
+ meta_file: .meta.yml
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
+recursively.
diff --git a/docs/plugins/offline.md b/docs/plugins/offline.md
new file mode 100644
index 000000000..6e6b72452
--- /dev/null
+++ b/docs/plugins/offline.md
@@ -0,0 +1,153 @@
+---
+title: Built-in offline plugin
+icon: material/connection
+---
+
+
+# Built-in offline plugin
+
+[MkDocs][mkdocs] is one of the few frameworks that allow to build offline-capable
+documentation that can be directly viewed by the user – no server needed. With
+the offline plugin, you can distribute the [`site` directory][mkdocs.site_dir]
+as a downloadable `.zip` file while retaining most interactive functionality.
+
+## Objective
+
+### How it works
+
+After [building your project], switch to the [`site` directory][mkdocs.site_dir]
+and open `index.html` in your browser – you're now viewing your documentation
+from your local file system! Most browsers will denote this by showing `file://`
+in the address bar. However, you'll realize that the site search is gone.
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the local file system due to the restrictions of modern browsers. More
+specifically and technically, all calls to the [Fetch API] will error with a
+message like:
+
+```
+Cross origin requests are only supported for protocol schemes: http, [...]
+```
+
+While browsers impose those restriction for security reasons, it reduces the
+interactivity of your project. The offline plugin makes sure that site search
+keeps working by moving the search index to a JavaScript file, and leveraging
+@squidfunk's [iframe-worker] shim.
+
+Additionally, the plugin automatically disables the
+[`use_directory_urls`][mkdocs.use_directory_urls] setting, ensuring that users
+can open your documentation directly from the local file system.
+
+There are some [limitations].
+
+ [building your project]: ../creating-your-site.md#building-your-site
+ [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ [iframe-worker]: https://github.com/squidfunk/iframe-worker
+ [limitations]: #limitations
+
+### When to use it
+
+As the name already indicates, the plugin should only be used when you're
+[building your project] for offline distribution. It's also good to know, that
+the offline plugin plays nicely with the following other plugins, helping to
+create even better offline-capable documentation:
+
+
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use external assets when building for
+ offline usage, as it automatically downloads them for distribution with
+ your documentation.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet[^1]__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your documentation can be distributed as a smaller `.zip` download__
+
+
+
+ [^1]:
+ You might wonder why the [privacy plugin][privacy] is necessary to build
+ truly offline-capable documentation with the offline plugin. While it's
+ certainly possible to also add support for downloading external assets to
+ the offline plugin, this functionality is already fully implemented in the
+ privacy plugin and is its very raison d'être.
+
+ Material for MkDocs follows a modular approach for its plugin system – many
+ of the plugins work perfectly together and enhance each others
+ functionalities, allowing to solve complex problems with a few lines
+ of configuration.
+
+ [privacy]: privacy.md
+ [optimize]: optimize.md
+
+## Configuration
+
+
+
+
+As with all [built-in plugins], getting started with the offline plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+building offline-capable documentation:
+
+``` yaml
+plugins:
+ - offline
+```
+
+The offline plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [offline]: offline.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to build online- as well as offline-capable documentation, it's a
+good idea to use an [environment variable][mkdocs.env]:
+
+``` yaml
+plugins:
+ - offline:
+ enabled: !ENV [OFFLINE, false]
+```
+
+## Limitations
+
+When enabling the offline plugin, make sure to disable the following settings,
+as they make use of the [Fetch API] which will error when invoked from the local
+file system:
+
+- [Instant loading]
+- [Site analytics]
+- [Versioning]
+- [Comment systems]
+
+ [Instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Site analytics]: ../setup/setting-up-site-analytics.md
+ [Versioning]: ../setup/setting-up-versioning.md
+ [Comment systems]: ../setup/adding-a-comment-system.md
diff --git a/docs/plugins/optimize.md b/docs/plugins/optimize.md
new file mode 100644
index 000000000..a30f7fb39
--- /dev/null
+++ b/docs/plugins/optimize.md
@@ -0,0 +1,443 @@
+---
+title: Built-in optimize plugin
+icon: material/rabbit
+---
+
+# Built-in optimize plugin
+
+The optimize plugin automatically identifies and optimizes all media files when
+[building your project] by using common compression and conversion techniques.
+As a result, your site loads significantly faster and yields better rankings in
+search engines.
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
+assets, optimizing them automatically in order to reduce the final size of the
+[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
+ship less bytes to your users, as well as a smaller download for
+[offline-capable documentation].
+
+Optimized images are [intelligently cached][intelligent caching], which is why
+the plugin will only optimize media files that changed since the last build.
+This makes it possible to swap out or update images, without having to worry
+about optimizing them, or even worse, forgetting to do so.
+
+In order to optimize media files, a few [dependencies] need to be available on
+your system.
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [dependencies]: #configuration
+
+### When to use it
+
+It's generally recommended to use the plugin, as media files are optimized
+automatically without the need for intervention, ensuring that your site loads
+as fast as possible. Optimized media files are one of the key components for a
+high and consistent ranking in search engines.
+
+Additionally, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated
+build pipelines tailored to your project:
+
+
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use unoptimized external assets, passing
+ them to the optimize plugin before copying them to the [`site` directory]
+ [mkdocs.site_dir].
+
+ ---
+
+ __External media files can be automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ 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 be distributed as a smaller `.zip` download__
+
+
+
+ [privacy]: privacy.md
+ [offline]: offline.md
+
+## Configuration
+
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the optimize plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe how
+media files are optimized automatically:
+
+``` yaml
+plugins:
+ - optimize
+```
+
+The optimize plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to optimize all media files, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [optimize]: optimize.md
+ [built-in plugins]: index.md
+ [image processing]: requirements/image-processing.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - optimize:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete media file optimization faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - optimize:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a media
+file or asset is only passed through the optimization pipeline when its contents
+change. If you swap out or update an image, the plugin detects it and updates
+the optimized version of the media file.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-optimize all media files, even though the cache may not be stale. It's
+normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - optimize:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where media files are cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - optimize:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Optimization
+
+Documentation often makes use of screenshots or diagrams for better
+visualization of things, both of which are prime candidates for optimization.
+The plugin automatically optimizes images using [pngquant] for `.png` files,
+and [Pillow] for `.jpg` files.
+
+The following settings are available for optimization:
+
+ [pngquant]: https://pngquant.org/
+ [Pillow]: https://pillow.readthedocs.io/
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable media file optimization. Currently,
+the plugin's sole purpose is to optimize media files, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the near future, other features
+might be added. If you want to disable optimization, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the optimization of `.png` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.png` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the speed/quality tradeoff that [pngquant] applies
+when optimizing `.png` files. The lower the number, the more aggressively
+[pngquant] will try to optimize:
+
+=== "Slower smaller "
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 1
+ ```
+
+=== "Faster larger "
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 10
+ ```
+
+A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether [pngquant] should strip optional metadata
+from `.png` files that are not required to display the image, e.g., [EXIF].
+If you want to preserve metadata, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png_strip: false
+```
+
+ [EXIF]: https://en.wikipedia.org/wiki/Exif
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the optimization of `.jpg` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.jpg` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the image quality that [Pillow] applies when
+optimizing `.jpg` files. If the images look blurry, it's a good idea to
+fine-tune and change this setting:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_quality: 75
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether [Pillow] should use progressive encoding
+when optimizing `.jpg` files, rendering faster on slow connections. If you want
+to disable progressive encoding, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_progressive: false
+```
+
+ [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_include:
+ - screenshots/*
+```
+
+This configuration enables optimization for all media files that are contained
+in the `screenshots` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - social:
+ optimize_exclude:
+ - vendor/*
+```
+
+This configuration disables optimization for all media files that are contained
+in the `vendor` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+### Reporting
+
+The following settings are available for reporting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should print the number of bytes
+gained after optimizing each file. If you want to disable this behavior, use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should print the total number of
+bytes gained after optimizing all files. If you want to disable this behavior,
+use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain_summary: false
+```
diff --git a/docs/plugins/privacy.md b/docs/plugins/privacy.md
new file mode 100644
index 000000000..d4141ac25
--- /dev/null
+++ b/docs/plugins/privacy.md
@@ -0,0 +1,416 @@
+---
+title: Built-in privacy plugin
+icon: material/shield-account
+---
+
+
+# Built-in privacy plugin
+
+The privacy plugin offers a streamlined solution for automatically self-hosting
+external assets. With just a single line of configuration, the plugin can
+automatically identify and download external assets, making GDPR compliance
+as effortless as it can possibly be.
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML for external assets, i.e., scripts, style
+sheets, images, and web fonts, downloads them, stores them in the
+[`site` directory][mkdocs.site_dir] and replaces all references with links to
+the downloaded copies for effortless self-hosting. For example:
+
+``` html
+
+```
+
+This external script is downloaded, and the link is replaced with:
+
+``` html
+
+```
+
+Of course, scripts and style sheets can reference further external assets,
+which is why this process is repeated recursively until no further external
+assets are detected:
+
+- Scripts are scanned for further scripts, style sheets and JSON files
+- Style sheets are scanned for images and web fonts
+
+Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
+requesting external assets, are removed from the output, as they're not
+necessary when self-hosting. After the plugin has done it's work, your project
+will be free of requests to external services.
+
+There are some [limitations].
+
+ [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin was developed to make compliance with the 2018 European
+__General Data Protection Regulation__ (GDPR) as simple as possible, while
+retaining the flexibility and power that Material for MkDocs offers, like for
+example its tight integration with [Google Fonts].
+
+But, that's only the start. For example, if your project includes a lot of
+images, enabling the plugin allows to move them outside of your repository, as
+the plugin will automatically download and store them in the [`site` directory]
+[mkdocs.site_dir] when [building your project].
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin allows to optimize all downloaded external assets
+ detected by the privacy plugin by using compression and conversion
+ techniques.
+
+ ---
+
+ __External media files are automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ 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__
+
+
+
+ [Google Fonts]: ../setup/changing-the-fonts.md
+ [building your project]: ../creating-your-site.md#building-your-site
+ [optimize]: optimize.md
+ [offline]: offline.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Configuration
+
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the privacy plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+effortlessly self-hosting external assets:
+
+``` yaml
+plugins:
+ - privacy
+```
+
+The privacy plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [privacy]: privacy.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - privacy:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete handling of external assets faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - privacy:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that external
+assets are only downloaded when they're not already contained in the cache.
+While the initial build might take some time, it's a good idea to use caching,
+as it will speed up consecutive builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-schedule downloads for all external assets, even though the cache may not be
+stale. It's normally not necessary to specify this setting, except for when
+debugging the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - privacy:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where downloaded copies are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### External assets
+
+The following settings are available for external assets:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should download external
+assets. If you only want the plugin to process [external links], you can disable
+handling of external assets with:
+
+``` yaml
+plugins:
+ - privacy:
+ assets: false
+```
+
+ [external links]: #external-links
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should downloads or only report
+external assets when they're encountered. If you already self-host all external
+assets, this setting can be used as a safety net to detect links to external
+assets placed by the author in pages:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch: true
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+external assets are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch_dir: my/custom/dir
+```
+
+This configuration stores the downloaded copies at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_include:
+ - unsplash.com/*
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_exclude: # (1)!
+ - cdn.jsdelivr.net/npm/mathjax@3/*
+ - giscus.app/*
+```
+
+1. [MathJax] loads web fonts for typesetting of mathematical content
+ through relative URLs, and thus cannot be automatically bundled by the
+ privacy plugin. [MathJax can be self-hosted].
+
+ [Giscus], which we recommend to use as a [comment system], uses a technique
+ called code-splitting to load only the code that is necessary, which
+ is implemented via relative URLs. [Giscus can be self-hosted] as well.
+
+ [MathJax]: ../reference/math.md
+ [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
+ [Giscus]: https://giscus.app/
+ [comment system]: ../setup/adding-a-comment-system.md
+ [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
+
+---
+
+### External links
+
+The following settings are available for external links:
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to parse and process external links to
+annotate them for [improved security], or to automatically add additional
+attributes to external links. If you want to disable processing of external
+links, use:
+
+``` yaml
+plugins:
+ - privacy:
+ links: false
+```
+
+ [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify additional attributes that should be added to
+external links, for example, to add `target="_blank"` to all external links
+so they open in a new tab:
+
+``` yaml
+plugins:
+ - privacy:
+ links_attr_map:
+ target: _blank
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not recommended to change this setting, as it will automatically
+annotate external links that open in a new window with `rel="noopener"` for
+[improved security]:
+
+``` yaml
+plugins:
+ - privacy:
+ links_noopener: true
+```
+
+## Limitations
+
+Dynamically created URLs as part of scripts are not detected, and thus cannot be
+downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
+
+``` js
+const cdn = "https://polyfill.io"
+const url = `${cdn}/v3/polyfill.min.js`
+```
+
+Instead, always use fully qualified URLs:
+
+``` js
+const url ="https://polyfill.io/v3/polyfill.min.js"
+```
diff --git a/docs/plugins/projects.md b/docs/plugins/projects.md
new file mode 100644
index 000000000..b308762f1
--- /dev/null
+++ b/docs/plugins/projects.md
@@ -0,0 +1,264 @@
+---
+title: Built-in projects plugin
+icon: material/folder-open
+---
+
+# Built-in projects plugin
+
+The projects plugin adds the ability to split your main project into multiple
+distinct projects, build them concurrently and preview them together as one.
+This is particularly useful when creating a multi-language project, but can also
+be used to split very large projects into smaller parts.
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`projects` directory][config.projects_dir] for
+`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
+If not configured otherwise, the plugin expects that your project has
+the following directory layout, e.g. for a multi-language project:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+├─ projects/
+│ ├─ en/
+│ │ ├─ docs/
+│ │ └─ mkdocs.yml
+│ └─ de/
+│ ├─ docs/
+│ └─ mkdocs.yml
+└─ mkdocs.yml
+```
+
+One of the most useful and interesting features of the plugin is that it allows
+[previewing your site] from the main project, while still being able to preview
+and build each project individually. This is especially useful for
+multi-language projects.
+
+If, when [previewing your site], you change a file in one of the projects, the
+plugin only rebuilds this project and makes sure that MkDocs will also reload
+the associated files. This also creates the opportunity for splitting your
+main project into several projects for a better editing experience.
+
+There are some [limitations], but we're working hard to remove them.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin came into existence because we needed a convenient and scalable
+method to build our [examples] repository, which features many self-contained
+and runnable projects that users can download and use as a basis when
+boostrapping a new project or [creating a reproduction].
+
+When you want to create a multi-language project, or have a very large existing
+project, you might consider using the plugin, as it makes managing, editing
+and building more comfortable.
+
+ [examples]: https://github.com/mkdocs-material/examples
+ [creating a reproduction]: ../guides/creating-a-reproduction.md
+
+## Configuration
+
+
+
+
+
+
+In order to get started with the projects plugin, just add the following lines
+to `mkdocs.yml`, and split your main project into several distinct projects that
+can be built concurrently:
+
+``` yaml
+plugins:
+ - projects
+```
+
+The projects plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [projects]: projects.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+build projects faster. If you want to disable concurrent processing completely,
+use:
+
+``` yaml
+plugins:
+ - projects:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a
+project is only rebuilt when its contents change. While the initial build might
+take some time, it's a good idea to use caching, as it will speed up consecutive
+builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+rebuild all projects, even though the cache may not be stale. It's normally not
+necessary to specify this setting, except for when debugging the plugin itself.
+Caching can be disabled with:
+
+``` yaml
+plugins:
+ - projects:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where the metadata is cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - projects:
+ cache_dir: my/custom/dir
+```
+
+### Projects
+
+The following settings are available for projects:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable building of projects. Currently, the
+plugin's sole purpose is to build projects, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable building of projects, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the folder where your projects are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects_dir: projects
+```
+
+Note that the [`projects` directory][config.projects_dir] is solely used for
+project organization – it is not included in project URLs, since projects are
+automatically hoisted by the plugin.
+
+The provided path is resolved from the root directory.
+
+### Hoisting
+
+The following settings are available for hoisting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable hoisting of themes files to the main
+project. If you disable this setting, each project receives a copy of the
+theme's files, which can be considered redundant:
+
+``` yaml
+plugins:
+ - projects:
+ hoisting: false
+```
+
+It's generally advisable to enable hoisting, as it yields faster deployments
+and faster loading of your project's sites, because the files are the same for
+all projects and can be deduplicated.
+
+### Limitations
+
+The plugin is one of the latest additions to Material for MkDocs, which means it
+is rather young and has some limitations. We're working hard to remove them, and
+we're happy to receive feedback and learn about your requirements in ?5800.
+Current limitations are:
+
+- __Basic multi-language support only__: we'll be investigating how to provide
+ better support for multi-language projects, allowing to easier interlink
+ projects and switch between them.
+
+- __Separate search indexes and sitemaps__: currently, the projects are entirely
+ separate, which means they will have separate search indexes and sitemaps.
diff --git a/docs/plugins/requirements/caching.md b/docs/plugins/requirements/caching.md
new file mode 100644
index 000000000..63b3f4a9e
--- /dev/null
+++ b/docs/plugins/requirements/caching.md
@@ -0,0 +1,35 @@
+---
+icon: material/database-outline
+---
+
+# Caching
+
+Some of the [built-in plugins] implement intelligent caching mechanisms, which
+massively speed up consecutive builds by reducing the amount of work that needs
+to be done. This guide explains how to configure caching in different
+environments.
+
+## Prerequisites
+
+Caching is entirely optional but enabled by default. It can be disabled per
+plugin. If not configured otherwise, plugins will cache their data in the
+`.cache` folder in the root of your project. For this reason it's recommended
+to create a `.gitignore` file in the root of your project:
+
+``` title=".gitignore"
+.cache
+```
+
+This ensures that cached files are not added to your git repository – something
+that is generally not recommended to do unless absolutely necessary. In some
+cases, you might need to check in cached files, e.g. when you need to
+pre-generate [social cards] locally, e.g., when you're not be able to install
+the image processing dependencies in your continuous integration (CI)
+environment.
+
+In this case, we recommend changing the `cache_dir` setting – something that all
+plugins that implement caching share – to a folder which you add to your git
+repository.
+
+ [built-in plugins]: ../index.md
+ [social cards]: ../../setup/setting-up-social-cards.md
diff --git a/docs/setup/dependencies/image-processing.md b/docs/plugins/requirements/image-processing.md
similarity index 73%
rename from docs/setup/dependencies/image-processing.md
rename to docs/plugins/requirements/image-processing.md
index ae053e05f..38b3dc03d 100644
--- a/docs/setup/dependencies/image-processing.md
+++ b/docs/plugins/requirements/image-processing.md
@@ -1,21 +1,38 @@
+---
+icon: material/image-sync-outline
+---
+
# Image processing
-Material for MkDocs depends on several libraries to allow for image processing
-as part of the build pipeline, including [social cards] and [image optimization].
-For this reason, a few external libraries must be installed on the host system.
-This section explains how to install them.
+Some of the [built-in plugins] depend on external libraries for efficient image
+processing, most notably the [social] plugin to generate [social cards], and the
+[optimize] plugin for applying [image optimization]. This guide explains how to
+install those libraries in different environments.
- [social cards]: ../setting-up-social-cards.md
- [image optimization]: ../building-an-optimized-site.md
+ [built-in plugins]: ../index.md
+ [social]: ../social.md
+ [social cards]: ../../setup/setting-up-social-cards.md
+ [optimize]: ../optimize.md
+ [image optimization]: ../../setup/building-an-optimized-site.md
## Dependencies
-Install the Python dependencies for image processing with:
+The libraries for image processing are entirely optional, and only need to be
+installed if you want to use the [social] plugin or the [optimize] plugin. The
+libraries are listed under the `imaging` extra:
```
-pip install pillow cairosvg
+pip install "mkdocs-material[imaging]"
```
+This will install compatible versions of the following packages:
+
+- [Pillow]
+- [CairoSVG]
+
+ [Pillow]: https://pillow.readthedocs.io/
+ [CairoSVG]: https://cairosvg.org/
+
### Cairo Graphics
[Cairo Graphics] is a graphics library and dependency of [Pillow], which
@@ -36,9 +53,8 @@ Material for MkDocs makes use of for generating [social cards] and performing
=== ":fontawesome-brands-windows: Windows"
As stated in the [installation guide], the easiest way to get up and running
- with the [Cairo Graphics] library on Windows is by installing [GTK+], since
- it has Cairo as a dependency. You can also download and install a
- precompiled [GTK runtime].
+ with the [Cairo Graphics] library on Windows is by installing [GTK+]. You
+ can also download a precompiled [GTK runtime].
=== ":material-linux: Linux"
@@ -70,8 +86,6 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
- [x] No installation needed in [GitHub Actions] (Ubuntu)
[Cairo Graphics]: https://www.cairographics.org/
- [Pillow]: https://pillow.readthedocs.io/
- [CairoSVG]: https://cairosvg.org/
[Homebrew]: https://brew.sh/
[installation guide]: https://www.cairographics.org/download/
[GTK+]: https://www.gtk.org/docs/installations/windows/
@@ -82,7 +96,7 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
### pngquant
[pngquant] is an excellent library for lossy PNG compression, and a direct
-dependency of the [built-in optimize plugin]. See the following section which
+dependency of the [built-in optimize plugin]. See the following section which
explains how to install [pngquant] system:
=== ":material-apple: macOS"
@@ -97,8 +111,8 @@ explains how to install [pngquant] system:
=== ":fontawesome-brands-windows: Windows"
- Installing [pngquant] on Windows is a little more involved. The
- [pngquant-winbuild] repository contains a guide on how to set up an
+ Installing [pngquant] on Windows is a little more involved. The
+ [pngquant-winbuild] repository contains a guide on how to set up an
environment for building [pngquant] on Windows.
=== ":material-linux: Linux"
@@ -113,6 +127,10 @@ explains how to install [pngquant] system:
The same is true for `yum` and `zypper`.
+The following environments come with a preinstalled version of [pngquant]:
+
+- [x] No installation needed in [Docker image]
+
[pngquant]: https://pngquant.org/
- [built-in optimize plugin]: ../building-an-optimized-site.md#built-in-optimize-plugin
+ [built-in optimize plugin]: ../../setup/building-an-optimized-site.md#built-in-optimize-plugin
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild
diff --git a/docs/plugins/search.md b/docs/plugins/search.md
new file mode 100644
index 000000000..517b2b128
--- /dev/null
+++ b/docs/plugins/search.md
@@ -0,0 +1,427 @@
+---
+title: Built-in search plugin
+icon: material/magnify
+---
+
+# Built-in search plugin
+
+The search plugin adds a search bar to the header, allowing users to search your
+documentation. It's powered by [lunr.js], a lightweight full-text search engine
+for the browser, elimininating the need for external services, and even works
+when building [offline-capable documentation].
+
+ [lunr.js]: https://lunrjs.com/
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML and builds a search index from all pages and
+sections by extracting the section titles and contents. It preserves some inline
+formatting like code blocks and lists, but removes all other formatting, so the
+search index is as small as possible.
+
+When a user visits your site, the search index is shipped to the browser,
+indexed with [lunr.js] and made available for fast and simple querying – no
+server needed. This ensures that the search index is always up to date with
+your documentation, yielding accurate results.
+
+### When to use it
+
+It's generally recommended to use the plugin, as interactive search functionality
+is a vital part of every good documentation. Additionally, the plugin integrates
+perfectly with several of the other [built-in plugins] that Material for MkDocs
+offers:
+
+
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ 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__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to [boost][meta.search.boost] specific
+ sections in search results or to [exclude][meta.search.exclude] them
+ entirely from being indexed, giving more granular control over search.
+
+ ---
+
+ __Simpler organization and management of search in different subsections__
+
+
+
+ [offline]: offline.md
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+
+
+
+As with all [built-in plugins], getting started with the search plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and your users
+will be able to search your documentation:
+
+``` yaml
+plugins:
+ - search
+```
+
+The search plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [search]: search.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - search:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Search
+
+The following settings are available for search:
+
+---
+
+####
+
+
+
+
+Use this setting to specify the language of the search index, enabling [stemming]
+support for other languages than English. The default value is automatically
+computed from the [site language], but can be explicitly set to another language
+or even multiple languages with:
+
+=== "Set language"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: en
+ ```
+
+=== "Add further languages"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: # (1)!
+ - en
+ - de
+ ```
+
+ 1. Be aware that including support for further languages increases the
+ base JavaScript payload by around 20kb and by another 15-30kb per
+ language, all before `gzip`.
+
+ [stemming]: https://en.wikipedia.org/wiki/Stemming
+ [site language]: ../setup/changing-the-language.md#site-language
+ [lunr languages]: https://github.com/MihaiValentin/lunr-languages
+
+Language support is provided by [lunr languages], a collection of
+language-specific stemmers and stop words for [lunr.js] maintained by the
+Open Source community.
+
+---
+
+The following languages are currently supported by [lunr languages]:
+
+
+
+- `ar` – Arabic
+- `da` – Danish
+- `de` – German
+- `du` – Dutch
+- `en` – English
+- `es` – Spanish
+- `fi` – Finnish
+- `fr` – French
+- `hi` – Hindi
+- `hu` – Hungarian
+- `hy` – Armenian
+- `it` – Italian
+- `ja` – Japanese
+- `kn` - Kannada
+- `ko` – Korean
+- `no` – Norwegian
+- `pt` – Portuguese
+- `ro` – Romanian
+- `ru` – Russian
+- `sa` – Sanskrit
+- `sv` – Swedish
+- `ta` – Tamil
+- `te` – Telugu
+- `th` – Thai
+- `tr` – Turkish
+- `vi` – Vietnamese
+- `zh` – Chinese
+
+
+
+If [lunr languages] doesn't provide support for the selected [site language],
+the plugin falls back to another language that yields the best stemming results.
+If you discover that the search results are not satisfactory, you can contribute
+to [lunr languages] by adding support for your language.
+
+---
+
+####
+
+
+
+
+Use this setting to specify the separator used to split words when building the
+search index on the client side. The default value is automatically computed
+from the [site language], but can also be explicitly set to another value with:
+
+``` yaml
+plugins:
+ - search:
+ separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+```
+
+Separators support [positive and negative lookahead assertions], which allows
+for rather complex expressions that yield precise control over how words are
+split when building the search index.
+
+Broken into its parts, this separator induces the following behavior:
+
+=== "Special characters"
+
+ ```
+ [\s\-,:!=\[\]()"/]+
+ ```
+
+ The first part of the expression inserts token boundaries for each
+ document before and after whitespace, hyphens, commas, brackets and
+ other special characters. If several of those special characters are
+ adjacent, they are treated as one.
+
+=== "Case changes"
+
+ ```
+ (?!\b)(?=[A-Z][a-z])
+ ```
+
+ Many programming languages have naming conventions like `PascalCase` or
+ `camelCase`. By adding this subexpression to the separator,
+ [words are split at case changes], tokenizing the word `PascalCase`
+ into `Pascal` and `Case`.
+
+=== "Version strings"
+
+ ```
+ \.(?!\d)
+ ```
+
+ When adding `.` to the separator, version strings like `1.2.3` are split
+ into `1`, `2` and `3`, which makes them undiscoverable via search. When
+ using this subexpression, a small lookahead is introduced which will
+ [preserve version strings] and keep them discoverable.
+
+=== "HTML/XML tags"
+
+ ```
+ &[lg]t;
+ ```
+
+ If your documentation includes HTML/XML code examples, you may want to allow
+ users to find [specific tag names]. Unfortunately, the `<` and `>` control
+ characters are encoded in code blocks as `<` and `>`. Adding this
+ subexpression to the separator allows for just that.
+
+ [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
+ [words are split at case changes]: ?q=searchHighlight
+ [preserve version strings]: ?q=9.0.0
+ [specific tag names]: ?q=script
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the [pipeline functions] that are used to filter and
+expand tokens after tokenizing them with the [`separator`][config.separator] and
+before adding them to the search index. The default value is automatically
+computed from the [site language], but can also be explicitly set with:
+
+``` yaml
+plugins:
+ - search:
+ pipeline:
+ - stemmer
+ - stopWordFilter
+ - trimmer
+```
+
+The following pipeline functions can be used:
+
+- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
+- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
+- `trimmer` – Trim whitespace from tokens
+
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+
+### Segmentation
+
+The plugin supports text segmentation of Chinese via [jieba], a popular
+Chinese text segmentation library. Other languages like Japanese and Korean are
+currently segmented on the client side, but we're considering to move this
+functionality into the plugin in the future.
+
+The following settings are available for segmentation:
+
+ [jieba]: https://pypi.org/project/jieba/
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a [custom dictionary] to be used by [jieba] for
+segmenting text, replacing the default dictionary. [jieba] comes with
+several dictionaries, which can be used with:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict: dict.txt
+```
+
+The following dictionaries are provided by [jieba]:
+
+- [dict.txt.small] – 占用内存较小的词典文件
+- [dict.txt.big] – 支持繁体分词更好的词典文件
+
+The provided path is resolved from the root directory.
+
+ [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
+ [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
+ [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify an additional [user dictionary] to be used by
+[jieba] for segmenting text, augmenting the default dictionary. User
+dictionaries are ideal for tuning the segmenter:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict_user: user_dict.txt
+```
+
+The provided path is resolved from the root directory.
+
+ [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to increase or decrease the relevance of a page in the search
+results, giving more weight to them. Use values above `1` to rank up and values
+below `1` to rank down:
+
+=== ":material-arrow-up-circle: Rank up"
+
+ ``` yaml
+ ---
+ search:
+ boost: 2 # (1)!
+ ---
+
+ # Page title
+ ...
+ ```
+
+ 1. When boosting pages, always start with low values.
+
+=== ":material-arrow-down-circle: Rank down"
+
+ ``` yaml
+ ---
+ search:
+ boost: 0.5
+ ---
+
+ # Page title
+ ...
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this property to exclude a page from the search results. Note that this will
+not only remove the page, but also all subsections of the page from the search
+results:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
diff --git a/docs/plugins/social.md b/docs/plugins/social.md
new file mode 100644
index 000000000..6093b8351
--- /dev/null
+++ b/docs/plugins/social.md
@@ -0,0 +1,1059 @@
+---
+title: Built-in social plugin
+icon: material/share-circle
+---
+
+# Built-in social plugin
+
+The social plugin automatically and intelligently generates beautiful and highly
+customizable social cards in different [layouts][default layouts] for each page
+of your project, rendering as preview images whenever you or somebody else share
+a link to your project on social media.
+
+## Objective
+
+### How it works
+
+The plugin automatically generates a customizable social card for each page
+of your project, which appears as a preview image when sharing a link to your
+project on social media, without the use of external services and just
+[a single line of configuration][configuration].
+
+With the use of an efficient [image processing] library, the plugin allows to
+define [custom layouts] for social cards, which can be adapted to match your
+project's style and branding. While it would technically be much simpler to
+generate social cards by using a web browser and an automation framework like
+[Puppeteer][^1], it would add further liabilities to your toolchain, with the
+potential to make build pipelines more complex, much more resource intense,
+and significantly slower.
+
+ [^1]:
+ [GitHub wrote in their blog] that they use [Puppeteer] to generate social
+ card images for repositories, issues, commits, discussions, and basically
+ everything else that appear as preview images when shared on social media.
+
+The generated social cards are [cached] and stored in the
+[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your
+project doesn't depend on external services. In order to generate social cards
+images, a few [dependencies] need to be available on your system.
+
+ [configuration]: #configuration
+ [image processing]: requirements/image-processing.md
+ [custom layouts]: ../setup/setting-up-social-cards.md#customization
+ [Puppeteer]: https://github.com/puppeteer/puppeteer
+ [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/
+ [cached]: #caching
+ [dependencies]: #configuration
+
+### When to use it
+
+There's one particular case when we don't recommend to use the plugin: when you
+build [offline-capable documentation] to offer it as a download. Otherwise, it
+always makes sense to enable the plugin, as links to your documentation shared
+on social media will appear much more appealing.
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each post and page, showing as previews on social media.
+
+ ---
+
+ __Links to your blog render beautiful social cards when shared on social media__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin can be used to [change the layout][meta.social.cards_layout]
+ for social cards or [change specific layout options]
+ [meta.social.cards_layout_options] like [background][option.background_color]
+ or [color][option.color] for a subset of pages.
+
+ ---
+
+ __Your documentation can use completely different social cards per section__
+
+
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [blog]: blog.md
+ [meta]: meta.md
+
+## Configuration
+
+
+
+
+
+
+In order to get started with the social plugin, just add the following lines to
+`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social
+cards for you:
+
+``` yaml
+plugins:
+ - social
+```
+
+The social plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to generate social card images, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [social]: social.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - social:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete social card generation faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - social:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that social
+cards are only regenerated when their contents change or they're not already
+contained in the cache. If any of the variables used in a layout changes, the
+plugin detects it and regenerates the social card.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-generate social cards for all pages, even though the cache may not be stale.
+It's normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - social:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where social card images are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should only log errors when
+generating social cards without terminating the build, e.g., invalid references
+to icons. To terminate the build, use:
+
+``` yaml
+plugins:
+ - social:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: warn
+ ```
+
+ Errors are reported as warnings, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: info
+ ```
+
+ Errors are only reported as informational messages.
+
+=== "`ignore`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: ignore
+ ```
+
+ Errors are only reported when using the `--verbose` flag.
+
+
+### Social cards
+
+The following settings are available for social card generation:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable social card generation. Currently, the
+plugin's sole purpose is to generate social cards, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable social card generation, use:
+
+``` yaml
+plugins:
+ - social:
+ cards: false
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+social cards are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_dir: my/custom/dir
+```
+
+This configuration stores the generated images at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+If you want to build a [custom social card layout][custom layouts], use this
+setting to change the folder where you store your custom layouts, the default
+being a folder called `layouts` in your root directory:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_dir: layouts
+```
+
+The provided path is resolved from the root directory.
+
+!!! tip "Where to store custom layouts"
+
+ Our recommendation is to locate the folder outside of the
+ [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]
+ are not copied to the [`site` directory][mkdocs.site_dir] when
+ [building your project], e.g., by adhering to the following directory
+ layout:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ *.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+####
+
+
+
+
+
+The plugin ships a growing list of [`default` layouts][default layouts] for
+social cards. If you've created a [custom social card layout][custom layouts],
+you can instruct the plugin to use it exactly as one of the included layouts:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout: my-custom-layout
+```
+
+The provided path is resolved from the[
+`layouts` directory][config.cards_layout_dir].
+
+!!! tip "How custom layouts are resolved"
+
+ By default, the plugin will load your [custom layouts] from a folder named
+ `layouts` in your root directory. If your layout is called
+ `my-custom-layout`, the directory layout must adhere to:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ my-custom-layout.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+####
+
+
+
+
+Use this setting to set options for the layout specified via [`cards_layout`]
+[config.cards_layout] (if the layout supports it), which allows for making
+layouts easily and entirely configurable:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ :
+```
+
+When creating a [custom layout][custom layouts], you are completely free in
+defining which parts of your layout can be parametrized. The [`default` layouts]
+[default layouts] included with the plugin support the following options:
+
+
+
+- [`background_color`][option.background_color]
+- [`background_image`][option.background_image]
+- [`color`][option.color]
+- [`font_family`][option.font_family]
+- [`logo`][option.logo]
+- [`title`][option.title]
+- [`description`][option.description]
+
+
+
+
+ [default layouts]: #layouts
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_include:
+ - blog/*
+```
+
+This configuration enables social card generation for all pages that are
+contained in the `blog` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_exclude:
+ - changelog/*
+```
+
+This configuration disables social card generation for all pages that are
+contained in the `changelog` folder and its subfolders inside the
+[`docs` directory][mkdocs.docs_dir].
+
+### Debugging
+
+The plugin includes a special mode for debugging layouts, which is very useful
+when creating [custom layouts], as it allows for quicker iteration and better
+understanding of composition.
+
+The following settings are available for debugging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable a special mode for debugging your layout, which
+renders each layer with a colored outline and its `x` and `y` offsets, and
+overlays a dot grid for alignment, so it's easier to understand how the
+distinct layers of your layout are composed together:
+
+``` yaml
+plugins:
+ - social:
+ debug: true
+```
+
+---
+
+####
+
+
+
+
+
+By default, the plugin automatically disables [`debug`][config.debug] mode when
+[building your project], so you can be sure that debug overlays are never
+deployed to production. If you want to change that, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_on_build: true
+```
+
+It's normally not necessary to change this setting, as it's just intended to
+be a safety net.
+
+---
+
+####
+
+
+
+
+
+When [`debug`][config.debug] mode is enabled, this setting specifies whether a
+dot grid is rendered on top of all layers, to allow for better alignment. If you
+want to switch the grid off, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the step size of the dot grid in pixels, if enabled,
+which can be useful to create perfectly aligned layers for ideal composition.
+It you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid_step: 64
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the color of the outlines that are added to each
+layer and the dot grid that is rendered on top of all layers. If you need to
+change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_color: yellow
+```
+
+In rare cases, it might be necessary to change this setting if the dot grid or
+the outlines are hard to distinguish, as the plugin will automatically adjust
+the color if not explicitly set.
+
+## Usage
+
+### Metadata
+
+The plugin allows to override a subset of settings through metadata (front
+matter) in order to customize social card generation, e.g., to set [options for
+the included default layouts][default layouts] for a single page, or even
+[for an entire subsection] of your project by leveraging the [meta] plugin.
+
+The following properties are available:
+
+ [for an entire subsection]: meta.md#how-it-works
+ [meta]: meta.md
+
+---
+
+####
+
+
+
+
+
+
+Use this property to override the [`cards`][config.cards] setting for the given
+page:
+
+``` yaml
+---
+social:
+ cards: false
+---
+
+# Page title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+
+Use this property to override the [`cards_layout`][config.cards_layout] setting
+for the given page:
+
+``` yaml
+---
+social:
+ cards_layout: my-custom-layout
+---
+
+# Page title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+Use this property to override the [`cards_layout_options`]
+[config.cards_layout_options] setting for the given page:
+
+``` yaml
+---
+social:
+ cards_layout_options:
+ background_color: blue # Change background color
+ background_image: null # Remove background image
+---
+
+# Page title
+...
+```
+
+Setting an option to `#!yaml null` resets the option.
+
+### Layouts
+
+While it is possible and simple to build [custom layouts], the plugin ships
+several predefined layouts, all of which are prefixed with `default`. The
+following layouts are included:
+
+=== "`default`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default
+ ```
+
+
+
+ ![Layout default]
+
+ This layout sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ –
+
+ - [`font_family`][option.font_family]
+ –
+
+
+
+=== "`default/variant`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/variant
+ ```
+
+
+
+ ![Layout default variant]
+
+ This layout includes the [page icon] and sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ –
+
+ - [`font_family`][option.font_family]
+ –
+
+
+
+=== "`default/accent`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/accent
+ ```
+
+
+
+ ![Layout default accent]
+
+ This layout sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ –
+
+ - [`font_family`][option.font_family]
+ –
+
+
+
+=== "`default/invert`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/invert
+ ```
+
+
+
+ ![Layout default invert]
+
+ This layout sets the following defaults:
+
+ - [`color`][option.background_color]
+ –
+
+ - [`font_family`][option.font_family]
+ –
+
+
+
+=== "`default/only/image`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/only/image
+ cards_layout_options:
+ background_image: layouts/background.png
+
+ ```
+
+
+
+ This layout only shows the given background image and scales it to cover.
+
+
+
+The [`default` layouts][default layouts] are very flexible and comfortable to
+use, as they replicate the original behavior of the plugin, sourcing default
+values for all options from other `theme` settings.
+
+The following options are available:
+
+ [Layout default]: ../assets/screenshots/social-cards.png
+ [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+ [Layout default accent]: ../assets/screenshots/social-cards-accent.png
+ [Layout default invert]: ../assets/screenshots/social-cards-invert.png
+
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [page icon]: ../reference/index.md#setting-the-page-icon
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [font]: ../setup/changing-the-fonts.md#regular-font
+
+---
+
+####
+
+
+
+
+Use this option to change the background color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: "#ff1493" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: rgb(255, 20, 147) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: deeppink # (1)!
+ ```
+
+ 1. See the [``][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+If this options is used together with [`background_image`]
+[option.background_image], the color is rendered on top of the image which
+allows for tinting images. If you want to remove the background color, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ background_color: transparent
+```
+
+ [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names
+ [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+
+---
+
+####
+
+
+
+
+
+Use this option to define a background image for the generated social card. Note
+that the image is tinted with the [`background_color`][option.background_color],
+which can also be set to `transparent`:
+
+=== "Image"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: transparent
+ ```
+
+=== "Image with tint"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: "#ff149366"
+ ```
+
+The provided path is resolved from the root directory.
+
+---
+
+####
+
+
+
+
+Use this option to change the foreground color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: "#ffffff" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: rgb(255, 255, 255) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: white # (1)!
+ ```
+
+ 1. See the [``][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+---
+
+####
+
+
+
+
+Use this option to change the font family of the generated social card. The
+plugin automatically downloads the font from [Google Fonts], so the font must
+point to an existing Google Font:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_family: Ubuntu
+```
+
+When you've found a font that you like on [Google Fonts], you can just copy the
+name from the font's specimen page and use it as the value for this option –
+no further configuration needed.
+
+ [Google Fonts]: https://fonts.google.com/
+
+---
+
+####
+
+
+
+
+
+Use this option to change the logo that is used in the generated social card.
+By default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]
+[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ logo: layouts/logo.png
+```
+
+The provided path is resolved from the root directory.
+
+ [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image
+ [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled
+
+---
+
+####
+
+
+
+
+
+Use this option to change the title of the generated social card. This overrides
+the computed page title as assigned by MkDocs, as well as the [`title`]
+[meta.title] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ title: My custom title
+```
+
+ [meta.title]: ../reference/index.md#setting-the-page-title
+
+---
+
+####
+
+
+
+
+
+Use this option to change the description of the generated social card. This
+overrides the set [`site_description`][mkdocs.site_description], if defined, as
+well as the [`description`][meta.description] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ description: My custom description
+```
+
+ [meta.description]: ../reference/index.md#setting-the-page-description
+
+---
+
+!!! question "Missing something?"
+
+ When setting up social cards, you might discover that you're missing
+ specific functionality – we're happy to consider adding it to the plugin!
+ You can [open a discussion] to ask a question, or create a [change request]
+ on our [issue tracker], so we can find out if it might be a good fit for
+ the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/docs/plugins/tags.md b/docs/plugins/tags.md
new file mode 100644
index 000000000..176918d7a
--- /dev/null
+++ b/docs/plugins/tags.md
@@ -0,0 +1,376 @@
+---
+title: Built-in tags plugin
+icon: material/tag-text
+---
+
+# Built-in tags plugin
+
+The tags plugin adds first-class support for categorizing pages with the use
+of tags, adding the possibility to group related pages and make them
+discoverable via search and dedicated tags indexes. If your documentation is
+large, tags can help to discover relevant information faster.
+
+## Objective
+
+### How it works
+
+The plugin scans all pages for the [`tags`][meta.tags] metadata property and
+generates a tags index, which is an inverted list of tags and the pages they
+appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
+allowing for maximum flexibility when adding tags to your project.
+
+### When to use it
+
+If you want to add one or multiple tags indexes to your project, the tags
+plugin is a perfect choice as it makes this process ridiculously simple.
+Additionally, it integrates perfectly with several of the other
+[built-in plugins] that Material for MkDocs offers:
+
+
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags][meta.tags], so they can't be
+ forgotten when adding pages.
+
+ ---
+
+ __Simpler organization and management of tags in different subsections__
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The tags plugin allows to categorize posts alongside with pages in your
+ project, to improve their discoverability and connect posts to your
+ documentation.
+
+ ---
+
+ __Your documentation's tag system integrates with your blog__
+
+
+
+ [meta]: meta.md
+ [blog]: blog.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+
+
+
+
+As with all [built-in plugins], getting started with the tags plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start using
+[tags][meta.tags] to categorize your pages:
+
+``` yaml
+plugins:
+ - tags
+```
+
+The tags plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [tags]: tags.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - tags:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Tags
+
+The following settings are available for tags:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable handling of tags. Currently, the plugin's
+sole purpose is to process tags, so it's equivalent to the [`enabled`]
+[config.enabled] setting, but in the future, other features might be added.
+If you want to disable handling of tags, use:
+
+``` yaml
+plugins:
+ - tags:
+ tags: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to specify the location of the tags index, which is the page
+used to render a list of all tags and their associated pages. If this setting is
+specified, tags become clickable, pointing to the corresponding section in the
+tags index:
+
+``` yaml
+plugins:
+ - tags:
+ tags_file: tags.md
+```
+
+The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
+section of `mkdocs.yml`. This setting is not required – you should only use it
+if you want to have a tags index.
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the locations of additional tags indexes, which are
+pages that render a subset of the tags index, in order to provide scoped tags
+indexes for specific sections:
+
+``` yaml
+plugins:
+ - tags:
+ tags_extra_files:
+ extra-1.md: [tag-id-1, tag-id-2, ...]
+ extra-2.md: [tag-id-3, tag-id-4, ...]
+ ...
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the function to use for generating URL-compatible
+slugs from tags. [Python Markdown Extensions] comes with a Unicode-aware
+[`slugify`][pymdownx.slugs.slugify] function:
+
+=== "Unicode"
+
+ ``` yaml
+ plugins:
+ - tags:
+ tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+=== "Unicode, case-sensitive"
+
+ ``` yaml
+ plugins:
+ - tags:
+ tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ ```
+
+When your project features non-European languages, it's advisable to use this
+configuration. Of course, you can also provide a custom slugification function
+for more granular control.
+
+ [toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`tags_slugify`][config.tags_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_separator: _
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing tags. By default,
+tag comparison is case-sensitive, but you can use the `casefold` function
+for case-insensitive comparison:
+
+``` yaml
+plugins:
+ - tags:
+ tags_compare: !!python/name:material.plugins.tags.casefold
+```
+
+You can also define your own comparison function, which must return a string
+representing the tag, that is used for sorting, and reference it in
+[`tags_compare`][config.tags_compare].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_compare_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing pages. By default,
+pages occur in order of appearance, but you can sort them by using the following
+configuration:
+
+=== "Sort by page title"
+
+ ``` yaml
+ plugins:
+ - tags:
+ tags_pages_compare: !!python/name:material.plugins.tags.page_title
+ ```
+
+=== "Sort by page URL"
+
+ ``` yaml
+ plugins:
+ - tags:
+ tags_pages_compare: !!python/name:material.plugins.tags.page_url
+ ```
+
+You can also define your own comparison function, which must return a string
+representing the page, that is used for sorting, and reference it in
+[`tags_pages_compare`][config.tags_pages_compare].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which pages are sorted when comparing
+them. By default, pages are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_pages_compare_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+The plugin allows to check tags against a predefined list, in order to catch
+typos or make sure that tags are not arbitrarily added. Specify the tags you
+want to allow with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_allowed:
+ - HTML5
+ - JavaScript
+ - CSS
+```
+
+The plugin stops the build if a page references a tag that is not part of
+this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
+metadata property.
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a page with one or more tags, making the page
+appear in the generated tags index. Tags are defined as a list of strings
+(whitespaces are allowed):
+
+``` yaml
+---
+tags:
+ - HTML5
+ - JavaScript
+ - CSS
+---
+
+# Page title
+...
+```
+
+If you want to prevent accidental typos when assigning tags to pages, you can
+set a predefined list of allowed tags in `mkdocs.yml` by using the
+[`tags_allowed`][config.tags_allowed] setting.
diff --git a/docs/plugins/typeset.md b/docs/plugins/typeset.md
new file mode 100644
index 000000000..16528d10d
--- /dev/null
+++ b/docs/plugins/typeset.md
@@ -0,0 +1,82 @@
+---
+title: Built-in typeset plugin
+icon: 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. This means that code
+blocks, icons, emojis and any other inline formatting can be rendered exactly
+as defined in the page's content.
+
+## Objective
+
+### How it works
+
+When [building your project], MkDocs extracts the plain text from headlines and
+drops the original formatting. This is generally useful and a good idea, since
+this information is made available to other plugins that might have problems
+when being passed HTML instead of plain text.
+
+However, it also means that the entire formatting is lost.
+
+The plugin hooks into the rendering process, extracts the original headlines,
+and makes them available to be used in templates and plugins. The templates of
+Material for MkDocs use this information to render an enriched version of the
+navigation and table of contents.
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### When to use it
+
+It's generally recommended to use the plugin, because it is a drop-in solution
+that doesn't require any configuration and is designed to work out of the box.
+Since it doesn't overwrite but only adds information, it's not expected to
+interfere with other plugins.
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the typeset plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe the
+enriched navigation and table of contents:
+
+``` yaml
+plugins:
+ - typeset
+```
+
+The typeset plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [typeset]: typeset.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - typeset:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index 8172ddd69..87c139b9b 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -34,7 +34,7 @@ See additional configuration options:
### Admonition icons
-[:octicons-tag-24: 8.3.0][Admonition icons support]
+
Each of the supported admonition types has a distinct icon, which can be changed
to any icon bundled with the theme, or even a [custom icon]. Add the following
@@ -101,7 +101,6 @@ theme:
quote: fontawesome/solid/quote-left
```
- [Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[supported types]: #supported-types
[icon search]: icons-emojis.md#search
@@ -291,7 +290,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
type qualifiers are now all deprecated and will be removed in the next major
version. This will also be mentioned in the upgrade guide.
-[`note`](#type:note){ #type:note }
+
: !!! note
@@ -299,7 +298,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`abstract`](#type:abstract){ #type:abstract }
+
: !!! abstract
@@ -307,7 +306,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`info`](#type:info){ #type:info }
+
: !!! info
@@ -315,7 +314,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`tip`](#type:tip){ #type:tip }
+
: !!! tip
@@ -323,7 +322,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`success`](#type:success){ #type:success }
+
: !!! success
@@ -331,7 +330,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`question`](#type:question){ #type:question }
+
: !!! question
@@ -339,7 +338,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`warning`](#type:warning){ #type:warning }
+
: !!! warning
@@ -347,7 +346,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`failure`](#type:failure){ #type:failure }
+
: !!! failure
@@ -355,7 +354,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`danger`](#type:danger){ #type:danger }
+
: !!! danger
@@ -363,7 +362,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`bug`](#type:bug){ #type:bug }
+
: !!! bug
@@ -371,7 +370,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`example`](#type:example){ #type:example }
+
: !!! example
@@ -379,7 +378,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-[`quote`](#type:quote){ #type:quote }
+
: !!! quote
@@ -391,8 +390,8 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
### Classic admonitions
-Prior to version [:octicons-tag-24: 8.5.6][Admonition modern], admonitions had
-a slightly different appearance:
+Prior to version , admonitions had a slightly
+different appearance:
!!! classic "Note"
@@ -427,8 +426,6 @@ If you want to restore this appearance, add the following CSS to an
- stylesheets/extra.css
```
-[Admonition modern]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.6
-
### Custom admonitions
If you want to add a custom admonition type, all you need is a color and an
diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
index f625a9e54..2ee13c12b 100644
--- a/docs/reference/annotations.md
+++ b/docs/reference/annotations.md
@@ -33,7 +33,7 @@ See additional configuration options:
### Annotation icons
-[:octicons-tag-24: 9.2.0][Annotation icons support]
+
The annotation icon can be changed to any icon bundled with the theme, or even
a [custom icon], e.g. to material/arrow-right-circle:. Simply add the following
@@ -67,7 +67,6 @@ Some popular choices:
- :material-star-four-points-circle: - `material/star-four-points-circle`
- :material-plus-circle-outline: - `material/plus-circle-outline`
- [Annotation icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[icon search]: icons-emojis.md#search
@@ -75,8 +74,8 @@ Some popular choices:
### Using annotations
-[:octicons-tag-24: 9.2.0][Annotation support] ·
-:octicons-beaker-24: Experimental
+
+
Annotations consist of two parts: a marker, which can be placed anywhere in
a block marked with the `annotate` class, and content located in a list below
@@ -104,8 +103,6 @@ Note that the `annotate` class must only be added to the outermost block. All
nested elements can use the same list to define annotations, except when
annotations are nested themselves.
- [Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
-
#### in annotations
When [SuperFences] is enabled, annotations can be nested inside annotations by
@@ -208,7 +205,7 @@ of a dedicated content tab (and not to the container, which is not supported):
#### in everything else
-The [Attribute Lists] extension is the key ingredient for adding annotations to
+The [Attribute Lists] extension is the key ingredient for adding annotations to
most elements, but it has some [limitations]. However, it's always possible to
leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
`div` with the `annotate` class:
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 0e36630b7..efc32cba0 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -13,8 +13,8 @@ during runtime using a JavaScript syntax highlighter.
## Configuration
-This configuration enables syntax highlighting on code blocks and inline code
-blocks, and allows to include source code directly from other files. Add the
+This configuration enables syntax highlighting on code blocks and inline code
+blocks, and allows to include source code directly from other files. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -46,8 +46,8 @@ See additional configuration options:
### Code copy button
-[:octicons-tag-24: 9.0.0][Code copy button support] ·
-:octicons-unlock-24: Feature flag
+
+
Code blocks can automatically render a button on the right side to allow the
user to copy a code block's contents to the clipboard. Add the following to
@@ -59,8 +59,6 @@ theme:
- content.code.copy
```
- [Code copy button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
??? info "Enabling or disabling code copy buttons for a specific code block"
If you don't want to enable code copy buttons globally, you can enable them
@@ -73,7 +71,7 @@ theme:
```
````
- Note that the language shortcode which has to come first must now also be
+ Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the copy button can also be disabled for a
specific code block:
@@ -85,9 +83,9 @@ theme:
### Code selection button
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.32.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Code blocks can include a button to allow for the selection of line ranges by
the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
@@ -101,8 +99,8 @@ theme:
??? info "Enabling or disabling code selection buttons for a specific code block"
- If you don't want to enable code selection buttons globally, you can enable
- them for a specific code block by using a slightly different syntax based on
+ If you don't want to enable code selection buttons globally, you can enable
+ them for a specific code block by using a slightly different syntax based on
the [Attribute Lists] extension:
```` yaml
@@ -111,7 +109,7 @@ theme:
```
````
- Note that the language shortcode which has to come first must now also be
+ Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the selection button can also be disabled for
a specific code block:
@@ -121,13 +119,12 @@ theme:
```
````
- [Insiders]: ../insiders/index.md
[line highlighting]: #highlighting-specific-lines
### Code annotations
-[:octicons-tag-24: 8.0.0][Code annotations support] ·
-:octicons-unlock-24: Feature flag
+
+
Code annotations offer a comfortable and friendly way to attach arbitrary
content to specific sections of code blocks by adding numeric markers in block
@@ -156,21 +153,20 @@ theme:
```
````
- Note that the language shortcode which has to come first must now also be
+ Note that the language shortcode which has to come first must now also be
prefixed by a `.`.
- [Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
#### Custom selectors
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.32.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Normally, code annotations can only be [placed in comments], as comments can be
considered safe for placement. However, sometimes it might be necessary to place
-annotations in parts of the code block where comments are not allowed, e.g. in
+annotations in parts of the code block where comments are not allowed, e.g. in
strings.
Additional selectors can be set per-language:
@@ -292,8 +288,8 @@ theme:
#### Stripping comments
-[:octicons-tag-24: 8.5.0][Stripping comments support] ·
-:octicons-beaker-24: Experimental
+
+
If you wish to strip the comment characters surrounding a code annotation,
simply add an `!` after the closing parenthesis of the code annotation:
@@ -320,8 +316,6 @@ Note that this only allows for a single code annotation to be rendered per
comment. If you want to add multiple code annotations, comments cannot be
stripped for technical reasons.
- [Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-
### Adding line numbers
Line numbers can be added to a code block by using the `linenums=""`
@@ -552,12 +546,11 @@ This will render annotations with a larger width:
### Annotations with numbers
-Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
-were rendered with markers showing the original number as used by the author.
-However, for technical reasons code annotation numbers restart each code block,
-which might lead to confusion. For this reason, code annotations now render as
-`+` signs which are rotated if they're open to denote that clicking them again
-will close them.
+Prior to , code annotations were rendered with markers
+showing the original number as used by the author. However, for technical
+reasons code annotation numbers restart each code block, which might lead to
+confusion. For this reason, code annotations now render as `+` signs which are
+rotated if they're open to denote that clicking them again will close them.
If you wish to revert to the prior behavior and display code annotation numbers,
you can add an [additional style sheet] and copy and paste the following CSS:
@@ -579,5 +572,3 @@ you can add an [additional style sheet] and copy and paste the following CSS:
extra_css:
- stylesheets/extra.css
```
-
- [code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index fc01226d7..5d08715ee 100644
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@@ -12,14 +12,14 @@ grouping code blocks and other content.
## Configuration
This configuration enables content tabs, and allows to nest arbitrary content
-inside content tabs, including code blocks and ... more content tabs! Add the
+inside content tabs, including code blocks and ... more content tabs! Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
- alternate_style: true
+ alternate_style: true
```
See additional configuration options:
@@ -32,9 +32,9 @@ See additional configuration options:
### Anchor links
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.17.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
In order to link to content tabs and share them more easily, [Insiders] adds
an anchor link to each content tab automatically, which you can copy via right
@@ -66,7 +66,6 @@ or to the [publishing guide for Insiders][tab_2].
Fore more information, please [see the extension guide][slugification].
- [Insiders]: ../insiders/index.md
[tab_1]: #-or-even-me
[tab_2]: ../publishing-your-site.md#insiders
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
@@ -74,11 +73,11 @@ or to the [publishing guide for Insiders][tab_2].
### Linked content tabs
-[:octicons-tag-24: 8.3.0][Linked content tabs support] ·
-:octicons-unlock-24: Feature flag
+
+
When enabled, all content tabs across the whole documentation site will be
-linked and switch to the same label when the user clicks on a tab. Add the
+linked and switch to the same label when the user clicks on a tab. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -100,7 +99,6 @@ integrated with [instant loading] and persisted across page loads.
[![Linked content tabs disabled]][Linked content tabs disabled]
- [Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
[Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md
index a3eb157c2..fd2db1bf1 100644
--- a/docs/reference/data-tables.md
+++ b/docs/reference/data-tables.md
@@ -10,7 +10,7 @@ like [sortable tables] can be achieved with a third-party library and some
[additional JavaScript].
[sortable tables]: #sortable-tables
- [additional JavaScript]: ../customization.md#additional-javascript
+ [additional JavaScript]: ../customization.md#additional-javascript
## Configuration
@@ -185,147 +185,7 @@ numbers, filesizes, dates and month names. See the [tablesort documentation]
### Import table from file
-[:octicons-cpu-24: Plugin][table-reader-docs]
+The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
+import data from a CSV or Excel file.
-You can also import data from a CSV or Excel file using the plugin [`mkdocs-table-reader-plugin`][table-reader-docs].
-
-First, you will need to install it with `pip`:
-
-```sh
-pip install mkdocs-table-reader-plugin
-```
-
-Then extend the `mkdocs.yml` file like this:
-
-```yaml
-plugins:
- - table-reader
-```
-
-Then, it is a simple process to import the data in to the Markdown files.
-
-=== "Import data from :fontawesome-solid-file-csv: CSV file"
-
- Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this:
-
- ```csv title="./data.csv"
- col1,col2,col3
- r1c1,r1c2,r1c3
- r2c1,r2c2,r2c3
- r3c1,r3c2,r3c3
- ```
-
- You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
-
- ```md title="./markdown.md"
- ...
-
- {{ read_csv('./data.csv') }}
-
- ...
- ```
-
-
-
- ...
-
- col1|col2|col3
- ----|----|----
- r1c1|r1c2|r1c3
- r2c1|r2c2|r2c3
- r3c1|r3c2|r3c3
-
- ...
-
-
-
-=== "Import data from :fontawesome-solid-file-excel: Excel file"
-
- Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this:
-
- ![][excel-file]{width="300px"}
-
- [excel-file]: https://i.stack.imgur.com/f32ks.png
-
- And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
-
- ```md title="./markdown.md"
- ...
-
- {{ read_excel('./Book1.xlsx', engine='openpyxl') }}
-
- ...
- ```
-
-
-
- It will then return a result like this:
-
- col1|col2|col3
- ----|----|----
- r1c1|r1c2|r1c3
- r2c1|r2c2|r2c3
- r3c1|r3c2|r3c3
-
-
-
- !!! warning "Warning"
-
- You may receive an error if you use `engine='openpyxl'`.
-
- If this happens, you can resolve it by installing it using `pip`:
-
- ```sh
- pip install openpyxl
- ```
-
- Read more here: [pandas.read_excel][pandas-read_excel-engine]
-
- [pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None
-
- !!! tip "Pro Tip: Multiple Sheets"
-
- If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter.
-
- It would look like this:
-
- ```md title="./markdown.md"
- ...
-
- {{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }}
-
- ...
- ```
-
- By default, Pandas will grab the first sheet in the workbook.
-
- Read more here: [pandas.read_excel][pandas-read_excel-sheet_name]
-
- [pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200
-
-=== "Import data from other file types"
-
- The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats:
-
-
-
- - [`read_csv`][table-reader-read_csv]
- - [`read_fwf`][table-reader-read_fwf]
- - [`read_yaml`][table-reader-read_yaml]
- - [`read_table`][table-reader-read_table]
- - [`read_json`][table-reader-read_json]
- - [`read_excel`][table-reader-read_excel]
- - [`read_raw`][table-reader-read_raw]
-
-
-
- You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs]
-
-[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
-[table-reader-read_csv]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_csv
-[table-reader-read_fwf]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_fwf
-[table-reader-read_yaml]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_yaml
-[table-reader-read_table]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_table
-[table-reader-read_json]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_json
-[table-reader-read_excel]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_excel
-[table-reader-read_raw]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_raw
+ [table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md
index dfbf38e8c..a336391d8 100644
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@@ -13,7 +13,7 @@ popular and flexible solution for drawing diagrams.
## Configuration
-[:octicons-tag-24: 8.2.0][Diagrams support]
+
This configuration enables native support for [Mermaid.js] diagrams. Material
for MkDocs will automatically initialize the JavaScript runtime when a page
@@ -42,7 +42,6 @@ No further configuration is necessary. Advantages over a custom integration:
diagrams. See the section on [other diagrams] for more information why this
is currently not implemented for all diagrams.
- [Diagrams support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[additional style sheets]: ../customization.md#additional-css
[other diagrams]: #other-diagram-types
diff --git a/docs/reference/grids.md b/docs/reference/grids.md
index 021394d3f..46b9f0e1b 100644
--- a/docs/reference/grids.md
+++ b/docs/reference/grids.md
@@ -45,15 +45,14 @@ elements in a rectangular shape.
### Using card grids
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.12.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Card grids wrap each grid item with a beautiful hover card that levitates on
hover. They come in two slightly different syntaxes: [list] and [block syntax],
adding support for distinct use cases.
- [Insiders]: ../insiders/index.md
[list]: #list-syntax
[block syntax]: #block-syntax
@@ -98,7 +97,7 @@ includes icons and links:
Install [`mkdocs-material`](#) with [`pip`](#) and get up
and running in minutes
-
+
[:octicons-arrow-right-24: Getting started](#)
- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -106,7 +105,7 @@ includes icons and links:
---
Focus on your content and generate a responsive and searchable static site
-
+
[:octicons-arrow-right-24: Reference](#)
- :material-format-font:{ .lg .middle } __Made to measure__
@@ -114,7 +113,7 @@ includes icons and links:
---
Change the colors, fonts, language, icons, logo and more with a few lines
-
+
[:octicons-arrow-right-24: Customization](#)
- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -137,7 +136,7 @@ includes icons and links:
Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
and running in minutes
-
+
[:octicons-arrow-right-24: Getting started][getting started]
- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -145,7 +144,7 @@ includes icons and links:
---
Focus on your content and generate a responsive and searchable static site
-
+
[:octicons-arrow-right-24: Reference][reference]
- :material-format-font:{ .lg .middle } __Made to measure__
@@ -153,7 +152,7 @@ includes icons and links:
---
Change the colors, fonts, language, icons, logo and more with a few lines
-
+
[:octicons-arrow-right-24: Customization][customization]
- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -227,9 +226,9 @@ to the grid.
### Using generic grids
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.12.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Generic grids allow for arranging arbitrary block elements in a grid, including
[admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks
diff --git a/docs/reference/images.md b/docs/reference/images.md
index c13cf86ee..a9009258d 100644
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@@ -4,8 +4,8 @@ icon: material/image-frame
# Images
-While images are first-class citizens of Markdown and part of the core syntax,
-it can be difficult to work with them. Material for MkDocs makes working with
+While images are first-class citizens of Markdown and part of the core syntax,
+it can be difficult to work with them. Material for MkDocs makes working with
images more comfortable, providing styles for image alignment and image
captions.
@@ -31,10 +31,10 @@ See additional configuration options:
### Lightbox
-[:octicons-tag-24: 0.1.0][Lightbox support] ·
-[:octicons-cpu-24: Plugin][glightbox]
+
+
-If you want to add image zoom functionality to your documentation, the
+If you want to add image zoom functionality to your documentation, the
[glightbox] plugin is an excellent choice, as it integrates perfectly
with Material for MkDocs. Install it with `pip`:
@@ -52,7 +52,6 @@ plugins:
We recommend checking out the available
[configuration options][glightbox options].
- [Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[glightbox]: https://github.com/blueswen/mkdocs-glightbox
[glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
@@ -154,7 +153,7 @@ browsers without support:
### Light and dark mode
-[:octicons-tag-24: 8.1.1][Light and dark mode support]
+
If you added a [color palette toggle] and want to show different images for
light and dark color schemes, you can append a `#only-light` or `#only-dark`
@@ -200,7 +199,6 @@ hash fragment to the image URL:
Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
name of your scheme.
- [Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
[color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
[Zelda light world]: ../assets/images/zelda-light-world.png#only-light
[Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 13e74e6be..ccecf2a74 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -7,75 +7,13 @@ within Markdown files.
## Configuration
-### Built-in typeset plugin
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.27.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
-
-The built-in typeset plugin __preserves HTML formatting__ in the navigation and
-table of contents. This means that now, code blocks, icons, emojis and other
-inline formatting will be preserved, which allows for a richer editing
-experience. Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
- - typeset
-```
-
-For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: – code blocks and icons are preserved from the
-section headlines; even [highlighting inline code blocks] is supported :tada:
-
- [highlighting inline code blocks]: code-blocks.md#highlighting-inline-code-blocks
-
-### Built-in meta plugin
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.21.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
-
-The built-in meta plugin allows to __set front matter per folder__, which is
-especially handy to ensure that all pages in a folder use specific templates or
-tags. Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
- - meta
-```
-
-> If you need to be able to build your documentation with and without
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
-
-The following configuration options are available:
-
-[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
-
-: :octicons-milestone-24: Default: `.meta.yml` – This option specifies the
- name of the meta files that the plugin should look for. The default setting
- assumes that meta files are called `.meta.yml`:
-
- ``` yaml
- plugins:
- - meta:
- meta_file: .meta.yml # (1)!
- ```
-
- 1. Note that it's strongly recommended to prefix meta files with a `.`,
- since otherwise they would be included in the build output.
-
- [built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin
- [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-
## Usage
### Setting the page `title`
-Each page has a designated title, which is used in the navigation sidebar, for
-[social cards] and in other places. While MkDocs attempts to automatically
-determine the title of a page in a [four step process], the title can also be
+Each page has a designated title, which is used in the navigation sidebar, for
+[social cards] and in other places. While MkDocs attempts to automatically
+determine the title of a page in a [four step process], the title can also be
explicitly set with the front matter `title` property:
``` yaml
@@ -83,7 +21,7 @@ explicitly set with the front matter `title` property:
title: Lorem ipsum dolor sit amet # (1)!
---
-# Document title
+# Page title
...
```
@@ -101,7 +39,7 @@ title: Lorem ipsum dolor sit amet # (1)!
### Setting the page `description`
A Markdown file can include a description that is added to the `meta` tags of
-a page, and is also used for [social cards]. It's a good idea to set a
+a page, and is also used for [social cards]. It's a good idea to set a
[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
the author does not explicitly define a description for a Markdown file:
@@ -110,7 +48,7 @@ the author does not explicitly define a description for a Markdown file:
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
---
-# Document title
+# Page title
...
```
@@ -121,8 +59,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
### Setting the page `icon`
-[:octicons-tag-24: 9.2.0][Page icon support] ·
-:octicons-beaker-24: Experimental
+
+
An icon can be assigned to each page, which is then rendered as part of the
navigation sidebar, as well as [navigation tabs], if enabled. Use the front
@@ -134,7 +72,7 @@ top of a Markdown file:
icon: material/emoticon-happy # (1)!
---
-# Document title
+# Page title
...
```
@@ -149,18 +87,17 @@ icon: material/emoticon-happy # (1)!
- [Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[Insiders]: ../insiders/index.md
[icon search]: icons-emojis.md#search
[navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
### Setting the page `status`
-[:octicons-tag-24: 9.2.0][Page status support] ·
-:octicons-beaker-24: Experimental
+
+
A status can be assigned to each page, which is then displayed as part of the
-navigation sidebar. First, associate a status identifier with a description by
+navigation sidebar. First, associate a status identifier with a description by
adding the following to `mkdocs.yml`:
``` yaml
@@ -180,7 +117,7 @@ extra:
```
The page status can now be set with the front matter `status` property. For
-example, you can mark a page as `new` with the following lines at the top of a
+example, you can mark a page as `new` with the following lines at the top of a
Markdown file:
``` yaml
@@ -188,7 +125,7 @@ Markdown file:
status: new
---
-# Document title
+# Page title
...
```
@@ -197,13 +134,11 @@ The following status identifiers are currently supported:
- :material-alert-decagram: – `new`
- :material-trash-can: – `deprecated`
- [Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
-
### Setting the page `subtitle`
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.25.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Each page can define a subtitle, which is then rendered below the title as part
of the navigation sidebar by using the front matter `subtitle` property, and
@@ -214,14 +149,14 @@ adding the following lines:
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---
-# Document title
+# Page title
...
```
### Setting the page `template`
If you're using [theme extension] and created a new page template in the
-`overrides` directory, you can enable it for a specific page. Add the following
+`overrides` directory, you can enable it for a specific page. Add the following
lines at the top of a Markdown file:
``` yaml
@@ -229,7 +164,7 @@ lines at the top of a Markdown file:
template: custom.html
---
-# Document title
+# Page title
...
```
@@ -244,7 +179,7 @@ template: custom.html
```
[theme extension]: ../customization.md#extending-the-theme
- [built-in meta plugin]: #built-in-meta-plugin
+ [built-in meta plugin]: ../plugins/meta.md
## Customization
diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md
index de9c4a7d8..75ea532b2 100644
--- a/docs/reference/tooltips.md
+++ b/docs/reference/tooltips.md
@@ -35,9 +35,9 @@ See additional configuration options:
### Improved tooltips
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.15.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
When improved tooltips are enabled, Material for MkDocs replaces the browser's
rendering logic for `title` attribute with beautiful little tooltips.
@@ -55,14 +55,12 @@ Now, tooltips will be rendered for the following elements:
- __Header__ – home button, header title, color palette switch and repository link
- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
-[Insiders]: ../insiders/index.md
-
## Usage
### Adding tooltips
The [Markdown syntax] allows to specify a `title` for each link, which will
-render as a beautiful tooltip when [improved tooltips] are enabled. Add a
+render as a beautiful tooltip when [improved tooltips] are enabled. Add a
tooltip to a link with the following lines:
``` markdown title="Link with tooltip, inline syntax"
@@ -107,7 +105,7 @@ extension:
### Adding abbreviations
-Abbreviations can be defined by using a special syntax similar to URLs and
+Abbreviations can be defined by using a special syntax similar to URLs and
[footnotes], starting with a `*` and immediately followed by the term or
acronym to be associated in square brackets:
@@ -137,7 +135,7 @@ pages with the following configuration:
[^1]:
It's highly recommended to put the Markdown file containing the
- abbreviations outside of the `docs` folder (here, a folder with the name
+ abbreviations outside of the `docs` folder (here, a folder with the name
`includes` is used), as MkDocs might otherwise complain about an
unreferenced file.
diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md
index 9fad62546..635848d5f 100644
--- a/docs/setup/adding-a-comment-system.md
+++ b/docs/setup/adding-a-comment-system.md
@@ -93,7 +93,7 @@ property to `true`:
comments: true
---
-# Document title
+# Page title
...
```
diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md
index 735df7033..c4597b650 100644
--- a/docs/setup/adding-a-git-repository.md
+++ b/docs/setup/adding-a-git-repository.md
@@ -9,8 +9,8 @@ static site, including stars and forks. Furthermore, the
### Repository
-[:octicons-tag-24: 0.1.0][Repository support] ·
-:octicons-milestone-24: Default: _none_
+
+
In order to display a link to the repository of your project as part of your
documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
@@ -29,20 +29,18 @@ GitHub repositories also include the tag of the latest release.[^1]
[^1]:
Unfortunately, GitHub only provides an API endpoint to obtain the [latest
- release] - not the latest tag. Thus, make sure to [create a release] (not
+ release] - not the latest tag. Thus, make sure to [create a release] (not
pre-release) for the latest tag you want to display next to the number of
stars and forks.
- [Repository support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
[latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
[create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
#### Repository name
-[:octicons-tag-24: 0.1.0][Repository name support] ·
-:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
-`Bitbucket`
+
+
MkDocs will infer the source provider by examining the URL and try to set the
_repository name_ automatically. If you wish to customize the name, set
@@ -52,14 +50,12 @@ _repository name_ automatically. If you wish to customize the name, set
repo_name: squidfunk/mkdocs-material
```
- [Repository name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
#### Repository icon
-[:octicons-tag-24: 5.0.0][Repository icon support] ·
-:octicons-milestone-24: Default:
-:fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
+
+
While the default repository icon is a generic git icon, it can be set to
any icon bundled with the theme by referencing a valid icon path in
@@ -93,14 +89,12 @@ Some popular choices:
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
- [Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
- [Repository icon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
[icon search]: ../reference/icons-emojis.md#search
#### Code actions
-[:octicons-tag-24: 9.0.0][Code actions support] ·
-:octicons-unlock-24: Feature flag
+
+
If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
@@ -152,7 +146,6 @@ theme:
- [Code actions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
[repository URL]: #repository
[GitHub]: https://github.com/
[GitLab]: https://about.gitlab.com/
@@ -172,8 +165,8 @@ links to all [contributors] or [authors] involved.
#### Document dates
-[:octicons-tag-24: 4.6.0][Document dates support] ·
-[:octicons-cpu-24: Plugin][git-revision-date-localized]
+
+
The [git-revision-date-localized] plugin adds support for adding the date of
last update and creation of a document at the bottom of each page. Install it
@@ -193,9 +186,9 @@ plugins:
The following configuration options are supported:
-[`enabled`](#+git-revision-date-localized.enabled){ #+git-revision-date-localized.enabled }
+
-: :octicons-milestone-24: Default: `true` – This option specifies whether
+: This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, e.g. for local builds, use an [environment variable]:
@@ -205,9 +198,9 @@ The following configuration options are supported:
enabled: !ENV [CI, false]
```
-[`type`](#+git-revision-date-localized.type){ #+git-revision-date-localized.type }
+
-: :octicons-milestone-24: Default: `date` – The format of the date to be
+: The format of the date to be
displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
and `timeago`:
@@ -217,9 +210,9 @@ The following configuration options are supported:
type: date
```
-[`enable_creation_date`](#+git-revision-date-localized.enable_creation_date){ #+git-revision-date-localized.enable_creation_date }
+
-: :octicons-milestone-24: Default: `false` – Enables the display of the
+: Enables the display of the
creation date of the file associated with the page next to the last updated
date at the bottom of the page:
@@ -229,12 +222,9 @@ The following configuration options are supported:
enable_creation_date: true
```
- !!! note
- If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code. For more information, see [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments).
+
-[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date }
-
-: :octicons-milestone-24: Default: `false` – Enables falling back to
+: Enables falling back to
the time when `mkdocs build` was executed. Can be used as a fallback when
the build is performed outside of a git repository:
@@ -248,15 +238,14 @@ The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
- [Document dates support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
#### Document contributors
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.19.0][Insiders] ·
-[:octicons-cpu-24: Plugin][git-committers] ·
-:octicons-beaker-24: Experimental
+
+
+
+
The [git-committers][^2] plugin renders the GitHub avatars of all contributors,
linking to their GitHub profiles at the bottom of each page. As always, it can
@@ -283,9 +272,9 @@ plugins:
The following configuration options are supported:
-[`enabled`](#+git-committers.enabled){ #+git-committers.enabled }
+
-: :octicons-milestone-24: Default: `true` – This option specifies whether
+: This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, e.g. for local builds, use an [environment variable]:
@@ -295,9 +284,9 @@ The following configuration options are supported:
enabled: !ENV [CI, false]
```
-[`repository`](#+git-committers.repository){ #+git-committers.repository }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must be set to the slug of the repository that contains your
documentation. The slug must follow the pattern `/`:
@@ -307,9 +296,9 @@ The following configuration options are supported:
repository: squidfunk/mkdocs-material
```
-[`branch`](#+git-committers.branch){ #+git-committers.branch }
+
-: :octicons-milestone-24: Default: `master` – This property should be set to
+: This property should be set to
the branch of the repository from which to retrieve the contributors. To use the `main` branch:
``` yaml
@@ -329,10 +318,10 @@ them at your own risk.
#### Document authors
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.19.0][Insiders] ·
-[:octicons-cpu-24: Plugin][git-authors] ·
-:octicons-beaker-24: Experimental
+
+
+
+
The [git-authors] plugin is a lightweight alternative to the
[git-committers] plugin and extracts the authors of a document from git to display
diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md
index d75a9370c..12d3cf75c 100644
--- a/docs/setup/building-an-optimized-site.md
+++ b/docs/setup/building-an-optimized-site.md
@@ -11,10 +11,10 @@ further useful automatic optimization techniques.
### Built-in projects plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.38.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
+
The built-in projects plugin allows to split your documentation into multiple
distinct MkDocs projects, __build them concurrently__ and
@@ -25,31 +25,10 @@ plugins:
- projects
```
-Next, create a folder called `projects` in your root directory which will
-contain all projects. For example, if we want to build a project with two
-additional languages, we can use:
+For a list of all settings, please consult the [plugin documentation].
-``` { .sh .no-copy }
-.
-├─ projects/
-│ ├─ de/
-│ │ ├─ docs/
-│ │ └─ mkdocs.yml
-│ └─ fr/
-│ ├─ docs/
-│ └─ mkdocs.yml
-└─ mkdocs.yml
-```
-
-If you now invoke `mkdocs serve` and change a file in one of the projects,
-the projects plugin makes sure that MkDocs will also reload those files. Note
-that the projects are currently entirely separate, which means they will have
-separate search indexes and sitemaps. We're happy to receive feedback on this
-plugin and learn about your requirements to make it better, as we plan to add
-support for merging and hoisting files.
-[Create a discussion to share your thoughts!][discussion]
-
- [discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [projects]: ../plugins/projects.md
+ [plugin documentation]: ../plugins/projects.md
??? info "Use cases for the projects plugin"
@@ -63,89 +42,12 @@ support for merging and hoisting files.
so that we can improve it together with our users and make it even more
powerful as we discover new use cases.
-The following configuration options are available:
-
-[`enabled`](#+projects.enabled){ #+projects.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - projects:
- enabled: !ENV [CI, false]
- ```
-
-[`concurrency`](#+projects.concurrency){ #+projects.concurrency }
-
-: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
- how many CPUs the plugin is allowed to use when building projects.
- With more CPUs, the plugin can do more work in the same time, thus complete
- optimization faster. Concurrent processing can be disabled with:
-
- ``` yaml
- plugins:
- - projects:
- concurrency: 1
- ```
-
-#### Projects
-
-The following configuration options are available for projects:
-
-[`projects`](#+projects.projects){ #+projects.projects }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- to build nested projects. If you want to switch the plugin off, e.g.
- for local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - projects:
- projects: !ENV [CI, false]
- ```
-
-[`projects_dir`](#+projects.projects_dir){ #+projects.projects_dir }
-
-: :octicons-milestone-24: Default: `projects` – This option specifies the
- name of the folder the plugin expects your projects to be stored. While it's
- usually not necessary to change this option, change it with:
-
- ``` yaml
- plugins:
- - projects:
- projects_dir: path/to/folder
- ```
-
-#### Hoisting
-
-The following configuration options are available for hoisting:
-
-[`hoisting`](#+projects.hoisting){ #+projects.hoisting }
-
-: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
- Default: `true` – This option specifies whether the plugin should hoist all
- themes files to the top-level project. If you disable this setting, each
- project will have a copy of the themes files, which in general, can be
- considered redundant:
-
- ``` yaml
- plugins:
- - projects:
- hoisting: false
- ```
-
- It's generally advisable to enable hoisting, as it leads to faster
- deployments and faster loading of your project's sites, because the files
- are the same for all projects.
-
### Built-in optimize plugin
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.29.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
+
The built-in optimize plugin automatically identifies and optimizes all media
files as part of the build using compression and conversion techniques. Add
@@ -156,177 +58,6 @@ plugins:
- optimize # (1)!
```
-1. Please ensure that all [dependencies for image processing] are installed,
- or the plugin will not work properly.
+For a list of all settings, please consult the [plugin documentation][optimize].
-> If you need to be able to build your documentation with and without
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
-
-The following configuration options are available:
-
-[`enabled`](#+optimize.enabled){ #+optimize.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - optimize:
- enabled: !ENV [CI, false]
- ```
-
-[`concurrency`](#+optimize.concurrency){ #+optimize.concurrency }
-
-: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
- how many CPUs the plugin is allowed to use when optimizing media files.
- With more CPUs, the plugin can do more work in the same time, thus complete
- optimization faster. Concurrent processing can be disabled with:
-
- ``` yaml
- plugins:
- - optimize:
- concurrency: 1
- ```
-
-#### Optimization
-
-Technical documentation often includes screenshots or diagrams, both of which
-are prime candidates for compression. The [built-in optimize plugin] allows to
-automatically compress images using [pngquant] (for PNGs), and [Pillow]
-(for JPGs).
-
-The following configuration options are available for optimization:
-
-[`optimize_png`](#+optimize.optimize_png){ #+optimize.optimize_png }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin should optimize PNG files using [pngquant], which must be
- installed on the system. PNG optimization can be disabled with:
-
- ``` yaml
- plugins:
- - optimize:
- optimize_png: false
- ```
-
-[`optimize_png_speed`](#+optimize.optimize_png_speed){ #+optimize.optimize_png_speed }
-
-: :octicons-milestone-24: Default: `4` of `[1,10]` – This option specifies the
- speed/quality tradeoff that [pngquant] applies when compressing. The lower
- the number, the more time will be spent optimizing:
-
- === "Slower small "
-
- ``` yaml
- plugins:
- - optimize:
- optimize_png_speed: 1
- ```
-
- === "Faster rough "
-
- ``` yaml
- plugins:
- - optimize:
- optimize_png_speed: 10
- ```
-
- A factor of `10` has 5% lower quality, but is 8x faster than the default `4`.
-
-[`optimize_png_strip`](#+optimize.optimize_png_strip){ #+optimize.optimize_png_strip }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- [pngquant] should remove all non-optional metadata that is not necessary
- for rendering images in a browser:
-
- ``` yaml
- plugins:
- - optimize:
- optimize_png_strip: false
- ```
-
-[`optimize_jpg`](#+optimize.optimize_jpg){ #+optimize.optimize_jpg }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin should optimize JPG files using [Pillow], a Python image
- processing library. JPG optimization can be disabled with:
-
- ``` yaml
- plugins:
- - optimize:
- optimize_jpg: false
- ```
-
-[`optimize_jpg_quality`](#+optimize.optimize_jpg_quality){ #+optimize.optimize_jpg_quality }
-
-: :octicons-milestone-24: Default: `60` of `[0,100]` – This option specifies
- the image quality that [Pillow] uses when compressing. If the images look
- blurry, it's a good idea to tune and change this setting:
-
- ``` yaml
- plugins:
- - optimize:
- optimize_jpg_quality: 75
- ```
-
-[`optimize_jpg_progressive`](#+optimize.optimize_jpg_progressive){ #+optimize.optimize_jpg_progressive }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- [Pillow] should use [progressive encoding] (faster rendering) when
- compressing JPGs. Progressive encoding can be disabled with:
-
- ``` yaml
- plugins:
- - optimize:
- optimize_jpg_progressive: false
- ```
-
- [Insiders]: ../insiders/index.md
- [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
- [dependencies for image processing]: dependencies/image-processing.md
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
- [pngquant]: https://pngquant.org/
- [Pillow]: https://pillow.readthedocs.io/
- [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
-
-#### Caching
-
-The [built-in optimize plugin] implements an intelligent caching mechanism,
-ensuring that media files are only pushed through the optimization pipeline when
-their contents change. If you swap out or update an image, the plugin will
-detect it and update the optimized version.
-
-The following configuration options are available for caching:
-
-[`cache`](#+optimize.cache){ #+optimize.cache }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin queries its cache for an existing artifact before starting an
- optimization job. It's normally not necessary to change this setting,
- except for when debugging the plugin itself. Caching can be disabled with:
-
- ``` yaml
- plugins:
- - optimize:
- cache: false
- ```
-
-[`cache_dir`](#+optimize.cache_dir){ #+optimize.cache_dir }
-
-: :octicons-milestone-24: Default: `.cache/plugins/optimize` – This option
- specifies the file system location of the plugin's cache. It's normally not
- necessary to change this setting, except for when debugging the plugin
- itself. The cache directory can be changed with:
-
- ``` yaml
- plugins:
- - optimize:
- cache_dir: .cache/plugins/optimize
- ```
-
- By default, all built-in plugins that implement caching will create a
- `.cache` directory in the same folder your `mkdocs.yml` resides, and create
- subfolders to not interfere with each other. If you use multiple instances
- of this plugin, it could be necessary to change this setting.
+ [optimize]: ../plugins/optimize.md
diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md
index 1af2e375a..54a3987c6 100644
--- a/docs/setup/building-for-offline-usage.md
+++ b/docs/setup/building-for-offline-usage.md
@@ -11,8 +11,8 @@ support for many of its features.
### Built-in offline plugin
-[:octicons-tag-24: 9.0.0][offline support] ·
-:octicons-cpu-24: Plugin
+
+
The built-in offline plugin makes sure that the [site search] works when you
distribute the contents of your [site directory] as a download. Simply add
@@ -23,27 +23,10 @@ plugins:
- offline
```
-The plugin will automatically disable the [`use_directory_urls`][use_directory_urls]
-setting, ensuring that users can open your documentation directly from the local
-file system.
+For a list of all settings, please consult the [plugin documentation].
-The following configuration options are available:
-
-[`enabled`](#+offline.enabled){ #+offline.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to switch
- the plugin off, e.g. for local builds, use an [environment variable]:
-
- ``` yaml
- plugins:
- - offline:
- enabled: !ENV [OFFLINE, false]
- ```
-
-Now, after invoking `mkdocs build`, you can open `site/index.html` directly
-in your browser and the [site search] will work as if the documentation was
-hosted on a regular server.
+ [offline]: ../plugins/offline.md
+ [plugin documentation]: ../plugins/offline.md
!!! tip "Automatically bundle all external assets"
@@ -51,11 +34,8 @@ hosted on a regular server.
while building documentation for offline usage, as it will automatically
download all external assets to distribute them with your documentation.
- [offline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
[site search]: setting-up-site-search.md
[site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
- [use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
#### Limitations
diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md
index af16f0d7b..dd8f510b8 100644
--- a/docs/setup/changing-the-colors.md
+++ b/docs/setup/changing-the-colors.md
@@ -1,7 +1,7 @@
# Changing the colors
As any proper Material Design implementation, Material for MkDocs supports
-Google's original [color palette], which can be easily configured through
+Google's original [color palette], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][custom colors].
@@ -14,8 +14,8 @@ fit your brand's identity by using [CSS variables][custom colors].
#### Color scheme
-[:octicons-tag-24: 5.2.0][Color scheme support] ·
-:octicons-milestone-24: Default: `default`
+
+
Material for MkDocs supports two color schemes: a __light mode__, which is just
called `default`, and a __dark mode__, which is called `slate`. The color scheme
@@ -50,12 +50,10 @@ Click on a tile to change the color scheme:
})
- [Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
-
#### Primary color
-[:octicons-tag-24: 0.2.0][Primary color support] ·
-:octicons-milestone-24: Default: `indigo`
+
+
The primary color is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
@@ -107,12 +105,10 @@ Click on a tile to change the primary color:
See our guide below to learn how to set [custom colors].
- [Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
-
#### Accent color
-[:octicons-tag-24: 0.2.0][Accent color support] ·
-:octicons-milestone-24: Default: `indigo`
+
+
The accent color is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
@@ -166,12 +162,10 @@ Click on a tile to change the accent color:
See our guide below to learn how to set [custom colors].
- [Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
-
### Color palette toggle
-[:octicons-tag-24: 7.1.0][Color palette toggle support] ·
-:octicons-milestone-24: Default: _none_
+
+
Offering a light _and_ dark color palette makes your documentation pleasant to
read at different times of the day, so the user can choose accordingly. Add the
@@ -213,9 +207,9 @@ and [`accent`][palette.accent] per color palette.
The following properties must be set for each toggle:
-[`icon`](#+palette.toggle.icon){ #+palette.toggle.icon }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must point to a valid icon path referencing any icon bundled
with the theme, or the build will not succeed. Some popular combinations:
@@ -225,13 +219,12 @@ The following properties must be set for each toggle:
* :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
* :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
-[`name`](#+palette.toggle.name){ #+palette.toggle.name }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property is used as the toggle's `title` attribute and should be set to
a discernable name to improve accessibility. It's rendered as a [tooltip].
- [Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[palette.scheme]: #color-scheme
[palette.primary]: #primary-color
[palette.accent]: #accent-color
@@ -240,8 +233,8 @@ The following properties must be set for each toggle:
### System preference
-[:octicons-tag-24: 7.1.0][System preference support] ·
-:octicons-milestone-24: Default: _none_
+
+
Each color palette can be linked to the user's system preference for light and
dark appearance by using a media query. Simply add a `media` property next to
@@ -270,13 +263,11 @@ When the user first visits your site, the media queries are evaluated in the
order of their definition. The first media query that matches selects the
default color palette.
- [System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-
#### Automatic light / dark mode
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.18.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Newer operating system allow to automatically switch between light and dark
appearance during day and night times. [Insiders] adds support for automatic
diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md
index d2d7a46af..dfd8ccaa9 100644
--- a/docs/setup/changing-the-fonts.md
+++ b/docs/setup/changing-the-fonts.md
@@ -11,8 +11,8 @@ or another destination should be used.
### Regular font
-[:octicons-tag-24: 0.1.2][Font support] ·
-:octicons-milestone-24: Default: [`Roboto`][Roboto]
+
+
The regular font is used for all body copy, headlines, and essentially
everything that does not need to be monospaced. It can be set to any
@@ -27,12 +27,11 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[Roboto]: https://fonts.google.com/specimen/Roboto
- [Font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font
-[:octicons-tag-24: 0.1.2][Font support] ·
-:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
+
+
The _monospaced font_ is used for code blocks and can be configured separately.
Just like the regular font, it can be set to any valid [Google Font]
@@ -50,8 +49,8 @@ The typeface will be loaded in 400.
### Autoloading
-[:octicons-tag-24: 1.0.0][Autoloading support] ·
-:octicons-milestone-24: Default: _none_
+
+
If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
to adhere to [data privacy] regulations, and fall back to system fonts, add the
@@ -69,7 +68,6 @@ theme:
by automatically downloading and self-hosting the web font files.
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
- [Autoloading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
## Customization
@@ -96,7 +94,7 @@ corresponding `@font-face` definition:
- stylesheets/extra.css
```
-The font can then be applied to specific elements, e.g. only headlines, or
+The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or monospaced font:
=== "Regular font"
diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md
index 5b34828d5..f8b59fc6a 100644
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@@ -9,8 +9,8 @@ available.
### Site language
-[:octicons-tag-24: 1.12.0][Site language support] ·
-:octicons-milestone-24: Default: `en`
+
+
You can set the site language in `mkdocs.yml` with:
@@ -41,7 +41,6 @@ the default slug function works. Consider using a [Unicode-aware slug function].
that some translations are missing, click on the link to add them. If your
language is not in the list, click here to [add a new language].
- [Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
[language selector]: #site-language-selector
[Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify
@@ -49,8 +48,8 @@ the default slug function works. Consider using a [Unicode-aware slug function].
### Site language selector
-[:octicons-tag-24: 7.0.0][Site language selector support] ·
-:octicons-milestone-24: Default: _none_
+
+
If your documentation is available in multiple languages, a language selector
pointing to those languages can be added to the header. Alternate languages
@@ -73,36 +72,35 @@ extra:
The following properties are available for each alternate language:
-[`name`](#+alternate.name){ #+alternate.name }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This value of this property is used inside the language selector as the
name of the language and must be set to a non-empty string.
-[`link`](#+alternate.link){ #+alternate.link }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs.
-[`lang`](#+alternate.lang){ #+alternate.lang }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must contain an [ISO 639-1 language code] and is used for
the `hreflang` attribute of the link, improving discoverability via search
engines.
[![Language selector preview]][Language selector preview]
- [Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[Language selector preview]: ../assets/screenshots/language-selection.png
### Directionality
-[:octicons-tag-24: 2.5.0][Directionality support] ·
-:octicons-milestone-24: Default: _automatically set_
+
+
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) directionality which is deduced from the
@@ -132,8 +130,6 @@ Click on a tile to change the directionality:
})
- [Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
-
## Customization
### Custom translations
diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md
index 79dbf65e8..414dcf4d7 100644
--- a/docs/setup/changing-the-logo-and-icons.md
+++ b/docs/setup/changing-the-logo-and-icons.md
@@ -1,7 +1,7 @@
# Changing the logo and icons
-When installing Material for MkDocs, you immediately get access to _over 8,000
-icons_ ready to be used for customization of specific parts of the theme and/or
+When installing Material for MkDocs, you immediately get access to _over 8,000
+icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also add
[additional icons] with minimal effort.
@@ -11,8 +11,8 @@ when writing your documentation in Markdown. Not enough? You can also add
### Logo
-[:octicons-tag-24: 0.1.0][Logo support] ·
-:octicons-milestone-24: Default: :material-library: – `material/library`
+
+
The logo can be changed to a user-provided image (any type, incl. `*.png` and
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
@@ -44,7 +44,6 @@ Add the following lines to `mkdocs.yml`:
- [Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
Normally, the logo in the header and sidebar links to the homepage of the
@@ -58,10 +57,10 @@ extra:
### Favicon
-[:octicons-tag-24: 0.1.0][Favicon support] ·
-:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
+
+
-The favicon can be changed to a path pointing to a user-provided image, which
+The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml
@@ -69,7 +68,6 @@ theme:
favicon: images/favicon.png
```
- [Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
### Site icons
diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md
index 779ec634b..739708384 100644
--- a/docs/setup/ensuring-data-privacy.md
+++ b/docs/setup/ensuring-data-privacy.md
@@ -1,6 +1,6 @@
# Ensuring data privacy
-Material for MkDocs makes compliance with data privacy regulations very easy,
+Material for MkDocs makes compliance with data privacy regulations very easy,
as it offers a native [cookie consent] solution to seek explicit consent from
users before setting up [analytics]. Additionally, external assets can be
automatically downloaded for [self-hosting].
@@ -13,9 +13,9 @@ automatically downloaded for [self-hosting].
### Cookie consent
-[:octicons-tag-24: 8.4.0][Cookie consent support] ·
-:octicons-milestone-24: Default: _none_ ·
-:octicons-beaker-24: Experimental
+
+
+
Material for MkDocs ships a native and extensible cookie consent form which
asks the user for consent prior to sending requests to third parties. Add the
@@ -37,21 +37,21 @@ extra:
The following properties are available:
-[`title`](#+consent.title){ #+consent.title }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
- This property sets the title of the cookie consent, which is rendered at the
+:
+ This property sets the title of the cookie consent, which is rendered at the
top of the form and must be set to a non-empty string.
-[`description`](#+consent.description){ #+consent.description }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property sets the description of the cookie consent, is rendered below
the title, and may include raw HTML (e.g. a links to the terms of service).
-[`cookies`](#+consent.cookies){ #+consent.cookies }
+
-: :octicons-milestone-24: Default: _none_ – This property allows to add custom
+: This property allows to add custom
cookies or change the initial `checked` state and name of built-in cookies.
Currently, the following cookies are built-in:
@@ -100,10 +100,10 @@ The following properties are available:
automatically include a setting for the user to disable it. [Custom cookies]
can be used from JavaScript.
-[`actions`](#+consent.actions){ #+consent.actions }
+
-: :octicons-milestone-24: Default: `[accept, manage]` – This property defines
- which buttons are shown and in which order, e.g. to allow the user to accept
+: This property defines
+ which buttons are shown and in which order, e.g. to allow the user to accept
cookies and manage settings:
``` yaml
@@ -128,13 +128,12 @@ When a user first visits your site, a cookie consent form is rendered:
[![Cookie consent enabled]][Cookie consent enabled]
[Custom cookies]: #custom-cookies
- [Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[Cookie consent enabled]: ../assets/screenshots/consent.png
#### Change cookie settings
In order to comply with GDPR, users must be able to change their cookie settings
-at any time. This can be done by adding a simple link to your [copyright notice]
+at any time. This can be done by adding a simple link to your [copyright notice]
in `mkdocs.yml`:
``` yaml
@@ -147,12 +146,12 @@ copyright: >
### Built-in privacy plugin
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.9.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
+
-The built-in privacy plugin automatically identifies [external assets] as part
+The built-in privacy plugin automatically identifies external assets as part
of the build process and downloads all assets for very simple self-hosting. Add
the following lines to `mkdocs.yml`:
@@ -161,254 +160,52 @@ plugins:
- privacy
```
-> If you need to be able to build your documentation with and without
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
+For a list of all settings, please consult the [plugin documentation].
-The following configuration options are available:
+ [plugin documentation]: ../plugins/privacy.md
-[`enabled`](#+privacy.enabled){ #+privacy.enabled }
+!!! tip "Hosting images externally and optimizing them automatically"
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
+ This option makes the [built-in privacy plugin] an excellent choice for
+ when you want to host assets like images outside of your git repository
+ in another location to keep them fresh and your repository lean.
- ``` yaml
- plugins:
- - privacy:
- enabled: !ENV [CI, false]
- ```
+ Additionally, as of , the
+ built-in privacy plugin was entirely rewritten and now works perfectly
+ with the [built-in optimize plugin], which means that external assets
+ can be passed through the same optimization pipeline as the rest of your
+ documentation. This means you can store and edit unoptimized files
+ outside of your repository, and let both plugins built a highly
+ optimized site for you.
-[`concurrency`](#+privacy.concurrency){ #+privacy.concurrency }
-
-: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
- how many CPUs the plugin is allowed to use when downloading external assets.
- With more CPUs, the plugin can do more work in the same time, thus complete
- its work faster. Concurrent processing can be disabled with:
-
- ``` yaml
- plugins:
- - privacy:
- concurrency: 1
- ```
-
- [Insiders]: ../insiders/index.md
- [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-
-#### External assets
-
-The following configuration options are available for external assets:
-
-[`assets`](#+privacy.assets){ #+privacy.assets }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- plugin should scan the HTML output to detect and process external assets:
-
- ``` yaml
- plugins:
- - privacy:
- assets: true
- ```
-
- If you've removed all external assets from your project via [customization],
- it's still a good idea to enable the plugin, as the plugin will make sure
- that there are no hidden external links in any Markdown files that were
- unintentionally added.
-
- Using `assets` in [strict mode] will make the build fail when external
- assets are detected.
-
-[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- plugin should download external assets it encountered and bundle them with
- your documentation:
-
- ``` yaml
- plugins:
- - privacy:
- assets_fetch: true
- ```
-
-[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
-
-: :octicons-milestone-24: Default: `assets/external` – This option
- specifies where the downloaded [external assets] will be stored. It's
- normally not necessary to change this option:
-
- ``` yaml
- plugins:
- - privacy:
- assets_fetch_dir: assets/external
- ```
-
- The path must be defined relative to [`docs_dir`][docs_dir].
-
-[`assets_include`](#+privacy.assets_include){ #+privacy.assets_include }
-
-: :octicons-milestone-24: Default: _none_ – This option allows to only include
- certain external assets for processing by the privacy plugin, so they will
- be downloaded and bundled during the build:
-
- ``` yaml
- plugins:
- - privacy:
- assets_include:
- - unsplash.com/*
- ```
-
- !!! tip "Hosting images externally and optimizing them automatically"
-
- This option makes the [built-in privacy plugin] an excellent choice for
- when you want to host assets like images outside of your git repository
- in another location to keep them fresh and your repository lean.
-
- Additionally, as of [:octicons-tag-24: insiders-4.30.0][Insiders], the
- built-in privacy plugin was entirely rewritten and now works perfectly
- with the [built-in optimize plugin], which means that external assets
- can be passed through the same optimization pipeline as the rest of your
- documentation. This means you can store and edit unoptimized files
- outside of your repository, and let both plugins built a highly
- optimized site for you.
-
- If you want to implement separate pipelines, i.e., optimize some images
- differently from others or exclude some images from downloading, you can
- use multiple instances of the [built-in privacy plugin].
-
-[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
-
-: :octicons-milestone-24: Default: _none_ – This option allows to exclude
- certain external assets from processing by the privacy plugin, so they will
- not be downloaded and bundled during the build:
-
- ``` yaml
- plugins:
- - privacy:
- assets_exclude: # (1)!
- - cdn.jsdelivr.net/npm/mathjax@3/*
- - giscus.app/*
- ```
-
- 1. [MathJax] loads web fonts for typesetting of mathematical content
- through relative URLs, and thus cannot be automatically bundled by the
- privacy plugin. [MathJax can be self-hosted].
-
- Giscus, which we recommend to use as a [comment system], uses a technique
- called code-splitting to load only the code that is necessary, which
- is implemented via relative URLs. [Giscus can be self-hosted] as well.
-
- Excluding specific external assets can be necessary if they contain
- dynamically created or relative URLs, which can't be resolved by the privacy
- plugin due to [technical limitations].
+ If you want to implement separate pipelines, i.e., optimize some images
+ differently from others or exclude some images from downloading, you can
+ use multiple instances of the [built-in privacy plugin].
!!! question "Why can't Material for MkDocs bundle all assets by design?"
The primary reason why Material for MkDocs can't just bundle all of its own
assets is the integration with [Google Fonts], which offers over a thousand
different fonts that can be used to render your documentation. Most of the
- fonts include several weights and are split up into different character sets
+ fonts include several weights and are split up into different character sets
to keep the download size small, so the browser only downloads what is
really needed. For Roboto, our default [regular font], this results in [42
`*.woff2` files in total][example].
-
+
If Material for MkDocs would bundle all font files, the download size would
- be in the hundreds of megabytes, slowing down automated builds. Furthermore,
- authors might add external assets like third-party scripts or style sheets
+ be in the hundreds of megabytes, slowing down automated builds. Furthermore,
+ authors might add external assets like third-party scripts or style sheets
that would need to be remembered to be defined as further local assets.
-
+
This is the very reason the [built-in privacy plugin] exists — it automates
the process of downloading all external assets manually to ensure compliance
with GDPR with some some [technical limitations].
- [customization]: ../customization.md
- [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
- [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
- [MathJax]: ../reference/math.md
- [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
- [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
- [comment system]: adding-a-comment-system.md
- [external assets]: #how-it-works
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[Google Fonts]: changing-the-fonts.md
[regular font]: changing-the-fonts.md#regular-font
[example]: #example
- [technical limitations]: #limitations
- [built-in optimize plugin]: building-an-optimized-site.md#built-in-optimize-plugin
+ [built-in optimize plugin]: ../plugins/optimize.md
-#### External links
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.26.0][Insiders] ·
-:octicons-beaker-24: Experimental
-
-The following configuration options are available for external links:
-
-[`links`](#+privacy.links){ #+privacy.links }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- plugin should parse and process external links. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - privacy:
- links: !ENV [CI, false]
- ```
-
-[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
-
-: :octicons-milestone-24: Default: _None_ – This option specifies custom
- attributes that should be added to external links, like for example
- `target="_blank"` so all external links open in a new window:
-
- ``` yaml
- plugins:
- - privacy:
- links_attr_map:
- target: _blank
- ```
-
-[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- plugin should automatically add [`rel="noopener"`][noopener] to all links
- with `target="_blank"` for security reasons:
-
- ``` yaml
- plugins:
- - privacy:
- links_noopener: true
- ```
-
- [noopener]: https://mathiasbynens.github.io/rel-noopener/
-
-#### How it works
-
-The [built-in privacy plugin] scans the resulting HTML for links to external
-resources, including external scripts, style sheets, images and web fonts, and
-downloads them to bundle them with your documentation site. Every URL referring
-to an external resource, no matter if part of a template or Markdown file, is
-then replaced with the URL to the local copy. An example:
-
-``` html
-
-```
-
-The external script is downloaded, and the link is replaced with:
-
-``` html
-
-```
-
-Style sheets are scanned for external `url(...)` references, e.g. images and
-web fonts, which are then also downloaded and bundled with your documentation
-site. This means that [Google Fonts] can be configured in `mkdocs.yml` as usual,
-as the [built-in privacy plugin] automatically downloads and bundles all
-dependent resources.
-
-As a third measure, [`preconnect`][preconnect] hints used for DNS pre-fetching
-which might also leak the visitors IP address to a third party are automatically
-removed during the build process.
??? example "Expand to inspect example"
@@ -480,68 +277,9 @@ removed during the build process.
└─ polyfill.io/v3/polyfill.min.js
```
- [built-in privacy plugin]: #built-in-privacy-plugin
+ [built-in privacy plugin]: ../plugins/privacy.md
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
-#### Caching recommended { #caching data-toc-label="Caching" }
-
-All downloaded files are written to the `.cache` directory, significantly
-reducing the duration of subsequent builds as only replacements need to be
-carried out. You might want to:
-
-1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
-2. When building your site for publishing, use a build cache to save the
- `.cache` directory in between builds. Taking the example from the
- [publishing guide], add the following lines:
-
- ``` yaml hl_lines="15-21"
- name: ci
- on:
- push:
- branches:
- - master
- - main
- jobs:
- deploy:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
- with:
- python-version: 3.x
- - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- - uses: actions/cache@v3
- with:
- key: mkdocs-material-${{ env.cache_id }}
- path: .cache
- restore-keys: |
- mkdocs-material-
- - run: pip install mkdocs-material
- - run: mkdocs gh-deploy --force
- ```
-
- [publishing guide]: ../publishing-your-site.md#with-github-actions
-
-#### Limitations
-
-Note that dynamically created URLs as part of scripts are not detected, and thus
-cannot be automatically downloaded. The [built-in privacy plugin] does not
-execute scripts – it can only detect fully qualified URLs to download and
-replace.
-
-In short, don't do this:
-
-``` js
-const cdn = "https://polyfill.io"
-const url = `${cdn}/v3/polyfill.min.js`
-```
-
-Instead, always use fully qualified URLs:
-
-``` js
-const url ="https://polyfill.io/v3/polyfill.min.js"
-```
-
## Customization
### Custom cookies
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index ea9182c28..69eafa2ad 100644
--- a/docs/setup/extensions/python-markdown-extensions.md
+++ b/docs/setup/extensions/python-markdown-extensions.md
@@ -15,8 +15,8 @@ are natively supported, meaning they work without any further adjustments.
### Arithmatex
-[:octicons-tag-24: 1.0.0][Arithmatex support] ·
-[:octicons-workflow-24: Extension][Arithmatex]
+
+
The [Arithmatex] extension allows for rendering of block and inline block
equations and integrates seamlessly with [MathJax][^1] – a library for
@@ -33,7 +33,7 @@ markdown_extensions:
generic: true
```
-Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
+Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with a few lines
of [additional JavaScript]:
@@ -77,7 +77,6 @@ See reference for usage:
- [Using inline block syntax]
[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
- [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
[MathJax]: https://www.mathjax.org/
[KaTeX]: https://github.com/Khan/KaTeX
@@ -87,8 +86,8 @@ See reference for usage:
### BetterEm
-[:octicons-tag-24: 0.1.0][BetterEm support] ·
-[:octicons-workflow-24: Extension][BetterEm]
+
+
The [BetterEm] extension improves the detection of Markup to emphasize text
in Markdown using special characters, i.e. for `**bold**` and `_italic_`
@@ -100,16 +99,15 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
+MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
documentation][BetterEm] for more information.
[BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
- [BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Caret, Mark & Tilde
-[:octicons-tag-24: 1.0.0][Caret support] ·
-[:octicons-workflow-24: Extension][Caret]
+
+
The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
and define sub- and superscript using a simple syntax. Enable them together
@@ -132,7 +130,6 @@ See reference for usage:
- [Sub- and superscripts]
[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
- [Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
[Highlighting text]: ../../reference/formatting.md#highlighting-text
@@ -140,8 +137,8 @@ See reference for usage:
### Critic
-[:octicons-tag-24: 1.0.0][Critic support] ·
-[:octicons-workflow-24: Extension][Critic]
+
+
The [Critic] extension allows for the usage of [Critic Markup] to highlight
added, deleted or updated sections in a document, i.e. for tracking changes in
@@ -154,9 +151,9 @@ markdown_extensions:
The following configuration options are supported:
-[`mode`](#+pymdownx.critic.mode){ #+pymdownx.critic.mode }
+
-: :octicons-milestone-24: Default: `view` – This option defines how the markup
+: This option defines how the markup
should be parsed, i.e. whether to just `view` all suggested changes, or
alternatively `accept` or `reject` them:
@@ -189,14 +186,13 @@ See reference for usage:
- [Highlighting changes]
[Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
- [Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
[Highlighting changes]: ../../reference/formatting.md#highlighting-changes
### Details
-[:octicons-tag-24: 1.9.0][Details support] ·
-[:octicons-workflow-24: Extension][Details]
+
+
The [Details] extension supercharges the [Admonition] extension, making the
resulting _call-outs_ collapsible, allowing them to be opened and closed by the
@@ -212,14 +208,13 @@ No configuration options are available. See reference for usage:
- [Collapsible blocks]
[Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
- [Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
[Admonition]: python-markdown.md#admonition
[Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
### Emoji
-[:octicons-tag-24: 1.0.0][Emoji support] ·
-[:octicons-workflow-24: Extension][Emoji]
+
+
The [Emoji] extension automatically inlines bundled and custom icons and emojis
in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
@@ -237,9 +232,9 @@ markdown_extensions:
The following configuration options are supported:
-[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index }
+
-: :octicons-milestone-24: Default: `emojione` – This option defines which set
+: This option defines which set
of emojis is used for rendering. Note that the use of `emojione` is not
recommended due to [restrictions in licensing][Emoji index]:
@@ -249,9 +244,9 @@ The following configuration options are supported:
emoji_index: !!python/name:materialx.emoji.twemoji
```
-[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator }
+
-: :octicons-milestone-24: Default: `to_png` – This option defines how the
+: This option defines how the
resolved emoji or icon shortcode is render. Note that icons can only be
used together with the `to_svg` configuration:
@@ -261,10 +256,10 @@ The following configuration options are supported:
emoji_generator: !!python/name:materialx.emoji.to_svg
```
-[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons }
+
-: :octicons-milestone-24: Default: _none_ – This option allows to list folders
- with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
+: This option allows to list folders
+ with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
explained in more detail in the [icon customization guide]:
``` yaml
@@ -288,7 +283,6 @@ See reference for usage:
- [Using icons in templates]
[Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
- [Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
[icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
[Using emojis]: ../../reference/icons-emojis.md#using-emojis
@@ -297,9 +291,8 @@ See reference for usage:
### Highlight
-[:octicons-tag-24: 5.0.0][Highlight support] ·
-[:octicons-workflow-24: Extension][Highlight] ·
-:octicons-zap-24: Supersedes [CodeHilite]
+
+
The [Highlight] extension adds support for syntax highlighting of code blocks
(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
@@ -319,9 +312,9 @@ markdown_extensions:
The following configuration options are supported:
-[`use_pygments`](#+pymdownx.highlight.use_pygments){ #+pymdownx.highlight.use_pygments }
+
-: :octicons-milestone-24: Default: `true` – This option allows to control
+: This option allows to control
whether highlighting should be carried out during build time using
[Pygments] or in the browser with a JavaScript syntax highlighter:
@@ -342,7 +335,7 @@ The following configuration options are supported:
use_pygments: false
```
- As an example, [Highlight.js], a JavaScript syntax highlighter, can be
+ As an example, [Highlight.js], a JavaScript syntax highlighter, can be
integrated with some [additional JavaScript] and an [additional style
sheet] in `mkdocs.yml`:
@@ -371,9 +364,9 @@ The following configuration options are supported:
syntax highlighting using [Pygments], so they don't apply if `use_pygments`
is set to `false`.
-[`pygments_lang_class`](#+pymdownx.highlight.pygments_lang_class){ #+pymdownx.highlight.pygments_lang_class }
+
-: :octicons-milestone-24: Default: `false` – This option instructs [Pygments]
+: This option instructs [Pygments]
to add a CSS class to identify the language of the code block, which is
essential for custom annotation markers to function:
@@ -383,9 +376,9 @@ markdown_extensions:
pygments_lang_class: true
```
-[`auto_title`](#+pymdownx.highlight.auto_title){ #+pymdownx.highlight.auto_title }
+
-: :octicons-milestone-24: Default: `false` – This option will automatically
+: This option will automatically
add a [title] to all code blocks that shows the name of the language being
used, e.g. `Python` is printed for a `py` block:
@@ -395,9 +388,9 @@ markdown_extensions:
auto_title: true
```
-[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums }
+
-: :octicons-milestone-24: Default: `false` – This option will add line numbers
+: This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
code blocks, consult the section on [adding line numbers][Adding line
numbers] in the code block reference, which also contains some tips on
@@ -409,9 +402,9 @@ markdown_extensions:
linenums: true
```
-[`linenums_style`](#+pymdownx.highlight.linenums_style){ #+pymdownx.highlight.linenums_style }
+
-: :octicons-milestone-24: Default: `table` – The [Highlight] extension
+: The [Highlight] extension
provides three ways to add line numbers, two of which are supported by
Material for MkDocs. While `table` wraps a code block in a ``
element, `pymdownx-inline` renders line numbers as part of the line itself:
@@ -423,13 +416,13 @@ markdown_extensions:
```
Note that `inline` will put line numbers next to the actual code, which
- means that they will be included when selecting text with the cursor or
+ means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of either `table`
or `pymdownx-inline` is recommended.
-[`anchor_linenums`](#+pymdownx.highlight.anchor_linenums){ #+pymdownx.highlight.anchor_linenums }
+
-: [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24:
+: :octicons-milestone-24:
Default: `false` – If a code blocks contains line numbers, enabling this
setting will wrap them with anchor links, so they can be hyperlinked and
shared more easily:
@@ -440,9 +433,9 @@ markdown_extensions:
anchor_linenums: true
```
-[`line_spans`](#+pymdownx.highlight.line_spans){ #+pymdownx.highlight.line_spans }
+
-: :octicons-milestone-24: Default: _none_ – When this option is set, each
+: When this option is set, each
line of a code block is wrapped in a `span`, which is essential for features
like line highlighting to work correctly:
@@ -465,7 +458,6 @@ See reference for usage:
- [Custom syntax theme]
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
- [Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[CodeHilite]: python-markdown.md#codehilite
[pymdownx.superfences]: #superfences
[pymdownx.inlinehilite]: #inlinehilite
@@ -473,7 +465,6 @@ See reference for usage:
[additional style sheet]: ../../customization.md#additional-css
[Highlight.js]: https://highlightjs.org/
[title]: ../../reference/code-blocks.md#adding-a-title
- [anchor_linenums support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
[Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
[Using code blocks]: ../../reference/code-blocks.md#usage
[Adding a title]: ../../reference/code-blocks.md#adding-a-title
@@ -482,10 +473,10 @@ See reference for usage:
### InlineHilite
-[:octicons-tag-24: 5.0.0][InlineHilite support] ·
-[:octicons-workflow-24: Extension][InlineHilite]
+
+
-The [InlineHilite] extension add support for syntax highlighting of inline code
+The [InlineHilite] extension add support for syntax highlighting of inline code
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
which it sources its configuration. Enable it via `mkdocs.yml`:
@@ -497,7 +488,7 @@ markdown_extensions:
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
-the [`css_class`][InlineHilite options] option, which must not be changed. See the
+the [`css_class`][InlineHilite options] option, which must not be changed. See the
[InlineHilite documentation][InlineHilite] for guidance.
See reference for usage:
@@ -505,17 +496,16 @@ See reference for usage:
- [Highlighting inline code blocks]
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
- [InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
[pymdownx.highlight]: #highlight
[Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
### Keys
-[:octicons-tag-24: 1.0.0][Keys support] ·
-[:octicons-workflow-24: Extension][Keys]
+
+
-The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
+The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
``` yaml
@@ -525,7 +515,7 @@ markdown_extensions:
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
-the [`class`][Keys options] option, which must not be changed. See the
+the [`class`][Keys options] option, which must not be changed. See the
[Keys documentation][Keys] for more information.
See reference for usage:
@@ -533,16 +523,15 @@ See reference for usage:
- [Adding keyboard keys]
[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
- [Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
[Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
### SmartSymbols
-[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
-[:octicons-workflow-24: Extension][SmartSymbols]
+
+
-The [SmartSymbols] extension converts some sequences of characters into their
+The [SmartSymbols] extension converts some sequences of characters into their
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
`mkdocs.yml`:
@@ -552,16 +541,15 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
+MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
documentation][SmartSymbols] for guidance.
[SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
- [SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Snippets
-[:octicons-tag-24: 0.1.0][Snippets support] ·
-[:octicons-workflow-24: Extension][Snippets]
+
+
The [Snippets] extension adds the ability to embed content from arbitrary files
into a document, including other documents or source files, by using a simple
@@ -573,7 +561,7 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
+MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
documentation][Snippets] for more information.
See reference for usage:
@@ -582,15 +570,13 @@ See reference for usage:
- [Embedding external files]
[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
- [Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
[Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
### SuperFences
-[:octicons-tag-24: 0.1.0][SuperFences support] ·
-[:octicons-workflow-24: Extension][SuperFences] ·
-:octicons-zap-24: Supersedes [Fenced Code Blocks]
+
+
The [SuperFences] extension allows for arbitrary nesting of code and content
blocks inside each other, including admonitions, tabs, lists and all other
@@ -603,9 +589,9 @@ markdown_extensions:
The following configuration options are supported:
-[`custom_fences`](#+pymdownx.superfences.custom_fences){ #+pymdownx.superfences.custom_fences }
+
-: :octicons-milestone-24: Default: _none_ – This option allows to define a
+: This option allows to define a
handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
diagrams to be interpreted in the browser:
@@ -638,7 +624,6 @@ See reference for usage:
- [Using entity-relationship diagrams]
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
- [SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
[diagrams]: ../../reference/diagrams.md
@@ -652,8 +637,8 @@ See reference for usage:
### Tabbed
-[:octicons-tag-24: 5.0.0][Tabbed support] ·
-[:octicons-workflow-24: Extension][Tabbed]
+
+
The [Tabbed] extension allows the usage of content tabs, a simple way to group
related content and code blocks under accessible tabs. Enable it via
@@ -667,12 +652,12 @@ markdown_extensions:
The following configuration options are supported:
-[`alternate_style`](#+pymdownx.tabbed.alternate_style){ #+pymdownx.tabbed.alternate_style }
+
-: [:octicons-tag-24: 7.3.1][Tabbed alternate support] ·
- :octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__
- – This option enables the content tabs [alternate style], which has
- [better behavior on mobile viewports], and is the only supported style:
+:
+ This option enables the content tabs
+ [alternate style], which has [better behavior on mobile viewports], and is
+ the only supported style:
``` yaml
markdown_extensions:
@@ -680,9 +665,9 @@ The following configuration options are supported:
alternate_style: true
```
-[`slugify`](#+pymdownx.tabbed.slugify){ #+pymdownx.tabbed.slugify }
+
-: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
+: This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][Slugs]:
@@ -716,8 +701,6 @@ See reference for usage:
- [Embedded content]
[Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
- [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
- [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
@@ -727,8 +710,8 @@ See reference for usage:
### Tasklist
-[:octicons-tag-24: 1.0.0][Tasklist support] ·
-[:octicons-workflow-24: Extension][Tasklist]
+
+
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Tasklist specification], following the same syntactical
@@ -742,10 +725,10 @@ markdown_extensions:
The following configuration options are supported:
-[`custom_checkbox`](#+pymdownx.tasklist.custom_checkbox){ #+pymdownx.tasklist.custom_checkbox }
+
-: :octicons-milestone-24: Default: `false` · This option toggles the rendering
- style of checkboxes, replacing native checkbox styles with beautiful icons,
+: This option toggles the rendering
+ style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore recommended:
``` yaml
@@ -754,10 +737,10 @@ The following configuration options are supported:
custom_checkbox: true
```
-[`clickable_checkbox`](#+pymdownx.tasklist.clickable_checkbox){ #+pymdownx.tasklist.clickable_checkbox }
+
-: :octicons-milestone-24: Default: `false` · This option toggles whether
- checkboxes are clickable. As the state is not persisted, the use of this
+: This option toggles whether
+ checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:
``` yaml
@@ -775,7 +758,6 @@ See reference for usage:
- [Using task lists]
[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
- [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists
diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md
index 0c581b6a7..4d7b0dfd7 100644
--- a/docs/setup/extensions/python-markdown.md
+++ b/docs/setup/extensions/python-markdown.md
@@ -11,8 +11,8 @@ reference for which features they need to be enabled.
### Abbreviations
-[:octicons-tag-24: 1.0.0][Abbreviations support] ·
-[:octicons-workflow-24: Extension][Abbreviations]
+
+
The [Abbreviations] extension adds the ability to add a small tooltip to an
element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
@@ -29,16 +29,15 @@ No configuration options are available. See reference for usage:
- [Adding a glossary]
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
- [Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
### Admonition
-[:octicons-tag-24: 0.1.0][Admonition support] ·
-[:octicons-workflow-24: Extension][Admonition]
+
+
-The [Admonition] extension adds support for admonitions, more commonly known as
+The [Admonition] extension adds support for admonitions, more commonly known as
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
it via `mkdocs.yml`:
@@ -55,7 +54,6 @@ No configuration options are available. See reference for usage:
- [Supported types]
[Admonition]: https://python-markdown.github.io/extensions/admonition/
- [Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding admonitions]: ../../reference/admonitions.md#usage
[Changing the title]: ../../reference/admonitions.md#changing-the-title
[Removing the title]: ../../reference/admonitions.md#removing-the-title
@@ -63,8 +61,8 @@ No configuration options are available. See reference for usage:
### Attribute Lists
-[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
-[:octicons-workflow-24: Extension][Attribute Lists]
+
+
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
@@ -87,7 +85,6 @@ No configuration options are available. See reference for usage:
- [Image lazy-loading]
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
- [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
[Using grids]: ../../reference/grids.md#using-grids
[Adding buttons]: ../../reference/buttons.md#adding-buttons
@@ -99,8 +96,8 @@ No configuration options are available. See reference for usage:
### Definition Lists
-[:octicons-tag-24: 1.1.0][Definition Lists support] ·
-[:octicons-workflow-24: Extension][Definition Lists]
+
+
The [Definition Lists] extension adds the ability to add definition lists (more
commonly known as [description lists] – `dl` in HTML) via Markdown to a
@@ -116,14 +113,13 @@ No configuration options are available. See reference for usage:
- [Using definition lists]
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
- [Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[Using definition lists]: ../../reference/lists.md#using-definition-lists
### Footnotes
-[:octicons-tag-24: 1.0.0][Footnotes support] ·
-[:octicons-workflow-24: Extension][Footnotes]
+
+
The [Footnotes] extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
@@ -139,14 +135,13 @@ No configuration options are supported. See reference for usage:
- [Adding footnote content]
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
- [Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
[Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
### Markdown in HTML
-[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
-[:octicons-workflow-24: Extension][Markdown in HTML]
+
+
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
which is useful for wrapping Markdown content with custom elements. Enable it
@@ -170,18 +165,17 @@ No configuration options are available. See reference for usage:
- [Image captions]
[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
- [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using annotations]: ../../reference/annotations.md#usage
[Using grids]: ../../reference/grids.md#usage
[Image captions]: ../../reference/images.md#image-captions
### Table of Contents
-[:octicons-tag-24: 0.1.0][Table of Contents support] ·
-[:octicons-workflow-24: Extension][Table of Contents]
+
+
The [Table of Contents] extension automatically generates a table of contents
-from a document, which Material for MkDocs will render as part of the resulting
+from a document, which Material for MkDocs will render as part of the resulting
page. Enable it via `mkdocs.yml`:
``` yaml
@@ -192,13 +186,12 @@ markdown_extensions:
The following configuration options are supported:
-[`title`](#+toc.title){ #+toc.title }
+
-: [:octicons-tag-24: 7.3.5][title support] ·
- :octicons-milestone-24: Default: _automatically set_ – This option sets the
- title of the table of contents in the right navigation sidebar, which is
- normally automatically sourced from the translations for the [site language]
- as set in `mkdocs.yml`:
+: –
+ This option sets the title of the table of contents in the right navigation
+ sidebar, which is normally automatically sourced from the translations for
+ the [site language] as set in `mkdocs.yml`:
``` yaml
markdown_extensions:
@@ -206,9 +199,9 @@ The following configuration options are supported:
title: On this page
```
-[`permalink`](#+toc.permalink){ #+toc.permalink }
+
-: :octicons-milestone-24: Default: `false` – This option adds an anchor link
+: This option adds an anchor link
containing the paragraph symbol `¶` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
@@ -229,11 +222,11 @@ The following configuration options are supported:
permalink: ⚓︎
```
-[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
+
-: :octicons-milestone-24: Default: `Permanent link` – This option sets the
+: This option sets the
title of the anchor link which is shown on hover and read by screen readers.
- For accessibility reasons, it might be beneficial to change it to a more
+ For accessibility reasons, it might be beneficial to change it to a more
discernable name, stating that the anchor links to the section itself:
``` yaml
@@ -242,9 +235,9 @@ The following configuration options are supported:
permalink_title: Anchor link to this section for reference
```
-[`slugify`](#+toc.slugify){ #+toc.slugify }
+
-: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
+: This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][Slugs]:
@@ -267,9 +260,9 @@ The following configuration options are supported:
slugify: !!python/object/apply:pymdownx.slugs.slugify
```
-[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
+
-: :octicons-milestone-24: Default: `6` – Define the range of levels to be
+: Define the range of levels to be
included in the table of contents. This may be useful for project
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
@@ -295,17 +288,15 @@ by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
- [Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
- [title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.5
[site language]: ../changing-the-language.md#site-language
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
### Tables
-[:octicons-tag-24: 0.1.0][Tables support] ·
-[:octicons-workflow-24: Extension][Tables]
+
+
-The [Tables] extension adds the ability to create tables in Markdown by using a
+The [Tables] extension adds the ability to create tables in Markdown by using a
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
default):
@@ -320,36 +311,34 @@ No configuration options are available. See reference for usage:
- [Column alignment]
[Tables]: https://python-markdown.github.io/extensions/tables/
- [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using data tables]: ../../reference/data-tables.md#usage
[Column alignment]: ../../reference/data-tables.md#column-alignment
## Superseded extensions
-The following [Python Markdown] extensions are not (or might not be) supported
+The following [Python Markdown] extensions are not (or might not be) supported
anymore, and are therefore not recommended for use. Instead, the alternatives
should be considered.
### Fenced Code Blocks
-[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
-[:octicons-workflow-24: Extension][Fenced Code Blocks]
+
+
Superseded by [SuperFences]. This extension might still work, but the
-[SuperFences] extension is superior in many ways, as it allows for arbitrary
+[SuperFences] extension is superior in many ways, as it allows for arbitrary
nesting, and is therefore recommended.
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
- [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### CodeHilite
-[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
-[:octicons-workflow-24: Extension][CodeHilite]
+
+
Superseded by [Highlight]. Support for CodeHilite was dropped in
-:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other
+, as [Highlight] has a better integration with other
essential extensions like [SuperFences] and [InlineHilite].
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
diff --git a/docs/setup/index.md b/docs/setup/index.md
index d20a3544d..124bf5a4c 100644
--- a/docs/setup/index.md
+++ b/docs/setup/index.md
@@ -16,7 +16,7 @@ setting up site search, and more.
- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
- :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
- :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
-- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
+- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
- :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
- :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages
@@ -66,7 +66,7 @@ versioned documentation that matches your project's versioning methodology.
[Blog]: setting-up-a-blog.md
[Comment System]: adding-a-comment-system.md
- [Versioning]: setting-up-versioning.md
+ [Versioning]: setting-up-versioning.md
[Repository]: adding-a-git-repository.md
## Optimization
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index 5cb2526c9..83065a120 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/docs/setup/setting-up-a-blog.md
@@ -9,19 +9,19 @@ indexes, [post slugs], configurable [pagination] and more.
__Check out our [blog], which is created with the new [built-in blog plugin]!__
- [archive]: #archive
- [category]: #categories
- [post slugs]: #+blog.post_url_format
- [pagination]: #pagination
+ [archive]: ../plugins/blog.md#archive
+ [category]: ../plugins/blog.md#categories
+ [post slugs]: ../plugins/blog.md#config.post_url_format
+ [pagination]: ../plugins/blog.md#pagination
[blog]: ../blog/index.md
## Configuration
### Built-in blog plugin
-[:octicons-tag-24: 9.2.0][Blog plugin support] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
The built-in blog plugin adds support for building a blog from a folder of
posts, which are annotated with dates and other structured data. First, add the
@@ -32,848 +32,23 @@ plugins:
- blog
```
-> If you need to be able to build your documentation with and without
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
+For a list of all settings, please consult the [plugin documentation].
-By default, the built-in blog plugin assumes that your blog is hosted inside
-the `blog` subfolder of your documentation ([this is configurable]). Next,
-you need to create the following structure:
+ [plugin documentation]: ../plugins/blog.md
-``` { .sh .no-copy }
-.
-├─ docs/
-│ └─ blog/
-│ ├─ posts/
-│ └─ index.md
-└─ mkdocs.yml
-```
-
-Since the built-in blog plugin auto-generates [archive] and [category] indexes,
-it must know where to add those to the navigation. Thus, make sure to add a
-`blog/index.md` file in `mkdocs.yml`:
-
-``` yaml
-nav:
- - Blog:
- - blog/index.md # (1)!
-```
-
-1. Within this file, you can specify the title of your blog, which is then
- picked up and used by the built-in blog plugin:
-
- ``` markdown
- # Blog
- ```
-
-The following configuration options are available:
-
-[`enabled`](#+blog.enabled){ #+blog.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - blog:
- enabled: !ENV [CI, false]
- ```
-
-[`blog_dir`](#+blog.blog_dir){ #+blog.blog_dir }
-
-: :octicons-milestone-24: Default: `blog` – This option specifies the folder
- where your posts and metadata live. The name of the folder will also be
- included in the generated URLs as a prefix to all blog-related pages. If
- you want to build a standalone blog, change it to `.`:
-
- === "Subdirectory"
-
- ``` yaml
- plugins:
- - blog:
- blog_dir: blog
- ```
-
- === "Standalone"
-
- ``` yaml
- plugins:
- - blog:
- blog_dir: .
- ```
-
- The path must be defined relative to [`docs_dir`][docs_dir].
-
-[`blog_toc`](#+blog.blog_toc){ #+blog.blog_toc }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether
- indexes include a table of contents with all post titles on the
- right side as an overview:
-
- ``` yaml
- plugins:
- - blog:
- blog_toc: true
- ```
-
- Note that this setting is also used as the default value for `archive_toc`
- and `categories_toc`, unless those settings are explicitly defined.
-
-__The built-in blog plugin has dozens of options that allow for advanced
-configuration. It's a good idea to [start writing your first post], and come
-back here later for fine-tuning the output.__
-
----
-
- [Blog plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[Insiders]: ../insiders/index.md
+ [built-in blog plugin]: ../plugins/blog.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
- [this is configurable]: #+blog.blog_dir
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[start writing your first post]: #writing-your-first-post
-#### Posts
-
-The following configuration options are available for posts:
-
-[`post_dir`](#+blog.post_dir){ #+blog.post_dir }
-
-: :octicons-milestone-24: Default: `{blog}/posts` – This option specifies
- the name of the folder in which the blog plugin should look for posts.
- The default settings assumes that the folder is called `posts`:
-
- ``` yaml
- plugins:
- - blog:
- post_dir: blog/posts
- ```
-
- The path must be defined relative to [`docs_dir`][docs_dir]. Note that the
- `{blog}` placeholder is replaced with the value specified in
- [`blog_dir`][this is configurable].
-
-[`post_date_format`](#+blog.post_date_format){ #+blog.post_date_format }
-
-: :octicons-milestone-24: Default: `long` – This option specifies the date
- format that is used when posts are rendered. Under the hood, the
- [built-in blog plugin] leverages [Babel] to render dates locale-aware using
- the configured [site language]. The following formats are supported:
-
- === "Monday, January 31, 2022"
-
- ``` yaml
- plugins:
- - blog:
- post_date_format: full
- ```
-
- === "January 31, 2022"
-
- ``` yaml
- plugins:
- - blog:
- post_date_format: long
- ```
-
- === "Jan 31, 2022"
-
- ``` yaml
- plugins:
- - blog:
- post_date_format: medium
- ```
-
- === "1/31/22"
-
- ``` yaml
- plugins:
- - blog:
- post_date_format: short
- ```
-
- Note that depending on the [site language], formats might look different
- for other languages. Additionally, [Babel] supports a [pattern syntax]
- which allows for custom formats.
-
-[`post_url_date_format`](#+blog.post_url_date_format){ #+blog.post_url_date_format }
-
-: :octicons-milestone-24: Default: `yyyy/MM/dd` – This option specifies the
- date format that is used in the URL of the post. The format string must
- adhere to [Babel]'s [pattern syntax]. Some examples:
-
- === ":material-link: blog/2022/01/31/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- post_url_date_format: yyyy/MM/dd
- ```
-
- === ":material-link: blog/2022/01/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- post_url_date_format: yyyy/MM
- ```
-
- === ":material-link: blog/2022/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- post_url_date_format: yyyy
- ```
-
- If you want to exclude the date altogether, e.g. when your blog features
- mostly evergreen content, you can remove the `date` placeholder from
- the format string (see below).
-
-[`post_url_format`](#+blog.post_url_format){ #+blog.post_url_format }
-
-: :octicons-milestone-24: Default: `{date}/{slug}` – This option specifies the
- format string that is used for the URL of the post. The following
- placeholders are currently supported:
-
- - `categories` – Replaced with the post's slugified [categories].
-
- - `date` – Replaced with the post's date, as configured in
- [`post_url_date_format`][post_url_date_format].
-
- - `slug` – Replaced with a slug generated from the post's title.
-
- - `file` – Replaced with the post's file name.
-
- === ":material-link: blog/2022/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- post_url_format: "{date}/{slug}"
- ```
-
- === ":material-link: blog/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- post_url_format: "{slug}"
- ```
-
- If you remove the `date` placeholder, make sure that post URLs don't
- collide with other the URLs of other pages added to the blog section, as
- this leads to undefined behavior.
-
-[`post_url_max_categories`](#+blog.post_url_max_categories){ #+blog.post_url_max_categories }
-
-: :octicons-milestone-24: Default: `1` – This option specifies the number of
- categories that are included in the URL if the `categories` placeholder is
- part of [`post_url_format`][post slugs]. If a post is assigned to multiple
- categories, they are joined with `/`:
-
- ``` yaml
- plugins:
- - blog:
- post_url_format: "{categories}/{slug}"
- post_url_max_categories: 2
- ```
-
-[`post_slugify`](#+blog.post_slugify){ #+blog.post_slugify }
-
-: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies
- which function to use for generating URL-compatible slugs from post titles.
- [Python Markdown Extensions] comes with several Unicode-aware
- slug functions which should be a good choice for non-ASCII languages:
-
- === "Unicode"
-
- ``` yaml
- plugins:
- - blog:
- post_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
-
- === "Unicode, case-sensitive"
-
- ``` yaml
- plugins:
- - blog:
- post_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
-
-[`post_slugify_separator`](#+blog.post_slugify_separator){ #+blog.post_slugify_separator }
-
-: :octicons-milestone-24: Default: `-` – This option specifies the separator
- which is used by the slug function. By default, a hyphen is used, but it can
- be changed to any string, including the empty string:
-
- ``` yaml
- plugins:
- - blog:
- post_slugify_separator: "-"
- ```
-
-[`post_excerpt`](#+blog.post_excerpt){ #+blog.post_excerpt }
-
-: :octicons-milestone-24: Default: `optional` – This option specifies whether
- [post excerpts] should be considered being optional or required by the
- [built-in blog plugin] when generating indexes. If excerpts are required,
- the plugin terminates with an error if a post doesn't define an excerpt:
-
- === "Optional"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt: optional
- ```
-
- === "Required"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt: required
- ```
-
-[`post_excerpt_max_authors`](#+blog.post_excerpt_max_authors){ #+blog.post_excerpt_max_authors }
-
-: :octicons-milestone-24: Default: `1` – This option specifies the number of
- authors rendered in post excerpts. While each post may be written by
- multiple authors, this setting allows to limit the display to just a few or
- even a single author, or disable authors in excerpts altogether:
-
- === "Render up to 2 authors in excerpts"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt_max_authors: 2
- ```
-
- === "Disable authors in excerpts"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt_max_authors: 0
- ```
-
-[`post_excerpt_max_categories`](#+blog.post_excerpt_max_categories){ #+blog.post_excerpt_max_categories }
-
-: :octicons-milestone-24: Default: `5` – This option specifies the number of
- categories rendered in post excerpts. While each post may be assigned to
- multiple categories, the [built-in blog plugin] can be instructed to only
- show the first `n` categories to keep it short and concise:
-
- === "Render up to 2 categories in excerpts"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt_max_categories: 2
- ```
-
- === "Disable categories in excerpts"
-
- ``` yaml
- plugins:
- - blog:
- post_excerpt_max_categories: 0
- ```
-
-[`post_excerpt_separator`](#+blog.post_excerpt_separator){ #+blog.post_excerpt_separator }
-
-: :octicons-milestone-24: Default: `` – This option specifies
- the separator the [built-in blog plugin] will look for in a post's content
- when generating [post excerpts]. All content after the separator is not
- considered to be part of the excerpt.
-
-[`post_readtime`](#+blog.post_readtime){ #+blog.post_readtime }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- [built-in blog plugin] should compute the reading time of a post
- automatically, which is then rendered in post excerpts, as well as in the
- posts themselves. If you want to disable reading time computation, add:
-
- ``` yaml
- plugins:
- - blog:
- post_readtime: false
- ```
-
-[`post_readtime_words_per_minute`](#+blog.post_readtime_words_per_minute){ #+blog.post_readtime_words_per_minute }
-
-: :octicons-milestone-24: Default: `265` – This option specifies the number
- of words that a reader is expected to read per minute when computing the
- reading time of a post. If you feel that estimation is not quite right,
- you can fine-tune reading time computation with the following setting:
-
- ``` yaml
- plugins:
- - blog:
- post_readtime_words_per_minute: 265
- ```
-
- [built-in blog plugin]: #built-in-blog-plugin
- [site language]: changing-the-language.md#site-language
- [Babel]: https://pypi.org/project/Babel/
- [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax
- [post_url_date_format]: #+blog.post_url_date_format
- [post excerpts]: #adding-an-excerpt
- [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
-
-#### Archive
-
-The following configuration options are available for archive index generation:
-
-[`archive`](#+blog.archive){ #+blog.archive }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- [built-in blog plugin] should generate archive indexes. An archive indexes
- shows all posts for a specific interval (e.g. year, month, etc.) in
- reverse chronological order. If you want to disable archive index
- generation, add:
-
- ``` yaml
- plugins:
- - blog:
- archive: false
- ```
-
-[`archive_name`](#+blog.archive_name){ #+blog.archive_name }
-
-: :octicons-milestone-24: Default: _automatically set_ – This option specifies
- the title of the archive section which the [built-in blog plugin] will
- generate and add to the navigation. If this setting is omitted, it's
- sourced from the translations, falling back to English. Change it with:
-
- ``` yaml
- plugins:
- - blog:
- archive_name: Archive
- ```
-
-[`archive_date_format`](#+blog.archive_date_format){ #+blog.archive_date_format }
-
-: :octicons-milestone-24: Default: `yyyy` – This option specifies the date
- format that is used when archive indexes are rendered. The format string
- must adhere to [Babel]'s [pattern syntax]. Popular settings are:
-
- === "2022"
-
- ``` yaml
- plugins:
- - blog:
- archive_date_format: yyyy
- ```
-
- === "January 2022"
-
- ``` yaml
- plugins:
- - blog:
- archive_date_format: MMMM yyyy
- ```
-
-[`archive_url_date_format`](#+blog.archive_url_date_format){ #+blog.archive_url_date_format }
-
-: :octicons-milestone-24: Default: `yyyy` – This option specifies the date
- format that is used in the archive index URL. The format string must adhere
- to [Babel]'s [pattern syntax]. Some examples:
-
- === ":material-link: blog/archive/2022/"
-
- ``` yaml
- plugins:
- - blog:
- archive_url_date_format: yyyy
- ```
-
- === ":material-link: blog/archive/2022/01/"
-
- ``` yaml
- plugins:
- - blog:
- archive_url_date_format: yyyy/MM
- ```
-
-[`archive_url_format`](#+blog.archive_url_format){ #+blog.archive_url_format }
-
-: :octicons-milestone-24: Default: `archive/{date}` – This option specifies
- the format string that is used for the URL of the archive index, and can
- be used to localize the URL:
-
- === ":material-link: blog/archive/2022/"
-
- ``` yaml
- plugins:
- - blog:
- archive_url_format: "archive/{date}"
- ```
-
- === ":material-link: blog/2022/"
-
- ``` yaml
- plugins:
- - blog:
- archive_url_format: "{date}"
- ```
-
-[`archive_toc`](#+blog.archive_toc){ #+blog.archive_toc }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether an
- archive index includes a table of contents with all post titles on the
- right side as an overview:
-
- ``` yaml
- plugins:
- - blog:
- archive_toc: true
- ```
-
-#### Categories
-
-The following configuration options are available for category index generation:
-
-[`categories`](#+blog.categories){ #+blog.categories }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- [built-in blog plugin] should generate category indexes. A category index
- shows all posts for a specific category in reverse chronological order. If
- you want to disable category index generation, add:
-
- ``` yaml
- plugins:
- - blog:
- categories: false
- ```
-
-[`categories_name`](#+blog.categories_name){ #+blog.categories_name }
-
-: :octicons-milestone-24: Default: _automatically set_ – This option specifies
- the title of the category section which the [built-in blog plugin] will
- generate and add to the navigation. If this setting is omitted, it's
- sourced from the translations, falling back to English. Change it with:
-
- ``` yaml
- plugins:
- - blog:
- categories_name: Categories
- ```
-
-[`categories_url_format`](#+blog.categories_url_format){ #+blog.categories_url_format }
-
-: :octicons-milestone-24: Default: `category/{slug}` – This option specifies
- the format string that is used for the URL of a category index, and can be
- used to localize the URL:
-
- === ":material-link: blog/category/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- categories_url_format: "category/{slug}"
- ```
-
- === ":material-link: blog/:material-dots-horizontal:/"
-
- ``` yaml
- plugins:
- - blog:
- categories_url_format: "{slug}"
- ```
-
-[`categories_slugify`](#+blog.categories_slugify){ #+blog.categories_slugify }
-
-: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies
- which function to use for generating URL-compatible slugs from categories.
- [Python Markdown Extensions] comes with several Unicode-aware
- slug functions which should be a good choice for non-ASCII languages:
-
- === "Unicode"
-
- ``` yaml
- plugins:
- - blog:
- categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
-
- === "Unicode, case-sensitive"
-
- ``` yaml
- plugins:
- - blog:
- categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
-
-[`categories_slugify_separator`](#+blog.categories_slugify_separator){ #+blog.categories_slugify_separator }
-
-: :octicons-milestone-24: Default: `-` – This option specifies the separator
- which is used by the slug function. By default, a hyphen is used, but it can
- be changed to any string, including the empty string:
-
- ``` yaml
- plugins:
- - blog:
- categories_slugify_separator: "-"
- ```
-
-[`categories_allowed`](#+blog.categories_allowed){ #+blog.categories_allowed }
-
-: :octicons-milestone-24: Default: _none_ – This option specifies the
- categories that are allowed to be used in posts. If this setting is omitted,
- the [built-in blog plugin] will not check category names. Use this option to
- define a list of categories in order to catch typos:
-
- ``` yaml
- plugins:
- - blog:
- categories_allowed:
- - General
- - Search
- - Performance
- ```
-
-[`categories_toc`](#+blog.categories_toc){ #+blog.categories_toc }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether a
- category index includes a table of contents with all post titles on the
- right side as an overview:
-
- ``` yaml
- plugins:
- - blog:
- categories_toc: true
- ```
-
-#### Pagination
-
-The following configuration options are available for index pagination:
-
-[`pagination`](#+blog.pagination){ #+blog.pagination }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- [built-in blog plugin] should paginate the index. The index shows all posts
- in reverse chronological order, which can be many. If you want to disable
- index pagination, add:
-
- ``` yaml
- plugins:
- - blog:
- pagination: false
- ```
-
-[`pagination_per_page`](#+blog.pagination_per_page){ #+blog.pagination_per_page }
-
-: :octicons-milestone-24: Default: `10` – This option specifies the number
- of posts rendered on a single index page. If more posts are found, they are
- assigned to a 2nd page, and so on. If you have large [post excerpts], it
- might be a good idea to reduce the number of posts per page:
-
- ``` yaml
- plugins:
- - blog:
- pagination_per_page: 5
- ```
-
-[`pagination_url_format`](#+blog.pagination_url_format){ #+blog.pagination_url_format }
-
-: :octicons-milestone-24: Default: `page/{page}` – This option specifies
- the format string that is used for the URL of the paginated index, and can
- be used to localize the URL:
-
- === ":material-link: blog/page/n/"
-
- ``` yaml
- plugins:
- - blog:
- pagination_url_format: "page/{page}"
- ```
-
- === ":material-link: blog/n/"
-
- ``` yaml
- plugins:
- - blog:
- pagination_url_format: "{page}"
- ```
-
-[`pagination_format`](#+blog.pagination_format){ #+blog.pagination_format }
-
-: :octicons-milestone-24: Default: `~2~` – This option specifies the format
- string that is provided to the [paginate] module, which allows to customize
- how pagination is constructed. Popular choices:
-
- === "1 2 3 .. n"
-
- ``` yaml
- plugins:
- - blog:
- pagination_format: "~2~"
- ```
-
- === "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
-
- ``` yaml
- plugins:
- - blog:
- pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
- ```
-
- === "1 :material-chevron-right:"
-
- ``` yaml
- plugins:
- - blog:
- pagination_format: "$link_previous $page $link_next"
- ```
-
- The [paginate] module exposes the following placeholders:
-
- - `$first_page` – number of first reachable page
- - `$last_page` – number of last reachable page
- - `$page` – number of currently selected page
- - `$page_count` – number of reachable pages
- - `$items_per_page` – maximal number of items per page
- - `$first_item` – index of first item on the current page
- - `$last_item` – index of last item on the current page
- - `$item_count` – total number of items
- - `$link_first` – link to first page (unless this is first page)
- - `$link_last` – link to last page (unless this is last page)
- - `$link_previous` – link to previous page (unless this is first page)
- - `$link_next` – link to next page (unless this is last page)
-
- [paginate]: https://pypi.org/project/paginate/
-
-[`pagination_if_single_page`](#+blog.pagination_if_single_page){ #+blog.pagination_if_single_page }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether
- the pagination should also be rendered if all posts fit into a single page.
- If you wish to always render pagination, add:
-
- ``` yaml
- plugins:
- - blog:
- pagination_if_single_page: true
- ```
-
-[`pagination_keep_content`](#+blog.pagination_keep_content){ #+blog.pagination_keep_content }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether
- paginated index pages should inherit the custom content from the index
- page, i.e. the content of `blog/index.md`:
-
- ``` yaml
- plugins:
- - blog:
- pagination_keep_content: true
- ```
-
-#### Authors
-
-The following configuration options are available for author info:
-
-[`authors`](#+blog.authors){ #+blog.authors }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether the
- [built-in blog plugin] should generate author info. If it is enabled, the
- plugin will look up authors in a file called `.authors.yml` and include
- authors in indexes and in posts. If you want to disable this behavior, add:
-
- ``` yaml
- plugins:
- - blog:
- authors: false
- ```
-
-[`authors_file`](#+blog.authors_file){ #+blog.authors_file }
-
-: :octicons-milestone-24: Default: `{blog}/.authors.yml` – This option
- specifies the name of the file where the authors for your posts resides.
- The default settings assumes that the file is called `.authors.yml`
- (mind the `.` at the beginning):
-
- ``` yaml
- plugins:
- - blog:
- authors_file: blog/.authors.yml
- ```
-
- The path must be defined relative to [`docs_dir`][docs_dir]. Note that the
- `{blog}` placeholder is replaced with the value specified in
- [`blog_dir`][this is configurable]. Also see the section on [adding authors].
-
- [adding authors]: #adding-authors
-
-#### Drafts
-
-The following configuration options are available for drafts:
-
-[`draft`](#+blog.draft){ #+blog.draft }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether the
- [built-in blog plugin] should also include posts marked as drafts when the
- site is being built. Including draft posts might be desired in deploy
- previews, which is why it exists in the first place:
-
- === "Render drafts"
-
- ``` yaml
- plugins:
- - blog:
- draft: true
- ```
-
- === "Don't render drafts"
-
- ``` yaml
- plugins:
- - blog:
- draft: false
- ```
-
-[`draft_on_serve`](#+blog.draft_on_serve){ #+blog.draft_on_serve }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- posts marked as drafts should be included [when previewing your site] with
- `mkdocs serve`. By default, drafts are rendered when previewing, but skipped
- when the site is being built:
-
- ``` yaml
- plugins:
- - blog:
- draft_on_serve: true
- ```
-
-[`draft_if_future_date`](#+blog.draft_if_future_date){ #+blog.draft_if_future_date }
-
-: :octicons-milestone-24: Default: `false` – This option specifies whether the
- [built-in blog plugin] should mark posts with a future date as drafts. When
- the date passed today, the post is automatically unmarked and included when
- the site is being built:
-
- ``` yaml
- plugins:
- - blog:
- draft_if_future_date: true
- ```
-
- [when previewing your site]: ../creating-your-site.md#previewing-as-you-write
-
### RSS
-[:octicons-tag-24: 9.2.0][Blog plugin support] ·
-[:octicons-cpu-24: Plugin][rss]
+
+
The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
-which provides a simple way to add an RSS feed to your blog (or to your whole
+which provides a simple way to add an RSS feed to your blog (or to your whole
documentation). Install it with `pip`:
```
@@ -901,9 +76,9 @@ plugins:
The following configuration options are supported:
-[`enabled`](#+rss.enabled){ #+rss.enabled }
+
-: :octicons-milestone-24: Default: `true` – This option specifies whether
+: This option specifies whether
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
@@ -913,9 +88,9 @@ The following configuration options are supported:
enabled: !ENV [CI, false]
```
-[`match_path`](#+rss.match_path){ #+rss.match_path }
+
-: :octicons-milestone-24: Default: `.*` – This option specifies which
+: This option specifies which
pages should be included in the feed. For example, to only include blog
posts in the feed, use the following regular expression:
@@ -925,10 +100,10 @@ The following configuration options are supported:
match_path: blog/posts/.*
```
-[`date_from_meta`](#+rss.date_from_meta){ #+rss.date_from_meta }
+
-: :octicons-milestone-24: Default: _none_ – This option specifies which
- front matter property should be used as a creation date of a page in the
+: This option specifies which
+ front matter property should be used as a creation date of a page in the
feed. It's recommended to use the `date` property:
``` yaml
@@ -938,9 +113,9 @@ The following configuration options are supported:
as_creation: date
```
-[`categories`](#+rss.categories){ #+rss.categories }
+
-: :octicons-milestone-24: Default: _none_ – This option specifies which
+: This option specifies which
front matter properties are used as categories as part of the feed. If you
use [categories] and [tags], add both with the following lines:
@@ -952,9 +127,9 @@ The following configuration options are supported:
- tags
```
-[`comments_path`](#+rss.comments_path){ #+rss.comments_path }
+
-: :octicons-milestone-24: Default: _none_ – This option specifies the anchor
+: This option specifies the anchor
at which comments for a post or page can be found. If you've integrated a
[comment system], add the following lines:
@@ -970,7 +145,7 @@ that the [RSS plugin][rss] comes with several other configuration options.
For further information, see the [documentation].
[rss]: https://guts.github.io/mkdocs-rss-plugin/
- [categories]: #categories
+ [categories]: ../plugins/blog.md#categories
[tags]: setting-up-tags.md#built-in-tags-plugin
[comment system]: adding-a-comment-system.md
[necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
@@ -1006,7 +181,7 @@ Create a new file called `hello-world.md` and add the following lines:
``` yaml
---
draft: true # (1)!
-date: 2022-01-31 # (2)!
+date: 2023-01-31
categories:
- Hello
- World
@@ -1016,9 +191,9 @@ categories:
...
```
-1. If you mark a post as a [draft], a red marker appears next to the post date
- on index pages. When the site is built, drafts are not included in the
- output. [This behavior can be changed], e.g. for rendering drafts when
+1. If you mark a post as a [draft], a red marker appears next to the post date
+ on index pages. When the site is built, drafts are not included in the
+ output. [This behavior can be changed], e.g. for rendering drafts when
building deploy previews.
2. If you wish to provide multiple dates, you can use the following syntax,
@@ -1042,8 +217,8 @@ When you spin up the [live preview server], you should be greeted by your first
post! You'll also realize, that [archive] and [category] indexes have been
automatically generated for you.
- [draft]: #drafts
- [This behavior can be changed]: #+blog.draft
+ [draft]: ../plugins/blog.md#drafts
+ [This behavior can be changed]: ../plugins/blog.md#config.draft
[live preview server]: ../creating-your-site.md#previewing-as-you-write
#### Adding an excerpt
@@ -1067,7 +242,7 @@ When the [built-in blog plugin] generates all indexes, the content before the
[excerpt separator] is automatically extracted, allowing the user to start
reading a post before deciding to jump in.
- [excerpt separator]: #+blog.post_excerpt_separator
+ [excerpt separator]: ../plugins/blog.md#config.post_excerpt_separator
#### Adding authors
@@ -1087,21 +262,21 @@ The [`.authors.yml`][authors_file] file associates each author with an
identifier (in this example `squidfunk`), which can then be used in posts.
The following properties are available for each author:
-[`name`](#+blog.authors_file.name){ #+blog.authors_file.name }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must define a name for the author. The name is displayed in
the left sidebar of each post as part of the author info.
-[`description`](#+blog.authors_file.description){ #+blog.authors_file.description }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property can be used to add a short description for the author, e.g.
the role or profession of the author, or any other title.
-[`avatar`](#+blog.authors_file.avatar){ #+blog.authors_file.avatar }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must point to a valid image URL, internal or external, and is
used as part of posts and excerpts as the author's avatar.
@@ -1112,7 +287,7 @@ each post, as well as in post excerpts on index pages:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
authors:
- squidfunk
...
@@ -1122,8 +297,8 @@ authors:
...
```
- [authors]: #authors
- [authors_file]: #+blog.authors_file
+ [authors]: ../plugins/blog.md#authors
+ [authors_file]: ../plugins/blog.md#config.authors_file
#### Adding categories
@@ -1134,7 +309,7 @@ add them to the front matter `categories` property:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
categories:
- Hello
- World
@@ -1150,7 +325,7 @@ define your desired categories in `mkdocs.yml` as part of the
[built-in blog plugin] will stop the build if a category is not found within
the list.
- [categories_allowed]: #+blog.categories_allowed
+ [categories_allowed]: ../plugins/blog.md#config.categories_allowed
#### Adding tags
@@ -1160,7 +335,7 @@ part of a post, the post is linked from the [tags index]:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
tags:
- Foo
- Bar
@@ -1170,7 +345,7 @@ tags:
...
```
-As usual, the tags are rendered above the main headline and posts are linked
+As usual, the tags are rendered above the main headline and posts are linked
on the tags index page, if configured. Note that posts are, as pages, only
linked with their titles.
@@ -1192,18 +367,18 @@ slug: hello-world
#### Adding related links
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.23.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
-Related links offer the perfect way to prominently add a _further reading_
-section to your post that is included in the left sidebar, guiding the user to
-other destinations of your documentation. Use the front matter `links` property
+Related links offer the perfect way to prominently add a _further reading_
+section to your post that is included in the left sidebar, guiding the user to
+other destinations of your documentation. Use the front matter `links` property
to add related links to a post:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
links:
- setup/setting-up-site-search.md#built-in-search-plugin
- insiders/index.md#how-to-become-a-sponsor
@@ -1219,7 +394,7 @@ links and even use nesting:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
links:
- setup/setting-up-site-search.md#built-in-search-plugin
- insiders/index.md#how-to-become-a-sponsor
@@ -1233,8 +408,8 @@ links:
```
If you look closely, you'll realize that you can even use an anchor to link to
-a specific section of a document, extending the possibilities of the [`nav`][nav]
-syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets
+a specific section of a document, extending the possibilities of the [`nav`][nav]
+syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets
the title of the anchor as a [subtitle] of the related link.
Note that all links must be relative to [`docs_dir`][docs_dir], as is also the
@@ -1245,9 +420,9 @@ case for the [`nav`][nav] setting.
#### Linking from and to posts
-While [post URLs][post slugs] are dynamically computed, the [built-in blog
-plugin] ensures that all links from and to posts and a post's assets are
-correct. If you want to link to a post, just use the path to the Markdown file
+While [post URLs][post slugs] are dynamically computed, the [built-in blog
+plugin] ensures that all links from and to posts and a post's assets are
+correct. If you want to link to a post, just use the path to the Markdown file
as a link reference (links must be relative):
``` markdown
@@ -1260,7 +435,7 @@ Linking from a post to a page, e.g. the index, follows the same method:
[Blog](../index.md)
```
-All assets inside the `posts` directory are copied to the `blog/assets` folder
+All assets inside the `posts` directory are copied to the `blog/assets` folder
when the site is being built. Of course, you can also reference assets from
posts outside of the `posts` directory. The [built-in blog plugin] ensures that
all links are correct.
@@ -1269,17 +444,17 @@ all links are correct.
When [enabled], the [readtime] package is used to compute the expected reading
time of each post, which is rendered as part of the post and post excerpt.
-Nowadays, many blogs show reading times, which is why the [built-in blog plugin]
+Nowadays, many blogs show reading times, which is why the [built-in blog plugin]
offers this capability as well.
Sometimes, however, the computed reading time might not feel accurate, or
-result in odd and unpleasant numbers. For this reason, reading time can be
+result in odd and unpleasant numbers. For this reason, reading time can be
overridden and explicitly set with the front matter `readtime` property for a
post:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
readtime: 15
---
@@ -1290,7 +465,7 @@ readtime: 15
This will disable automatic reading time computation.
[readtime]: https://pypi.org/project/readtime/
- [enabled]: #+blog.post_readtime
+ [enabled]: ../plugins/blog.md#config.post_readtime
#### Setting defaults
@@ -1341,7 +516,7 @@ values defined for a post, which means you can define common properties in
Besides posts, it's also possible to add static pages to your blog by listing
the pages in the [`nav`][nav] section of `mkdocs.yml`. All generated indexes
-are included after the last specified page. For example, to add a page on the
+are included after the last specified page. For example, to add a page on the
authors of the blog, add the following to `mkdocs.yml`:
``` yaml
@@ -1356,11 +531,11 @@ nav:
### Custom index pages
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.24.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
-If you want to add custom content to automatically generated [archive] and
+If you want to add custom content to automatically generated [archive] and
[category] indexes, e.g. to add a category description prior to the list of
posts, you can manually create the category page in the same location where
the [built-in blog plugin] would create it:
@@ -1404,8 +579,8 @@ All post excerpts belonging to the category are automatically appended.
[add the category]: #adding-categories
[page description]: ../reference/index.md#setting-the-page-description
- [categories_url_format]: #+blog.categories_url_format
- [categories_slugify]: #+blog.categories_slugify
+ [categories_url_format]: ../plugins/blog.md#config.categories_url_format
+ [categories_slugify]: ../plugins/blog.md#config.categories_slugify
### Overriding templates
diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md
index 72d0f14b0..74ab68c3c 100644
--- a/docs/setup/setting-up-navigation.md
+++ b/docs/setup/setting-up-navigation.md
@@ -1,6 +1,6 @@
# Setting up navigation
-A clear and concise navigation structure is an important aspect of good project
+A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs] and [sections], and one
of its flagship features: [instant loading].
@@ -13,8 +13,8 @@ of its flagship features: [instant loading].
### Instant loading
-[:octicons-tag-24: 5.0.0][Instant loading support] ·
-:octicons-unlock-24: Feature flag
+
+
When instant loading is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR] without fully reloading the page. Add
@@ -31,14 +31,14 @@ are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
Page Application__. Now, the search index survives navigation, which is
especially useful for large documentation sites.
- [Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
#### Instant prefetching :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.36.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
+
Instant prefetching is a new experimental feature that will start to fetch a
page once the user hovers over a link. This will reduce the perceived loading
@@ -52,12 +52,10 @@ theme:
- navigation.instant.prefetch
```
- [Insiders]: ../insiders/index.md
-
### Anchor tracking
-[:octicons-tag-24: 8.0.0][Anchor tracking support] ·
-:octicons-unlock-24: Feature flag
+
+
When anchor tracking is enabled, the URL in the address bar is automatically
updated with the active anchor as highlighted in the table of contents. Add the
@@ -69,24 +67,22 @@ theme:
- navigation.tracking
```
- [Anchor tracking support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
-
### Navigation tabs
-[:octicons-tag-24: 1.1.0][Navigation tabs support] ·
-:octicons-unlock-24: Feature flag
+
+
When tabs are enabled, top-level sections are rendered in a menu layer below
the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
the following lines to `mkdocs.yml`:
[^1]:
- Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
+ Prior to , navigation tabs had a slightly different
behavior. All top-level pages (i.e. all top-level entries directly
referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
were grouped under the first tab which received the title of the first page.
This made it impossible to include a top-level page (or external link) as a
- tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
+ tab item, as was reported in #1884 and #2072. From
on, navigation tabs include all top-level pages and sections.
``` yaml
@@ -103,14 +99,13 @@ theme:
[![Navigation tabs disabled]][Navigation tabs disabled]
- [Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs
-[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
-:octicons-unlock-24: Feature flag
+
+
When sticky tabs are enabled, navigation tabs will lock below the header and
always remain visible when scrolling down. Just add the following two feature
@@ -131,14 +126,13 @@ theme:
[![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
- [Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections
-[:octicons-tag-24: 6.2.0][Navigation sections support] ·
-:octicons-unlock-24: Feature flag
+
+
When sections are enabled, top-level sections are rendered as groups in the
sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
@@ -158,7 +152,6 @@ theme:
[![Navigation sections disabled]][Navigation sections disabled]
- [Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
[Navigation sections disabled]: ../assets/screenshots/navigation.png
@@ -168,8 +161,8 @@ feature flags are enabled, sections are rendered for level 2 navigation items.
### Navigation expansion
-[:octicons-tag-24: 6.2.0][Navigation expansion support] ·
-:octicons-unlock-24: Feature flag
+
+
When expansion is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually.
@@ -189,15 +182,15 @@ theme:
[![Navigation expansion disabled]][Navigation expansion disabled]
- [Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
### Navigation path Breadcrumbs { id=navigation-path }
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.28.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
+
When navigation paths are activated, a breadcrumb navigation is rendered above
the title of each page, which might make orientation easier for users visiting your
@@ -223,11 +216,12 @@ theme:
### Navigation pruning
-[:octicons-tag-24: 9.2.0][Navigation pruning support] ·
-:octicons-beaker-24: Experimental
+
+
+
-When pruning is enabled, only the visible navigation items are included in the
-rendered HTML, __reducing the size of the built site by 33% or more__. Add the
+When pruning is enabled, only the visible navigation items are included in the
+rendered HTML, __reducing the size of the built site by 33% or more__. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -245,13 +239,12 @@ This feature flag is especially useful for documentation sites with 100+ or even
Navigation pruning will replace all expandable sections with links to the first
page in that section (or the section index page).
- [Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[navigation.expand]: #navigation-expansion
### Section index pages
-[:octicons-tag-24: 7.3.0][Section index pages support] ·
-:octicons-unlock-24: Feature flag
+
+
When section index pages are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. Add the
@@ -289,7 +282,6 @@ nav:
1. MkDocs also considers files called `README.md` as [index pages].
- [Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #navigation-integration
@@ -299,8 +291,9 @@ nav:
#### Anchor following
-[:octicons-tag-24: 8.5.0][Anchor following support] ·
-:octicons-beaker-24: Experimental
+
+
+
When anchor following for the [table of contents] is enabled, the sidebar is
automatically scrolled so that the active anchor is always visible. Add the
@@ -312,12 +305,10 @@ theme:
- toc.follow
```
- [Anchor following support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-
#### Navigation integration
-[:octicons-tag-24: 6.2.0][Navigation integration support] ·
-:octicons-unlock-24: Feature flag
+
+
When navigation integration for the [table of contents] is enabled, it is always
rendered as part of the navigation sidebar on the left. Add the following lines
@@ -342,15 +333,14 @@ theme:
[![Navigation integration disabled]][Navigation integration disabled]
[table of contents]: extensions/python-markdown.md#table-of-contents
- [Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
[navigation.indexes]: #section-index-pages
### Back-to-top button
-[:octicons-tag-24: 7.1.0][Back-to-top button support] ·
-:octicons-unlock-24: Feature flag
+
+
A back-to-top button can be shown when the user, after scrolling down, starts
to scroll up again. It's rendered centered and just below the header. Add the
@@ -362,14 +352,15 @@ theme:
- navigation.top
```
- [Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-
## Usage
### Hiding the sidebars
+
+
+
The navigation and/or table of contents sidebars can be hidden for a document
-with the front matter `hide` property. Add the following lines at the top of a
+with the front matter `hide` property. Add the following lines at the top of a
Markdown file:
``` yaml
@@ -379,7 +370,7 @@ hide:
- toc
---
-# Document title
+# Page title
...
```
@@ -401,6 +392,10 @@ hide:
### Hiding the navigation path
+
+
+
+
While the [navigation path] is rendered above the main headline, sometimes, it
might be desirable to hide it for a specific page, which can be achieved with
the front matter `hide` property:
@@ -411,7 +406,7 @@ hide:
- path
---
-# Document title
+# Page title
...
```
@@ -424,7 +419,7 @@ hide:
Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There are two modes:
-[`search`](#mode:search){ #mode:search }
+
: This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard:
@@ -433,7 +428,7 @@ to navigate your project documentation via keyboard. There are two modes:
* ++esc++ , ++tab++ : close search dialog
* ++enter++ : follow selected result
-[`global`](#mode:global){ #mode:global }
+
: This mode is active when _search is not focussed_ and when there's no other
focussed element that is susceptible to keyboard input. The following keys
diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md
index 912606d56..a88e23c12 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -13,8 +13,8 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable
### Google Analytics
-[:octicons-tag-24: 7.1.8][Google Analytics support] ·
-:octicons-milestone-24: Default: _none_
+
+
Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
already set up Google Analytics and have a property, enable it by adding the
@@ -32,8 +32,6 @@ extra:
property: G-XXXXXXXXXX
```
- [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
-
??? question "How to measure site search usage?"
Besides page views and events, [site search] can be tracked to better
@@ -50,8 +48,8 @@ extra:
### Was this page helpful?
-[:octicons-tag-24: 8.4.0][Was this page helpful? support] ·
-:octicons-milestone-24: Default: _none_
+
+
A simple [feedback widget] can be included at the bottom of each page,
encouraging users to give instant feedback whether a page was helpful or not.
@@ -85,7 +83,7 @@ extra:
Both properties, `title` and `ratings`, are required. Note that it's allowed to
define more than two ratings, e.g. to implement a 1-5 star rating. Since the
-feedback widget sends data to a third-party service, it is, of course, natively
+feedback widget sends data to a third-party service, it is, of course, natively
integrated with the [cookie consent] feature[^2].
[^2]:
@@ -103,7 +101,7 @@ integrated with the [cookie consent] feature[^2].
2. Go to the __configure__ page on the left hand menu, then select
__custom definitions__
- 3. Click the __custom metrics__ tab and then __create custom metrics__,
+ 3. Click the __custom metrics__ tab and then __create custom metrics__,
enter the following values:
* Metric name: Page helpful
@@ -121,7 +119,7 @@ integrated with the [cookie consent] feature[^2].
(the custom metric created in step 3)
* Rows: `Page location`
* Values: Drag in both `Event count` and `Page helpful`
- * Filters: Add a new filter for
+ * Filters: Add a new filter for
`Event name / exactly matches / feedback`
!!! warning "Delay in data availability"
@@ -143,9 +141,9 @@ integrated with the [cookie consent] feature[^2].
The following properties are available for each rating:
-[`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must point to a valid icon path referencing [any icon bundled
with the theme][custom icons], or the build will not succeed. Some popular
combinations:
@@ -154,24 +152,24 @@ The following properties are available for each rating:
* :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
* :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
-[`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
The value of this property is shown on user interaction (i.e. keyboard focus
or mouse hover), explaining the meaning of the rating behind the icon.
-[`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
The value of this property is sent as a data value with the custom event
that is transmitted to Google Analytics[^3] (or any custom integration).
[^3]:
Note that for Google Analytics, the data value must be an integer.
-[`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
The value of this property is shown after the user selected the rating.
It may contain arbitrary HTML tags, which is especially useful to ask the
user to provide more detailed feedback for the current page through a form.
@@ -185,7 +183,7 @@ The following properties are available for each rating:
https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
```
- In this example, when clicking the link, the user is redirected to the "new
+ In this example, when clicking the link, the user is redirected to the "new
issue" form of your repository, with a pre-filled title including the path
of the current document, e.g.:
@@ -195,7 +193,6 @@ The following properties are available for each rating:
An alternative to GitHub issues is [Google Forms].
- [Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[feedback widget]: #feedback
[analytics]: #google-analytics
[feedback report]: ../assets/screenshots/feedback-report.png
@@ -216,7 +213,7 @@ hide:
- feedback
---
-# Document title
+# Page title
...
```
@@ -224,7 +221,7 @@ hide:
### Custom site analytics
-In order to integrate another analytics service provider offering a
+In order to integrate another analytics service provider offering a
JavaScript-based tracking solution, just follow the guide on [theme extension]
and create a new partial in the `overrides` folder. The name of the partial is
used to configure the custom integration via `mkdocs.yml`:
diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md
index 8ed79f602..605c9c9a4 100644
--- a/docs/setup/setting-up-site-search.md
+++ b/docs/setup/setting-up-site-search.md
@@ -16,11 +16,11 @@ not be compliant with privacy regulations. Moreover, search even works
### Built-in search plugin
-[:octicons-tag-24: 0.1.0][Search support] ·
-:octicons-cpu-24: Plugin
+
+
The built-in search plugin integrates seamlessly with Material for MkDocs,
-adding multilingual client-side search with [lunr] and [lunr-languages]. It's
+adding multilingual client-side search with [lunr] and [lunr-languages]. It's
enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used:
@@ -29,227 +29,18 @@ plugins:
- search
```
-The following configuration options are supported:
+For a list of all settings, please consult the [plugin documentation].
-[`lang`](#+search.lang){ #+search.lang }
+ [plugin documentation]: ../plugins/search.md
-: :octicons-milestone-24: Default: _automatically set_ – This option allows
- to include the language-specific stemmers provided by [lunr-languages].
- Note that Material for MkDocs will set this automatically based on the
- [site language], but it may be overridden, e.g. to support multiple
- languages:
-
- === "A single language"
-
- ``` yaml
- plugins:
- - search:
- lang: en
- ```
-
- === "Multiple languages"
-
- ``` yaml
- plugins:
- - search:
- lang: # (1)!
- - en
- - de
- ```
-
- 1. Be aware that including support for other languages increases the
- general JavaScript payload by around 20kb (before `gzip`) and by
- another 15-30kb per language.
-
- The following languages are supported by [lunr-languages]:
-
-
-
- - `ar` – Arabic
- - `da` – Danish
- - `de` – German
- - `du` – Dutch
- - `en` – English
- - `es` – Spanish
- - `fi` – Finnish
- - `fr` – French
- - `hi` – Hindi
- - `hu` – Hungarian
- - `hy` – Armenian
- - `it` – Italian
- - `ja` – Japanese
- - `kn` - Kannada
- - `ko` – Korean
- - `no` – Norwegian
- - `pt` – Portuguese
- - `ro` – Romanian
- - `ru` – Russian
- - `sa` – Sanskrit
- - `sv` – Swedish
- - `ta` – Tamil
- - `te` – Telugu
- - `th` – Thai
- - `tr` – Turkish
- - `vi` – Vietnamese
- - `zh` – Chinese
-
-
-
- Material for MkDocs goes to great lengths to support languages that are not
- part of this list by automatically falling back to the stemmer yielding the
- best result.
-
-[`separator`](#+search.separator){ #+search.separator }
-
-: :octicons-milestone-24: Default: _automatically set_ – The separator for
- indexing and query tokenization can be customized, making it possible to
- index parts of words separated by other characters than whitespace and `-`,
- e.g. by including `.`:
-
- ``` yaml
- plugins:
- - search:
- separator: '[\s\-\.]+'
- ```
-
- With :octicons-tag-24: 9.0.0, a faster and more flexible tokenizer method
- is shipped, allowing for __tokenizing with lookahead__, which yields more
- influence on the way documents are indexed. As a result, we use the
- following separator setting for this site's search:
-
- ``` yaml
- plugins:
- - search:
- separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
- ```
-
- Broken into its parts, the separator induces the following behavior:
-
- === "Special characters"
-
- ```
- [\s\-,:!=\[\]()"/]+
- ```
-
- The first part of the expression inserts token boundaries for each
- document before and after whitespace, hyphens, commas, brackets and
- other special characters. If several of those special characters are
- adjacent, they are treated as one.
-
- === "Case changes"
-
- ```
- (?!\b)(?=[A-Z][a-z])
- ```
-
- Many programming languages have naming conventions like `PascalCase` or
- `camelCase`. By adding this subexpression to the separator,
- [words are split at case changes], tokenizing the word `PascalCase`
- into `Pascal` and `Case`.
-
- [:octicons-arrow-right-24: Read more on tokenizing case changes]
- [tokenize case changes]
-
- === "Version strings"
-
- ```
- \.(?!\d)
- ```
-
- When adding `.` to the separator, version strings like `1.2.3` are split
- into `1`, `2` and `3`, which makes them undiscoverable via search. When
- using this subexpression, a small lookahead is introduced which will
- [preserve version strings] and keep them discoverable.
-
- [:octicons-arrow-right-24: Read more on tokenizing version numbers]
- [tokenize version numbers]
-
- === "HTML/XML tags"
-
- ```
- &[lg]t;
- ```
-
- If your documentation includes HTML/XML code examples, you may want to allow
- users to find specific tag names. Unfortunately, the `<` and `>` control
- characters are encoded in code blocks as `<` and `>`. Adding this
- subexpression to the separator allows for just that.
-
- [:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
- [tokenize html-xml tags]
-
- [Search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[lunr]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
- [lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
- [site language]: changing-the-language.md#site-language
- [words are split at case changes]: ?q=searchHighlight
- [preserve version strings]: ?q=9.0.0
- [tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
- [tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
- [tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
-
-#### Chinese language support
-
-[:octicons-tag-24: 9.2.0][Chinese language support] ·
-:octicons-beaker-24: Experimental
-
-In order to add support for Chinese languages to the [built-in search plugin],
-install the text segmentation library [jieba] via `pip`, and the plugin will
-run all text through the segmenter:
-
-``` sh
-pip install jieba
-```
-
-The following configuration options are available:
-
-[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
-
-: :octicons-milestone-24: Default: _none_ – This option allows for specifying
- a [custom dictionary] to be used by [jieba] for segmenting text, replacing
- the default dictionary:
-
- ``` yaml
- plugins:
- - search:
- jieba_dict: dict.txt # (1)!
- ```
-
- 1. The following alternative dictionaries are provided by [jieba]:
-
- - [dict.txt.small] – 占用内存较小的词典文件
- - [dict.txt.big] – 支持繁体分词更好的词典文件
-
-[`jieba_dict_user`](#+search.jieba_dict_user){ #+search.jieba_dict_user }
-
-: :octicons-milestone-24: Default: _none_ – This option allows for specifying
- an additional [user dictionary] to be used by [jieba] for segmenting text,
- augmenting the default dictionary:
-
- ``` yaml
- plugins:
- - search:
- jieba_dict_user: user_dict.txt
- ```
-
- User dictionaries can be used for tuning the segmenter to preserve
- technical terms.
-
- [Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
- [chinese search]: ../blog/posts/chinese-search-support.md
- [jieba]: https://pypi.org/project/jieba/
- [built-in search plugin]: #built-in-search-plugin
- [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
- [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
- [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
- [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
### Search suggestions
-[:octicons-tag-24: 7.2.0][Search suggestions support] ·
-:octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+
+
+
When search suggestions are enabled, the search will display the likeliest
completion for the last word which can be accepted with the ++arrow-right++ key.
@@ -264,14 +55,13 @@ theme:
Searching for [:octicons-search-24: search su][Search suggestions example]
yields ^^search suggestions^^ as a suggestion.
- [Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search suggestions example]: ?q=search+su
### Search highlighting
-[:octicons-tag-24: 7.2.0][Search highlighting support] ·
-:octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+
+
+
When search highlighting is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
@@ -286,13 +76,12 @@ theme:
Searching for [:octicons-search-24: code blocks][Search highlighting example]
highlights all occurrences of both terms.
- [Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
### Search sharing
-[:octicons-tag-24: 7.2.0][Search sharing support] ·
-:octicons-unlock-24: Feature flag
+
+
When search sharing is activated, a :material-share-variant: share button is
rendered next to the reset button, which allows to deep link to the current
@@ -307,13 +96,12 @@ theme:
When a user clicks the share button, the URL is automatically copied to the
clipboard.
- [Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-
## Usage
### Search boosting
-[:octicons-tag-24: 8.3.0][boost support]
+
+
Pages can be boosted in search with the front matter `search.boost` property,
which will make them rank higher. Add the following lines at the top of a
@@ -327,7 +115,7 @@ Markdown file:
boost: 2 # (1)!
---
- # Document title
+ # Page title
...
```
@@ -342,19 +130,18 @@ Markdown file:
boost: 0.5
---
- # Document title
+ # Page title
...
```
- [boost support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
-
### Search exclusion
-[:octicons-tag-24: 9.0.0][exclusion support] ·
-:octicons-beaker-24: Experimental
+
+
+
Pages can be excluded from search with the front matter `search.exclude`
-property, removing them from the index. Add the following lines at the top of a
+property, removing them from the index. Add the following lines at the top of a
Markdown file:
``` yaml
@@ -363,12 +150,10 @@ search:
exclude: true
---
-# Document title
+# Page title
...
```
- [exclusion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
#### Excluding sections
When [Attribute Lists] is enabled, specific sections of pages can be excluded
@@ -378,7 +163,7 @@ heading:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
- # Document title
+ # Page title
## Section 1
@@ -420,7 +205,7 @@ inline- or block-level element:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
- # Document title
+ # Page title
The content of this block is included
diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md
index 14daa4206..ca8557112 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -4,8 +4,8 @@ status: new
# Setting up social cards
-Material for MkDocs can automatically create beautiful social cards for your
-documentation, which appear as link previews on social media platforms. You
+Material for MkDocs can automatically create beautiful social cards for your
+documentation, which appear as link previews on social media platforms. You
can select from several [pre-designed layouts][default layouts] or create
[custom layouts] to match your unique style and branding.
@@ -36,35 +36,22 @@ Social card of our [formatting] reference
### Built-in social plugin
-[:octicons-tag-24: 8.5.0][Social cards support] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
-The built-in social plugin automatically generate a custom preview image for
-each page. Install all [dependencies for image processing][^1] and add the
+The built-in social plugin automatically generate a custom preview image for
+each page. Install all [dependencies for image processing] and add the
following lines to `mkdocs.yml`:
- [^1]:
- The awesome thing about social cards is that they are generated during
- build time and directly distributed with your documentation, no external
- services involved. While it would technically be simpler to generate
- social cards using a web browser and an automation framework like
- [Puppeteer], it would add further liabilities to the toolchain, with the
- potential to make build pipelines more complex and resource intense.
-
- For this reason, Material for MkDocs again follows its core principle of
- making it as simple and powerful as possible, providing an easy-to-use
- framework for building [custom layouts] using Python image processing
- libraries.
-
``` yaml
plugins:
- social
```
-> Note that [Insiders] contains a ground up rewrite of the social plugin that
-> generates images much more efficiently in parallel and allows to build
-> entirely [custom layouts].
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/blog.md
!!! info "The [`site_url`][site_url] setting must be set"
@@ -78,481 +65,18 @@ plugins:
site_url: https://example.com
```
+ [dependencies for image processing]: ../plugins/requirements/image-processing.md
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
-The following configuration options are available:
-
-[`enabled`](#+social.enabled){ #+social.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - social:
- enabled: !ENV [CI, false]
- ```
-
-[`concurrency`](#+social.concurrency){ #+social.concurrency }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: _number of CPUs_ – How many CPUs the plugin is allowed to use when
- generating social cards. With more CPUs, the plugin can do more work in the
- same time, thus complete generation faster. Concurrent processing can be
- disabled with:
-
- ``` yaml
- plugins:
- - social:
- concurrency: 1
- ```
-
- [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
- [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
- [dependencies for image processing]: dependencies/image-processing.md
- [Puppeteer]: https://github.com/puppeteer/puppeteer
- [Insiders]: ../insiders/index.md
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-
-#### Social cards
-
-The following configuration options are available for card generation:
-
-[`cards`](#+social.cards){ #+social.cards }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- to generate social card images. If you want to switch the plugin off, e.g.
- for local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - social:
- cards: !ENV [CI, false]
- ```
-
-[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
-
-: :octicons-milestone-24: Default: `assets/images/social` – This option
- specifies where the generated social cards will be stored. While it's
- usually not necessary to change this option, change it with:
-
- ``` yaml
- plugins:
- - social:
- cards_dir: assets/images/social
- ```
-
-
-
-[`cards_color`](#+social.cards_color){ #+social.cards_color } – :material-trash-can: Deprecated, use [`cards_layout_options`][layout options]
-
-: :octicons-milestone-24: Default: [`theme.palette.primary`][primary color] –
- This option specifies the colors for the background `fill` and foreground
- `text` when generating the social card:
-
- ``` yaml
- plugins:
- - social:
- cards_color:
- fill: "#0FF1CE"
- text: "#FFFFFF"
- ```
-
-[`cards_font`](#+social.cards_font){ #+social.cards_font } – :material-trash-can: Deprecated, use [`cards_layout_options`][layout options]
-
-: :octicons-milestone-24: Default: [`theme.font.text`][font] – This option
- specifies which font to use for rendering the social card, which can be
- any font hosted on [Google Fonts]:
-
- ``` yaml
- plugins:
- - social:
- cards_font: Ubuntu
- ```
-
-
-
-[`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: _none_ – This option specifies where the social plugin should try
- to resolve [custom layouts] from, taking precedence over the included
- layouts:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_dir: layouts
- ```
-
-[`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `default` – Layout specification the social card should use. The
- plugin includes the following layouts which make use of the [color palette]
- and [font]:
-
- === "`default`"
-
- ``` yaml
- plugins:
- - social:
- cards_layout: default
- ```
-
- This layout uses the configured [primary color] as a background:
-
- [![Layout default]][Layout default]
-
- === "`default/variant`"
-
- ``` yaml
- plugins:
- - social:
- cards_layout: default/variant
- ```
-
- This layout includes the [page icon] as a watermark, if defined:
-
- [![Layout default variant]][Layout default variant]
-
- === "`default/accent`"
-
- ``` yaml
- plugins:
- - social:
- cards_layout: default/accent
- ```
-
- This layout uses the configured [accent color] as a background:
-
- [![Layout default accent]][Layout default accent]
-
- === "`default/invert`"
-
- ``` yaml
- plugins:
- - social:
- cards_layout: default/invert
- ```
-
- This layout inverts the background and foreground colors:
-
- [![Layout default invert]][Layout default invert]
-
- === "`default/only/image`"
-
- ``` yaml
- plugins:
- - social:
- cards_layout: default/only/image
- cards_layout_options:
- background_image: layouts/background.png
-
- ```
-
- This layout will only show the given background image and scale to fit:
-
- [![Layer background image]][Layer background image]
-
- All [`default`][default layouts] layouts make use of the following
- [template variables]:
-
- - :material-page-layout-header: – `config.site_name`
- - :material-page-layout-body: – `page.meta.title` or `page.title`
- - :material-page-layout-footer: – `page.meta.description` or `config.site_description`
- - :material-page-layout-sidebar-right: – `theme.logo` or `theme.icon.logo`
-
-[`cards_layout_options`](#+social.cards_layout_options){ #+social.cards_layout_options }
-
-: [:octicons-tag-24: 9.1.10][Layout options support] · :octicons-milestone-24:
- Default: _none_ – This option allows to set [parameters] as provided by
- the layout specification. For [custom layouts], this key can be used to
- provide layout-specific options, making layouts entirely configurable.
-
- ---
-
- All [`default`][default layouts] layouts expose the following parameters:
-
- [`background_color`](#+social.cards_layout_options.background_color){ #+social.cards_layout_options.background_color }
-
- : Set a background color, which can be a [CSS color keyword], or a 3, 4, 6
- or 8 letter HEX color code. Alpha channels are supported as well:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- background_color: "#0FF1CE"
- ```
-
- [`background_image`](#+social.cards_layout_options.background_image){ #+social.cards_layout_options.background_image }
-
- : [:octicons-tag-24: insiders-4.33.0][Insiders] – Set a background image.
- If a `background_color` is set, like for the
- [`default`][default layouts] layouts, the image is tinted (overlayed)
- with the color. Thus, the background color must be (partially)
- transparent for the image to become visible:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- background_color: "#00000000"
- background_image: layouts/background.png
- ```
-
- The path of the image must be defined relative to the project root.
-
- [`color`](#+social.cards_layout_options.color){ #+social.cards_layout_options.color }
-
- : Set a foreground color, which can be a [CSS color keyword], or a 3, 4, 6
- or 8 letter HEX color code. The color is primarily used to tint text and
- icons:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- color: "#0FF1CE"
- ```
-
- [`font_family`](#+social.cards_layout_options.font_family){ #+social.cards_layout_options.font_family }
-
- : Set a font family. This overrides the [font] that is set as part of the
- theme configuration. The [built-in social plugin] will automatically
- download the font from [Google Fonts]:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- font_family: Ubuntu
- ```
-
- [`title`](#+social.cards_layout_options.title){ #+social.cards_layout_options.title }
-
- : [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the social card
- title, which takes precedence over `page.title` and `page.meta.title`:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- title: Social card title
- ```
-
- [`description`](#+social.cards_layout_options.description){ #+social.cards_layout_options.description }
-
- : [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the social card
- description, which takes precedence over `site_description` and
- `page.meta.description`:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- description: Social card description
- ```
-
- [`logo`](#+social.cards_layout_options.logo){ #+social.cards_layout_options.logo }
-
- : [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the logo used as
- part of the social card, overriding the `theme.logo` or
- `theme.icon.logo` settings which are used as defaults:
-
- ``` yaml
- plugins:
- - social:
- cards_layout_options:
- logo: layouts/logo.png
- ```
-
- The path of the image must be defined relative to the project root.
-
-[`cards_include`](#+privacy.cards_include){ #+privacy.cards_include }
-
-: [:octicons-tag-24: insiders-4.35.0][Insiders] · :octicons-milestone-24:
- Default: _none_ – This option allows to only generate social cards for
- certain subsections of your documentation, e.g. to generate different
- cards for different subfolders with multiple instances of the plugin:
-
- ``` yaml
- plugins:
- - social:
- cards_include:
- - blog/*
- ```
-
-[`cards_exclude`](#+privacy.cards_exclude){ #+privacy.cards_exclude }
-
-: :octicons-milestone-24: Default: _none_ – This option allows to exclude
- certain subsections of your documentation from generating social cards:
-
- ``` yaml
- plugins:
- - social:
- cards_exclude:
- - changelog/*.md
- ```
-
- [color palette]: ./changing-the-colors.md#color-palette
- [primary color]: ./changing-the-colors.md#primary-color
- [accent color]: ./changing-the-colors.md#accent-color
- [font]: ./changing-the-fonts.md#regular-font
- [Google Fonts]: https://fonts.google.com/
- [layout options]: #+social.cards_layout_options
- [page icon]: ../reference/index.md#setting-the-page-icon
- [Layout default]: ../assets/screenshots/social-cards.png
- [Layout default variant]: ../assets/screenshots/social-cards-variant.png
- [Layout default accent]: ../assets/screenshots/social-cards-accent.png
- [Layout default invert]: ../assets/screenshots/social-cards-invert.png
- [template variables]: https://www.mkdocs.org/dev-guide/themes/#template-variables
- [parameters]: #parameters
- [default layouts]: #+social.cards_layout
- [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
- [Layout options support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.1.10
-
-#### Debugging
-
-The following configuration options are available for debugging:
-
-[`debug`](#+social.debug){ #+social.debug }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `false` – This option enables a special debug mode, which renders
- each layer with an outline and its `x` and `y` offset in order to understand
- how the layout is composed, and optionally renders a grid for easier
- alignment:
-
- ``` yaml
- plugins:
- - social:
- debug: true
- ```
-
- === "With debug mode"
-
- [![Debug mode enabled]][Debug mode enabled]
-
- === "Without"
-
- [![Debug mode disabled]][Debug mode disabled]
-
- [Debug mode enabled]: ../assets/screenshots/social-cards-debug.png
- [Debug mode disabled]: ../assets/screenshots/social-cards-variant.png
-
-[`debug_on_build`](#+social.debug_on_build){ #+social.debug_on_build }
-
-: [:octicons-tag-24: insiders-4.34.1][Insiders] · :octicons-milestone-24:
- Default: `false` – Whether debug mode should be automatically disabled
- [when building your site] with `mkdocs build`. It can be changed with:
-
- ``` yaml
- plugins:
- - social:
- debug_on_build: true
- ```
-
- This setting is just intended to be a safety net, so that when building
- your site social cards definitely won't contain the dot grid or layer
- outlines by accident.
-
-[`debug_grid`](#+social.debug_grid){ #+social.debug_grid }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `true` – This option enables the rendering of a dot grid when
- [`debug`][debug] is enabled (see screenshot above). The grid can be switched
- off with:
-
- ``` yaml
- plugins:
- - social:
- debug_grid: false
- ```
-
-[`debug_grid_step`](#+social.debug_grid_step){ #+social.debug_grid_step }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `32` – This option specifies the step size of the grid in pixels,
- if enabled, which can be used to align elements. It can be changed with:
-
- ``` yaml
- plugins:
- - social:
- debug_grid_step: 64
- ```
-
-[`debug_color`](#+social.debug_color){ #+social.debug_color }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `grey` – This option sets the color of the layer outlines and
- the grid which are rendered when [`debug`][debug] is enabled. It can be
- changed with:
-
- ``` yaml
- plugins:
- - social:
- debug_color: yellow
- ```
-
- [debug]: #+social.debug
- [when building your site]: ../creating-your-site.md#building-your-site
-
-#### Caching
-
-The [built-in social plugin] implements an intelligent caching mechanism,
-ensuring that social cards are only re-generated when they're not contained in
-the cache or their contents change. If any of the variables used in a layout
-changes, the plugin will detect it and re-generate the card.
-
-The following configuration options are available for caching:
-
-[`cache`](#+social.cache){ #+social.cache }
-
-: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
- Default: `true` – Whether the plugin queries its cache for an existing
- artifact before starting a generation job. It's normally not necessary to
- change this setting, except for when debugging the plugin itself. Caching
- can be disabled with:
-
- ``` yaml
- plugins:
- - social:
- cache: false
- ```
-
-[`cache_dir`](#+social.cache_dir){ #+social.cache_dir }
-
-: :octicons-milestone-24: Default: `.cache/plugins/social` – This option
- specifies the file system location of the plugin's cache. It's normally not
- necessary to change this setting, except for when debugging the plugin
- itself. The cache directory can be changed with:
-
- ``` yaml
- plugins:
- - social:
- cache_dir: .cache/plugins/social
- ```
-
- By default, all built-in plugins that implement caching will create a
- `.cache` directory in the same folder your `mkdocs.yml` resides, and create
- subfolders to not interfere with each other. If you use multiple instances
- of this plugin, it could be necessary to change this setting.
-
- [built-in social plugin]: #built-in-social-plugin
- [publishing guide]: ../publishing-your-site.md#with-github-actions
-
## Usage
If you want to adjust the title or set a custom description for the social card,
you can set the front matter [`title`][Changing the title] and
-[`description`][Changing the description] properties, which take precedence over
+[`description`][Changing the description] properties, which take precedence over
the defaults, or use:
-- [`cards_layout_options.title`](#+social.cards_layout_options.title)
-- [`cards_layout_options.description`](#+social.cards_layout_options.description)
+- [`cards_layout_options.title`](../plugins/social.md#option.title)
+- [`cards_layout_options.description`](../plugins/social.md#option.description)
[Changing the title]: ../reference/index.md#setting-the-page-title
[Changing the description]: ../reference/index.md#setting-the-page-description
@@ -602,12 +126,14 @@ comes with CJK characters, e.g. one from the `Noto Sans` font family:
### Changing the layout
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
If you want to use a different layout for a single page (e.g. your landing
page), you can use the `social` front matter property together with the
-[`cards_layout`](#+social.cards_layout) key, exactly as in `mkdocs.yml`:
+[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
+in `mkdocs.yml`:
``` yaml
---
@@ -615,7 +141,7 @@ social:
cards_layout: custom
---
-# Headline
+# Page title
...
```
@@ -623,17 +149,18 @@ You can apply those changes for entire subtrees of your documentation, e.g.,
to generate different social cards for your blog and API reference, by using
the [built-in meta plugin].
- [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+ [built-in meta plugin]: ../plugins/meta.md
### Parametrizing the layout
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
Besides changing the entire layout, you can override all options that a layout
exposes. This means you can parametrize social cards with custom front matter
properties, such as `tags`, `date`, `author` or anything you can think of.
-Simply define [`cards_layout_options`](#+social.cards_layout_options):
+Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
``` yaml
---
@@ -643,7 +170,7 @@ social:
background_image: null # Remove background image
---
-# Headline
+# Page title
...
```
@@ -653,8 +180,9 @@ the [built-in meta plugin].
### Disabling social cards
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
If you wish to disable social cards for a page, simply add the following to the
front matter of the Markdown document:
@@ -665,15 +193,15 @@ social:
cards: false
---
-# Headline
+# Page title
...
```
## Customization
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.33.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
+
[Insiders] ships a ground up rewrite of the [built-in social plugin] and
introduces a brand new layout system based on a combination of YAML and
@@ -755,6 +283,9 @@ haven't defined any layers, the cards are transparent.
The following sections explain how to create custom layouts.
+ [Insiders]: ../insiders/index.md
+ [built-in social plugin]: ../plugins/social.md
+ [Google Fonts]: https://fonts.google.com/
[Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
[study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material-insiders/tree/master/src/plugins/social/layouts
@@ -785,8 +316,8 @@ useful for alignment and composition.
#### Origin
-[:octicons-tag-24: insiders-4.35.0][Insiders] ·
-:octicons-beaker-24: Experimental
+
+
The `origin` for the `x` and `y` values can be changed, so that the layer is
aligned to one of the edges or corners of the layout, e.g., to the bottom right
@@ -934,7 +465,7 @@ automatically scaled down to fit the layer:
![Layer typography shrink]
-While truncating with an ellipsis is the default, auto-shrinking can be enabled
+While truncating with an ellipsis is the default, auto-shrinking can be enabled
by setting `overflow` to `shrink`:
``` yaml hl_lines="7"
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 0eaca3772..1146e98bc 100644
--- a/docs/setup/setting-up-tags.md
+++ b/docs/setup/setting-up-tags.md
@@ -11,8 +11,8 @@ can help to discover relevant information faster.
### Built-in tags plugin
-[:octicons-tag-24: 8.2.0][Tags support] ·
-:octicons-cpu-24: Plugin
+
+
The built-in tags plugin adds the ability to categorize any page with tags
as part of the front matter of the page. In order to add support for tags, add
@@ -23,206 +23,14 @@ plugins:
- tags
```
-The following configuration options are available:
+For a list of all settings, please consult the [plugin documentation].
-[`enabled`](#+tags.enabled){ #+tags.enabled }
-
-: :octicons-milestone-24: Default: `true` – This option specifies whether
- the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
-
- ``` yaml
- plugins:
- - tags:
- enabled: !ENV [CI, false]
- ```
-
-[`tags_file`](#+tags.tags_file){ #+tags.tags_file }
-
-: :octicons-milestone-24: Default: _none_ – This option specifies which page
- should be used to render the tags index. See the section on [adding a tags
- index][tags index] for more information. If this option is specified, tags
- become clickable, pointing to the corresponding section in the tags index:
-
- ``` yaml
- plugins:
- - tags:
- tags_file: tags.md
- ```
-
- The page holding the tags index can be linked anywhere in the `nav` section
- of `mkdocs.yml`. Note, however, that this options is not required – only use
- it if you want a tags index page.
-
-[`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files }
-
-: [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24:
- Default: _none_ – This option specifies additional pages, i.e. to render
- subsets of the [tags index], in order to provide scoped tags indexes for
- specific sections:
-
- ``` yaml
- plugins:
- - tags:
- tags_extra_files:
- compatibility.md:
- - compat # (1)!
- web.md:
- - html
- - js
- - css
- ```
-
- 1. Each page can be assigned a list of [tag identifiers], which must be
- defined as part of `extra.tags` in `mkdocs.yml`:
-
- ``` yaml
- extra:
- tags:
- Compatibility: compat
- HTML5: html
- JavaScript: js
- CSS: css
- ```
-
- In this example, all pages with the tag `Compatibility` will be included
- in the additional tags index on `compatibility.md`, all pages defining
- at least one of the tags `HTML5`, `JavaScript` or `CSS` will be included
- in the additional tags index on `web.md`.
-
- Note that the values listed under each tags extra file must be alphanumeric
- [tag identifiers], not tags themselves. See #3864 for more information.
-
-[`tags_slugify`](#+tags.tags_slugify){ #+tags.tags_slugify }
-
-: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
- Default: `headerid.slugify` – This option specifies which function to use for
- generating URL-compatible slugs from tags. [Python Markdown Extensions]
- includes several Unicode-aware slug functions which are a good choice for
- non-ASCII languages:
-
- === "Unicode"
-
- ``` yaml
- plugins:
- - tags:
- tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
-
- === "Unicode, case-sensitive"
-
- ``` yaml
- plugins:
- - tags:
- tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
-
-[`tags_slugify_separator`](#+tags.tags_slugify_separator){ #+tags.tags_slugify_separator }
-
-: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
- Default: `-` – This option specifies the separator which is used by the slug function. By default, a hyphen is used, but it can
- be changed to any string:
-
- ``` yaml
- plugins:
- - tags:
- tags_slugify_separator: "-"
- ```
-
-[`tags_compare`](#+tags.tags_compare){ #+tags.tags_compare }
-
-: [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
- Default: `None` – This option specifies which function to use when
- comparing tag values for sorting. If you wish to compare tags irregardless
- of casing, use:
-
- ``` yaml
- plugins:
- - tags:
- tags_compare: !!python/name:material.plugins.tags.casefold
- ```
-
- You can also define your own comparison function which must return a tag
- value (as a string) that is used for sorting, and reference it accordingly.
-
-[`tags_compare_reverse`](#+tags.tags_compare_reverse){ #+tags.tags_compare_reverse }
-
-: [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
- Default: `false` – This option specifies whether tags are sorted in reverse
- order. It is mainly provided for completeness. To change direction, use:
-
- ``` yaml
- plugins:
- - tags:
- tags_compare_reverse: true
- ```
-
-[`tags_pages_compare`](#+tags.tags_pages_compare){ #+tags.tags_pages_compare }
-
-: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
- Default: `None` – This option specifies which function to use when
- comparing pages for sorting. If you wish to sort pages, use:
-
- === "Sort by page title"
-
- ``` yaml
- plugins:
- - tags:
- tags_pages_compare: !!python/name:material.plugins.tags.page_title
- ```
-
- === "Sort by page URL"
-
- ``` yaml
- plugins:
- - tags:
- tags_pages_compare: !!python/name:material.plugins.tags.page_url
- ```
-
- You can also define your own comparison function which must return a page
- value (as a string) that is used for sorting, and reference it accordingly.
-
-[`tags_pages_compare_reverse`](#+tags.tags_pages_compare_reverse){ #+tags.tags_pages_compare_reverse }
-
-: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
- Default: `false` – This option specifies whether pages are sorted in reverse
- order. It is mainly provided for completeness. To change direction, use:
-
- ``` yaml
- plugins:
- - tags:
- tags_pages_compare_reverse: true
- ```
-
-[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed }
-
-: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
- Default: _none_ – This option allows the author to define explicitly which
- tags are allowed to be used on pages. If this setting is omitted, the
- [built-in tags plugin] won't check tag names. Use this option to define a
- list of tags in order to catch typos:
-
- ``` yaml
- plugins:
- - tags:
- tags_allowed:
- - HTML5
- - JavaScript
- - CSS
- ```
-
- [Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
- [Insiders]: ../insiders/index.md
- [tag identifiers]: #tag-icons-and-identifiers
- [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+ [plugin documentation]: ../plugins/tags.md
### Tag icons and identifiers
-[:octicons-tag-24: 8.5.0][Tag icons support] ·
-:octicons-beaker-24: Experimental
+
+
Each tag can be associated with an icon, which is then rendered inside the tag.
Before assigning icons to tags, associate each tag with a unique identifier,
@@ -248,7 +56,7 @@ extra:
associated will use the default tag icon which is :material-pound:
Next, each identifier can be associated with an icon, even a [custom icon], by
-adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
+adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
setting:
=== "Tag icon"
@@ -296,7 +104,6 @@ setting:
CSS: css
```
- [Tag icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
[custom icon]: changing-the-logo-and-icons.md#additional-icons
[icon search]: ../reference/icons-emojis.md#search
@@ -305,7 +112,7 @@ setting:
### Adding tags
When the [built-in tags plugin] is enabled, tags can be added for a document
-with the front matter `tags` property. Add the following lines at the top of a
+with the front matter `tags` property. Add the following lines at the top of a
Markdown file:
``` sh
@@ -378,6 +185,6 @@ hide:
- tags
---
-# Document title
+# Page title
...
```
diff --git a/docs/setup/setting-up-the-footer.md b/docs/setup/setting-up-the-footer.md
index 8a94f12b6..ae816e19f 100644
--- a/docs/setup/setting-up-the-footer.md
+++ b/docs/setup/setting-up-the-footer.md
@@ -1,7 +1,7 @@
# Setting up the footer
The footer of your project documentation is a great place to add links to
-websites or platforms you or your company are using as additional marketing
+websites or platforms you or your company are using as additional marketing
channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
configure via `mkdocs.yml`.
@@ -10,8 +10,8 @@ configure via `mkdocs.yml`.
### Navigation
-[:octicons-tag-24: 9.0.0][Navigation footer support] ·
-:octicons-unlock-24: Feature flag
+
+
The footer can include links to the previous and next page of the current page.
If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
@@ -22,15 +22,13 @@ theme:
- navigation.footer
```
- [Navigation footer support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
### Social links
-[:octicons-tag-24: 1.0.0][Social links support] ·
-:octicons-milestone-24: Default: _none_
+
+
-Social links are rendered next to the copyright notice as part of the
-footer of your project documentation. Add a list of social links in `mkdocs.yml`
+Social links are rendered next to the copyright notice as part of the
+footer of your project documentation. Add a list of social links in `mkdocs.yml`
with:
``` yaml
@@ -53,9 +51,9 @@ extra:
The following properties are available for each link:
-[`icon`](#+social.icon){ #+social.icon }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:
This property must contain a valid path to any icon bundled with the theme,
or the build will not succeed. Some popular choices:
@@ -72,10 +70,10 @@ The following properties are available for each link:
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-discord: – `fontawesome/brands/discord`
-[`link`](#+social.link){ #+social.link }
+
-: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
- This property must be set to a relative or absolute URL including the URI
+:
+ This property must be set to a relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== ":fontawesome-brands-mastodon: Mastodon"
@@ -96,10 +94,10 @@ The following properties are available for each link:
link: mailto:
```
-[`name`](#+social.name){ #+social.name }
+
-: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
- This property is used as the link's `title` attribute and can be set to a
+:
+ This property is used as the link's `title` attribute and can be set to a
discernable name to improve accessibility:
``` yaml
@@ -111,13 +109,12 @@ The following properties are available for each link:
```
[icon search]: ../reference/icons-emojis.md#search
- [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[rel=me]: https://docs.joinmastodon.org/user/profile/#verification
### Copyright notice
-[:octicons-tag-24: 0.1.0][Copyright notice support] ·
-:octicons-milestone-24: Default: _none_
+
+
A custom copyright banner can be rendered as part of the footer, which is
displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@@ -126,12 +123,10 @@ displayed next to the social links. It can be defined as part of `mkdocs.yml`:
copyright: Copyright © 2016 - 2020 Martin Donath
```
- [Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-
### Generator notice
-[:octicons-tag-24: 7.3.0][Generator notice support] ·
-:octicons-milestone-24: Default: `true`
+
+
The footer displays a _Made with Material for MkDocs_ notice to denote how
the site was generated. The notice can be removed with the following option
@@ -155,7 +150,6 @@ extra:
Thus, if you remove this notice, please consider [sponsoring][Insiders] the
project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
- [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Insiders]: ../insiders/index.md
## Usage
@@ -163,7 +157,7 @@ extra:
### Hiding prev/next links
The footer navigation showing links to the previous and next page can be hidden
-with the front matter `hide` property. Add the following lines at the top of a
+with the front matter `hide` property. Add the following lines at the top of a
Markdown file:
``` yaml
@@ -172,7 +166,7 @@ hide:
- footer
---
-# Document title
+# Page title
...
```
@@ -180,14 +174,13 @@ hide:
### Custom copyright
-[:octicons-tag-24: 8.0.0][Custom copyright support] ·
-:octicons-file-symlink-file-24: Customization
+
+
In order to customize and override the [copyright notice], [extend the theme]
and [override the `copyright.html` partial][overriding partials], which normally
includes the `copyright` property set in `mkdocs.yml`.
- [Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[copyright notice]: #copyright-notice
[generator notice]: #generator-notice
[extend the theme]: ../customization.md#extending-the-theme
diff --git a/docs/setup/setting-up-the-header.md b/docs/setup/setting-up-the-header.md
index 9a9009436..a8548a381 100644
--- a/docs/setup/setting-up-the-header.md
+++ b/docs/setup/setting-up-the-header.md
@@ -1,6 +1,6 @@
# Setting up the header
-Material for MkDocs' header can be customized to show an announcement bar that
+Material for MkDocs' header can be customized to show an announcement bar that
disappears upon scrolling, and provides some options for further configuration.
It also includes the [search bar] and a place to display your project's
[git repository], as explained in those dedicated guides.
@@ -12,8 +12,8 @@ It also includes the [search bar] and a place to display your project's
### Automatic hiding
-[:octicons-tag-24: 6.2.0][Automatic hiding support] ·
-:octicons-unlock-24: Feature flag
+
+
When autohiding is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the
@@ -25,12 +25,10 @@ theme:
- header.autohide
```
- [Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
-
### Announcement bar
-[:octicons-tag-24: 5.0.0][Announcement bar support] ·
-:octicons-file-symlink-file-24: Customization
+
+
Material for MkDocs includes an announcement bar, which is the perfect place to
display project news or other important information to the user. When the user
@@ -46,15 +44,14 @@ block][overriding blocks], which is empty by default:
{% endblock %}
```
- [Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[extend the theme]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
#### Mark as read
-[:octicons-tag-24: 8.4.0][dismiss support] ·
-:octicons-unlock-24: Feature flag ·
-:octicons-beaker-24: Experimental
+
+
+
In order to render temporary announcements that can be marked as read by the
user, a button to dismiss the current announcement can be included. Add the
@@ -72,5 +69,4 @@ automatically.
[Scroll to the top of this page][top] to see it in action.
- [dismiss support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[top]: #
diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md
index a4bc3d105..80877a6d5 100644
--- a/docs/setup/setting-up-versioning.md
+++ b/docs/setup/setting-up-versioning.md
@@ -11,8 +11,8 @@ documentation remain untouched.
### Versioning
-[:octicons-tag-24: 7.0.0][Versioning support] ·
-[:octicons-package-24: Utility][mike]
+
+
[mike] makes it easy to deploy multiple versions of your project documentation.
It integrates natively with Material for MkDocs and can be enabled via
@@ -51,15 +51,14 @@ Check out the versioning example to see it in action –
to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to.
- [Versioning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Version selector preview]: ../assets/screenshots/versioning.png
[version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike
### Version warning
-[:octicons-tag-24: 8.0.0][Version warning support] ·
-:octicons-file-symlink-file-24: Customization
+
+
If you're using versioning, you might want to display a warning when the user
visits any other version than the latest version. Using [theme extension],
@@ -76,7 +75,7 @@ you can [override the `outdated` block][overriding blocks]:
{% endblock %}
```
-1. Given this value for the `href` attribute, the link will always redirect to
+1. Given this value for the `href` attribute, the link will always redirect to
the root of your site, which will then redirect to the latest version. This
ensures that older versions of your site do not depend on a specific alias,
e.g. `latest`, to allow for changing the alias later on without breaking
@@ -113,7 +112,6 @@ extra:
Make sure one alias matches the [default version], as this is where users are
redirected to.
- [Version warning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
[Version warning preview]: ../assets/screenshots/version-warning.png
@@ -121,7 +119,7 @@ redirected to.
## Usage
-While this section outlines the basic workflow for publishing new versions,
+While this section outlines the basic workflow for publishing new versions,
it's best to check out [mike's documentation][mike] to make yourself familiar
with its mechanics.
diff --git a/includes/mkdocs.md b/includes/mkdocs.md
new file mode 100644
index 000000000..fc3629eae
--- /dev/null
+++ b/includes/mkdocs.md
@@ -0,0 +1,11 @@
+ [mkdocs]: https://www.mkdocs.org
+ [mkdocs.dotfiles]: https://www.mkdocs.org/dev-guide/themes/#dot-files
+ [mkdocs.metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
+ [mkdocs.env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+ [mkdocs.docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+ [mkdocs.site_dir]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+ [mkdocs.site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+ [mkdocs.nav]: https://www.mkdocs.org/user-guide/configuration/#nav
+ [mkdocs.plugins]: https://www.mkdocs.org/user-guide/configuration/#plugins
+ [mkdocs.strict]: https://www.mkdocs.org/user-guide/configuration/#strict
+ [mkdocs.use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
diff --git a/material/.overrides/assets/stylesheets/custom.024fa163.min.css b/material/.overrides/assets/stylesheets/custom.024fa163.min.css
new file mode 100644
index 000000000..3316f1fcd
--- /dev/null
+++ b/material/.overrides/assets/stylesheets/custom.024fa163.min.css
@@ -0,0 +1 @@
+@keyframes heart{0%,40%,80%,to{transform:scale(1)}20%,60%{transform:scale(1.15)}}.md-typeset .twitter{color:#00acee}.md-typeset .mastodon{color:#897ff8}.md-typeset .mdx-video{width:auto}.md-typeset .mdx-video__inner{height:0;padding-bottom:56.138%;position:relative;width:100%}.md-typeset .mdx-video iframe{border:none;height:100%;left:0;overflow:hidden;position:absolute;top:0;width:100%}.md-typeset .mdx-heart{animation:heart 1s infinite}.md-typeset .mdx-insiders{color:#e91e63}.md-typeset .mdx-badge{font-size:.85em}.md-typeset .mdx-badge--heart{--md-typeset-a-color:#e92063;--md-accent-fg-color:#ff4281;--md-accent-fg-color--transparent:#e920631a}.md-typeset .mdx-badge--heart .twemoji{animation:heart 1s infinite}[dir=ltr] .md-typeset .mdx-badge__icon{border-top-left-radius:.1rem}[dir=rtl] .md-typeset .mdx-badge__icon{border-top-right-radius:.1rem}[dir=ltr] .md-typeset .mdx-badge__icon{border-bottom-left-radius:.1rem}[dir=rtl] .md-typeset .mdx-badge__icon{border-bottom-right-radius:.1rem}.md-typeset .mdx-badge__icon{background:var(--md-accent-fg-color--transparent);padding:.2rem}.md-typeset .mdx-badge__icon:last-child{border-radius:.1rem}[dir=ltr] .md-typeset .mdx-badge__text{border-top-right-radius:.1rem}[dir=rtl] .md-typeset .mdx-badge__text{border-top-left-radius:.1rem}[dir=ltr] .md-typeset .mdx-badge__text{border-bottom-right-radius:.1rem}[dir=rtl] .md-typeset .mdx-badge__text{border-bottom-left-radius:.1rem}.md-typeset .mdx-badge__text{box-shadow:0 0 0 1px inset var(--md-accent-fg-color--transparent);padding:.2rem .3rem}.md-typeset .mdx-switch button{cursor:pointer;transition:opacity .25s}.md-typeset .mdx-switch button:focus,.md-typeset .mdx-switch button:hover{opacity:.75}.md-typeset .mdx-switch button>code{background-color:var(--md-primary-fg-color);color:var(--md-primary-bg-color);display:block}.md-typeset .mdx-columns ol,.md-typeset .mdx-columns ul{-moz-columns:2;column-count:2}@media screen and (max-width:29.9375em){.md-typeset .mdx-columns ol,.md-typeset .mdx-columns ul{-moz-columns:initial;columns:initial}}.md-typeset .mdx-columns li{-moz-column-break-inside:avoid;break-inside:avoid}.md-typeset .mdx-flags{margin:2em auto}.md-typeset .mdx-flags ol{list-style:none}.md-typeset .mdx-flags ol li{margin-bottom:1em}.md-typeset .mdx-flags__item{display:flex;gap:.6rem}.md-typeset .mdx-flags__content{display:flex;flex:1;flex-direction:column}.md-typeset .mdx-flags__content span{align-items:baseline;display:inline-flex;justify-content:space-between}.md-typeset .mdx-flags__content>span:nth-child(2){font-size:80%}.md-typeset .mdx-flags__content code{float:right}.md-typeset .mdx-social{height:min(27rem,80vw);position:relative}.md-typeset .mdx-social:hover .mdx-social__image{background-color:#e4e4e40d}.md-typeset .mdx-social__layer{margin-top:4rem;position:absolute;transform-style:preserve-3d;transition:.25s cubic-bezier(.7,0,.3,1)}.md-typeset .mdx-social__layer:hover .mdx-social__label{opacity:1}.md-typeset .mdx-social__layer:hover .mdx-social__image{background-color:#7f7f7ffc}.md-typeset .mdx-social__layer:hover~.mdx-social__layer{opacity:0}.md-typeset .mdx-social__image{box-shadow:-.25rem .25rem .5rem #0000000d;transform:rotate(-40deg) skew(15deg,15deg) scale(.7);transition:all .25s}.md-typeset .mdx-social__image img{display:block}.md-typeset .mdx-social__label{background-color:var(--md-default-fg-color--light);color:var(--md-default-bg-color);display:block;opacity:0;padding:.2rem .4rem;position:absolute;transition:all .25s}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(6){transform:translateY(-30px)}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(5){transform:translateY(-20px)}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(4){transform:translateY(-10px)}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(3){transform:translateY(0)}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(2){transform:translateY(10px)}.md-typeset .mdx-social:hover .mdx-social__layer:first-child{transform:translateY(20px)}.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(0){transform:translateY(30px)}.md-banner{color:var(--md-footer-fg-color--lighter)}.md-banner strong{white-space:nowrap}.md-banner a,.md-banner strong{color:var(--md-footer-fg-color)}.md-banner a:focus,.md-banner a:hover{color:currentcolor}.md-banner a:focus .twemoji,.md-banner a:hover .twemoji{background-color:var(--md-footer-fg-color);box-shadow:none}.md-banner .twemoji{border-radius:100%;box-shadow:inset 0 0 0 .05rem currentcolor;display:inline-block;height:1.2rem;padding:.25rem;transition:all .25s;vertical-align:bottom;width:1.2rem}.md-banner .twemoji svg{display:block;max-height:none}.mdx-container{background:url("data:image/svg+xml;utf8,
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from re import Match
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+# @todo
+def on_page_markdown(
+ markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+):
+
+ # Replace callback
+ def replace(match: Match):
+ type, args = match.groups()
+ args = args.strip()
+ if type == "version":
+ if args.startswith("insiders-"):
+ return _badge_for_version_insiders(args, page, files)
+ else:
+ return _badge_for_version(args, page, files)
+ elif type == "sponsors": return _badge_for_sponsors(page, files)
+ elif type == "flag": return flag(args, page, files)
+ elif type == "option": return option(args)
+ elif type == "setting": return setting(args)
+ elif type == "feature": return _badge_for_feature(args, page, files)
+ elif type == "plugin": return _badge_for_plugin(args, page, files)
+ elif type == "extension": return _badge_for_extension(args, page, files)
+ elif type == "utility": return _badge_for_utility(args, page, files)
+ elif type == "default":
+ if args == "none": return _badge_for_default_none(page, files)
+ elif args == "computed": return _badge_for_default_computed(page, files)
+ else: return _badge_for_default(args, page, files)
+
+ # Otherwise, raise an error
+ raise RuntimeError(f"Unknown shortcode: {type}")
+
+ # Find and replace all external asset URLs in current page
+ return re.sub(
+ r"",
+ replace, markdown, flags = re.I | re.M
+ )
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Create a flag of a specific type
+def flag(args: str, page: Page, files: Files):
+ type, *_ = args.split(" ", 1)
+ if type == "experimental": return _badge_for_experimental(page, files)
+ elif type == "required": return _badge_for_required(page, files)
+ elif type == "customization": return _badge_for_customization(page, files)
+ elif type == "metadata": return _badge_for_metadata(page, files)
+ elif type == "multiple": return _badge_for_multiple(page, files)
+ raise RuntimeError(f"Unknown type: {type}")
+
+# Create a linkable option
+def option(type: str):
+ _, *_, name = re.split(r"[.:]", type)
+ return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
+
+# Create a linkable setting - @todo append them to the bottom of the page
+def setting(type: str):
+ _, *_, name = re.split(r"[.*]", type)
+ return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
+
+# -----------------------------------------------------------------------------
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve_path(path: str, page: Page, files: Files):
+ path, anchor, *_ = f"{path}#".split("#")
+ path = _resolve(files.get_file_from_path(path), page)
+ return "#".join([path, anchor]) if anchor else path
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve(file: File, page: Page):
+ path = posixpath.relpath(file.src_uri, page.file.src_uri)
+ return posixpath.sep.join(path.split(posixpath.sep)[1:])
+
+# -----------------------------------------------------------------------------
+
+# Create badge
+def _badge(icon: str, text: str = "", type: str = ""):
+ classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
+ return "".join([
+ f"",
+ *([f"{icon} "] if icon else []),
+ *([f"{text} "] if text else []),
+ f" ",
+ ])
+
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+ icon = "material-heart"
+ href = _resolve_path("insiders/index.md", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Sponsors only')",
+ type = "heart"
+ )
+
+# Create badge for version
+def _badge_for_version(text: str, page: Page, files: Files):
+ spec = text
+ path = f"changelog/index.md#{spec}"
+
+ # Return badge
+ icon = "material-tag-outline"
+ href = _resolve_path("conventions.md#version", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Minimum version')",
+ text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+ )
+
+# Create badge for version of Insiders
+def _badge_for_version_insiders(text: str, page: Page, files: Files):
+ spec = text.replace("insiders-", "")
+ path = f"insiders/changelog.md#{spec}"
+
+ # Return badge
+ icon = "material-tag-heart-outline"
+ href = _resolve_path("conventions.md#version-insiders", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Minimum version')",
+ text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+ )
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+ icon = "material-toggle-switch"
+ href = _resolve_path("conventions.md#feature", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Optional feature')",
+ text = text
+ )
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+ icon = "material-floppy"
+ href = _resolve_path("conventions.md#plugin", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Plugin')",
+ text = text
+ )
+
+# Create badge for extension
+def _badge_for_extension(text: str, page: Page, files: Files):
+ icon = "material-language-markdown"
+ href = _resolve_path("conventions.md#extension", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Markdown extension')",
+ text = text
+ )
+
+# Create badge for utility
+def _badge_for_utility(text: str, page: Page, files: Files):
+ icon = "material-package-variant"
+ href = _resolve_path("conventions.md#utility", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Third-party utility')",
+ text = text
+ )
+
+# Create badge for default value
+def _badge_for_default(text: str, page: Page, files: Files):
+ icon = "material-water"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value')",
+ text = text
+ )
+
+# Create badge for empty default value
+def _badge_for_default_none(page: Page, files: Files):
+ icon = "material-water-outline"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value is empty')"
+ )
+
+# Create badge for computed default value
+def _badge_for_default_computed(page: Page, files: Files):
+ icon = "material-water-check"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value is computed')"
+ )
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+ icon = "material-list-box-outline"
+ href = _resolve_path("conventions.md#metadata", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Metadata property')"
+ )
+
+# Create badge for required value flag
+def _badge_for_required(page: Page, files: Files):
+ icon = "material-alert"
+ href = _resolve_path("conventions.md#required", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Required value')"
+ )
+
+# Create badge for customization flag
+def _badge_for_customization(page: Page, files: Files):
+ icon = "material-brush-variant"
+ href = _resolve_path("conventions.md#customization", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Customization')"
+ )
+
+# Create badge for multiple instance flag
+def _badge_for_multiple(page: Page, files: Files):
+ icon = "material-inbox-multiple"
+ href = _resolve_path("conventions.md#multiple-instances", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Multiple instances')"
+ )
+
+# Create badge for experimental flag
+def _badge_for_experimental(page: Page, files: Files):
+ icon = "material-flask-outline"
+ href = _resolve_path("conventions.md#experimental", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Experimental')"
+ )
diff --git a/material/.overrides/main.html b/material/.overrides/main.html
index bec1d1558..28b26eda8 100644
--- a/material/.overrides/main.html
+++ b/material/.overrides/main.html
@@ -3,7 +3,7 @@
-#}
{% extends "base.html" %}
{% block extrahead %}
- @squidfunk on
diff --git a/material/assets/stylesheets/main.046329b4.min.css b/material/assets/stylesheets/main.0efb648e.min.css
similarity index 55%
rename from material/assets/stylesheets/main.046329b4.min.css
rename to material/assets/stylesheets/main.0efb648e.min.css
index 77ac5aae8..5c8c99f31 100644
--- a/material/assets/stylesheets/main.046329b4.min.css
+++ b/material/assets/stylesheets/main.0efb648e.min.css
@@ -1 +1 @@
-@charset "UTF-8";html{-webkit-text-size-adjust:none;-moz-text-size-adjust:none;text-size-adjust:none;box-sizing:border-box}*,:after,:before{box-sizing:inherit}@media (prefers-reduced-motion){*,:after,:before{transition:none!important}}body{margin:0}a,button,input,label{-webkit-tap-highlight-color:transparent}a{color:inherit;text-decoration:none}hr{border:0;box-sizing:initial;display:block;height:.05rem;overflow:visible;padding:0}small{font-size:80%}sub,sup{line-height:1em}img{border-style:none}table{border-collapse:initial;border-spacing:0}td,th{font-weight:400;vertical-align:top}button{background:#0000;border:0;font-family:inherit;font-size:inherit;margin:0;padding:0}input{border:0;outline:none}:root{--md-primary-fg-color:#4051b5;--md-primary-fg-color--light:#5d6cc0;--md-primary-fg-color--dark:#303fa1;--md-primary-bg-color:#fff;--md-primary-bg-color--light:#ffffffb3;--md-accent-fg-color:#526cfe;--md-accent-fg-color--transparent:#526cfe1a;--md-accent-bg-color:#fff;--md-accent-bg-color--light:#ffffffb3}[data-md-color-scheme=default]{color-scheme:light}[data-md-color-scheme=default] img[src$="#gh-dark-mode-only"],[data-md-color-scheme=default] img[src$="#only-dark"]{display:none}:root,[data-md-color-scheme=default]{--md-default-fg-color:#000000de;--md-default-fg-color--light:#0000008a;--md-default-fg-color--lighter:#00000052;--md-default-fg-color--lightest:#00000012;--md-default-bg-color:#fff;--md-default-bg-color--light:#ffffffb3;--md-default-bg-color--lighter:#ffffff4d;--md-default-bg-color--lightest:#ffffff1f;--md-code-fg-color:#36464e;--md-code-bg-color:#f5f5f5;--md-code-hl-color:#ffff0080;--md-code-hl-number-color:#d52a2a;--md-code-hl-special-color:#db1457;--md-code-hl-function-color:#a846b9;--md-code-hl-constant-color:#6e59d9;--md-code-hl-keyword-color:#3f6ec6;--md-code-hl-string-color:#1c7d4d;--md-code-hl-name-color:var(--md-code-fg-color);--md-code-hl-operator-color:var(--md-default-fg-color--light);--md-code-hl-punctuation-color:var(--md-default-fg-color--light);--md-code-hl-comment-color:var(--md-default-fg-color--light);--md-code-hl-generic-color:var(--md-default-fg-color--light);--md-code-hl-variable-color:var(--md-default-fg-color--light);--md-typeset-color:var(--md-default-fg-color);--md-typeset-a-color:var(--md-primary-fg-color);--md-typeset-mark-color:#ffff0080;--md-typeset-del-color:#f5503d26;--md-typeset-ins-color:#0bd57026;--md-typeset-kbd-color:#fafafa;--md-typeset-kbd-accent-color:#fff;--md-typeset-kbd-border-color:#b8b8b8;--md-typeset-table-color:#0000001f;--md-typeset-table-color--light:rgba(0,0,0,.035);--md-admonition-fg-color:var(--md-default-fg-color);--md-admonition-bg-color:var(--md-default-bg-color);--md-warning-fg-color:#000000de;--md-warning-bg-color:#ff9;--md-footer-fg-color:#fff;--md-footer-fg-color--light:#ffffffb3;--md-footer-fg-color--lighter:#ffffff73;--md-footer-bg-color:#000000de;--md-footer-bg-color--dark:#00000052;--md-shadow-z1:0 0.2rem 0.5rem #0000000d,0 0 0.05rem #0000001a;--md-shadow-z2:0 0.2rem 0.5rem #0000001a,0 0 0.05rem #00000040;--md-shadow-z3:0 0.2rem 0.5rem #0003,0 0 0.05rem #00000059}.md-icon svg{fill:currentcolor;display:block;height:1.2rem;width:1.2rem}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;--md-text-font-family:var(--md-text-font,_),-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif;--md-code-font-family:var(--md-code-font,_),SFMono-Regular,Consolas,Menlo,monospace}aside,body,input{font-feature-settings:"kern","liga";color:var(--md-typeset-color);font-family:var(--md-text-font-family)}code,kbd,pre{font-feature-settings:"kern";font-family:var(--md-code-font-family)}:root{--md-typeset-table-sort-icon:url('data:image/svg+xml;charset=utf-8,
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from re import Match
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+# @todo
+def on_page_markdown(
+ markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+):
+
+ # Replace callback
+ def replace(match: Match):
+ type, args = match.groups()
+ args = args.strip()
+ if type == "version":
+ if args.startswith("insiders-"):
+ return _badge_for_version_insiders(args, page, files)
+ else:
+ return _badge_for_version(args, page, files)
+ elif type == "sponsors": return _badge_for_sponsors(page, files)
+ elif type == "flag": return flag(args, page, files)
+ elif type == "option": return option(args)
+ elif type == "setting": return setting(args)
+ elif type == "feature": return _badge_for_feature(args, page, files)
+ elif type == "plugin": return _badge_for_plugin(args, page, files)
+ elif type == "extension": return _badge_for_extension(args, page, files)
+ elif type == "utility": return _badge_for_utility(args, page, files)
+ elif type == "default":
+ if args == "none": return _badge_for_default_none(page, files)
+ elif args == "computed": return _badge_for_default_computed(page, files)
+ else: return _badge_for_default(args, page, files)
+
+ # Otherwise, raise an error
+ raise RuntimeError(f"Unknown shortcode: {type}")
+
+ # Find and replace all external asset URLs in current page
+ return re.sub(
+ r"",
+ replace, markdown, flags = re.I | re.M
+ )
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Create a flag of a specific type
+def flag(args: str, page: Page, files: Files):
+ type, *_ = args.split(" ", 1)
+ if type == "experimental": return _badge_for_experimental(page, files)
+ elif type == "required": return _badge_for_required(page, files)
+ elif type == "customization": return _badge_for_customization(page, files)
+ elif type == "metadata": return _badge_for_metadata(page, files)
+ elif type == "multiple": return _badge_for_multiple(page, files)
+ raise RuntimeError(f"Unknown type: {type}")
+
+# Create a linkable option
+def option(type: str):
+ _, *_, name = re.split(r"[.:]", type)
+ return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
+
+# Create a linkable setting - @todo append them to the bottom of the page
+def setting(type: str):
+ _, *_, name = re.split(r"[.*]", type)
+ return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
+
+# -----------------------------------------------------------------------------
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve_path(path: str, page: Page, files: Files):
+ path, anchor, *_ = f"{path}#".split("#")
+ path = _resolve(files.get_file_from_path(path), page)
+ return "#".join([path, anchor]) if anchor else path
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve(file: File, page: Page):
+ path = posixpath.relpath(file.src_uri, page.file.src_uri)
+ return posixpath.sep.join(path.split(posixpath.sep)[1:])
+
+# -----------------------------------------------------------------------------
+
+# Create badge
+def _badge(icon: str, text: str = "", type: str = ""):
+ classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
+ return "".join([
+ f"",
+ *([f"{icon} "] if icon else []),
+ *([f"{text} "] if text else []),
+ f" ",
+ ])
+
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+ icon = "material-heart"
+ href = _resolve_path("insiders/index.md", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Sponsors only')",
+ type = "heart"
+ )
+
+# Create badge for version
+def _badge_for_version(text: str, page: Page, files: Files):
+ spec = text
+ path = f"changelog/index.md#{spec}"
+
+ # Return badge
+ icon = "material-tag-outline"
+ href = _resolve_path("conventions.md#version", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Minimum version')",
+ text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+ )
+
+# Create badge for version of Insiders
+def _badge_for_version_insiders(text: str, page: Page, files: Files):
+ spec = text.replace("insiders-", "")
+ path = f"insiders/changelog.md#{spec}"
+
+ # Return badge
+ icon = "material-tag-heart-outline"
+ href = _resolve_path("conventions.md#version-insiders", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Minimum version')",
+ text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+ )
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+ icon = "material-toggle-switch"
+ href = _resolve_path("conventions.md#feature", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Optional feature')",
+ text = text
+ )
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+ icon = "material-floppy"
+ href = _resolve_path("conventions.md#plugin", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Plugin')",
+ text = text
+ )
+
+# Create badge for extension
+def _badge_for_extension(text: str, page: Page, files: Files):
+ icon = "material-language-markdown"
+ href = _resolve_path("conventions.md#extension", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Markdown extension')",
+ text = text
+ )
+
+# Create badge for utility
+def _badge_for_utility(text: str, page: Page, files: Files):
+ icon = "material-package-variant"
+ href = _resolve_path("conventions.md#utility", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Third-party utility')",
+ text = text
+ )
+
+# Create badge for default value
+def _badge_for_default(text: str, page: Page, files: Files):
+ icon = "material-water"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value')",
+ text = text
+ )
+
+# Create badge for empty default value
+def _badge_for_default_none(page: Page, files: Files):
+ icon = "material-water-outline"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value is empty')"
+ )
+
+# Create badge for computed default value
+def _badge_for_default_computed(page: Page, files: Files):
+ icon = "material-water-check"
+ href = _resolve_path("conventions.md#default", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Default value is computed')"
+ )
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+ icon = "material-list-box-outline"
+ href = _resolve_path("conventions.md#metadata", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Metadata property')"
+ )
+
+# Create badge for required value flag
+def _badge_for_required(page: Page, files: Files):
+ icon = "material-alert"
+ href = _resolve_path("conventions.md#required", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Required value')"
+ )
+
+# Create badge for customization flag
+def _badge_for_customization(page: Page, files: Files):
+ icon = "material-brush-variant"
+ href = _resolve_path("conventions.md#customization", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Customization')"
+ )
+
+# Create badge for multiple instance flag
+def _badge_for_multiple(page: Page, files: Files):
+ icon = "material-inbox-multiple"
+ href = _resolve_path("conventions.md#multiple-instances", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Multiple instances')"
+ )
+
+# Create badge for experimental flag
+def _badge_for_experimental(page: Page, files: Files):
+ icon = "material-flask-outline"
+ href = _resolve_path("conventions.md#experimental", page, files)
+ return _badge(
+ icon = f"[:{icon}:]({href} 'Experimental')"
+ )
diff --git a/src/assets/stylesheets/main/components/_tag.scss b/src/assets/stylesheets/main/components/_tag.scss
index 95551ab3c..ac8d39050 100644
--- a/src/assets/stylesheets/main/components/_tag.scss
+++ b/src/assets/stylesheets/main/components/_tag.scss
@@ -50,7 +50,6 @@
font-weight: 700;
line-height: 1.6;
letter-spacing: initial;
- vertical-align: middle;
background: var(--md-default-fg-color--lightest);
border-radius: px2rem(48px);
diff --git a/src/plugins/info/plugin.py b/src/plugins/info/plugin.py
index 41dc0373f..7c6fdc17e 100644
--- a/src/plugins/info/plugin.py
+++ b/src/plugins/info/plugin.py
@@ -80,6 +80,10 @@ class InfoPlugin(BasePlugin[InfoConfig]):
log.error("Please upgrade to the latest version.")
self._help_on_versions_and_exit(present, current)
+ # Exit if archive creation is disabled
+ if not self.config.archive:
+ sys.exit(1)
+
# Print message that we're creating a bug report
log.info("Started archive creation for bug report")
diff --git a/src/plugins/search/config.py b/src/plugins/search/config.py
index e601fb8fd..e150fbb36 100644
--- a/src/plugins/search/config.py
+++ b/src/plugins/search/config.py
@@ -41,6 +41,9 @@ pipeline = ("stemmer", "stopWordFilter", "trimmer")
# Search plugin configuration
class SearchConfig(Config):
+ enabled = Type(bool, default = True)
+
+ # Settings for search
lang = Optional(LangOption())
separator = Optional(Type(str))
pipeline = ListOfItems(Choice(pipeline), default = [])
diff --git a/src/plugins/search/plugin.py b/src/plugins/search/plugin.py
index 33fe4bbf7..cc88986b1 100644
--- a/src/plugins/search/plugin.py
+++ b/src/plugins/search/plugin.py
@@ -58,6 +58,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Initialize plugin
def on_config(self, config):
+ if not self.config.enabled:
+ return
+
+ # Retrieve default value for language
if not self.config.lang:
self.config.lang = [self._translate(
config, "search.config.lang"
@@ -104,6 +108,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Add page to search index
def on_page_context(self, context, *, page, config, nav):
+ if not self.config.enabled:
+ return
+
+ # Index page
self.search_index.add_entry_from_context(page)
page.content = re.sub(
r"\s?data-search-\w+=\"[^\"]+\"",
@@ -113,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Generate search index
def on_post_build(self, *, config):
+ if not self.config.enabled:
+ return
+
+ # Write search index
base = os.path.join(config.site_dir, "search")
path = os.path.join(base, "search_index.json")
diff --git a/src/plugins/social/plugin.py b/src/plugins/social/plugin.py
index 5c550c7d6..b7e0781a0 100644
--- a/src/plugins/social/plugin.py
+++ b/src/plugins/social/plugin.py
@@ -79,7 +79,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
if "Image" not in globals():
raise PluginError(
"Required dependencies of \"social\" plugin not found. "
- "Install with: pip install pillow cairosvg"
+ "Install with: pip install \"mkdocs-material[imaging]\""
)
# Move color options