` 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:
+ - plugins/search.md # (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..3c4f72669
--- /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 meta file name 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..760c01b90
--- /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..e989e7d7d
--- /dev/null
+++ b/docs/plugins/projects.md
@@ -0,0 +1,365 @@
+---
+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.
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the location or name of configuration files the
+plugin will look for when scanning the [`projects` directory]
+[config.projects_dir]. Adjusting this setting can be necessary when the
+configuration files are located in subdirectories of projects, e.g.
+`docs/mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_files: "**/mkdocs.yml" # (1)!
+```
+
+1. If all projects share the same location for their configuration files, e.g.,
+ `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
+ to resolve than a `**` glob pattern.
+
+ ``` yaml
+ plugins:
+ - projects:
+ projects_config_files: "*/docs/mkdocs.yml"
+ ```
+
+ This configuration fits the following directory structure, which is quite
+ common for projects using git submodules:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ ├─ projects/
+ │ ├─ git-submodule-a/
+ │ │ └─ docs/
+ │ │ └─ mkdocs.yml
+ │ └─ git-submodule-b/
+ │ └─ docs/
+ │ └─ mkdocs.yml
+ └─ mkdocs.yml
+ ```
+
+The provided path is resolved from the [`projects` directory]
+[config.projects_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to transform the configuration of each project as read from
+`mkdocs.yml` before it is built, which allows for adjusting the configuration
+of each project when building them together, but leave them untouched when
+building them individually:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_transform: !!python/name:projects.transform
+```
+
+The provided module and function name are looked up in Python's [module search
+path]. You need to add your root directory to the search path when building
+your site, so Python can resolve it. The easiest way is to add the working
+directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
+
+``` .sh
+export PYTHONPATH=.
+```
+
+!!! tip "How to define a configuration transformation function"
+
+ The [`python/name`][python-name] tag is provided by [PyYAML] and must point
+ to a valid module and function name within Python's [module search path].
+ The plugin passes the `project` and top-level `config` objects to the
+ function.
+
+ As an example, we can inherit the [`use_directory_urls`]
+ [mkdocs.use_directory_urls] setting for all projects from the top-level
+ configuration:
+
+ ``` py title="projects/__init__.py"
+ from mkdocs.config.defaults import MkDocsConfig
+
+ # Transform project configuration
+ def transform(project: MkDocsConfig, config: MkDocsConfig):
+ project.use_directory_urls = config.use_directory_urls
+ ```
+
+ [module search path]: https://docs.python.org/3/library/sys_path_init.html
+ [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+ [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
+ [PyYAML]: https://pyyaml.org/
+
+### 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 74%
rename from docs/setup/dependencies/image-processing.md
rename to docs/plugins/requirements/image-processing.md
index ae053e05f..c53cbf6ad 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]: ../../plugins/optimize.md
[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/publishing-your-site.md b/docs/publishing-your-site.md
index 8549c3bb8..3ec02f150 100644
--- a/docs/publishing-your-site.md
+++ b/docs/publishing-your-site.md
@@ -34,24 +34,36 @@ contents:
deploy:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: 3.x
- - uses: actions/cache@v2
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+ - uses: actions/cache@v3
with:
- key: ${{ github.ref }}
+ key: mkdocs-material-${{ env.cache_id }}
path: .cache
- - run: pip install mkdocs-material # (3)!
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install mkdocs-material # (4)!
- run: mkdocs gh-deploy --force
```
- 1. You can change the name to your liking.
+ 1. You can change the name to your liking.
2. At some point, GitHub renamed `master` to `main`. If your default branch
is named `master`, you can safely remove `main`, vice versa.
- 3. This is the place to install further [MkDocs plugins] or Markdown
+ 3. Store the `cache_id` environmental variable to access it later during cache
+ `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+ - The `--utc` option makes sure that each workflow runner uses the same time zone.
+ - The `%V` format assures a cache update once a week.
+ - You can change the format to `%F` to have daily cache updates.
+
+ You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+ 4. This is the place to install further [MkDocs plugins] or Markdown
extensions with `pip` to be used during the build:
``` sh
@@ -77,14 +89,17 @@ contents:
runs-on: ubuntu-latest
if: github.event.repository.fork == false
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: 3.x
- - uses: actions/cache@v2
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+ - uses: actions/cache@v3
with:
- key: ${{ github.ref }}
+ key: mkdocs-material-${{ env.cache_id }}
path: .cache
+ restore-keys: |
+ mkdocs-material-
- run: apt-get install pngquant # (1)!
- run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- run: mkdocs gh-deploy --force
@@ -113,9 +128,10 @@ Your documentation should shortly appear at `.github.io/`.
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[Insiders]: insiders/index.md
- [built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin
+ [built-in optimize plugin]: plugins/optimize.md
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
[publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+ [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
### with MkDocs
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index 8172ddd69..0bcf9e863 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
@@ -243,7 +242,7 @@ only the `inline` modifier:
``` markdown
!!! info inline end "Lorem ipsum"
-
+
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
@@ -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
@@ -504,5 +501,5 @@ After applying the customization, you can use the custom admonition type:
- [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
[additional style sheet]: ../customization.md#additional-css
diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
index 8d15e3d07..2ee13c12b 100644
--- a/docs/reference/annotations.md
+++ b/docs/reference/annotations.md
@@ -31,13 +31,51 @@ See additional configuration options:
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+### Annotation icons
+
+
+
+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
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ annotation: material/arrow-right-circle # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+Some popular choices:
+
+- :material-plus-circle: - `material/plus-circle`
+- :material-circle-medium: - `material/circle-medium`
+- :material-record-circle: - `material/record-circle`
+- :material-arrow-right-circle: - `material/arrow-right-circle`
+- :material-arrow-right-circle-outline: - `material/arrow-right-circle-outline`
+- :material-chevron-right-circle: - `material/chevron-right-circle`
+- :material-star-four-points-circle: - `material/star-four-points-circle`
+- :material-plus-circle-outline: - `material/plus-circle-outline`
+
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [icon search]: icons-emojis.md#search
+
## Usage
### Using annotations
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.6.0][Insiders] ·
-: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
@@ -65,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.
- [Insiders]: ../insiders/index.md
-
#### in annotations
When [SuperFences] is enabled, annotations can be nested inside annotations by
@@ -169,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 f75b0eefd..275ad00d0 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:
@@ -83,11 +81,11 @@ theme:
```
````
-### Code selection button :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+### 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 :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+#### 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=""`
@@ -358,27 +352,53 @@ argument placed right after the language shortcode. Note that line counts start
at `1`, regardless of the starting line number specified as part of
[`linenums`][Adding line numbers]:
-```` markdown title="Code block with highlighted lines"
-``` py hl_lines="2 3"
-def bubble_sort(items):
- for i in range(len(items)):
- for j in range(len(items) - 1 - i):
- if items[j] > items[j + 1]:
- items[j], items[j + 1] = items[j + 1], items[j]
-```
-````
+=== "Lines"
-
+ ```` markdown title="Code block with highlighted lines"
+ ``` py hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+ ````
-``` py linenums="1" hl_lines="2 3"
-def bubble_sort(items):
- for i in range(len(items)):
- for j in range(len(items) - 1 - i):
- if items[j] > items[j + 1]:
- items[j], items[j + 1] = items[j + 1], items[j]
-```
+
-
+ ``` py linenums="1" hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+
+
+ ``` py linenums="1" hl_lines="3-5"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+
[Adding line numbers]: #adding-line-numbers
@@ -485,11 +505,11 @@ override it as part of your [additional style sheet]:
- stylesheets/extra.css
```
- [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+ [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
[color schemes]: ../setup/changing-the-colors.md#color-scheme
[types of string tokens]: https://pygments.org/docs/tokens/#literals
[additional style sheet]: ../customization.md#additional-css
- [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+ [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
### Annotation tooltip width
@@ -523,35 +543,3 @@ This will render annotations with a larger width:
1. Muuuuuuuuuuuuuuuch more space for content
-
-### 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.
-
-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:
-
-=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
-
- ``` css
- .md-typeset .md-annotation__index > ::before {
- content: attr(data-md-annotation-id);
- }
- .md-typeset :focus-within > .md-annotation__index > ::before {
- transform: none;
- }
- ```
-
-=== ":octicons-file-code-16: `mkdocs.yml`"
-
- ``` yaml
- 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 1099db430..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 poenpyxl
- ```
-
- 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/formatting.md b/docs/reference/formatting.md
index 7dec1ca69..d1e0c9a23 100644
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@@ -106,7 +106,7 @@ When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
superscripted with a simple syntax, which is more convenient than directly
using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
-``` markdown title="Text with sub- und superscripts"
+``` markdown title="Text with sub- and superscripts"
- H~2~O
- A^T^A
```
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/icons-emojis.md b/docs/reference/icons-emojis.md
index 00f9158cf..69909d450 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -5,11 +5,12 @@ icon: material/emoticon-happy-outline
# Icons, Emojis
One of the best features of Material for MkDocs is the possibility to use [more
-than 10,000 icons][icon search] and thousands of emojis in your project
-documentation with practically zero additional effort. Moreover, custom icons
-can be added and used in `mkdocs.yml`, documents and templates.
+than 10,000 icons][icon search] and thousands of emojis in your project
+documentation with practically zero additional effort. Moreover, [custom icons
+can be added] and used in `mkdocs.yml`, documents and templates.
[icon search]: #search
+ [custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
## Search
@@ -74,7 +75,7 @@ between two colons. If you're using [Twemoji] (recommended), you can look up
the shortcodes at [Emojipedia]:
``` title="Emoji"
-:smile:
+:smile:
```
@@ -102,7 +103,7 @@ a valid path to any icon bundled with the theme, which are located in the
- [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
#### with colors
@@ -198,7 +199,7 @@ With the help of the [built-in typeset plugin], you can use icons and emojis
in headings, which will then be rendered in the sidebars. The plugin preserves
Markdown and HTML formatting.
- [built-in typeset plugin]: ./index.md#built-in-typeset-plugin
+ [built-in typeset plugin]: ../plugins/typeset.md
## Customization
diff --git a/docs/reference/images.md b/docs/reference/images.md
index f120352de..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`
@@ -172,7 +171,36 @@ hash fragment to the image URL:
- [Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
+!!! warning "Requirements when using [custom color schemes]"
+
+ The built-in [color schemes] define the aforementioned hash fragments, but
+ if you're using [custom color schemes], you'll also have to add the
+ following selectors to your scheme, depending on whether it's a light or
+ dark scheme:
+
+ === "Custom light scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-light"] img[src$="#only-dark"],
+ [data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
+ display: none; /* Hide dark images in light mode */
+ }
+ ```
+
+ === "Custom dark scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-dark"] img[src$="#only-light"],
+ [data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
+ display: none; /* Hide light images in dark mode */
+ }
+ ```
+
+ Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
+ name of your scheme.
+
[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
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [custom color schemes]: ../setup/changing-the-colors.md#custom-color-schemes
diff --git a/docs/reference/index.md b/docs/reference/index.md
index ab5f7c477..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,9 +59,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
### Setting the page `icon`
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.5.0][Insiders] ·
-: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
@@ -135,7 +72,7 @@ top of a Markdown file:
icon: material/emoticon-happy # (1)!
---
-# Document title
+# Page title
...
```
@@ -156,12 +93,11 @@ icon: material/emoticon-happy # (1)!
### Setting the page `status`
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.22.0][Insiders] ·
-: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
@@ -181,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
@@ -189,7 +125,7 @@ Markdown file:
status: new
---
-# Document title
+# Page title
...
```
@@ -200,9 +136,9 @@ The following status identifiers are currently supported:
### 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
@@ -213,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
@@ -228,7 +164,7 @@ lines at the top of a Markdown file:
template: custom.html
---
-# Document title
+# Page title
...
```
@@ -243,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/math.md b/docs/reference/math.md
new file mode 100644
index 000000000..92744158e
--- /dev/null
+++ b/docs/reference/math.md
@@ -0,0 +1,198 @@
+---
+icon: material/alphabet-greek
+---
+
+# Math
+
+[MathJax] and [KaTeX] are two popular libraries for displaying
+mathematical content in browsers. Although both libraries offer similar
+functionality, they use different syntaxes and have different configuration
+options. This documentation site provides information on how to integrate them
+with Material for MkDocs easily.
+
+ [MathJax]: https://www.mathjax.org/
+ [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
+ [MathML]: https://en.wikipedia.org/wiki/MathML
+ [AsciiMath]: http://asciimath.org/
+ [KaTeX]: https://katex.org/
+
+
+## Configuration
+
+The following configuration enables support for rendering block and
+inline block equations using [MathJax] and [KaTeX].
+
+### MathJax
+
+[MathJax] is a powerful and flexible library that supports multiple input formats,
+such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
+HTML, SVG, MathML. To use MathJax within your project, add the following lines
+to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
+
+ ``` js
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => { // (1)!
+ MathJax.typesetPromise()
+ })
+ ```
+
+ 1. This integrates MathJax with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
+ extra_javascript:
+ - javascripts/mathjax.js
+ - https://polyfill.io/v3/polyfill.min.js?features=es6
+ - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+ ```
+
+See additional configuration options:
+
+- [Arithmatex]
+
+ [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+
+### KaTeX
+
+[KaTeX] is a lightweight library that focuses on speed and simplicity. It
+supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
+[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
+
+ ``` js
+ document$.subscribe(({ body }) => { // (1)!
+ renderMathInElement(body, {
+ delimiters: [
+ { left: "$$", right: "$$", display: true },
+ { left: "$", right: "$", display: false },
+ { left: "\\(", right: "\\)", display: false },
+ { left: "\\[", right: "\\]", display: true }
+ ],
+ })
+ })
+ ```
+
+ 1. This integrates KaTeX with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/katex.js
+ - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)!
+ - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
+
+ extra_css:
+ - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
+ ```
+
+ 1. Alternatively, you can add these JavaScript and CSS files via `script` tags by overriding HTML files.
+
+
+
+
+
+
+
+## Usage
+
+### Using block syntax
+
+Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
+lines:
+
+``` latex title="block syntax"
+$$
+\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
+$$
+```
+
+
+
+$$
+\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
+$$
+
+
+
+### Using inline block syntax
+
+Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
+
+``` latex title="inline syntax"
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+```
+
+
+
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+
+
+
+
+## Comparing MathJax and KaTeX
+
+When deciding between MathJax and KaTeX, there are several key factors to
+consider:
+
+- __Speed__: KaTeX is generally faster than MathJax. If your site requires rendering large
+quantities of complex equations quickly, KaTeX may be the better choice.
+
+- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
+process a variety of mathematical markup languages (like AsciiMath and MathML).
+If you need advanced LaTeX features, MathJax may be more suitable.
+
+- __Output Format__: Both libraries support HTML and SVG outputs. However,
+MathJax also offers MathML output, which can be essential for accessibility, as
+it is readable by screen readers.
+
+- __Configurability__: MathJax provides a range of configuration options,
+allowing for more precise control over its behavior. If you have specific
+rendering requirements, MathJax might be a more flexible choice.
+
+- __Browser Support__: While both libraries work well in modern browsers,
+MathJax has broader compatibility with older browsers. If your audience uses a
+variety of browsers, including older ones, MathJax might be a safer option.
+
+In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
+more features and better compatibility at the expense of speed. The choice
+between the two will largely depend on your specific needs and constraints.
diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md
deleted file mode 100644
index f41074402..000000000
--- a/docs/reference/mathjax.md
+++ /dev/null
@@ -1,120 +0,0 @@
----
-icon: material/alphabet-greek
----
-
-# MathJax
-
-[MathJax] is a beautiful and accessible way to display mathematical content
-in the browser, adds support for mathematical typesetting in different notations
-(e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
-Material for MkDocs.
-
- [MathJax]: https://www.mathjax.org/
- [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
- [MathML]: https://en.wikipedia.org/wiki/MathML
- [AsciiMath]: http://asciimath.org/
-
-## Configuration
-
-This configuration enables support for rendering block and inline block
-equations through [MathJax]. Create a configuration file and add the following
-lines to `mkdocs.yml`:
-
-=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
-
- ``` js
- window.MathJax = {
- tex: {
- inlineMath: [["\\(", "\\)"]],
- displayMath: [["\\[", "\\]"]],
- processEscapes: true,
- processEnvironments: true
- },
- options: {
- ignoreHtmlClass: ".*|",
- processHtmlClass: "arithmatex"
- }
- };
-
- document$.subscribe(() => { // (1)!
- MathJax.typesetPromise()
- })
- ```
-
- 1. This integrates MathJax with [instant loading].
-
-=== ":octicons-file-code-16: `mkdocs.yml`"
-
- ``` yaml
- markdown_extensions:
- - pymdownx.arithmatex:
- generic: true
-
- extra_javascript:
- - javascripts/mathjax.js
- - https://polyfill.io/v3/polyfill.min.js?features=es6
- - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
- ```
-
-See additional configuration options:
-
-- [Arithmatex]
-
- [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
- [instant loading]: ../setup/setting-up-navigation.md#instant-loading
-
-
-
-
-
-## Usage
-
-### Using block syntax
-
-Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
-lines:
-
-``` latex title="MathJax, block syntax"
-$$
-\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
-$$
-```
-
-
-
-$$
-\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
-$$
-
-
-
-### Using inline block syntax
-
-Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
-
-``` latex title="MathJax, inline syntax"
-The homomorphism $f$ is injective if and only if its kernel is only the
-singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
-that $f(a)=f(b)$.
-```
-
-
-
-The homomorphism $f$ is injective if and only if its kernel is only the
-singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
-that $f(a)=f(b)$.
-
-
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/schema.json b/docs/schema.json
index d04afb354..f1677d463 100644
--- a/docs/schema.json
+++ b/docs/schema.json
@@ -98,7 +98,7 @@
"items": {
"title": "Path to JavaScript file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/customization/#additional-javascript",
- "pattern": "\\.js($|\\?)"
+ "pattern": "\\.m?js($|\\?)"
},
"uniqueItems": true,
"minItems": 1
diff --git a/docs/schema/assets/icons.json b/docs/schema/assets/icons.json
index ed2d43c15..eab0e2d52 100644
--- a/docs/schema/assets/icons.json
+++ b/docs/schema/assets/icons.json
@@ -104,6 +104,7 @@
"fontawesome/brands/d-and-d",
"fontawesome/brands/dailymotion",
"fontawesome/brands/dashcube",
+ "fontawesome/brands/debian",
"fontawesome/brands/deezer",
"fontawesome/brands/delicious",
"fontawesome/brands/deploydog",
@@ -375,11 +376,13 @@
"fontawesome/brands/square-reddit",
"fontawesome/brands/square-snapchat",
"fontawesome/brands/square-steam",
+ "fontawesome/brands/square-threads",
"fontawesome/brands/square-tumblr",
"fontawesome/brands/square-twitter",
"fontawesome/brands/square-viadeo",
"fontawesome/brands/square-vimeo",
"fontawesome/brands/square-whatsapp",
+ "fontawesome/brands/square-x-twitter",
"fontawesome/brands/square-xing",
"fontawesome/brands/square-youtube",
"fontawesome/brands/squarespace",
@@ -409,6 +412,7 @@
"fontawesome/brands/themeco",
"fontawesome/brands/themeisle",
"fontawesome/brands/think-peaks",
+ "fontawesome/brands/threads",
"fontawesome/brands/tiktok",
"fontawesome/brands/trade-federation",
"fontawesome/brands/trello",
@@ -459,6 +463,7 @@
"fontawesome/brands/wpexplorer",
"fontawesome/brands/wpforms",
"fontawesome/brands/wpressr",
+ "fontawesome/brands/x-twitter",
"fontawesome/brands/xbox",
"fontawesome/brands/xing",
"fontawesome/brands/y-combinator",
@@ -9470,6 +9475,8 @@
"octicons/device-desktop-24",
"octicons/device-mobile-16",
"octicons/device-mobile-24",
+ "octicons/devices-16",
+ "octicons/devices-24",
"octicons/diamond-16",
"octicons/diamond-24",
"octicons/diff-16",
@@ -9501,8 +9508,17 @@
"octicons/feed-discussion-16",
"octicons/feed-forked-16",
"octicons/feed-heart-16",
+ "octicons/feed-issue-closed-16",
+ "octicons/feed-issue-draft-16",
+ "octicons/feed-issue-open-16",
+ "octicons/feed-issue-reopen-16",
"octicons/feed-merged-16",
"octicons/feed-person-16",
+ "octicons/feed-plus-16",
+ "octicons/feed-public-16",
+ "octicons/feed-pull-request-closed-16",
+ "octicons/feed-pull-request-draft-16",
+ "octicons/feed-pull-request-open-16",
"octicons/feed-repo-16",
"octicons/feed-rocket-16",
"octicons/feed-star-16",
@@ -9523,6 +9539,8 @@
"octicons/file-directory-fill-16",
"octicons/file-directory-fill-24",
"octicons/file-directory-open-fill-16",
+ "octicons/file-directory-symlink-16",
+ "octicons/file-directory-symlink-24",
"octicons/file-media-24",
"octicons/file-moved-16",
"octicons/file-removed-16",
@@ -9707,6 +9725,10 @@
"octicons/person-fill-24",
"octicons/pin-16",
"octicons/pin-24",
+ "octicons/pin-slash-16",
+ "octicons/pin-slash-24",
+ "octicons/pivot-column-16",
+ "octicons/pivot-column-24",
"octicons/play-16",
"octicons/play-24",
"octicons/plug-16",
@@ -9731,6 +9753,7 @@
"octicons/quote-24",
"octicons/read-16",
"octicons/read-24",
+ "octicons/redo-16",
"octicons/rel-file-path-16",
"octicons/rel-file-path-24",
"octicons/reply-16",
@@ -9738,12 +9761,14 @@
"octicons/repo-16",
"octicons/repo-24",
"octicons/repo-clone-16",
+ "octicons/repo-clone-24",
"octicons/repo-deleted-16",
"octicons/repo-forked-16",
"octicons/repo-forked-24",
"octicons/repo-locked-16",
"octicons/repo-locked-24",
"octicons/repo-pull-16",
+ "octicons/repo-pull-24",
"octicons/repo-push-16",
"octicons/repo-push-24",
"octicons/repo-template-16",
@@ -9847,6 +9872,10 @@
"octicons/thumbsup-24",
"octicons/tools-16",
"octicons/tools-24",
+ "octicons/tracked-by-closed-completed-16",
+ "octicons/tracked-by-closed-completed-24",
+ "octicons/tracked-by-closed-not-planned-16",
+ "octicons/tracked-by-closed-not-planned-24",
"octicons/trash-16",
"octicons/trash-24",
"octicons/triangle-down-16",
@@ -9861,6 +9890,7 @@
"octicons/trophy-24",
"octicons/typography-16",
"octicons/typography-24",
+ "octicons/undo-16",
"octicons/unfold-16",
"octicons/unfold-24",
"octicons/unlink-16",
@@ -9884,6 +9914,7 @@
"octicons/webhook-16",
"octicons/workflow-16",
"octicons/workflow-24",
+ "octicons/x-12",
"octicons/x-16",
"octicons/x-24",
"octicons/x-circle-16",
@@ -9918,6 +9949,7 @@
"simple/acm",
"simple/actigraph",
"simple/activision",
+ "simple/acura",
"simple/adafruit",
"simple/adblock",
"simple/adblockplus",
@@ -9941,12 +9973,14 @@
"simple/adobexd",
"simple/adonisjs",
"simple/adp",
+ "simple/adroll",
"simple/adyen",
"simple/aerlingus",
"simple/aeroflot",
"simple/aeromexico",
"simple/aerospike",
"simple/aew",
+ "simple/affine",
"simple/affinity",
"simple/affinitydesigner",
"simple/affinityphoto",
@@ -9959,19 +9993,23 @@
"simple/aiqfome",
"simple/airasia",
"simple/airbnb",
+ "simple/airbrakedotio",
"simple/airbus",
"simple/airbyte",
"simple/aircall",
"simple/aircanada",
"simple/airchina",
"simple/airfrance",
+ "simple/airindia",
"simple/airplayaudio",
"simple/airplayvideo",
"simple/airtable",
"simple/ajv",
"simple/akamai",
+ "simple/akaunting",
"simple/alacritty",
"simple/albertheijn",
+ "simple/alby",
"simple/alchemy",
"simple/aldinord",
"simple/aldisud",
@@ -9981,15 +10019,16 @@
"simple/algorand",
"simple/alibabacloud",
"simple/alibabadotcom",
+ "simple/alienware",
"simple/aliexpress",
"simple/alipay",
- "simple/alitalia",
"simple/allegro",
"simple/alliedmodders",
"simple/allocine",
"simple/alltrails",
"simple/alpinedotjs",
"simple/alpinelinux",
+ "simple/alteryx",
"simple/altiumdesigner",
"simple/alwaysdata",
"simple/amazon",
@@ -9997,19 +10036,26 @@
"simple/amazonapigateway",
"simple/amazonaws",
"simple/amazoncloudwatch",
+ "simple/amazondocumentdb",
"simple/amazondynamodb",
"simple/amazonec2",
"simple/amazonecs",
"simple/amazoneks",
"simple/amazonfiretv",
"simple/amazongames",
+ "simple/amazoniam",
"simple/amazonlumberyard",
+ "simple/amazonluna",
"simple/amazonpay",
"simple/amazonprime",
"simple/amazonrds",
+ "simple/amazonredshift",
+ "simple/amazonroute53",
"simple/amazons3",
+ "simple/amazonsimpleemailservice",
"simple/amazonsqs",
"simple/amd",
+ "simple/ameba",
"simple/americanairlines",
"simple/americanexpress",
"simple/amg",
@@ -10055,12 +10101,15 @@
"simple/apachemaven",
"simple/apachenetbeanside",
"simple/apacheopenoffice",
+ "simple/apacheparquet",
"simple/apachepulsar",
"simple/apacherocketmq",
"simple/apachesolr",
"simple/apachespark",
+ "simple/apachestorm",
"simple/apachetomcat",
"simple/aparat",
+ "simple/apifox",
"simple/apollographql",
"simple/apostrophe",
"simple/appian",
@@ -10072,12 +10121,14 @@
"simple/applepodcasts",
"simple/appletv",
"simple/appsignal",
+ "simple/appsmith",
"simple/appstore",
"simple/appveyor",
"simple/appwrite",
"simple/aqua",
"simple/aral",
"simple/arangodb",
+ "simple/arcgis",
"simple/archicad",
"simple/archiveofourown",
"simple/archlinux",
@@ -10085,9 +10136,12 @@
"simple/arduino",
"simple/argo",
"simple/argos",
+ "simple/ariakit",
"simple/arkecosystem",
"simple/arlo",
"simple/arm",
+ "simple/armkeil",
+ "simple/arstechnica",
"simple/artifacthub",
"simple/artixlinux",
"simple/artstation",
@@ -10116,6 +10170,7 @@
"simple/audiotechnica",
"simple/aurelia",
"simple/auth0",
+ "simple/authelia",
"simple/authy",
"simple/autodesk",
"simple/autohotkey",
@@ -10123,11 +10178,13 @@
"simple/autoprefixer",
"simple/avajs",
"simple/avast",
+ "simple/avira",
"simple/awesomelists",
"simple/awesomewm",
"simple/awsamplify",
"simple/awsfargate",
"simple/awslambda",
+ "simple/awsorganizations",
"simple/axios",
"simple/azureartifacts",
"simple/azuredataexplorer",
@@ -10135,6 +10192,7 @@
"simple/azurefunctions",
"simple/azurepipelines",
"simple/babel",
+ "simple/babylondotjs",
"simple/backblaze",
"simple/backbonedotjs",
"simple/backendless",
@@ -10164,6 +10222,8 @@
"simple/beijingsubway",
"simple/bem",
"simple/bentley",
+ "simple/bento",
+ "simple/bentoml",
"simple/betfair",
"simple/bigbasket",
"simple/bigbluebutton",
@@ -10174,6 +10234,7 @@
"simple/bim",
"simple/binance",
"simple/biolink",
+ "simple/bisecthosting",
"simple/bit",
"simple/bitbucket",
"simple/bitcoin",
@@ -10198,6 +10259,7 @@
"simple/boardgamegeek",
"simple/boehringeringelheim",
"simple/boeing",
+ "simple/bombardier",
"simple/bookalope",
"simple/bookbub",
"simple/bookmeter",
@@ -10209,6 +10271,7 @@
"simple/borgbackup",
"simple/bosch",
"simple/bose",
+ "simple/botblecms",
"simple/boulanger",
"simple/bower",
"simple/box",
@@ -10216,8 +10279,11 @@
"simple/brandfolder",
"simple/brave",
"simple/breaker",
+ "simple/brevo",
"simple/britishairways",
"simple/broadcom",
+ "simple/bsd",
+ "simple/bspwm",
"simple/bt",
"simple/buddy",
"simple/budibase",
@@ -10241,6 +10307,8 @@
"simple/bytedance",
"simple/c",
"simple/cachet",
+ "simple/caddy",
+ "simple/cadillac",
"simple/cafepress",
"simple/caffeine",
"simple/cairographics",
@@ -10250,6 +10318,8 @@
"simple/canonical",
"simple/canva",
"simple/capacitor",
+ "simple/cardano",
+ "simple/carrd",
"simple/carrefour",
"simple/carthrottle",
"simple/carto",
@@ -10268,18 +10338,23 @@
"simple/chainguard",
"simple/chainlink",
"simple/chakraui",
+ "simple/channel4",
"simple/chartdotjs",
"simple/chartmogul",
"simple/chase",
"simple/chatbot",
+ "simple/chatwoot",
"simple/checkio",
"simple/checkmarx",
+ "simple/checkmk",
"simple/chef",
"simple/chemex",
"simple/chevrolet",
+ "simple/chianetwork",
"simple/chinaeasternairlines",
"simple/chinasouthernairlines",
"simple/chocolatey",
+ "simple/chromatic",
"simple/chromecast",
"simple/chrysler",
"simple/chupachups",
@@ -10287,6 +10362,7 @@
"simple/cinema4d",
"simple/circle",
"simple/circleci",
+ "simple/circuitverse",
"simple/cirrusci",
"simple/cisco",
"simple/citrix",
@@ -10294,7 +10370,9 @@
"simple/civicrm",
"simple/civo",
"simple/ckeditor4",
+ "simple/clarifai",
"simple/claris",
+ "simple/clarivate",
"simple/clickhouse",
"simple/clickup",
"simple/clion",
@@ -10315,6 +10393,7 @@
"simple/cmake",
"simple/cncf",
"simple/cnn",
+ "simple/cocacola",
"simple/cockpit",
"simple/cockroachlabs",
"simple/cocoapods",
@@ -10340,6 +10419,8 @@
"simple/coderwall",
"simple/codesandbox",
"simple/codeship",
+ "simple/codesignal",
+ "simple/codestream",
"simple/codewars",
"simple/codingame",
"simple/codingninjas",
@@ -10353,7 +10434,9 @@
"simple/commitlint",
"simple/commodore",
"simple/commonworkflowlanguage",
+ "simple/compilerexplorer",
"simple/composer",
+ "simple/comptia",
"simple/comsol",
"simple/conan",
"simple/concourse",
@@ -10364,6 +10447,7 @@
"simple/consul",
"simple/contactlesspayment",
"simple/containerd",
+ "simple/contao",
"simple/contentful",
"simple/conventionalcommits",
"simple/convertio",
@@ -10380,9 +10464,12 @@
"simple/coveralls",
"simple/cpanel",
"simple/cplusplus",
+ "simple/cplusplusbuilder",
"simple/craftcms",
+ "simple/craftsman",
"simple/cratedb",
"simple/crayon",
+ "simple/creality",
"simple/createreactapp",
"simple/creativecommons",
"simple/creativetechnology",
@@ -10404,6 +10491,7 @@
"simple/cultura",
"simple/curl",
"simple/curseforge",
+ "simple/cyberdefenders",
"simple/cycling74",
"simple/cypress",
"simple/cytoscapedotjs",
@@ -10438,6 +10526,7 @@
"simple/dbt",
"simple/dcentertainment",
"simple/debian",
+ "simple/decapcms",
"simple/dedge",
"simple/deepin",
"simple/deepnote",
@@ -10449,6 +10538,7 @@
"simple/delphi",
"simple/delta",
"simple/deno",
+ "simple/denon",
"simple/dependabot",
"simple/derspiegel",
"simple/designernews",
@@ -10475,14 +10565,18 @@
"simple/discover",
"simple/disqus",
"simple/disroot",
+ "simple/distrokid",
"simple/django",
"simple/dlib",
"simple/dlna",
"simple/dm",
"simple/docker",
"simple/docsdotrs",
+ "simple/docsify",
+ "simple/docusaurus",
"simple/docusign",
"simple/dogecoin",
+ "simple/doi",
"simple/dolby",
"simple/doordash",
"simple/dotenv",
@@ -10499,6 +10593,7 @@
"simple/dropbox",
"simple/drupal",
"simple/dsautomobiles",
+ "simple/dts",
"simple/dtube",
"simple/ducati",
"simple/duckdb",
@@ -10515,8 +10610,11 @@
"simple/e3",
"simple/ea",
"simple/eagle",
+ "simple/easyeda",
"simple/easyjet",
"simple/ebay",
+ "simple/ebox",
+ "simple/eclipseadoptium",
"simple/eclipseche",
"simple/eclipseide",
"simple/eclipsejetty",
@@ -10533,6 +10631,7 @@
"simple/elasticcloud",
"simple/elasticsearch",
"simple/elasticstack",
+ "simple/elavon",
"simple/electron",
"simple/electronbuilder",
"simple/electronfiddle",
@@ -10561,6 +10660,7 @@
"simple/epicgames",
"simple/epson",
"simple/equinixmetal",
+ "simple/ericsson",
"simple/erlang",
"simple/esbuild",
"simple/esea",
@@ -10568,6 +10668,7 @@
"simple/eslint",
"simple/esphome",
"simple/espressif",
+ "simple/esri",
"simple/etcd",
"simple/ethereum",
"simple/ethiopianairlines",
@@ -10592,12 +10693,14 @@
"simple/facebooklive",
"simple/faceit",
"simple/facepunch",
+ "simple/falco",
"simple/falcon",
"simple/fampay",
"simple/fandango",
"simple/fandom",
"simple/fanfou",
"simple/fantom",
+ "simple/fareharbor",
"simple/farfetch",
"simple/fastapi",
"simple/fastify",
@@ -10613,7 +10716,9 @@
"simple/feedly",
"simple/ferrari",
"simple/ferrarinv",
+ "simple/ferretdb",
"simple/ffmpeg",
+ "simple/fi",
"simple/fiat",
"simple/fidoalliance",
"simple/fifa",
@@ -10625,6 +10730,8 @@
"simple/filezilla",
"simple/fing",
"simple/firebase",
+ "simple/firefish",
+ "simple/fireflyiii",
"simple/firefox",
"simple/firefoxbrowser",
"simple/fireship",
@@ -10640,13 +10747,16 @@
"simple/flatpak",
"simple/flattr",
"simple/flickr",
+ "simple/flightaware",
"simple/flipboard",
"simple/flipkart",
"simple/floatplane",
"simple/flood",
"simple/fluentbit",
"simple/fluentd",
+ "simple/fluke",
"simple/flutter",
+ "simple/flux",
"simple/fluxus",
"simple/flyway",
"simple/fmod",
@@ -10659,6 +10769,7 @@
"simple/foodpanda",
"simple/ford",
"simple/forestry",
+ "simple/forgejo",
"simple/formstack",
"simple/fortinet",
"simple/fortran",
@@ -10678,8 +10789,11 @@
"simple/freedesktopdotorg",
"simple/freelancer",
"simple/freenas",
+ "simple/freepik",
"simple/frontendmentor",
+ "simple/frontify",
"simple/fsecure",
+ "simple/fsharp",
"simple/fugacloud",
"simple/fujifilm",
"simple/fujitsu",
@@ -10690,11 +10804,14 @@
"simple/g2",
"simple/g2a",
"simple/gameandwatch",
+ "simple/gamebanana",
"simple/gamedeveloper",
"simple/gamejolt",
+ "simple/gamemaker",
"simple/garmin",
"simple/gatling",
"simple/gatsby",
+ "simple/gdal",
"simple/geant",
"simple/geeksforgeeks",
"simple/generalelectric",
@@ -10748,19 +10865,28 @@
"simple/googleads",
"simple/googleadsense",
"simple/googleanalytics",
+ "simple/googleappsscript",
"simple/googleassistant",
+ "simple/googlebard",
+ "simple/googlebigquery",
"simple/googlecalendar",
"simple/googlecardboard",
"simple/googlechat",
"simple/googlechrome",
"simple/googleclassroom",
"simple/googlecloud",
+ "simple/googlecloudcomposer",
"simple/googlecolab",
+ "simple/googlecontaineroptimizedos",
+ "simple/googledatastudio",
+ "simple/googledocs",
"simple/googledomains",
"simple/googledrive",
"simple/googleearth",
+ "simple/googleearthengine",
"simple/googlefit",
"simple/googlefonts",
+ "simple/googleforms",
"simple/googlehangouts",
"simple/googlehome",
"simple/googlekeep",
@@ -10780,12 +10906,14 @@
"simple/googlescholar",
"simple/googlesearchconsole",
"simple/googlesheets",
+ "simple/googleslides",
"simple/googlestreetview",
"simple/googletagmanager",
"simple/googletranslate",
"simple/gotomeeting",
"simple/grab",
"simple/gradle",
+ "simple/gradleplaypublisher",
"simple/grafana",
"simple/grammarly",
"simple/grandfrais",
@@ -10802,6 +10930,7 @@
"simple/grubhub",
"simple/grunt",
"simple/gsk",
+ "simple/gstreamer",
"simple/gtk",
"simple/guangzhoumetro",
"simple/guilded",
@@ -10811,6 +10940,7 @@
"simple/gunicorn",
"simple/gurobi",
"simple/gutenberg",
+ "simple/h3",
"simple/habr",
"simple/hackaday",
"simple/hackclub",
@@ -10820,12 +10950,15 @@
"simple/hackerrank",
"simple/hackster",
"simple/hackthebox",
+ "simple/hal",
"simple/handlebarsdotjs",
+ "simple/handm",
"simple/handshake",
"simple/handshake_protocol",
"simple/happycow",
"simple/harbor",
"simple/harmonyos",
+ "simple/hashicorp",
"simple/hashnode",
"simple/haskell",
"simple/hasura",
@@ -10836,6 +10969,8 @@
"simple/hcl",
"simple/headlessui",
"simple/headspace",
+ "simple/hearth",
+ "simple/hearthisdotat",
"simple/hedera",
"simple/hellofresh",
"simple/hellyhansen",
@@ -10845,6 +10980,7 @@
"simple/here",
"simple/heroku",
"simple/hetzner",
+ "simple/hexlet",
"simple/hexo",
"simple/hey",
"simple/hibernate",
@@ -10861,15 +10997,19 @@
"simple/homify",
"simple/honda",
"simple/honey",
+ "simple/honor",
"simple/hootsuite",
"simple/hoppscotch",
"simple/hotelsdotcom",
"simple/hotjar",
+ "simple/hotwire",
"simple/houdini",
"simple/houzz",
"simple/hp",
+ "simple/hsbc",
"simple/html5",
"simple/htmlacademy",
+ "simple/htop",
"simple/httpie",
"simple/huawei",
"simple/hubspot",
@@ -10884,6 +11024,7 @@
"simple/hypothesis",
"simple/hyundai",
"simple/i18next",
+ "simple/i3",
"simple/iata",
"simple/ibeacon",
"simple/ibm",
@@ -10904,6 +11045,7 @@
"simple/ifixit",
"simple/ifood",
"simple/ifttt",
+ "simple/igdb",
"simple/iheartradio",
"simple/ikea",
"simple/iledefrancemobilites",
@@ -10911,10 +11053,15 @@
"simple/imdb",
"simple/imgur",
"simple/immer",
+ "simple/immich",
"simple/imou",
+ "simple/improvmx",
"simple/indeed",
+ "simple/indigo",
+ "simple/inertia",
"simple/infiniti",
"simple/influxdb",
+ "simple/infoq",
"simple/informatica",
"simple/infosys",
"simple/infracost",
@@ -10933,11 +11080,14 @@
"simple/intellijidea",
"simple/interactiondesignfoundation",
"simple/interactjs",
+ "simple/interbase",
"simple/intercom",
"simple/intermarche",
"simple/internetarchive",
+ "simple/internetcomputer",
"simple/internetexplorer",
"simple/intigriti",
+ "simple/intuit",
"simple/invision",
"simple/invoiceninja",
"simple/iobroker",
@@ -10946,6 +11096,9 @@
"simple/ios",
"simple/iota",
"simple/ipfs",
+ "simple/iris",
+ "simple/isc2",
+ "simple/iscsquared",
"simple/issuu",
"simple/istio",
"simple/itchdotio",
@@ -10969,10 +11122,12 @@
"simple/jenkinsx",
"simple/jest",
"simple/jet",
+ "simple/jetblue",
"simple/jetbrains",
"simple/jetpackcompose",
"simple/jfrog",
"simple/jfrogbintray",
+ "simple/jfrogpipelines",
"simple/jinja",
"simple/jira",
"simple/jirasoftware",
@@ -10981,6 +11136,7 @@
"simple/joomla",
"simple/joplin",
"simple/jordan",
+ "simple/jovian",
"simple/jpeg",
"simple/jquery",
"simple/jrgroup",
@@ -10989,6 +11145,8 @@
"simple/json",
"simple/jsonwebtokens",
"simple/jss",
+ "simple/juce",
+ "simple/juejin",
"simple/juke",
"simple/julia",
"simple/junipernetworks",
@@ -11004,6 +11162,7 @@
"simple/kakao",
"simple/kakaotalk",
"simple/kalilinux",
+ "simple/kamailio",
"simple/kaniko",
"simple/karlsruherverkehrsverbund",
"simple/kasasmart",
@@ -11014,6 +11173,7 @@
"simple/kaufland",
"simple/kde",
"simple/kdenlive",
+ "simple/kedro",
"simple/keepachangelog",
"simple/keepassxc",
"simple/kentico",
@@ -11031,7 +11191,9 @@
"simple/kik",
"simple/kingstontechnology",
"simple/kinopoisk",
+ "simple/kinsta",
"simple/kirby",
+ "simple/kit",
"simple/kitsu",
"simple/klarna",
"simple/klm",
@@ -11041,6 +11203,7 @@
"simple/known",
"simple/koa",
"simple/koc",
+ "simple/kodak",
"simple/kodi",
"simple/kofax",
"simple/kofi",
@@ -11076,12 +11239,15 @@
"simple/lbry",
"simple/leaderprice",
"simple/leaflet",
+ "simple/leagueoflegends",
"simple/leanpub",
"simple/leetcode",
"simple/legacygames",
+ "simple/leica",
"simple/lemmy",
"simple/lenovo",
"simple/lens",
+ "simple/leptos",
"simple/lerna",
"simple/leroymerlin",
"simple/less",
@@ -11090,6 +11256,7 @@
"simple/levelsdotfyi",
"simple/lg",
"simple/lgtm",
+ "simple/liberadotchat",
"simple/liberapay",
"simple/librariesdotio",
"simple/librarything",
@@ -11098,7 +11265,9 @@
"simple/lichess",
"simple/lidl",
"simple/lifx",
+ "simple/lightburn",
"simple/lighthouse",
+ "simple/lightning",
"simple/line",
"simple/lineageos",
"simple/linear",
@@ -11106,7 +11275,6 @@
"simple/linkerd",
"simple/linkfire",
"simple/linktree",
- "simple/linode",
"simple/linux",
"simple/linuxcontainers",
"simple/linuxfoundation",
@@ -11121,9 +11289,11 @@
"simple/livewire",
"simple/llvm",
"simple/lmms",
+ "simple/local",
"simple/lodash",
"simple/logitech",
"simple/logmein",
+ "simple/logseq",
"simple/logstash",
"simple/looker",
"simple/loom",
@@ -11131,12 +11301,14 @@
"simple/loopback",
"simple/lospec",
"simple/lotpolishairlines",
+ "simple/ltspice",
"simple/lua",
"simple/lubuntu",
"simple/ludwig",
"simple/lufthansa",
"simple/lumen",
"simple/lunacy",
+ "simple/lutris",
"simple/lydia",
"simple/lyft",
"simple/maas",
@@ -11147,32 +11319,39 @@
"simple/magento",
"simple/magisk",
"simple/mailchimp",
+ "simple/maildotcom",
"simple/maildotru",
"simple/mailgun",
"simple/majorleaguehacking",
"simple/makerbot",
+ "simple/mambaui",
"simple/mamp",
"simple/man",
"simple/manageiq",
"simple/manjaro",
+ "simple/mantine",
"simple/mapbox",
+ "simple/maplibre",
"simple/mariadb",
"simple/mariadbfoundation",
"simple/markdown",
"simple/marketo",
"simple/marko",
"simple/marriott",
+ "simple/marvelapp",
"simple/maserati",
"simple/mastercard",
"simple/mastercomfig",
"simple/mastodon",
"simple/materialdesign",
"simple/materialdesignicons",
+ "simple/matillion",
"simple/matomo",
"simple/matrix",
"simple/matterdotjs",
"simple/mattermost",
"simple/matternet",
+ "simple/mautic",
"simple/max",
"simple/maxplanckgesellschaft",
"simple/maytag",
@@ -11187,9 +11366,11 @@
"simple/mediamarkt",
"simple/mediatek",
"simple/mediatemple",
+ "simple/medibangpaint",
"simple/medium",
"simple/meetup",
"simple/mega",
+ "simple/meilisearch",
"simple/mendeley",
"simple/mercadopago",
"simple/mercedes",
@@ -11205,8 +11386,10 @@
"simple/metrodemadrid",
"simple/metrodeparis",
"simple/mewe",
+ "simple/mg",
"simple/microbit",
"simple/microdotblog",
+ "simple/microeditor",
"simple/microgenetics",
"simple/micropython",
"simple/microsoft",
@@ -11228,17 +11411,24 @@
"simple/microsofttranslator",
"simple/microsoftvisio",
"simple/microsoftword",
+ "simple/microstation",
"simple/microstrategy",
"simple/midi",
+ "simple/mikrotik",
+ "simple/milvus",
"simple/minds",
"simple/minecraft",
"simple/minetest",
"simple/mini",
+ "simple/minio",
"simple/minutemailer",
+ "simple/miraheze",
"simple/miro",
+ "simple/misskey",
"simple/mitsubishi",
"simple/mix",
"simple/mixcloud",
+ "simple/mixpanel",
"simple/mlb",
"simple/mlflow",
"simple/mobx",
@@ -11253,9 +11443,12 @@
"simple/monero",
"simple/moneygram",
"simple/mongodb",
+ "simple/mongoose",
+ "simple/mongoosedotws",
"simple/monica",
"simple/monkeytie",
- "simple/monogames",
+ "simple/monkeytype",
+ "simple/monogame",
"simple/monoprix",
"simple/monster",
"simple/monzo",
@@ -11270,9 +11463,11 @@
"simple/msibusiness",
"simple/mta",
"simple/mtr",
+ "simple/mubi",
"simple/mui",
"simple/mulesoft",
"simple/muller",
+ "simple/multisim",
"simple/mumble",
"simple/musescore",
"simple/musicbrainz",
@@ -11288,10 +11483,13 @@
"simple/nasa",
"simple/nationalgrid",
"simple/nativescript",
+ "simple/natsdotio",
"simple/naver",
"simple/nba",
"simple/nbb",
+ "simple/nbc",
"simple/ndr",
+ "simple/near",
"simple/nec",
"simple/neo4j",
"simple/neovim",
@@ -11304,6 +11502,7 @@
"simple/netto",
"simple/neutralinojs",
"simple/newbalance",
+ "simple/newegg",
"simple/newjapanprowrestling",
"simple/newrelic",
"simple/newyorktimes",
@@ -11311,11 +11510,15 @@
"simple/nextcloud",
"simple/nextdoor",
"simple/nextdotjs",
+ "simple/nextra",
"simple/nfc",
"simple/nginx",
+ "simple/nginxproxymanager",
"simple/ngrok",
+ "simple/ngrx",
"simple/niconico",
"simple/nike",
+ "simple/nikon",
"simple/nim",
"simple/nintendo",
"simple/nintendo3ds",
@@ -11351,6 +11554,7 @@
"simple/nuxtdotjs",
"simple/nvidia",
"simple/nx",
+ "simple/nxp",
"simple/nzxt",
"simple/observable",
"simple/obsidian",
@@ -11358,6 +11562,7 @@
"simple/ocaml",
"simple/octanerender",
"simple/octave",
+ "simple/octobercms",
"simple/octoprint",
"simple/octopusdeploy",
"simple/oculus",
@@ -11390,20 +11595,24 @@
"simple/openmined",
"simple/opennebula",
"simple/openproject",
+ "simple/openscad",
"simple/opensea",
"simple/opensearch",
+ "simple/opensourcehardware",
"simple/opensourceinitiative",
"simple/openssl",
"simple/openstack",
"simple/openstreetmap",
"simple/opensuse",
"simple/opentelemetry",
+ "simple/opentf",
"simple/openverse",
"simple/openvpn",
"simple/openwrt",
"simple/openzeppelin",
"simple/openzfs",
"simple/opera",
+ "simple/operagx",
"simple/opnsense",
"simple/opsgenie",
"simple/opslevel",
@@ -11413,6 +11622,7 @@
"simple/org",
"simple/origin",
"simple/osano",
+ "simple/osgeo",
"simple/oshkosh",
"simple/osmc",
"simple/osu",
@@ -11421,18 +11631,22 @@
"simple/overleaf",
"simple/ovh",
"simple/owasp",
+ "simple/owncloud",
"simple/oxygen",
"simple/oyo",
"simple/p5dotjs",
"simple/packagist",
"simple/packer",
+ "simple/paddlepaddle",
"simple/paddypower",
"simple/pagekit",
"simple/pagerduty",
"simple/pagespeedinsights",
"simple/pagseguro",
"simple/palantir",
+ "simple/paloaltonetworks",
"simple/paloaltosoftware",
+ "simple/panasonic",
"simple/pandas",
"simple/pandora",
"simple/pantheon",
@@ -11442,11 +11656,15 @@
"simple/passport",
"simple/pastebin",
"simple/patreon",
+ "simple/paychex",
+ "simple/payloadcms",
"simple/payoneer",
"simple/paypal",
"simple/paytm",
"simple/pcgamingwiki",
"simple/peakdesign",
+ "simple/pearson",
+ "simple/peerlist",
"simple/peertube",
"simple/pegasusairlines",
"simple/pelican",
@@ -11465,6 +11683,7 @@
"simple/pfsense",
"simple/phabricator",
"simple/philipshue",
+ "simple/phoenixframework",
"simple/phonepe",
"simple/photobucket",
"simple/photocrowd",
@@ -11472,6 +11691,7 @@
"simple/php",
"simple/phpmyadmin",
"simple/phpstorm",
+ "simple/piaggiogroup",
"simple/picardsurgeles",
"simple/picartodottv",
"simple/picnic",
@@ -11517,7 +11737,9 @@
"simple/pocketbase",
"simple/pocketcasts",
"simple/podcastaddict",
+ "simple/podcastindex",
"simple/podman",
+ "simple/poe",
"simple/poetry",
"simple/pointy",
"simple/pokemon",
@@ -11531,6 +11753,7 @@
"simple/portainer",
"simple/postcss",
"simple/postgresql",
+ "simple/posthog",
"simple/postman",
"simple/postmates",
"simple/powerapps",
@@ -11544,14 +11767,17 @@
"simple/prdotco",
"simple/preact",
"simple/precommit",
+ "simple/prefect",
"simple/premierleague",
"simple/prestashop",
"simple/presto",
"simple/prettier",
+ "simple/pretzel",
"simple/prevention",
"simple/prezi",
"simple/prime",
"simple/primevideo",
+ "simple/printables",
"simple/prisma",
"simple/prismic",
"simple/privateinternetaccess",
@@ -11565,12 +11791,16 @@
"simple/prosieben",
"simple/protocolsdotio",
"simple/protodotio",
+ "simple/proton",
+ "simple/protoncalendar",
"simple/protondb",
+ "simple/protondrive",
"simple/protonmail",
"simple/protonvpn",
"simple/protools",
"simple/protractor",
"simple/proxmox",
+ "simple/pterodactyl",
"simple/pubg",
"simple/publons",
"simple/pubmed",
@@ -11585,6 +11815,7 @@
"simple/pusher",
"simple/pwa",
"simple/pycharm",
+ "simple/pydantic",
"simple/pyg",
"simple/pypi",
"simple/pypy",
@@ -11592,8 +11823,8 @@
"simple/pysyft",
"simple/pytest",
"simple/python",
+ "simple/pythonanywhere",
"simple/pytorch",
- "simple/pytorchlightning",
"simple/pyup",
"simple/qantas",
"simple/qatarairways",
@@ -11603,6 +11834,7 @@
"simple/qiita",
"simple/qiskit",
"simple/qiwi",
+ "simple/qlik",
"simple/qmk",
"simple/qt",
"simple/qualcomm",
@@ -11619,6 +11851,7 @@
"simple/quicktime",
"simple/quip",
"simple/quora",
+ "simple/qwant",
"simple/qwiklabs",
"simple/qzone",
"simple/r",
@@ -11627,6 +11860,8 @@
"simple/racket",
"simple/radar",
"simple/radiopublic",
+ "simple/radixui",
+ "simple/radstudio",
"simple/railway",
"simple/rainmeter",
"simple/rakuten",
@@ -11646,11 +11881,13 @@
"simple/reactquery",
"simple/reactrouter",
"simple/reacttable",
+ "simple/readdotcv",
"simple/readme",
"simple/readthedocs",
"simple/realm",
"simple/reason",
"simple/reasonstudios",
+ "simple/recoil",
"simple/red",
"simple/redbubble",
"simple/reddit",
@@ -11665,6 +11902,7 @@
"simple/reebok",
"simple/relay",
"simple/relianceindustrieslimited",
+ "simple/remark",
"simple/remix",
"simple/renault",
"simple/render",
@@ -11678,8 +11916,10 @@
"simple/researchgate",
"simple/resharper",
"simple/resurrectionremixos",
+ "simple/retool",
"simple/retroarch",
"simple/retropie",
+ "simple/revanced",
"simple/revealdotjs",
"simple/reverbnation",
"simple/revoltdotchat",
@@ -11693,9 +11933,13 @@
"simple/ring",
"simple/riotgames",
"simple/ripple",
+ "simple/riscv",
"simple/riseup",
+ "simple/roadmapdotsh",
"simple/roamresearch",
+ "simple/robinhood",
"simple/roblox",
+ "simple/robloxstudio",
"simple/robotframework",
"simple/rocketdotchat",
"simple/rocksdb",
@@ -11704,6 +11948,7 @@
"simple/rollsroyce",
"simple/rollupdotjs",
"simple/rome",
+ "simple/rootme",
"simple/roots",
"simple/rootsbedrock",
"simple/rootssage",
@@ -11723,6 +11968,9 @@
"simple/rubygems",
"simple/rubyonrails",
"simple/rubysinatra",
+ "simple/ruff",
+ "simple/rumble",
+ "simple/rundeck",
"simple/runkeeper",
"simple/runkit",
"simple/rust",
@@ -11731,14 +11979,18 @@
"simple/s7airlines",
"simple/sabanci",
"simple/safari",
+ "simple/sage",
"simple/sahibinden",
"simple/sailfishos",
+ "simple/sailsdotjs",
"simple/salesforce",
"simple/saltproject",
"simple/samsung",
"simple/samsungpay",
"simple/sandisk",
"simple/sanfranciscomunicipalrailway",
+ "simple/sanic",
+ "simple/sanity",
"simple/saopaulometro",
"simple/sap",
"simple/sass",
@@ -11753,6 +12005,7 @@
"simple/scipy",
"simple/scopus",
"simple/scpfoundation",
+ "simple/scrapbox",
"simple/scratch",
"simple/screencastify",
"simple/scribd",
@@ -11760,7 +12013,9 @@
"simple/scrollreveal",
"simple/scrumalliance",
"simple/scrutinizerci",
+ "simple/scylladb",
"simple/seagate",
+ "simple/searxng",
"simple/seat",
"simple/securityscorecard",
"simple/sefaria",
@@ -11772,6 +12027,7 @@
"simple/semanticuireact",
"simple/semanticweb",
"simple/semaphoreci",
+ "simple/semrush",
"simple/semver",
"simple/sencha",
"simple/sendinblue",
@@ -11787,6 +12043,7 @@
"simple/sfml",
"simple/shadow",
"simple/shanghaimetro",
+ "simple/sharex",
"simple/sharp",
"simple/shazam",
"simple/shell",
@@ -11797,11 +12054,13 @@
"simple/shopee",
"simple/shopify",
"simple/shopware",
+ "simple/shortcut",
"simple/shotcut",
"simple/showpad",
"simple/showtime",
"simple/shutterstock",
"simple/siemens",
+ "simple/sifive",
"simple/signal",
"simple/similarweb",
"simple/simkl",
@@ -11809,7 +12068,9 @@
"simple/simpleicons",
"simple/simplenote",
"simple/sinaweibo",
+ "simple/singaporeairlines",
"simple/singlestore",
+ "simple/sitecore",
"simple/sitepoint",
"simple/sketch",
"simple/sketchfab",
@@ -11821,6 +12082,7 @@
"simple/skypack",
"simple/skype",
"simple/skypeforbusiness",
+ "simple/skyrock",
"simple/slack",
"simple/slackware",
"simple/slashdot",
@@ -11852,6 +12114,7 @@
"simple/sonarlint",
"simple/sonarqube",
"simple/sonarsource",
+ "simple/sonatype",
"simple/songkick",
"simple/songoda",
"simple/sonicwall",
@@ -11862,6 +12125,7 @@
"simple/sourceengine",
"simple/sourceforge",
"simple/sourcegraph",
+ "simple/sourcehut",
"simple/sourcetree",
"simple/southwestairlines",
"simple/spacemacs",
@@ -11875,9 +12139,13 @@
"simple/speakerdeck",
"simple/spectrum",
"simple/speedtest",
+ "simple/speedypage",
+ "simple/sphinx",
+ "simple/spigotmc",
"simple/spinnaker",
"simple/spinrilla",
"simple/splunk",
+ "simple/spoj",
"simple/spond",
"simple/spotify",
"simple/spotlight",
@@ -11893,6 +12161,7 @@
"simple/squareenix",
"simple/squarespace",
"simple/ssrn",
+ "simple/sst",
"simple/stackbit",
"simple/stackblitz",
"simple/stackedit",
@@ -11904,6 +12173,7 @@
"simple/stadia",
"simple/staffbase",
"simple/standardjs",
+ "simple/standardresume",
"simple/starbucks",
"simple/stardock",
"simple/starlingbank",
@@ -11934,7 +12204,9 @@
"simple/streamlit",
"simple/stripe",
"simple/strongswan",
+ "simple/stryker",
"simple/stubhub",
+ "simple/studio3t",
"simple/styledcomponents",
"simple/stylelint",
"simple/styleshare",
@@ -11942,10 +12214,12 @@
"simple/subaru",
"simple/sublimetext",
"simple/substack",
+ "simple/subtitleedit",
"simple/subversion",
"simple/suckless",
"simple/sumologic",
"simple/supabase",
+ "simple/supercrease",
"simple/supermicro",
"simple/superuser",
"simple/surrealdb",
@@ -11954,6 +12228,7 @@
"simple/suzuki",
"simple/svelte",
"simple/svg",
+ "simple/svgdotjs",
"simple/svgo",
"simple/swagger",
"simple/swarm",
@@ -11961,6 +12236,7 @@
"simple/swift",
"simple/swiggy",
"simple/swiper",
+ "simple/swr",
"simple/symantec",
"simple/symbolab",
"simple/symfony",
@@ -11988,6 +12264,7 @@
"simple/tata",
"simple/tauri",
"simple/taxbuzz",
+ "simple/tcs",
"simple/teamcity",
"simple/teamspeak",
"simple/teamviewer",
@@ -12002,15 +12279,18 @@
"simple/tensorflow",
"simple/teradata",
"simple/teratail",
+ "simple/termius",
"simple/terraform",
"simple/tesco",
"simple/tesla",
"simple/testcafe",
"simple/testin",
"simple/testinglibrary",
+ "simple/testrail",
"simple/tether",
"simple/textpattern",
"simple/tga",
+ "simple/thangs",
"simple/thealgorithms",
"simple/theconversation",
"simple/theirishtimes",
@@ -12025,19 +12305,23 @@
"simple/thingiverse",
"simple/thinkpad",
"simple/threadless",
+ "simple/threads",
"simple/threedotjs",
"simple/threema",
"simple/thumbtack",
"simple/thunderbird",
+ "simple/thurgauerkantonalbank",
"simple/thymeleaf",
"simple/ticketmaster",
"simple/tidal",
+ "simple/tiddlywiki",
"simple/tide",
"simple/tidyverse",
"simple/tietoevry",
"simple/tiktok",
"simple/tile",
"simple/timescale",
+ "simple/tina",
"simple/tinder",
"simple/tinyletter",
"simple/tistory",
@@ -12046,6 +12330,7 @@
"simple/tnt",
"simple/todoist",
"simple/toggl",
+ "simple/toggltrack",
"simple/tokyometro",
"simple/toml",
"simple/tomorrowland",
@@ -12054,11 +12339,13 @@
"simple/torbrowser",
"simple/torproject",
"simple/toshiba",
+ "simple/tourbox",
"simple/toyota",
"simple/tplink",
"simple/tqdm",
"simple/traefikmesh",
"simple/traefikproxy",
+ "simple/trailforks",
"simple/trainerroad",
"simple/trakt",
"simple/transportforireland",
@@ -12068,10 +12355,12 @@
"simple/trello",
"simple/trendmicro",
"simple/treyarch",
+ "simple/trilium",
"simple/triller",
"simple/trino",
"simple/tripadvisor",
"simple/tripdotcom",
+ "simple/trivy",
"simple/trove",
"simple/trpc",
"simple/truenas",
@@ -12085,6 +12374,7 @@
"simple/tui",
"simple/tumblr",
"simple/tunein",
+ "simple/turbo",
"simple/turborepo",
"simple/turbosquid",
"simple/turkishairlines",
@@ -12103,12 +12393,15 @@
"simple/ubisoft",
"simple/ublockorigin",
"simple/ubuntu",
+ "simple/ubuntumate",
"simple/udacity",
"simple/udemy",
"simple/ufc",
"simple/uikit",
"simple/ulule",
+ "simple/umami",
"simple/umbraco",
+ "simple/uml",
"simple/unacademy",
"simple/underarmour",
"simple/underscoredotjs",
@@ -12116,8 +12409,10 @@
"simple/unicode",
"simple/unilever",
"simple/unitedairlines",
+ "simple/unitednations",
"simple/unity",
"simple/unlicense",
+ "simple/uno",
"simple/unocss",
"simple/unraid",
"simple/unrealengine",
@@ -12133,6 +12428,7 @@
"simple/uptobox",
"simple/upwork",
"simple/usps",
+ "simple/utorrent",
"simple/v",
"simple/v2ex",
"simple/v8",
@@ -12143,21 +12439,25 @@
"simple/valve",
"simple/vapor",
"simple/vault",
+ "simple/vaultwarden",
"simple/vauxhall",
"simple/vbulletin",
"simple/vectorlogozone",
"simple/vectorworks",
"simple/veeam",
"simple/veepee",
+ "simple/vega",
"simple/velog",
"simple/venmo",
"simple/vercel",
"simple/verdaccio",
"simple/veritas",
"simple/verizon",
+ "simple/vespa",
"simple/vexxhost",
"simple/vfairs",
"simple/viadeo",
+ "simple/viaplay",
"simple/viber",
"simple/vim",
"simple/vimeo",
@@ -12167,20 +12467,24 @@
"simple/virtualbox",
"simple/virustotal",
"simple/visa",
+ "simple/visualbasic",
"simple/visualstudio",
"simple/visualstudiocode",
"simple/vite",
"simple/vitess",
"simple/vitest",
"simple/vivaldi",
+ "simple/vivawallet",
"simple/vivino",
"simple/vk",
"simple/vlcmediaplayer",
"simple/vmware",
"simple/vodafone",
+ "simple/voipdotms",
"simple/volkswagen",
"simple/volvo",
"simple/vonage",
+ "simple/vorondesign",
"simple/vowpalwabbit",
"simple/vox",
"simple/vsco",
@@ -12190,6 +12494,7 @@
"simple/vuetify",
"simple/vulkan",
"simple/vultr",
+ "simple/vyond",
"simple/w3c",
"simple/wacom",
"simple/wagtail",
@@ -12197,11 +12502,13 @@
"simple/wakatime",
"simple/walkman",
"simple/wallabag",
+ "simple/walletconnect",
"simple/walmart",
"simple/wantedly",
"simple/wappalyzer",
"simple/warnerbros",
"simple/warp",
+ "simple/wasabi",
"simple/wasmcloud",
"simple/wasmer",
"simple/wattpad",
@@ -12224,10 +12531,12 @@
"simple/webrtc",
"simple/webstorm",
"simple/webtoon",
+ "simple/webtrees",
"simple/wechat",
"simple/wegame",
"simple/weightsandbiases",
"simple/welcometothejungle",
+ "simple/wellfound",
"simple/wemo",
"simple/westerndigital",
"simple/wetransfer",
@@ -12237,6 +12546,7 @@
"simple/wii",
"simple/wiiu",
"simple/wikidata",
+ "simple/wikidotgg",
"simple/wikidotjs",
"simple/wikimediacommons",
"simple/wikipedia",
@@ -12245,6 +12555,7 @@
"simple/winamp",
"simple/windicss",
"simple/windows",
+ "simple/windows10",
"simple/windows11",
"simple/windows95",
"simple/windowsterminal",
@@ -12273,6 +12584,7 @@
"simple/writedotas",
"simple/wwe",
"simple/wwise",
+ "simple/x",
"simple/xamarin",
"simple/xaml",
"simple/xampp",
@@ -12294,10 +12606,12 @@
"simple/yale",
"simple/yamahacorporation",
"simple/yamahamotorcorporation",
+ "simple/yaml",
"simple/yammer",
"simple/yarn",
"simple/ycombinator",
"simple/yelp",
+ "simple/yeti",
"simple/yoast",
"simple/yolo",
"simple/yourtraveldottv",
@@ -12322,6 +12636,7 @@
"simple/zendframework",
"simple/zenn",
"simple/zenodo",
+ "simple/zensar",
"simple/zerodha",
"simple/zeromq",
"simple/zerply",
@@ -12329,9 +12644,11 @@
"simple/zhihu",
"simple/zig",
"simple/zigbee",
+ "simple/zilch",
"simple/zillow",
"simple/zincsearch",
"simple/zingat",
+ "simple/zod",
"simple/zoho",
"simple/zoiper",
"simple/zomato",
diff --git a/docs/schema/extensions/pymdownx.json b/docs/schema/extensions/pymdownx.json
index a7f4722f0..a821ca62c 100644
--- a/docs/schema/extensions/pymdownx.json
+++ b/docs/schema/extensions/pymdownx.json
@@ -224,6 +224,10 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.use_pygments",
"type": "boolean"
},
+ "pygments_lang_class": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.pygments_lang_class",
+ "type": "boolean"
+ },
"auto_title": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.auto_title",
"type": "boolean"
@@ -247,6 +251,10 @@
"anchor_linenums": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums",
"type": "boolean"
+ },
+ "line_spans": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.line_spans",
+ "type": "string"
}
},
"additionalProperties": false
@@ -531,6 +539,26 @@
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
"type": "boolean",
"default": true
+ },
+ "url_download": {
+ "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+ "type": "boolean",
+ "default": false
+ },
+ "url_max_size": {
+ "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+ "type": "integer",
+ "default": 33554432
+ },
+ "url_timeout": {
+ "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+ "type": "number",
+ "default": 10.0
+ },
+ "url_request_headers": {
+ "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+ "type": "object",
+ "default": {}
}
},
"additionalProperties": false
@@ -612,6 +640,11 @@
],
"default": true
},
+ "combine_header_slug": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.combine_header_slug",
+ "type": "boolean",
+ "default": true
+ },
"slugify": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
diff --git a/docs/schema/extra.json b/docs/schema/extra.json
index 4f294854a..b2a3db6ad 100644
--- a/docs/schema/extra.json
+++ b/docs/schema/extra.json
@@ -132,6 +132,22 @@
}
]
},
+ "annotate": {
+ "title": "Custom selectors for annotations",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
+ "type": "object",
+ "patternProperties": {
+ ".*": {
+ "title": "Custom selector",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
+ "type": "array",
+ "items": {
+ "type": "string",
+ "pattern": "^\\.\\w+"
+ }
+ }
+ }
+ },
"consent": {
"title": "Cookie consent",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",
diff --git a/docs/schema/plugins.json b/docs/schema/plugins.json
index cc73450a5..c25767d58 100644
--- a/docs/schema/plugins.json
+++ b/docs/schema/plugins.json
@@ -25,6 +25,9 @@
{
"$ref": "plugins/blog.json"
},
+ {
+ "$ref": "plugins/group.json"
+ },
{
"$ref": "plugins/info.json"
},
@@ -34,9 +37,15 @@
{
"$ref": "plugins/offline.json"
},
+ {
+ "$ref": "plugins/optimize.json"
+ },
{
"$ref": "plugins/privacy.json"
},
+ {
+ "$ref": "plugins/projects.json"
+ },
{
"$ref": "plugins/search.json"
},
@@ -45,6 +54,9 @@
},
{
"$ref": "plugins/tags.json"
+ },
+ {
+ "$ref": "plugins/typeset.json"
}
]
},
@@ -81,7 +93,7 @@
]
},
"external-community": {
- "description": "External plugins, schema provided by the community",
+ "description": "External plugins, schema provided by our community",
"anyOf": [
{
"$ref": "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/schema.json"
diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json
index 380e63e9a..0163ec227 100644
--- a/docs/schema/plugins/blog.json
+++ b/docs/schema/plugins/blog.json
@@ -3,7 +3,7 @@
"title": "Built-in blog plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
"enum": [
"blog"
]
@@ -12,30 +12,37 @@
"type": "object",
"properties": {
"blog": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.enabled",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.enabled",
"type": "boolean",
"default": true
},
"blog_dir": {
"title": "Blog directory",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_dir",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_dir",
"type": "string",
"default": "blog"
},
"blog_toc": {
"title": "Blog table of contents",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_toc",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_toc",
"type": "boolean",
"default": false
},
+ "post_dir": {
+ "title": "Blog posts directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_dir",
+ "type": "string",
+ "default": "\"{blog\\}/posts\""
+ },
"post_date_format": {
"title": "Format string for post dates",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_date_format",
+ "default": "long",
"oneOf": [
{
"enum": [
@@ -48,12 +55,11 @@
{
"type": "string"
}
- ],
- "default": "long"
+ ]
},
"post_url_date_format": {
"title": "Format string for post dates in URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_date_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_date_format",
"oneOf": [
{
"enum": [
@@ -70,7 +76,7 @@
},
"post_url_format": {
"title": "Format string for post URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_format",
"oneOf": [
{
"enum": [
@@ -87,24 +93,24 @@
},
"post_url_max_categories": {
"title": "Number of categories in post URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_max_categories",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_max_categories",
"type": "number",
"default": 1
},
"post_slugify": {
"title": "Post slugify function",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"post_slugify_separator": {
"title": "Post slugify separator",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify_separator",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify_separator",
"type": "string",
"default": "\"-\""
},
"post_excerpt": {
"title": "Post excerpts",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt",
"oneOf": [
{
"title": "Post excerpts are optional",
@@ -123,49 +129,49 @@
},
"post_excerpt_max_authors": {
"title": "Number of authors to render in post excerpts",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_authors",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_authors",
"type": "number",
"default": 1
},
"post_excerpt_max_categories": {
"title": "Number of categories to render in post excerpts",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_categories",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_categories",
"type": "number",
"default": 5
},
"post_excerpt_separator": {
"title": "Post excerpt separator",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_separator",
"type": "string",
"default": ""
},
"post_readtime": {
"title": "Post reading time computation",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime",
"type": "boolean",
"default": true
},
"post_readtime_words_per_minute": {
"title": "Post reading time words per minute",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime_words_per_minute",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime_words_per_minute",
"type": "number",
"default": 265
},
"archive": {
"title": "Archive",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive",
"type": "boolean",
"default": true
},
"archive_name": {
"title": "Archive name",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_name",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_name",
"type": "string",
"default": "Archive"
},
"archive_date_format": {
"title": "Format string for archive dates",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_date_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_date_format",
"oneOf": [
{
"enum": [
@@ -181,7 +187,7 @@
},
"archive_url_date_format": {
"title": "Format string for archive dates in URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_date_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_date_format",
"oneOf": [
{
"enum": [
@@ -197,7 +203,7 @@
},
"archive_url_format": {
"title": "Format string for archive URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_format",
"oneOf": [
{
"enum": [
@@ -211,25 +217,25 @@
},
"archive_toc": {
"title": "Archive table of contents",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_toc",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_toc",
"type": "boolean",
"default": false
},
"categories": {
"title": "Categories",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories",
"type": "boolean",
"default": true
},
"categories_name": {
"title": "Categories name",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_name",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_name",
"type": "string",
"default": "Categories"
},
"categories_url_format": {
"title": "Format string for category URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_url_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_url_format",
"oneOf": [
{
"enum": [
@@ -244,18 +250,18 @@
},
"categories_slugify": {
"title": "Categories slugify function",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"categories_slugify_separator": {
"title": "Categories slugify separator",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify_separator",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify_separator",
"type": "string",
"default": "\"-\""
},
"categories_allowed": {
"title": "Categories allowed",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_allowed",
"type": "array",
"items": {
"type": "string"
@@ -265,25 +271,25 @@
},
"categories_toc": {
"title": "Categories table of contents",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_toc",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_toc",
"type": "boolean",
"default": false
},
"pagination": {
"title": "Pagination",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination",
"type": "boolean",
"default": true
},
"pagination_per_page": {
"title": "Posts per page",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_per_page",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_per_page",
"type": "number",
"default": 10
},
"pagination_url_format": {
"title": "Format string for pagination URLs",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_url_format",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_url_format",
"oneOf": [
{
"enum": [
@@ -298,7 +304,7 @@
},
"pagination_template": {
"title": "Template string for pagination",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_template",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_template",
"oneOf": [
{
"enum": [
@@ -315,37 +321,37 @@
},
"pagination_keep_content": {
"title": "Paginated indexes inherit content",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_keep_content",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_keep_content",
"type": "boolean",
"default": false
},
"authors": {
"title": "Author info",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors",
"type": "boolean",
"default": true
},
"authors_file": {
"title": "Authors file",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_file",
"type": "string",
- "default": ".authors.yml"
+ "default": "\"{blog\\}/.authors.yml\""
},
"draft": {
"title": "Render posts marked as drafts",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft",
"type": "boolean",
"default": false
},
"draft_on_serve": {
"title": "Render posts marked as drafts when previewing",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_on_serve",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_on_serve",
"type": "boolean",
"default": true
},
"draft_if_future_date": {
"title": "Automatically mark posts with future dates as drafts",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_if_future_date",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_if_future_date",
"type": "boolean",
"default": false
}
diff --git a/docs/schema/plugins/group.json b/docs/schema/plugins/group.json
new file mode 100644
index 000000000..f5c564703
--- /dev/null
+++ b/docs/schema/plugins/group.json
@@ -0,0 +1,29 @@
+{
+ "$schema": "https://json-schema.org/draft-07/schema",
+ "title": "Built-in group plugin",
+ "oneOf": [
+ {
+ "type": "object",
+ "properties": {
+ "group": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/",
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.enabled",
+ "type": "boolean",
+ "default": true
+ },
+ "plugins": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.plugins",
+ "$ref": "../plugins.json"
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+ }
+ ]
+}
diff --git a/docs/schema/plugins/info.json b/docs/schema/plugins/info.json
index 26cc6236a..f026b010c 100644
--- a/docs/schema/plugins/info.json
+++ b/docs/schema/plugins/info.json
@@ -3,7 +3,7 @@
"title": "Built-in info plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
"enum": [
"info"
]
@@ -12,12 +12,30 @@
"type": "object",
"properties": {
"info": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled",
+ "type": "boolean",
+ "default": true
+ },
+ "enabled_on_serve": {
+ "title": "Enable plugin when previewing",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled_on_serve",
+ "type": "boolean",
+ "default": false
+ },
+ "archive": {
+ "title": "Enable creation of archive",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive",
+ "type": "boolean",
+ "default": true
+ },
+ "archive_stop_on_violation": {
+ "title": "Stop creation of archive on violation",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive_stop_on_violation",
"type": "boolean",
"default": true
}
diff --git a/docs/schema/plugins/meta.json b/docs/schema/plugins/meta.json
index aef3495dd..4aa12445e 100644
--- a/docs/schema/plugins/meta.json
+++ b/docs/schema/plugins/meta.json
@@ -3,7 +3,7 @@
"title": "Built-in meta plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
"enum": [
"meta"
]
@@ -12,12 +12,18 @@
"type": "object",
"properties": {
"meta": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
"type": "object",
"properties": {
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.enabled",
+ "type": "boolean",
+ "default": true
+ },
"meta_file": {
"title": "Meta file name",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+meta.meta_file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.meta_file",
"pattern": "\\.yml$",
"default": "\"**/.meta.yml\""
}
diff --git a/docs/schema/plugins/offline.json b/docs/schema/plugins/offline.json
index e97b620aa..3c0f5ea65 100644
--- a/docs/schema/plugins/offline.json
+++ b/docs/schema/plugins/offline.json
@@ -3,7 +3,7 @@
"title": "Built-in offline plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
"enum": [
"offline"
]
@@ -12,12 +12,12 @@
"type": "object",
"properties": {
"offline": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#+offline.enabled",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/#config.enabled",
"type": "boolean",
"default": true
}
diff --git a/docs/schema/plugins/optimize.json b/docs/schema/plugins/optimize.json
new file mode 100644
index 000000000..346eee078
--- /dev/null
+++ b/docs/schema/plugins/optimize.json
@@ -0,0 +1,120 @@
+{
+ "$schema": "https://json-schema.org/draft-07/schema",
+ "title": "Built-in optimize plugin",
+ "oneOf": [
+ {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
+ "enum": [
+ "optimize"
+ ]
+ },
+ {
+ "type": "object",
+ "properties": {
+ "optimize": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.enabled",
+ "type": "boolean",
+ "default": true
+ },
+ "concurrency": {
+ "title": "Concurrency (number of CPUs)",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.concurrency",
+ "type": "number"
+ },
+ "cache": {
+ "title": "Enable caching",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache",
+ "type": "boolean",
+ "default": true
+ },
+ "cache_dir": {
+ "title": "Cache directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache_dir",
+ "type": "string",
+ "default": ".cache/plugins/optimize"
+ },
+ "optimize_png": {
+ "title": "Optimization of PNGs",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png",
+ "type": "boolean",
+ "default": true
+ },
+ "optimize_png_speed": {
+ "title": "Speed/quality tradeoff [1,10]",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_speed",
+ "type": "number",
+ "default": 4
+ },
+ "optimize_png_strip": {
+ "title": "Strip unnecessary metadata from PNGs",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_strip",
+ "type": "boolean",
+ "default": true
+ },
+ "optimize_jpg": {
+ "title": "Optimization of JPGs",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg",
+ "type": "boolean",
+ "default": true
+ },
+ "optimize_jpg_quality": {
+ "title": "Speed/quality tradeoff for pngquant [0,10]",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_quality",
+ "type": "number",
+ "default": 60
+ },
+ "optimize_jpg_progressive": {
+ "title": "Progressive encoding (faster rendering)",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_progressive",
+ "type": "boolean",
+ "default": true
+ },
+ "optimize_include": {
+ "title": "Files or folders to include",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
+ "type": "array",
+ "items": {
+ "title": "Files or folders matching this pattern will be included",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "optimize_exclude": {
+ "title": "Files or folders to exclude",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
+ "type": "array",
+ "items": {
+ "title": "Files or folders matching this pattern will be excluded",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "print_gain": {
+ "title": "Print optimization gain",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain",
+ "type": "boolean",
+ "default": true
+ },
+ "print_gain_summary": {
+ "title": "Print optimization gain summary",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain_summary",
+ "type": "boolean",
+ "default": true
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+ }
+ ]
+}
diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json
index 4afa6559f..85593a117 100644
--- a/docs/schema/plugins/privacy.json
+++ b/docs/schema/plugins/privacy.json
@@ -3,7 +3,7 @@
"title": "Built-in privacy plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
"enum": [
"privacy"
]
@@ -12,74 +12,83 @@
"type": "object",
"properties": {
"privacy": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.enabled",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.concurrency",
"type": "number"
},
- "external_assets": {
- "title": "External assets",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets",
- "oneOf": [
- {
- "title": "Bundle external assets",
- "enum": ["bundle"]
- },
- {
- "title": "Report external assets as warnings",
- "enum": ["report"]
- }
- ],
- "default": "bundle"
- },
- "external_assets_dir": {
- "title": "External assets download directory",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir",
- "type": "string",
- "default": "assets/external"
- },
- "external_assets_include": {
- "title": "External assets to include",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
- "type": "array",
- "items": {
- "title": "External assets matching this pattern will be downloaded",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
- "pattern": ".*"
- },
- "uniqueItems": true,
- "minItems": 1
- },
- "external_assets_exclude": {
- "title": "External assets to exclude",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
- "type": "array",
- "items": {
- "title": "External assets matching this pattern will not be downloaded",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
- "pattern": ".*"
- },
- "uniqueItems": true,
- "minItems": 1
- },
- "external_links": {
- "title": "External links",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links",
+ "cache": {
+ "title": "Enable caching",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache",
"type": "boolean",
"default": true
},
- "external_links_attr_map": {
+ "cache_dir": {
+ "title": "Cache directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache_dir",
+ "type": "string",
+ "default": ".cache/plugins/privacy"
+ },
+ "assets": {
+ "title": "Process external assets",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets",
+ "type": "boolean",
+ "default": true
+ },
+ "assets_fetch": {
+ "title": "Download external assets",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch",
+ "type": "boolean",
+ "default": true
+ },
+ "assets_fetch_dir": {
+ "title": "Download external assets to this directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch_dir",
+ "type": "string",
+ "default": "assets/external"
+ },
+ "assets_include": {
+ "title": "External assets to include",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
+ "type": "array",
+ "items": {
+ "title": "External assets matching this pattern will be downloaded",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "assets_exclude": {
+ "title": "External assets to exclude",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
+ "type": "array",
+ "items": {
+ "title": "External assets matching this pattern will not be downloaded",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "links": {
+ "title": "Process external links",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links",
+ "type": "boolean",
+ "default": true
+ },
+ "links_attr_map": {
"title": "Custom attributes to add to external links",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_attr_map",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_attr_map",
"type": "object",
"patternProperties": {
"^[\\w_]+$": {
@@ -87,9 +96,9 @@
}
}
},
- "external_links_noopener": {
+ "links_noopener": {
"title": "Behavior for external links that open in new windows",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_noopener",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_noopener",
"type": "boolean",
"default": true
}
diff --git a/docs/schema/plugins/projects.json b/docs/schema/plugins/projects.json
new file mode 100644
index 000000000..e8d42329a
--- /dev/null
+++ b/docs/schema/plugins/projects.json
@@ -0,0 +1,82 @@
+{
+ "$schema": "https://json-schema.org/draft-07/schema",
+ "title": "Built-in projects plugin",
+ "oneOf": [
+ {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
+ "enum": [
+ "projects"
+ ]
+ },
+ {
+ "type": "object",
+ "properties": {
+ "projects": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.enabled",
+ "type": "boolean",
+ "default": true
+ },
+ "concurrency": {
+ "title": "Concurrency (number of CPUs)",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.concurrency",
+ "type": "number"
+ },
+ "cache": {
+ "title": "Enable caching",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache",
+ "type": "boolean",
+ "default": true
+ },
+ "cache_dir": {
+ "title": "Cache directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache_dir",
+ "type": "string",
+ "default": ".cache/plugins/projects"
+ },
+ "projects": {
+ "title": "Enable projects",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects",
+ "type": "boolean",
+ "default": true
+ },
+ "projects_dir": {
+ "title": "Projects directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_dir",
+ "type": "string",
+ "default": "projects"
+ },
+ "projects_config_files": {
+ "title": "Projects configuration files",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_files",
+ "type": "string",
+ "default": "\"*/mkdocs.yml\""
+ },
+ "projects_config_transform": {
+ "title": "Projects configuration transform",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_transform",
+ "type": "string",
+ "defaultSnippets": [
+ {
+ "body": "!!python/name:${1:module}.${2:function}"
+ }
+ ]
+ },
+ "hosting": {
+ "title": "Enable hoisting",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.hoisting",
+ "type": "boolean",
+ "default": true
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+ }
+ ]
+}
diff --git a/docs/schema/plugins/search.json b/docs/schema/plugins/search.json
index bbd1641b5..68112b917 100644
--- a/docs/schema/plugins/search.json
+++ b/docs/schema/plugins/search.json
@@ -3,7 +3,7 @@
"title": "Built-in search plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
"enum": [
"search"
]
@@ -12,7 +12,7 @@
"type": "object",
"properties": {
"search": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
"type": "object",
"properties": {
"lang": {
@@ -33,12 +33,12 @@
},
"separator": {
"title": "Separator for indexing and query tokenization",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.separator",
"type": "string"
},
"pipeline": {
"title": "Text processing pipeline for indexing",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.pipeline",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.pipeline",
"type": "array",
"items": {
"enum": [
@@ -51,12 +51,12 @@
},
"jieba_dict": {
"title": "Jieba dictionary replacement",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict",
"type": "string"
},
"jieba_dict_user": {
"title": "Jieba dictionary augmentation",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict_user",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict_user",
"type": "string"
}
},
@@ -69,7 +69,7 @@
"definitions": {
"lang": {
"title": "Site search language",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.lang",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.lang",
"oneOf": [
{
"title": "Site search language: Arabic",
diff --git a/docs/schema/plugins/social.json b/docs/schema/plugins/social.json
index 161d7cf8c..efc29594a 100644
--- a/docs/schema/plugins/social.json
+++ b/docs/schema/plugins/social.json
@@ -3,7 +3,7 @@
"title": "Built-in social plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
"enum": [
"social"
]
@@ -12,54 +12,129 @@
"type": "object",
"properties": {
"social": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
"type": "object",
"properties": {
- "cards": {
- "title": "Social card generation",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.enabled",
"type": "boolean",
"default": true
},
- "cards_color": {
- "title": "Social card color palette",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
- "type": "object",
- "properties": {
- "fill": {
- "title": "Background fill color",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
- "type": "string"
- },
- "text": {
- "title": "Foreground text color",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
- "type": "string"
- }
- },
- "additionalProperties": false,
- "required": [
- "fill",
- "text"
- ]
+ "concurrency": {
+ "title": "Concurrency (number of CPUs)",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.concurrency",
+ "type": "number"
},
- "cards_font": {
- "$ref": "../assets/fonts.json"
+ "cache": {
+ "title": "Enable caching",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache",
+ "type": "boolean",
+ "default": true
+ },
+ "cache_dir": {
+ "title": "Cache directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache_dir",
+ "type": "string",
+ "default": ".cache/plugins/social"
+ },
+ "cards": {
+ "title": "Social cards",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards",
+ "type": "boolean",
+ "default": true
},
"cards_dir": {
- "title": "Social card directory",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
+ "title": "Social cards directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir",
"type": "string",
"default": "assets/images/social"
+ },
+ "cards_layout_dir": {
+ "title": "Social cards layout directory",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_dir",
+ "type": "string",
+ "default": "layouts"
+ },
+ "cards_layout": {
+ "title": "Social cards layout",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout",
+ "default": "default",
+ "oneOf": [
+ {
+ "enum": [
+ "default",
+ "default/accent",
+ "default/invert",
+ "default/variant"
+ ]
+ },
+ {
+ "type": "string"
+ }
+ ]
+ },
+ "cards_layout_options": {
+ "title": "Social cards layout options",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_options",
+ "type": "object"
+ },
+ "cards_include": {
+ "title": "Pages or folders to include",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
+ "type": "array",
+ "items": {
+ "title": "Pages or folders matching this pattern will be included",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "cards_exclude": {
+ "title": "Pages or folders to exclude",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
+ "type": "array",
+ "items": {
+ "title": "Pages or folders matching this pattern will be excluded",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
+ "pattern": ".*"
+ },
+ "uniqueItems": true,
+ "minItems": 1
+ },
+ "debug": {
+ "title": "Debug mode",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug",
+ "type": "boolean",
+ "default": true
+ },
+ "debug_on_build": {
+ "title": "Always disable debug mode on build",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_on_build",
+ "type": "boolean",
+ "default": false
+ },
+ "debug_grid": {
+ "title": "Debug grid",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid",
+ "type": "boolean",
+ "default": true
+ },
+ "debug_grid_step": {
+ "title": "Debug grid step size",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid_step",
+ "type": "number",
+ "default": 32
+ },
+ "debug_color": {
+ "title": "Debug color",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_color",
+ "type": "string",
+ "default": "yellow"
}
},
- "additionalProperties": false,
- "defaultSnippets": [
- {
- "label": "cards_font",
- "body": "cards_font: ${1:Roboto}"
- }
- ]
+ "additionalProperties": false
}
},
"additionalProperties": false
diff --git a/docs/schema/plugins/tags.json b/docs/schema/plugins/tags.json
index 541b0fdae..b85385796 100644
--- a/docs/schema/plugins/tags.json
+++ b/docs/schema/plugins/tags.json
@@ -3,7 +3,7 @@
"title": "Built-in tags plugin",
"oneOf": [
{
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
"enum": [
"tags"
]
@@ -12,24 +12,24 @@
"type": "object",
"properties": {
"tags": {
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.enabled",
"type": "boolean",
"default": true
},
"tags_file": {
"title": "Markdown file to render tags index",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_file",
"pattern": "\\.md$",
"default": "tags.md"
},
"tags_extra_files": {
"title": "Markdown files to render additional tags indexes",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_extra_files",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_extra_files",
"type": "object",
"patternProperties": {
"\\.md$": {
@@ -44,18 +44,38 @@
},
"tags_slugify": {
"title": "Tags slugify function",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"tags_slugify_separator": {
"title": "Tags slugify separator",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify_separator",
"type": "string",
"default": "\"-\""
},
+ "tags_compare": {
+ "title": "Sort tags by this function",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare",
+ "default": "!!python/name:material.plugins.tags.casefold"
+ },
+ "tags_compare_reverse": {
+ "title": "Soft tags in reverse",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare_reverse",
+ "default": false
+ },
+ "tags_pages_compare": {
+ "title": "Sort tags pages by this function",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare",
+ "default": "!!python/name:material.plugins.tags.page_title"
+ },
+ "tags_pages_compare_reverse": {
+ "title": "Soft tags pages in reverse",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare_reverse",
+ "default": false
+ },
"tags_allowed": {
"title": "Tags allowed",
- "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_allowed",
"type": "array",
"items": {
"type": "string"
diff --git a/docs/schema/plugins/typeset.json b/docs/schema/plugins/typeset.json
new file mode 100644
index 000000000..d6fcdb188
--- /dev/null
+++ b/docs/schema/plugins/typeset.json
@@ -0,0 +1,31 @@
+{
+ "$schema": "https://json-schema.org/draft-07/schema",
+ "title": "Built-in typeset plugin",
+ "oneOf": [
+ {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
+ "enum": [
+ "typeset"
+ ]
+ },
+ {
+ "type": "object",
+ "properties": {
+ "typeset": {
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "title": "Enable plugin",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/#config.enabled",
+ "type": "boolean",
+ "default": true
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+ }
+ ]
+}
diff --git a/docs/schema/theme.json b/docs/schema/theme.json
index 9f51b902f..1f903153b 100644
--- a/docs/schema/theme.json
+++ b/docs/schema/theme.json
@@ -214,6 +214,12 @@
"ka"
]
},
+ {
+ "title": "Site language: Kannada",
+ "enum": [
+ "kn"
+ ]
+ },
{
"title": "Site language: Korean",
"enum": [
@@ -304,6 +310,12 @@
"ru"
]
},
+ {
+ "title": "Site language: Sanskrit",
+ "enum": [
+ "sa"
+ ]
+ },
{
"title": "Site language: Serbo-Croatian",
"enum": [
@@ -340,6 +352,12 @@
"sv"
]
},
+ {
+ "title": "Site language: Telugu",
+ "enum": [
+ "te"
+ ]
+ },
{
"title": "Site language: Thai",
"enum": [
@@ -611,6 +629,13 @@
"content.code.copy"
]
},
+ {
+ "title": "Code selection button",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-selection-button",
+ "enum": [
+ "content.code.select"
+ ]
+ },
{
"title": "Linked content tabs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs",
@@ -918,7 +943,8 @@
"grey",
"blue grey",
"black",
- "white"
+ "white",
+ "custom"
]
},
"accent": {
@@ -945,7 +971,8 @@
"grey",
"blue grey",
"black",
- "white"
+ "white",
+ "custom"
]
},
"icon": {
diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md
index 9fad62546..00022d939 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
...
```
@@ -102,6 +102,6 @@ If you wish to enable comments for an entire folder, you can use the
[Giscus GitHub App]: https://github.com/apps/giscus
[theme extension]: ../customization.md#extending-the-theme
- [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
+ [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
[overriding partials]: ../customization.md#overriding-partials
- [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+ [built-in meta plugin]: ../plugins/meta.md
diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md
index 2315c7c48..9b54aef6f 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,9 +222,15 @@ The following configuration options are supported:
enable_creation_date: true
```
-[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date }
+ !!! note "When using build environments"
-: :octicons-milestone-24: Default: `false` – Enables falling back to
+ 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].
+
+
+
+: 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:
@@ -245,15 +244,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
@@ -280,9 +278,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]:
@@ -292,9 +290,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 `/`:
@@ -304,9 +302,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
@@ -326,14 +324,16 @@ 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 extracts the authors of a document from git to display
-them at the bottom of each page. It's a lightweight alternative to the
-[git-committers] plugin. Install it with `pip`:
+The [git-authors] plugin is a lightweight alternative to the
+[git-committers] plugin and extracts the authors of a document from git to display
+them at the bottom of each page.
+
+[Insiders] offers deep integration for [git-authors]. This means the [customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme) are not necessary, and additional styling (such as nice icons) are added. Simply install it with `pip`:
```
pip install mkdocs-git-authors-plugin
diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md
index 1110dfc98..a75b101ae 100644
--- a/docs/setup/building-an-optimized-site.md
+++ b/docs/setup/building-an-optimized-site.md
@@ -1,7 +1,3 @@
----
-status: new
----
-
# Building an optimized site
Material for MkDocs, by default, allows to build optimized sites that rank great
@@ -13,12 +9,45 @@ further useful automatic optimization techniques.
## Configuration
-### Built-in optimize plugin :material-alert-decagram:{ .mdx-pulse title="Added on January 21, 2023" }
+### 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.29.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
+__serve them together__. Add the following to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [projects]: ../plugins/projects.md
+ [plugin documentation]: ../plugins/projects.md
+
+??? info "Use cases for the projects plugin"
+
+ Ideal use cases for the projects plugin are:
+
+ - Building a multi-language site
+ - Building a blog alongside your documentation
+ - Splitting large code bases for better performance
+
+ Note that the plugin is currently experimental. We're releasing it early,
+ so that we can improve it together with our users and make it even more
+ powerful as we discover new use cases.
+
+### Built-in optimize plugin
+
+
+
+
+
The built-in optimize plugin automatically identifies and optimizes all media
files as part of the build using compression and conversion techniques. Add
@@ -26,180 +55,9 @@ the following lines to `mkdocs.yml`:
``` yaml
plugins:
- - optimize # (1)!
+ - optimize
```
-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: path/to/folder
- ```
-
- 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..5c13b5742 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,12 +34,9 @@ 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
+ [built-in privacy plugin]:../plugins/privacy.md
#### Limitations
diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md
index 07106b8eb..444c81d82 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
@@ -105,12 +103,12 @@ Click on a tile to change the primary color:
})
- [Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
+See our guide below to learn how to set [custom colors].
#### 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
@@ -162,12 +160,13 @@ Click on a tile to change the accent color:
})
- [Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
+See our guide below to learn how to set [custom colors].
### 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
@@ -209,9 +208,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:
@@ -221,13 +220,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
@@ -236,8 +234,9 @@ 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
@@ -266,13 +265,12 @@ 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
@@ -318,11 +316,24 @@ reload the site.
### Custom colors
+
+
+
Material for MkDocs implements colors using [CSS variables] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional style sheet] and
tweak the values of the CSS variables.
+First, set the [`primary`][palette.primary] or [`accent`][palette.accent] values
+in `mkdocs.yml` to `custom`, to signal to the theme that you want to define
+custom colors, e.g., when you want to override the `primary` color:
+
+``` yaml
+theme:
+ palette:
+ primary: custom
+```
+
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__YouTube__, and want to set the primary color to your brand's palette. Just
add:
@@ -347,7 +358,7 @@ add:
See the file containing the [color definitions] for a list of all CSS variables.
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
- [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+ [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
[additional style sheet]: ../customization.md#additional-css
diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md
index d2d7a46af..f3af6ac3f 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,8 +68,7 @@ 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
+ [built-in privacy plugin]:../plugins/privacy.md
## 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 e3ddc2326..d23a86611 100644
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@@ -1,7 +1,7 @@
# Changing the language
Material for MkDocs supports internationalization (i18n) and provides
-translations for template variables and labels in 50+ languages. Additionally,
+translations for template variables and labels in 60+ languages. Additionally,
the site search can be configured to use a language-specific stemmer, if
available.
@@ -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:
@@ -37,11 +37,10 @@ the default slug function works. Consider using a [Unicode-aware slug function].
!!! tip "Translations missing? Help us out, it takes only 5 minutes"
Material for MkDocs relies on outside contributions for adding and updating
- translations for the almost 60 languages it supports. If your language shows
- 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].
+ translations for the more than 60 languages it supports. If your language
+ shows 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
@@ -176,5 +172,5 @@ adjust the ones you want to override:
```
[theme extension]: ../customization.md#extending-the-theme
- [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
- [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
+ [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
+ [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md
index c267fba00..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,9 +68,43 @@ 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
+
+[:octicons-tag-24: 9.2.0][Site icon support]
+
+Most icons you see on your site, such as navigation icons, can also be changed. For example,
+to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
+
+```yaml
+theme:
+ icon:
+ previous: fontawesome/solid/angle-left
+ next: fontawesome/solid/angle-right
+```
+
+The following is a complete list of customizable icons used by the theme:
+
+| Icon name | Purpose |
+|:-------------|:------------------------------------------------------------------------------|
+| `logo` | See [Logo](#logo) |
+| `menu` | Open drawer |
+| `alternate` | Change language |
+| `search` | Search icon |
+| `share` | Share search |
+| `close` | Reset search, dismiss announcements |
+| `top` | Back-to-top button |
+| `edit` | Edit current page |
+| `view` | View page source |
+| `repo` | Repository icon |
+| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons) |
+| `tag` | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
+| `previous` | Previous page in footer, hide search on mobile |
+| `next` | Next page in footer |
+
+ [Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
+
## Customization
### Additional icons
diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md
index 5f2417963..3b53fb12f 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,10 @@ 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 +38,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 +101,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 +129,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 +147,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,244 +161,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 } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
-
-: :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:
-
-[`external_assets`](#+privacy.external_assets){ #+privacy.external_assets }
-
-: :octicons-milestone-24: Default: `bundle` – This option specifies what the
- plugin should do when encountering external assets. There are two options:
- while `report` will issue warning messages during the build, `bundle` will
- automatically download all external files and adjust all references:
-
- ``` yaml
- plugins:
- - privacy:
- external_assets: bundle
- ```
-
- If you've removed all external assets from your project via [customization],
- it's still a good idea to enable the plugin and set the mode to `report`,
- as the plugin will make sure that there are no hidden external links in any
- Markdown files that were unintentionally added.
-
- Using `report` in [strict mode] will make the build fail when external
- assets are detected.
-
-[`external_assets_dir`](#+privacy.external_assets_dir){ #+privacy.external_assets_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:
- external_assets_dir: assets/external
- ```
-
- The path must be defined relative to [`docs_dir`][docs_dir].
-
-[`external_assets_include`](#+privacy.external_assets_include){ #+privacy.external_assets_include } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
-
-: :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:
- external_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].
-
-[`external_assets_exclude`](#+privacy.external_assets_exclude){ #+privacy.external_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:
- external_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/mathjax.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:
-
-[`external_links`](#+privacy.external_links){ #+privacy.external_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:
- external_links: !ENV [CI, false]
- ```
-
-[`external_links_attr_map`](#+privacy.external_links_attr_map){ #+privacy.external_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:
- external_links_attr_map:
- target: _blank
- ```
-
-[`external_links_noopener`](#+privacy.external_links_noopener){ #+privacy.external_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:
- external_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"
@@ -470,72 +278,27 @@ 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-18"
- name: ci
- on:
- push:
- branches:
- - master
- - main
- jobs:
- deploy:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v2
- - uses: actions/setup-python@v2
- with:
- python-version: 3.x
- - uses: actions/cache@v2
- with:
- key: ${{ github.ref }}
- path: .cache
- - 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
+
+
+
If you've customized the [cookie consent] and added a `custom` cookie, the user
-will be prompted to accept your custom cookie. Use [additional JavaScript] to
-check whether the user accepted it:
+will be prompted to accept or reject your custom cookie. Once the user accepts
+or rejects the cookie consent, or [changes the settings], the page reloads[^1].
+Use [additional JavaScript] to query the result:
+
+ [^1]:
+ We reload the page to make interop with custom cookies simpler. If Material
+ for MkDocs would implement a callback-based approach, the author would need
+ to make sure to correctly update all scripts that use cookies. Additionally,
+ the cookie consent is only answered initially, which is why we consider this
+ to be a good trade-off of DX and UX.
=== ":octicons-file-code-16: `docs/javascripts/consent.js`"
@@ -543,6 +306,8 @@ check whether the user accepted it:
var consent = __md_get("__consent")
if (consent && consent.custom) {
/* The user accepted the cookie */
+ } else {
+ /* The user rejected the cookie */
}
```
@@ -554,3 +319,4 @@ check whether the user accepted it:
```
[additional JavaScript]: ../customization.md#additional-javascript
+ [changes the settings]: #change-cookie-settings
diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md
index 3f6ad8943..3b19859ce 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,18 +77,17 @@ 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
[additional JavaScript]: ../../customization.md#additional-javascript
- [Using block syntax]: ../../reference/mathjax.md#using-block-syntax
- [Using inline block syntax]: ../../reference/mathjax.md#using-inline-block-syntax
+ [Using block syntax]: ../../reference/math.md#using-block-syntax
+ [Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
### 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,21 @@ 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 enables the content tabs
+ [combine_header_slug style] flag, which prepends the id of the header to
+ the id of the tab:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ combine_header_slug: true
+ ```
+
+
+
+: 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,9 +713,8 @@ 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
+ [combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
[Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
@@ -727,8 +723,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 +738,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 +750,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 +771,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
new file mode 100644
index 000000000..124bf5a4c
--- /dev/null
+++ b/docs/setup/index.md
@@ -0,0 +1,90 @@
+# Setup
+
+Material for MkDocs offers a wide range of options for customizing your
+documentation. In this section, we will explain how you can create a meaningful
+structure for your site, change the look and feel, add a blog and comment system,
+and build a highly optimized site.
+
+## Site structure
+
+Set up and customize the structure of your documentation by configuring the
+header and footer to your taste, choosing among many modes of navigation,
+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-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
+
+
+
+ [Language]: changing-the-language.md
+ [Navigation]: setting-up-navigation.md
+ [Header]: setting-up-the-header.md
+ [Footer]: setting-up-the-footer.md
+ [Search]: setting-up-site-search.md
+ [Tags]: setting-up-tags.md
+
+
+## Appearance
+
+Match your brand's colors, fonts, icons, logo, and more with a few lines of
+configuration – Material for MkDocs makes it easy to extend the basic
+configuration or alter the appearance.
+
+
+
+- :material-brush-variant: __[Colors]__ Change colors with an existing color palette or customize with CSS
+- :material-format-font: __[Fonts]__ – Choose among 1,000 Google Fonts or load self-hosted fonts
+- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the 8,000+ icons, or add new ones
+- :material-cards-variant: __[Social Cards]__ – Automatically create social media previews when sharing links
+
+
+
+ [Colors]: changing-the-colors.md
+ [Fonts]: changing-the-fonts.md
+ [Logo & Icons]: changing-the-logo-and-icons.md
+ [Social Cards]: setting-up-social-cards.md
+
+## Content
+
+Create a blog, integrate a comment system, connect a git repository, and set up
+versioned documentation that matches your project's versioning methodology.
+
+
+
+- :material-book-open-outline: __[Blog]__ – Set up a standalone blog or host it alongside your documentation
+- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer
+- :octicons-versions-16: __[Versioning]__ – Deploy multiple versions by integrating with external utilities
+- :octicons-repo-16: __[Repository]__ – Connect your documentation to your git repository
+
+
+
+ [Blog]: setting-up-a-blog.md
+ [Comment System]: adding-a-comment-system.md
+ [Versioning]: setting-up-versioning.md
+ [Repository]: adding-a-git-repository.md
+
+## Optimization
+
+Add site analytics and build an optimized site by adding automatic image
+compression, complying with GDPR data privacy regulations, and making it
+offline-capable.
+
+
+
+- :material-google-analytics: __[Site analytics]__ – Learn how your users experience your documentation
+- :material-screwdriver: __[Optimized site]__ – Create optimized sites that rank great on search engines
+- :octicons-lock-16: __[Data Privacy]__ – Ensure compliance with data privacy regulations
+- :octicons-cloud-offline-16: __[Offline usage]__ – Build an online and offline-capable documentation
+
+
+
+ [Site analytics]: setting-up-site-analytics.md
+ [Optimized site]: building-an-optimized-site.md
+ [Data Privacy]: ensuring-data-privacy.md
+ [Offline usage]: building-for-offline-usage.md
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index 1470cf79d..d6324ac8d 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/docs/setup/setting-up-a-blog.md
@@ -9,20 +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-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.23.0][Insiders] ·
-: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
@@ -33,819 +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:
-
-``` { .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: path/to/folder
- ```
-
- === "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.__
-
----
+ [plugin documentation]: ../plugins/blog.md
[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_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_template`](#+blog.pagination_template){ #+blog.pagination_template }
-
-: :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_template: "~2~"
- ```
-
- === "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
-
- ``` yaml
- plugins:
- - blog:
- pagination_template: "$link_first $link_previous ~2~ $link_next $link_last"
- ```
-
- === "1 :material-chevron-right:"
-
- ``` yaml
- plugins:
- - blog:
- pagination_template: "$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_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: `.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: .authors.yml
- ```
-
- The path must be defined relative to [`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-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.23.0][Insiders] ·
-[: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`:
```
@@ -873,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]:
@@ -885,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:
@@ -897,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
@@ -910,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:
@@ -924,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:
@@ -942,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
@@ -978,7 +181,7 @@ Create a new file called `hello-world.md` and add the following lines:
``` yaml
---
draft: true # (1)!
-date: 2022-01-31
+date: 2023-01-31
categories:
- Hello
- World
@@ -988,17 +191,34 @@ 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,
+ allowing you to define a date when you last updated the blog post +
+ further custom dates you can add to the template:
+
+ ``` yaml
+ ---
+ date:
+ created: 2022-01-31
+ updated: 2022-02-02
+ ---
+
+ # Hello world!
+ ```
+
+ Note that the creation date __must__ be set under `date.created`, as each
+ blog post must have a creation date set.
+
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
@@ -1022,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
@@ -1031,31 +251,32 @@ post with one or multiple [authors]. First, create the
[`.authors.yml`][authors_file] file in your blog directory, and add an author:
``` yaml
-squidfunk:
- name: Martin Donath
- description: Creator
- avatar: https://github.com/squidfunk.png
+authors:
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
```
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.
@@ -1066,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
...
@@ -1076,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
@@ -1088,7 +309,7 @@ add them to the front matter `categories` property:
``` yaml
---
-date: 2022-01-31
+date: 2023-01-31
categories:
- Hello
- World
@@ -1104,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
@@ -1114,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
@@ -1124,25 +345,42 @@ 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.
- [built-in tags plugin]: setting-up-tags.md#built-in-tags-plugin
+ [built-in tags plugin]: ../plugins/tags.md
[tags index]: setting-up-tags.md#adding-a-tags-index
+#### Changing the slug
+
+Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:
+
+``` yaml
+---
+slug: hello-world
+---
+
+# Hello there world!
+...
+```
+
#### Adding related links
-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
+ - plugins/search.md
- insiders/index.md#how-to-become-a-sponsor
---
@@ -1156,9 +394,9 @@ 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
+ - plugins/search.md
- insiders/index.md#how-to-become-a-sponsor
- Nested section:
- External link: https://example.com
@@ -1170,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
@@ -1182,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
@@ -1197,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.
@@ -1206,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
---
@@ -1227,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
@@ -1272,13 +510,13 @@ Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
values defined for a post, which means you can define common properties in
`.meta.yml` and then add specific properties or overrides for each post.
- [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+ [built-in meta plugin]: ../plugins/meta.md
### Adding pages
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
@@ -1293,10 +531,11 @@ nav:
### Custom index pages
-[: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:
@@ -1340,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
@@ -1351,14 +590,10 @@ which means you can override all templates used for the blog by using
The following templates are added by the [built-in blog plugin]:
-- [`blog.html`][blog.html] – Template for blog index
+- [`blog.html`][blog.html] – Template for blog, archive and category index
- [`blog-post.html`][blog-post.html] – Template for blog post
-- [`blog-archive.html`][blog-archive.html] – Template for blog archive index
-- [`blog-category.html`][blog-category.html] – Template for blog category index
[theme extension]: ../customization.md#extending-the-theme
- [blog.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog.html
- [blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.html
- [blog-archive.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-archive.html
- [blog-category.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-category.html
+ [blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog.html
+ [blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog-post.htmlhtml
diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md
index ea8684256..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,13 +31,31 @@ 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.2.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" }
+
+
+
+
+
+
+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
+time for the user, especially on slow connections, as the page will be available
+immediately upon navigation. Enable it with:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+ - navigation.instant.prefetch
+```
+
### 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
@@ -49,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
@@ -83,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
@@ -111,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
@@ -138,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
@@ -148,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.
@@ -169,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
@@ -203,12 +216,12 @@ theme:
### Navigation pruning
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.16.0][Insiders] ·
-: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
@@ -226,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).
- [Insiders]: ../insiders/index.md
[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
@@ -270,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
@@ -280,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
@@ -293,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
@@ -323,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
@@ -343,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
@@ -360,7 +370,7 @@ hide:
- toc
---
-# Document title
+# Page title
...
```
@@ -382,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:
@@ -392,7 +406,7 @@ hide:
- path
---
-# Document title
+# Page title
...
```
@@ -405,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:
@@ -414,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 e27c1f143..0f5a1da37 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -13,32 +13,24 @@ 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 with both, Google Analytics 4 and the now phasing
-out Universal Analytics. Depending on the given property prefix, add the
+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
following lines to `mkdocs.yml`:
-=== ":material-google-analytics: Google Analytics 4"
+ [^1]:
+ Prior to Material for MkDocs 9.2.0, Universal Analytics was supported as
+ well. However, since Universal Analytics has been sunset, this integration
+ was removed in 9.2.0.
- ``` yaml
- extra:
- analytics:
- provider: google
- property: G-XXXXXXXXXX
- ```
-
-=== ":material-google-analytics: Universal Analytics"
-
- ``` yaml
- extra:
- analytics:
- provider: google
- property: UA-XXXXXXXX-X
- ```
-
- [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
+``` yaml
+extra:
+ analytics:
+ provider: google
+ property: G-XXXXXXXXXX
+```
??? question "How to measure site search usage?"
@@ -46,28 +38,18 @@ following lines to `mkdocs.yml`:
understand how people use your documentation and what they expect to find.
In order to enable site search tracking, the following steps are required:
- === ":material-google-analytics: Google Analytics 4"
-
- 1. Go to your Google Analytics __admin settings__
- 2. Select the property for the respective tracking code
- 3. Select the __data streams__ tab and click the corresponding URL
- 4. Click the gear icon within the __enhanced measurement__ section
- 5. Ensure that __site search__ is enabled
-
- === ":material-google-analytics: Universal Analytics"
-
- 1. Go to your Google Analytics __admin settings__
- 2. Select the property for the respective tracking code
- 3. Go to the __view settings__ tab
- 4. Scroll down and enable __site search settings__
- 5. Set the __query parameter__ to `q`
+ 1. Go to your Google Analytics __admin settings__
+ 2. Select the property for the respective tracking code
+ 3. Select the __data streams__ tab and click the corresponding URL
+ 4. Click the gear icon within the __enhanced measurement__ section
+ 5. Ensure that __site search__ is enabled
[site search]: setting-up-site-search.md
### 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.
@@ -101,10 +83,10 @@ 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
-integrated with the [cookie consent] feature[^1].
+feedback widget sends data to a third-party service, it is, of course, natively
+integrated with the [cookie consent] feature[^2].
- [^1]:
+ [^2]:
If the user doesn't accept the `analytics` cookie, the feedback widget is
not shown.
@@ -114,59 +96,54 @@ integrated with the [cookie consent] feature[^1].
[Google Analytics] that will quickly show you the worst- and best-rated
pages of your project documentation.
- === ":material-google-analytics: Google Analytics 4"
+ 1. Go to your Google Analytics __dashboard__
- 1. Go to your Google Analytics __dashboard__
+ 2. Go to the __configure__ page on the left hand menu, then select
+ __custom definitions__
- 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__,
+ enter the following values:
- 3. Click the __custom metrics__ tab and then __create custom metrics__,
- enter the following values:
+ * Metric name: Page helpful
+ * Description: Was this page helpful?
+ * Event parameter: `data`
+ * Unit of measurement: Standard
- * Metric name: Page helpful
- * Description: Was this page helpful?
- * Event parameter: `data`
- * Unit of measurement: Standard
+ 4. Go to the __explore__ page on the left hand menu, create a new
+ __blank exploration__
- 4. Go to the __explore__ page on the left hand menu, create a new
- __blank exploration__
+ 5. Configure the report as follows:
- 5. Configure the report as follows:
+ * Dimensions: Add `Event name` and `Page location`
+ * Metrics: Add `Event count` and `Page helpful`
+ (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
+ `Event name / exactly matches / feedback`
- * Dimensions: Add `Event name` and `Page location`
- * Metrics: Add `Event count` and `Page helpful`
- (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
- `Event name / exactly matches / feedback`
+ !!! warning "Delay in data availability"
- !!! warning "Delay in data availability"
-
- The report may take 24 hours or longer to begin displaying data
-
- === ":material-google-analytics: Universal Analytics"
-
- 1. Go to your Google Analytics __dashboard__
- 2. Open the __customization__ panel on the left and go to __custom reports__
- 3. Create a __new custom report__ and set a custom __title__ and __name__
- 4. Add `Avg. Value` and `Total Events` to __metric group__
- 5. Add `Event Label` to __dimension drilldown__
- 6. Add `Event Category` to __filters__ and filter for the value __feedback__
+ The report may take 24 hours or longer to begin displaying data
Now, after you've saved the report and collected some feedback ratings,
you'll have a list of all pages with the total number of ratings, and an
average rating per page. This should help you identify pages that need to
be improved:
+ !!! danger "Google Analytics 4 does not support average values"
+
+ To our knowledge, Google Analytics 4 has currently no feature that
+ allows to define a custom calculated metric to compute the average
+ rating of a page. See #5740.
+
[![feedback report]][feedback report]
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:
@@ -175,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[^2] (or any custom integration).
+ that is transmitted to Google Analytics[^3] (or any custom integration).
- [^2]:
+ [^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.
@@ -206,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.:
@@ -216,12 +193,11 @@ 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
[custom feedback integration]: #custom-site-feedback
- [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
[Google Forms]: https://www.google.com/forms/about/
## Usage
@@ -237,7 +213,7 @@ hide:
- feedback
---
-# Document title
+# Page title
...
```
@@ -245,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 937daf02c..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,223 +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
- - `hu` – Hungarian
- - `it` – Italian
- - `ja` – Japanese
- - `no` – Norwegian
- - `pt` – Portuguese
- - `ro` – Romanian
- - `ru` – Russian
- - `sv` – Swedish
- - `th` – Thai
- - `tr` – Turkish
- - `vi` – Vietnamese
-
-
-
- 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-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.14.0][Insiders] ·
-:octicons-beaker-24: Experimental
-
-[Insiders] adds search support for the Chinese language (see our [blog article]
-[chinese search] from May 2022) by integrating with the text segmentation
-library [jieba], which can be installed with `pip`.
-
-``` sh
-pip install jieba
-```
-
-If [jieba] is installed, the [built-in search plugin] automatically detects
-Chinese characters and runs them through the segmenter. The following
-configuration options are available:
-
-[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
-
-: [:octicons-tag-24: insiders-4.17.2][Insiders] · :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-tag-24: insiders-4.17.2][Insiders] · :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.
-
- [Insiders]: ../insiders/index.md
- [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.
@@ -260,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.
@@ -282,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
@@ -303,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
@@ -323,7 +115,7 @@ Markdown file:
boost: 2 # (1)!
---
- # Document title
+ # Page title
...
```
@@ -338,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
@@ -359,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
@@ -374,7 +163,7 @@ heading:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
- # Document title
+ # Page title
## Section 1
@@ -416,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 48ec14c59..ca8557112 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -1,322 +1,641 @@
+---
+status: new
+---
+
# Setting up social cards
-Social cards, also known as social previews, are images that are displayed when
-a link to your project documentation is shared on social media. Material for
-MkDocs can generate beautiful social cards automatically, using the [colors],
-[fonts] and [logo][^1] defined in `mkdocs.yml`,
-e.g.:
+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.
+
+---
+
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__[How to build custom social cards]__ by @james-willett – :octicons-clock-24:
+24m – Learn how to create entirely custom social cards perfectly matching your
+branding for each page automatically!
+
+ [How to build custom social cards]: https://www.youtube.com/watch?v=4OjnOc6ftJ8
-[![Social cards preview]][Social cards preview]
+[![Layout default variant]][Layout default variant]
-The social preview image for the page on [setting up site analytics].
-[Twitter's Card validator] shows how it will look when shared.
+Social card of our [formatting] reference
- [^1]:
- Both types of logos, images (`theme.logo`) and icons (`theme.icon.logo`)
- are supported. While an image logo is used as-is, icons are filled with the
- color used in the header (white or black), which depends on the primary
- color. Note that custom logos and icons must reside in the `docs_dir` for
- the plugin to find them. For guidance, see #4920. This limitation will be
- lifted in the future when the social plugin will receive its next update.
-
- [colors]: changing-the-colors.md#primary-color
- [fonts]: changing-the-fonts.md#regular-font
- [logo]: changing-the-logo-and-icons.md#logo
- [Social cards preview]: ../assets/screenshots/social-cards.png
- [setting up site analytics]: setting-up-site-analytics.md
- [Twitter's Card validator]: https://cards-dev.twitter.com/validator
+ [custom layouts]: #customization
+ [formatting]: ../reference/formatting.md
## Configuration
### Built-in social plugin
-[:octicons-tag-24: 8.5.0][Social cards support] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
+
+
+
-First, ensure you've installed all [dependencies] and have a valid [`site_url`]
-[site_url], as social preview images must be referenced via absolute URLs.
-Then, add the following lines to `mkdocs.yml`:
+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`:
``` yaml
plugins:
- social
```
-The following configuration options are available:
+For a list of all settings, please consult the [plugin documentation].
-[`cards`](#+social.cards){ #+social.cards }
+ [plugin documentation]: ../plugins/blog.md
-: :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]:
+!!! info "The [`site_url`][site_url] setting must be set"
+
+ Note that you must set [`site_url`][site_url] when using the social plugin,
+ or the generated cards will not be correctly linked. Social media services
+ like Twitter and Facebook demand that social previews point to an absolute
+ URL, which the plugin can only compute when [`site_url`][site_url] is set.
+ Example:
``` yaml
- plugins:
- - social:
- cards: !ENV [CARDS, false]
+ site_url: https://example.com
```
-[`cards_color`](#+social.cards_color){ #+social.cards_color }
-
-: :octicons-milestone-24: Default: [`theme.palette.primary`][palette.primary]
- – This option specifies the colors for the background `fill` and foreground
- `text` when generating the social card:
-
- ``` yaml
- plugins:
- - social:
- cards_color:
- fill: "#0FF1CE" # (1)!
- text: "#FFFFFF"
- ```
-
- 1. Colors can either be defined as HEX colors, or as [CSS color keywords].
- Note that HEX colors must be enclosed in quotes.
-
-[`cards_font`](#+social.cards_font){ #+social.cards_font }
-
-: :octicons-milestone-24: Default: [`theme.font.text`][font.text] – 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: Roboto
- ```
-
- !!! question "Why do social cards render boxes for CJK languages?"
-
- Some fonts do not contain CJK characters, like for example the
- [default font, `Roboto`][font.text]. In case your `site_name`,
- `site_description`, or [page title] contain CJK characters, choose
- another font from [Google Fonts] which comes with CJK characters, e.g.
- one from the `Noto Sans` font family:
-
- === "Chinese (Simplified)"
-
- ``` yaml
- plugins:
- - social:
- cards_font: Noto Sans SC
- ```
-
- === "Chinese (Traditional)"
-
- ``` yaml
- plugins:
- - social:
- cards_font: Noto Sans TC
- ```
-
- === "Japanese"
-
- ``` yaml
- plugins:
- - social:
- cards_font: Noto Sans JP
- ```
-
- === "Korean"
-
- ``` yaml
- plugins:
- - social:
- cards_font: Noto Sans KR
- ```
-
-[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
-
-: :octicons-milestone-24: Default: `assets/images/social` – This option
- specifies where the generated social card images will be written to. It's
- normally not necessary to change this option:
-
- ``` yaml
- plugins:
- - social:
- cards_dir: path/to/folder
- ```
-
- [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
- [dependencies]: #dependencies
+ [dependencies for image processing]: ../plugins/requirements/image-processing.md
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
- [palette.primary]: changing-the-colors.md#primary-color
- [font.text]: changing-the-fonts.md#regular-font
- [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
- [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
- [Google Fonts]: https://fonts.google.com
- [page title]: ../reference/index.md#setting-the-page-title
-
-#### Dependencies
-
-Two Python libraries must be installed alongside Material for MkDocs to generate
-the social preview images, both of which are based on [Cairo Graphics] –
-[Pillow] and [CairoSVG]:
-
-```
-pip install pillow cairosvg
-```
-
-Both libraries are built with native extensions which need to be installed as
-well. The [Docker image] comes with all dependencies pre-installed. If you don't
-want to use Docker, see the following section which explains how to install all
-dependencies on your system:
-
-=== ":material-apple: macOS"
-
- Make sure [Homebrew] is installed, which is a modern package manager for
- macOS. Next, use the following command to install all necessary
- dependencies:
-
- ```
- brew install cairo freetype libffi libjpeg libpng zlib
- ```
-
-=== ":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].
-
-=== ":material-linux: Linux"
-
- There are several package managers for Linux with varying availability per
- distribution. The [installation guide] explains how to install the [Cairo
- Graphics] library for your distribution:
-
- === ":material-ubuntu: Ubuntu"
-
- ```
- apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
- ```
-
- === ":material-fedora: Fedora"
-
- ```
- yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
- ```
-
- === ":fontawesome-brands-suse: openSUSE"
-
- ```
- zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
- ```
-
- [Cairo Graphics]: https://www.cairographics.org/
- [Pillow]: https://pillow.readthedocs.io/
- [CairoSVG]: https://cairosvg.org/
- [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
- [Homebrew]: https://brew.sh/
- [installation guide]: https://www.cairographics.org/download/
- [GTK+]: https://www.gtk.org/docs/installations/windows/
- [GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
-
-#### Caching recommended { #caching data-toc-label="Caching" }
-
-The [built-in social plugin] automatically fetches the fonts you define in
-`mkdocs.yml` from Google Fonts, and uses them to render the text that is
-displayed on the social card. The font files and generated cards are both
-written to the `.cache` directory, which is used in subsequent builds to detect
-whether the social cards need to be regenerated. 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-18"
- name: ci
- on:
- push:
- branches:
- - master
- - main
- jobs:
- deploy:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v2
- - uses: actions/setup-python@v2
- with:
- python-version: 3.x
- - uses: actions/cache@v2
- with:
- key: ${{ github.ref }}
- path: .cache
- - run: pip install mkdocs-material
- - run: mkdocs gh-deploy --force
- ```
-
- [built-in social plugin]: #built-in-social-plugin
- [publishing guide]: ../publishing-your-site.md#with-github-actions
-
-#### Meta tags
-
-The [built-in social plugin] automatically sets all necessary `meta` tags,
-equivalent to the following two customizations, which you can set manually when
-you don't want to use it:
-
-=== ":material-graph: Open Graph"
-
- ``` html
- {% extends "base.html" %}
-
- {% block extrahead %}
- {% set title = config.site_name %}
- {% if page and page.meta and page.meta.title %}
- {% set title = title ~ " - " ~ page.meta.title %}
- {% elif page and page.title and not page.is_homepage %}
- {% set title = title ~ " - " ~ page.title %}
- {% endif %}
-
+
+
+
Layer 0
+
+
+
+
+
+
Layer 1
+
+
+
+
+
+
Layer 2
+
+
+
+
+
+
Layer 3
+
+
+
+
+
+
Layer 4
+
+
+
+
+
+
Layer 5
+
+
+
+
+
+| Origin | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+
+ Supported values for origin
+
+
+
+### Backgrounds
+
+Each layer can be assigned a background color and image. If both are given, the
+color is rendered on top of the image, allowing for semi-transparent, tinted
+backgrounds:
+
+=== "Background color"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ color: "#4051b5"
+ ```
+
+ ![Layer background color]
+
+=== "Background image"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ ```
+
+ ![Layer background image]
+
+=== "Background image, tinted"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ color: "#4051b5ee" # (1)!
+ ```
+
+ 1. The color value can be set to a [CSS color keyword], or a 3, 4, 6 or 8
+ letter HEX color code, allowing for semi-transparent layers.
+
+ ![Layer background]
+
+Background images are automatically scaled to fit the layer while preserving
+aspect-ratio. Notice how we omitted `size` and `offset`, because we want to
+fill the entire area of the social card.
+
+[Layer background color]: ../assets/screenshots/social-cards-layer-background-color.png
+[Layer background image]: ../assets/screenshots/social-cards-layer-background-image.png
+[Layer background]: ../assets/screenshots/social-cards-layer-background.png
+
+### Typography
+
+Now, we can add dynamic typography that is sourced from Markdown files - this is
+the actual raison d'être of the [built-in social plugin]. [Jinja templates] are
+used to render a text string that is then added to the image:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}" # (1)!
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+1. The following variables can be used in [Jinja templates]:
+
+ - [`config.*`][config variable]
+ - [`page.*`][page variable]
+ - [`layout.*`][layout options]
+
+ The author is free in defining `layout.*` options, which can be used to pass
+ arbitrary data to the layout from `mkdocs.yml`.
+
+This renders a text layer with the title of the page with a line height of 1.25,
+and a maximum number of 3 lines. The plugin automatically computes the font size
+from the line height, the number of lines, and font metrics like ascender and
+descender.[^2] This renders:
+
+ [^2]:
+ If the plugin would require the author to specify the font size and line
+ height manually, it would be impossible to guarantee that the text fits
+ into the layer. For this reason we implemented a declarative approach,
+ where the author specifies the desired line height and number of lines, and
+ the plugin computes the font size automatically.
+
+![Layer typography]
+
+ [config variable]: https://www.mkdocs.org/dev-guide/themes/#config
+ [page variable]: https://www.mkdocs.org/dev-guide/themes/#page
+ [Layer typography]: ../assets/screenshots/social-cards-layer-typography.png
+
+#### Overflow
+
+If the text overflows the layer, there are two possible behaviors: either the
+text is automatically truncated and shortened with an ellipsis, or the text is
+automatically scaled down to fit the layer:
+
+``` { .markdown .no-copy }
+# If we use a very long headline, we can see how the text will be truncated
+```
+
+=== ":octicons-ellipsis-16: Ellipsis"
+
+ ![Layer typography ellipsis]
+
+=== ":material-arrow-collapse: Shrink"
+
+ ![Layer typography shrink]
+
+While truncating with an ellipsis is the default, auto-shrinking can be enabled
+by setting `overflow` to `shrink`:
+
+``` yaml hl_lines="7"
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}"
+ overflow: shrink
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+ [Layer typography ellipsis]: ../assets/screenshots/social-cards-layer-typography-ellipsis.png
+ [Layer typography shrink]: ../assets/screenshots/social-cards-layer-typography-shrink.png
+
+#### Alignment
+
+Text can be aligned to all corners and edges of the layer. For example, if we
+want to align the text to the middle of the layer, we can set `align` to `start center`, which will render as:
+
+![Layer typography align]
+
+ [Layer typography align]: ../assets/screenshots/social-cards-layer-typography-align.png
+
+The following table shows the supported values:
+
+
+
+| Alignment | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+
+ Supported values for text alignment
+
+
+
+#### Font
+
+The [built-in social plugin] integrates with [Google Fonts] and will
+automatically download the font files for you. The `font` property accepts a
+`family` and `style` property, where the `family` must be set to the name of the
+font, and the `style` to one of the supported font styles. For example, setting
+`family` to `Roboto` will automatically download the following files:
+
+``` { .sh .no-copy #example }
+.cache/plugins/social/fonts
+└─ Roboto/
+ ├─ Black.ttf
+ ├─ Black Italic.ttf
+ ├─ Bold.ttf
+ ├─ Bold Italic.ttf
+ ├─ Italic.ttf
+ ├─ Light.ttf
+ ├─ Light Italic.ttf
+ ├─ Medium.ttf
+ ├─ Medium Italic.ttf
+ ├─ Regular.ttf
+ ├─ Thin.ttf
+ └─ Thin Italic.ttf
+```
+
+In that case, the author can use `Bold` or `Medium Italic` as the `style`. If
+the font style specified in the layer is not part of the font family, the
+font always falls back to `Regular` and prints a warning in [`debug`][debug]
+mode, as `Regular` is included with all font families.
+
+### Icons
+
+Authors can leverage the full range of icons that are shipped with Material for
+MkDocs, or even provide custom icons by using theme extension and going through
+the process described in the guide on [additional icons]. Icons can even be
+tinted by using the `color` property:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 144, height: 144 }
+ offset: { x: 992, y: 64 }
+ icon:
+ value: material/cat
+ color: white
+```
+
+This will render the icon in the top right corner of the social card:
+
+![Layer icon]
+
+The possibilities are endless. For example, icons can be used to draw shapes
+like circles:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 2400, height: 2400 }
+ offset: { x: -1024, y: 64 }
+ icon:
+ value: material/circle
+ color: "#5c6bc0"
+ - size: { width: 1800, height: 1800 }
+ offset: { x: 512, y: -1024 }
+ icon:
+ value: material/circle
+ color: "#3949ab"
+```
+
+This will add two circles to the background:
+
+![Layer icon circles]
+
+### Tags
+
+The new [built-in social plugin] gives full flexibility of the meta tags that
+are added to your site, which are necessary to instruct services like Twitter
+or Discord how to display your social card. All default layouts use the following
+set of tags, which you can copy to your layout and adapt:
+
+``` yaml
+definitions:
+
+ - &page_title_with_site_name >-
+ {%- if not page.is_homepage -%}
+ {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
+ {%- else -%}
+ {{ page.meta.get("title", page.title) }}
+ {%- endif -%}
+
+ - &page_description >-
+ {{ page.meta.get("description", config.site_description) or "" }}
+
+tags:
+
+ og:type: website
+ og:title: *page_title_with_site_name
+ og:description: *page_description
+ og:image: "{{ image.url }}"
+ og:image:type: "{{ image.type }}"
+ og:image:width: "{{ image.width }}"
+ og:image:height: "{{ image.height }}"
+ og:url: "{{ page.canonical_url }}"
+
+ twitter:card: summary_large_image
+ twitter.title: *page_title_with_site_name
+ twitter:description: *page_description
+ twitter:image: "{{ image.url }}"
+```
+
+Note that this examples makes use of [YAML anchors] to minify repetition. The
+ `definitions` property is solely intended for the definition on aliases that
+ can then be referenced with anchors.
+
+ [YAML anchors]: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
+
+__Are you missing something? Please [open a discussion] and let us know!__
+
+ [additional icons]: ./changing-the-logo-and-icons.md#additional-icons
+ [Layer icon]: ../assets/screenshots/social-cards-layer-icon.png
+ [Layer icon circles]: ../assets/screenshots/social-cards-layer-icon-circles.png
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 30ed0c935..8ceaf1273 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,169 +23,15 @@ 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.plugin.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_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,
@@ -211,7 +57,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"
@@ -259,7 +105,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
@@ -267,8 +112,11 @@ 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
@@ -303,11 +151,14 @@ search preview, which now allows to __find pages by tags__.
and then add specific tags for each page. The tags in `.meta.yml` are
appended.
- [built-in tags plugin]: #built-in-tags-plugin
- [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+ [built-in tags plugin]: ../plugins/tags.md
+ [built-in meta plugin]: ../plugins/meta.md
### Adding a tags index
+
+
+
The [built-in tags plugin] allows to define a file to render a [tags index]
[tags.tags_file], which can be any page that is part of the `nav` section. To
add a tags index, create a page, e.g. `tags.md`:
@@ -341,6 +192,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 fb91e72d2..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:
@@ -70,11 +68,12 @@ The following properties are available for each link:
* :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
* :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
* :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"
@@ -95,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
@@ -110,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`:
@@ -125,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
@@ -154,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
@@ -162,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
@@ -171,7 +166,7 @@ hide:
- footer
---
-# Document title
+# Page title
...
```
@@ -179,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..b7e83c02d 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,28 @@ 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
+### Stay on the same page when switching versions
+
+When the user chooses a version in the version selector, they usually want to go
+to the page corresponding to the page they were previously viewing. Material for
+MkDocs implements this behavior by default, but there are a few caveats:
+
+- the [`site_url`] must be set correctly in `mkdocs.yml`. See the ["Publishing a
+ new version"](#publishing-a-new-version) section for an example.
+- you must be viewing the site at that URL (and not locally, for example).
+- the redirect happens via JavaScript and there is no way to know which page you
+ will be redirected to ahead of time.
+
+[`site_url`]: https://www.mkdocs.org/user-guide/configuration/#site_url
+
### 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 +89,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 +126,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 +133,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.
@@ -135,7 +147,13 @@ mike deploy --push --update-aliases 0.1 latest
```
Note that every version will be deployed as a subdirectory of your `site_url`,
-e.g.:
+which you should set explicitly. For example, if your `mkdocs.yml` contains:
+
+``` yaml
+site_url: 'https://docs.example.com/' # Trailing slash is recommended
+```
+
+the documentation will be published to URLs such as:
- _docs.example.com/0.1/_
- _docs.example.com/0.2/_
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 65e0be071..24defe9f5 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -95,8 +95,8 @@ changes into your templates. A good starting point is to [inspect the diff].
[inspect the diff]: https://github.com/squidfunk/mkdocs-material/pull/4628/files#diff-3ca112736b9164701b599f34780107abf14bb79fe110c478cac410be90899828
[MkDocs 1.4.1]: https://github.com/mkdocs/mkdocs/releases/tag/1.4.1
[in config.plugins]: https://github.com/squidfunk/mkdocs-material/search?q=%22in+config.plugins%22
- [content.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/content.html
- [header.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
+ [content.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/content.html
+ [header.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/header.html
## Upgrading from 7.x to 8.x
@@ -127,7 +127,7 @@ changes into your templates. A good starting point is to [inspect the diff].
#### `pymdownx.tabbed`
Support for the legacy style of the [Tabbed] extension was dropped in favor
-of the new, alternate implementation which has [better behavior on mobile
+of the new, alternate implementation which has [better behavior on mobile
viewports]:
=== "8.x"
@@ -135,7 +135,7 @@ viewports]:
``` yaml
markdown_extensions:
- pymdownx.tabbed:
- alternate_style: true
+ alternate_style: true
```
=== "7.x"
@@ -1119,7 +1119,7 @@ matches the new structure:
[CSS variables]: setup/changing-the-colors.md#custom-colors
[icon integration]: reference/icons-emojis.md#search
- [prebuilt search indexes]: setup/setting-up-site-search.md#built-in-search-plugin
+ [prebuilt search indexes]: plugins/search.md
### Changes to `mkdocs.yml`
@@ -1217,7 +1217,7 @@ was renamed to `separator`:
tokenizer: '[\s\-\.]+'
```
- [plugin options]: setup/setting-up-site-search.md#built-in-search-plugin
+ [plugin options]: plugins/search.md
#### `extra.social.*`
@@ -1245,7 +1245,7 @@ in order to match the new way of specifying which icon to be used:
### Changes to `*.html` files { data-search-exclude }
The templates have undergone a set of changes to make them future-proof. If
-you've used theme extension to override a block or template, make sure that it
+you've used theme extension to override a block or template, make sure that it
matches the new structure:
- If you've overridden a __block__, check `base.html` for potential changes
@@ -1947,7 +1947,7 @@ matches the new structure:
Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
includes a mandatory change of the base font-size from `10px` to `20px` which
-means all `rem` values needed to be updated. Within the theme, `px` to `rem`
+means all `rem` values needed to be updated. Within the theme, `px` to `rem`
calculation is now encapsulated in a new function called `px2rem` which is part
of the SASS code base.
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/.icons/fontawesome/brands/cloudsmith.svg b/material/.icons/fontawesome/brands/cloudsmith.svg
deleted file mode 100644
index d2b086356..000000000
--- a/material/.icons/fontawesome/brands/cloudsmith.svg
+++ /dev/null
@@ -1 +0,0 @@
--1)return h(d,x,me,oe,se,q,$);for(_e=new Array(q),F=new Array(q),Cr=w(q,$),V=Math.ceil(u*q)+5,ne=V,I=!0,C=-1;++Cue&&(ue=Qe),z=0,oe[C]===Ar)if(Mr=c(H,d,x),z=T>0?T:l(d,x,me,oe,H,C,Mr),g=Tr+p(H,C,Mr,y,z),g>ue)ue=g,ne=V;else{if(de&&--ne<=0)return Math.max(ue,_e[q-1])*Cr;de=!1}Tr=Qe,T=F[C],F[C]=z,_e[C]=ue}}return ue=_e[q-1],ue*Cr},J.isWordStart=c=function(d,x,E){var O,y;return d===0?!0:(O=x[d],y=x[d-1],i(y)||O!==E[d]&&y===E[d-1])},J.isWordEnd=a=function(d,x,E,O){var y,g;return d===O-1?!0:(y=x[d],g=x[d+1],i(g)||y===E[d]&&g!==E[d+1])},i=function(d){return d===" "||d==="."||d==="-"||d==="_"||d==="/"||d==="\\"},b=function(d){var x;return dy?O:y)+10):g+R*y},J.scoreConsecutives=l=function(d,x,E,O,y,g,T){var F,z,I,H,C,$,V;for(z=d.length,H=E.length,I=z-y,C=H-g,F=I-1&&(C=c(I,d,x),C&&(y=I))),z=-1,H=0;++z1&&I>1))return t;for(y=0,V=0,ne=0,C=0,T=-1,F=-1;++F-1){V++;continue}else break;for(;++T12*F)return!1;for(g=-1;++gO)return!1;return!0}}).call(J)});var _r=Oe(De=>{(function(){var e,r,t,n,o,i,a,c,u,s;s=Ne(),i=s.isMatch,e=s.computeScore,c=s.scoreSize,u=20,t=2.5,De.score=function(f,p,l){var v,h,m,b;return h=l.preparedQuery,v=l.allowErrors,v||i(f,h.core_lw,h.core_up)?(b=f.toLowerCase(),m=e(f,b,h),m=a(f,b,m,l),Math.ceil(m)):0},a=function(f,p,l,v){var h,m,b,w,S,R,d,x,E,O;if(l===0)return 0;for(E=v.preparedQuery,O=v.useExtensionBonus,x=v.pathSeparator,S=f.length-1;f[S]===x;)S--;if(b=f.lastIndexOf(x,S),d=S-b,R=1,O&&(R+=o(p,E.ext,b,S,2),l*=R),b===-1)return l;for(w=E.depth;b>-1&&w-- >0;)b=f.lastIndexOf(x,b-1);return m=b===-1?l:R*e(f.slice(b+1,S+1),p.slice(b+1,S+1),E),h=.5*u/(u+r(f,S+1,x)),h*m+(1-h)*l*c(0,t*d)},De.countDir=r=function(f,p,l){var v,h;if(p<1)return 0;for(v=0,h=-1;++hl)))return 0;for(w=p.length,m=v-S,m0?.9*o(f,p,l,S-2,h-1):b/m}}).call(De)});var Jr=Oe((cn,pn)=>{(function(){var e,r,t,n,o,i,a,c;c=_r(),t=c.countDir,o=c.getExtension,pn.exports=e=function(){function u(s,f){var p,l,v;if(v=f!=null?f:{},p=v.optCharRegEx,l=v.pathSeparator,!(s&&s.length))return null;this.query=s,this.query_lw=s.toLowerCase(),this.core=r(s,p),this.core_lw=this.core.toLowerCase(),this.core_up=a(this.core),this.depth=t(s,s.length,l),this.ext=o(this.query_lw),this.charCodes=n(this.query_lw)}return u}(),i=/[ _\-:\/\\]/g,r=function(u,s){return s==null&&(s=i),u.replace(s,"")},a=function(u){var s,f,p,l;for(f="",p=0,l=u.length;p{(function(){var e,r,t,n,o;n=Ne(),r=_r(),e=Jr(),t=function(i){return i.candidate},o=function(i,a){return a.score-i.score},mn.exports=function(i,a,c){var u,s,f,p,l,v,h,m,b,w,S,R,d;for(m=[],f=c.key,l=c.maxResults,p=c.maxInners,S=c.usePathScoring,b=p!=null&&p>0?p:i.length+1,u=f!=null,h=S?r:n,R=0,d=i.length;R0&&(m.push({candidate:s,score:v}),!--b))));R++);return m.sort(o),i=m.map(t),l!=null&&(i=i.slice(0,l)),i}}).call(ln)});var dn=Oe(Or=>{(function(){var e,r,t,n,o,i,a,c,u,s;s=Ne(),t=s.isMatch,n=s.isWordStart,u=s.scoreConsecutives,c=s.scoreCharacter,a=s.scoreAcronyms,Or.match=o=function(f,p,l){var v,h,m,b,w,S;return v=l.allowErrors,w=l.preparedQuery,b=l.pathSeparator,v||t(f,w.core_lw,w.core_up)?(S=f.toLowerCase(),m=r(f,S,w),m.length===0||f.indexOf(b)>-1&&(h=e(f,S,w,b),m=i(m,h)),m):[]},Or.wrap=function(f,p,l){var v,h,m,b,w,S,R,d,x;if(l.wrap!=null&&(x=l.wrap,S=x.tagClass,d=x.tagOpen,R=x.tagClose),S==null&&(S="highlight"),d==null&&(d=''),R==null&&(R=" "),f===p)return d+f+R;if(m=o(f,p,l),m.length===0)return f;for(b="",v=-1,w=0;++vw&&(b+=f.substring(w,h),w=h);++vw&&(b+=d,b+=f.substring(w,h),b+=R,w=h)}return w<=f.length-1&&(b+=f.substring(w)),b},e=function(f,p,l,v){var h,m,b;for(b=f.length-1;f[b]===v;)b--;if(h=f.lastIndexOf(v,b),h===-1)return[];for(m=l.depth;m-- >0;)if(h=f.lastIndexOf(v,h-1),h===-1)return[];return h++,b++,r(f.slice(h,b),p.slice(h,b),l,h)},i=function(f,p){var l,v,h,m,b,w,S;if(b=f.length,w=p.length,w===0)return f.slice();if(b===0)return p.slice();for(h=-1,m=0,v=p[m],S=[];++h0?x:u(f,p,C,$,y,g,oe),R=ne+c(y,g,oe,S,O)),se=q[g],x=E[g],V>se?z=m:(V=se,z=w),R>V?(V=R,z=h):O=0,q[g]=V,E[g]=O,de[++H]=V>0?z:b;for(y=T-1,g=I-1,H=y*I+g,d=!0,F=[];d&&y>=0&&g>=0;)switch(de[H]){case w:y--,H-=I;break;case m:g--,H--;break;case h:F.push(y+v),g--,y--,H-=I+1;break;default:d=!1}return F.reverse(),F}}).call(Or)});var Br=Oe((vn,bn)=>{(function(){var e,r,t,n,o,i,a,c;t=hn(),n=dn(),c=Ne(),i=_r(),e=Jr(),a=null,r=(typeof process!="undefined"&&process!==null?process.platform:void 0)==="win32"?"\\":"/",bn.exports={filter:function(u,s,f){return f==null&&(f={}),s!=null&&s.length&&(u!=null&&u.length)?(f=o(f,s),t(u,s,f)):[]},score:function(u,s,f){return f==null&&(f={}),u!=null&&u.length&&(s!=null&&s.length)?(f=o(f,s),f.usePathScoring?i.score(u,s,f):c.score(u,s,f)):0},match:function(u,s,f){var p,l,v;return f==null&&(f={}),u?s?u===s?function(){v=[];for(var h=0,m=u.length;0<=m?hm;0<=m?h++:h--)v.push(h);return v}.apply(this):(f=o(f,s),n.match(u,s,f)):[]:[]},wrap:function(u,s,f){return f==null&&(f={}),u?s?(f=o(f,s),n.wrap(u,s,f)):[]:[]},prepareQuery:function(u,s){return s==null&&(s={}),s=o(s,u),s.preparedQuery}},o=function(u,s){return u.allowErrors==null&&(u.allowErrors=!1),u.usePathScoring==null&&(u.usePathScoring=!0),u.useExtensionBonus==null&&(u.useExtensionBonus=!1),u.pathSeparator==null&&(u.pathSeparator=r),u.optCharRegEx==null&&(u.optCharRegEx=null),u.wrap==null&&(u.wrap=null),u.preparedQuery==null&&(u.preparedQuery=a&&a.query===s?a:a=new e(s,u)),u}}).call(vn)});/*! *****************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */var Lr=function(e,r){return Lr=Object.setPrototypeOf||{__proto__:[]}instanceof Array&&function(t,n){t.__proto__=n}||function(t,n){for(var o in n)Object.prototype.hasOwnProperty.call(n,o)&&(t[o]=n[o])},Lr(e,r)};function j(e,r){if(typeof r!="function"&&r!==null)throw new TypeError("Class extends value "+String(r)+" is not a constructor or null");Lr(e,r);function t(){this.constructor=e}e.prototype=r===null?Object.create(r):(t.prototype=r.prototype,new t)}function nt(e,r,t,n){function o(i){return i instanceof t?i:new t(function(a){a(i)})}return new(t||(t=Promise))(function(i,a){function c(f){try{s(n.next(f))}catch(p){a(p)}}function u(f){try{s(n.throw(f))}catch(p){a(p)}}function s(f){f.done?i(f.value):o(f.value).then(c,u)}s((n=n.apply(e,r||[])).next())})}function Ge(e,r){var t={label:0,sent:function(){if(i[0]&1)throw i[1];return i[1]},trys:[],ops:[]},n,o,i,a;return a={next:c(0),throw:c(1),return:c(2)},typeof Symbol=="function"&&(a[Symbol.iterator]=function(){return this}),a;function c(s){return function(f){return u([s,f])}}function u(s){if(n)throw new TypeError("Generator is already executing.");for(;t;)try{if(n=1,o&&(i=s[0]&2?o.return:s[0]?o.throw||((i=o.return)&&i.call(o),0):o.next)&&!(i=i.call(o,s[1])).done)return i;switch(o=0,i&&(s=[s[0]&2,i.value]),s[0]){case 0:case 1:i=s;break;case 4:return t.label++,{value:s[1],done:!1};case 5:t.label++,o=s[1],s=[0];continue;case 7:s=t.ops.pop(),t.trys.pop();continue;default:if(i=t.trys,!(i=i.length>0&&i[i.length-1])&&(s[0]===6||s[0]===2)){t=0;continue}if(s[0]===3&&(!i||s[1]>i[0]&&s[1]=e.length&&(e=void 0),{value:e&&e[n++],done:!e}}};throw new TypeError(r?"Object is not iterable.":"Symbol.iterator is not defined.")}function W(e,r){var t=typeof Symbol=="function"&&e[Symbol.iterator];if(!t)return e;var n=t.call(e),o,i=[],a;try{for(;(r===void 0||r-- >0)&&!(o=n.next()).done;)i.push(o.value)}catch(c){a={error:c}}finally{try{o&&!o.done&&(t=n.return)&&t.call(n)}finally{if(a)throw a.error}}return i}function U(e,r,t){if(t||arguments.length===2)for(var n=0,o=r.length,i;n1||c(l,v)})})}function c(l,v){try{u(n[l](v))}catch(h){p(i[0][3],h)}}function u(l){l.value instanceof ve?Promise.resolve(l.value.v).then(s,f):p(i[0][2],l)}function s(l){c("next",l)}function f(l){c("throw",l)}function p(l,v){l(v),i.shift(),i.length&&c(i[0][0],i[0][1])}}function it(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var r=e[Symbol.asyncIterator],t;return r?r.call(e):(e=typeof G=="function"?G(e):e[Symbol.iterator](),t={},n("next"),n("throw"),n("return"),t[Symbol.asyncIterator]=function(){return this},t);function n(i){t[i]=e[i]&&function(a){return new Promise(function(c,u){a=e[i](a),o(c,u,a.done,a.value)})}}function o(i,a,c,u){Promise.resolve(u).then(function(s){i({value:s,done:c})},a)}}function _(e){return typeof e=="function"}function Ye(e){var r=function(n){Error.call(n),n.stack=new Error().stack},t=e(r);return t.prototype=Object.create(Error.prototype),t.prototype.constructor=t,t}var Je=Ye(function(e){return function(t){e(this),this.message=t?t.length+` errors occurred during unsubscription:
-`+t.map(function(n,o){return o+1+") "+n.toString()}).join(`
- `):"",this.name="UnsubscriptionError",this.errors=t}});function fe(e,r){if(e){var t=e.indexOf(r);0<=t&&e.splice(t,1)}}var ie=function(){function e(r){this.initialTeardown=r,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var r,t,n,o,i;if(!this.closed){this.closed=!0;var a=this._parentage;if(a)if(this._parentage=null,Array.isArray(a))try{for(var c=G(a),u=c.next();!u.done;u=c.next()){var s=u.value;s.remove(this)}}catch(m){r={error:m}}finally{try{u&&!u.done&&(t=c.return)&&t.call(c)}finally{if(r)throw r.error}}else a.remove(this);var f=this.initialTeardown;if(_(f))try{f()}catch(m){i=m instanceof Je?m.errors:[m]}var p=this._finalizers;if(p){this._finalizers=null;try{for(var l=G(p),v=l.next();!v.done;v=l.next()){var h=v.value;try{at(h)}catch(m){i=i!=null?i:[],m instanceof Je?i=U(U([],W(i)),W(m.errors)):i.push(m)}}}catch(m){n={error:m}}finally{try{v&&!v.done&&(o=l.return)&&o.call(l)}finally{if(n)throw n.error}}}if(i)throw new Je(i)}},e.prototype.add=function(r){var t;if(r&&r!==this)if(this.closed)at(r);else{if(r instanceof e){if(r.closed||r._hasParent(this))return;r._addParent(this)}(this._finalizers=(t=this._finalizers)!==null&&t!==void 0?t:[]).push(r)}},e.prototype._hasParent=function(r){var t=this._parentage;return t===r||Array.isArray(t)&&t.includes(r)},e.prototype._addParent=function(r){var t=this._parentage;this._parentage=Array.isArray(t)?(t.push(r),t):t?[t,r]:r},e.prototype._removeParent=function(r){var t=this._parentage;t===r?this._parentage=null:Array.isArray(t)&&fe(t,r)},e.prototype.remove=function(r){var t=this._finalizers;t&&fe(t,r),r instanceof e&&r._removeParent(this)},e.EMPTY=function(){var r=new e;return r.closed=!0,r}(),e}();var Rr=ie.EMPTY;function Be(e){return e instanceof ie||e&&"closed"in e&&_(e.remove)&&_(e.add)&&_(e.unsubscribe)}function at(e){_(e)?e():e.unsubscribe()}var te={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var Te={setTimeout:function(e,r){for(var t=[],n=2;n0},enumerable:!1,configurable:!0}),r.prototype._trySubscribe=function(t){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,t)},r.prototype._subscribe=function(t){return this._throwIfClosed(),this._checkFinalizedStatuses(t),this._innerSubscribe(t)},r.prototype._innerSubscribe=function(t){var n=this,o=this,i=o.hasError,a=o.isStopped,c=o.observers;return i||a?Rr:(this.currentObservers=null,c.push(t),new ie(function(){n.currentObservers=null,fe(c,t)}))},r.prototype._checkFinalizedStatuses=function(t){var n=this,o=n.hasError,i=n.thrownError,a=n.isStopped;o?t.error(i):a&&t.complete()},r.prototype.asObservable=function(){var t=new L;return t.source=this,t},r.create=function(t,n){return new ht(t,n)},r}(L);var ht=function(e){j(r,e);function r(t,n){var o=e.call(this)||this;return o.destination=t,o.source=n,o}return r.prototype.next=function(t){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.next)===null||o===void 0||o.call(n,t)},r.prototype.error=function(t){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.error)===null||o===void 0||o.call(n,t)},r.prototype.complete=function(){var t,n;(n=(t=this.destination)===null||t===void 0?void 0:t.complete)===null||n===void 0||n.call(t)},r.prototype._subscribe=function(t){var n,o;return(o=(n=this.source)===null||n===void 0?void 0:n.subscribe(t))!==null&&o!==void 0?o:Rr},r}(B);var ze={now:function(){return(ze.delegate||Date).now()},delegate:void 0};var dt=function(e){j(r,e);function r(t,n,o){t===void 0&&(t=1/0),n===void 0&&(n=1/0),o===void 0&&(o=ze);var i=e.call(this)||this;return i._bufferSize=t,i._windowTime=n,i._timestampProvider=o,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=n===1/0,i._bufferSize=Math.max(1,t),i._windowTime=Math.max(1,n),i}return r.prototype.next=function(t){var n=this,o=n.isStopped,i=n._buffer,a=n._infiniteTimeWindow,c=n._timestampProvider,u=n._windowTime;o||(i.push(t),!a&&i.push(c.now()+u)),this._trimBuffer(),e.prototype.next.call(this,t)},r.prototype._subscribe=function(t){this._throwIfClosed(),this._trimBuffer();for(var n=this._innerSubscribe(t),o=this,i=o._infiniteTimeWindow,a=o._buffer,c=a.slice(),u=0;u0?e.prototype.requestAsyncId.call(this,t,n,o):(t.actions.push(this),t._scheduled||(t._scheduled=Ce.requestAnimationFrame(function(){return t.flush(void 0)})))},r.prototype.recycleAsyncId=function(t,n,o){var i;if(o===void 0&&(o=0),o!=null?o>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,t,n,o);var a=t.actions;n!=null&&((i=a[a.length-1])===null||i===void 0?void 0:i.id)!==n&&(Ce.cancelAnimationFrame(n),t._scheduled=void 0)},r}(er);var yt=function(e){j(r,e);function r(){return e!==null&&e.apply(this,arguments)||this}return r.prototype.flush=function(t){this._active=!0;var n=this._scheduled;this._scheduled=void 0;var o=this.actions,i;t=t||o.shift();do if(i=t.execute(t.state,t.delay))break;while((t=o[0])&&t.id===n&&o.shift());if(this._active=!1,i){for(;(t=o[0])&&t.id===n&&o.shift();)t.unsubscribe();throw i}},r}(rr);var Wr=new yt(xt);var pe=new L(function(e){return e.complete()});function tr(e){return e&&_(e.schedule)}function zr(e){return e[e.length-1]}function Ie(e){return _(zr(e))?e.pop():void 0}function ae(e){return tr(zr(e))?e.pop():void 0}function gt(e,r){return typeof zr(e)=="number"?e.pop():r}var Le=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function nr(e){return _(e==null?void 0:e.then)}function or(e){return _(e[Me])}function ir(e){return Symbol.asyncIterator&&_(e==null?void 0:e[Symbol.asyncIterator])}function ar(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function jn(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var sr=jn();function ur(e){return _(e==null?void 0:e[sr])}function fr(e){return ot(this,arguments,function(){var t,n,o,i;return Ge(this,function(a){switch(a.label){case 0:t=e.getReader(),a.label=1;case 1:a.trys.push([1,,9,10]),a.label=2;case 2:return[4,ve(t.read())];case 3:return n=a.sent(),o=n.value,i=n.done,i?[4,ve(void 0)]:[3,5];case 4:return[2,a.sent()];case 5:return[4,ve(o)];case 6:return[4,a.sent()];case 7:return a.sent(),[3,2];case 8:return[3,10];case 9:return t.releaseLock(),[7];case 10:return[2]}})})}function cr(e){return _(e==null?void 0:e.getReader)}function P(e){if(e instanceof L)return e;if(e!=null){if(or(e))return $n(e);if(Le(e))return qn(e);if(nr(e))return Nn(e);if(ir(e))return wt(e);if(ur(e))return Dn(e);if(cr(e))return Qn(e)}throw ar(e)}function $n(e){return new L(function(r){var t=e[Me]();if(_(t.subscribe))return t.subscribe(r);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function qn(e){return new L(function(r){for(var t=0;t0&&(f=new xe({next:function(E){return x.next(E)},error:function(E){m=!0,b(),p=Qr(w,o,E),x.error(E)},complete:function(){h=!0,b(),p=Qr(w,a),x.complete()}}),P(R).subscribe(f))})(s)}}function Qr(e,r){for(var t=[],n=2;n{let r=yr();return typeof r!="undefined"?e.contains(r):!1}),he(e===yr()),le())}function Dt(e){return{x:e.scrollLeft,y:e.scrollTop}}function Qt(e){return N(K(e,"scroll"),K(window,"resize")).pipe(Vr(0,Wr),k(()=>Dt(e)),he(Dt(e)))}var Gt=function(){if(typeof Map!="undefined")return Map;function e(r,t){var n=-1;return r.some(function(o,i){return o[0]===t?(n=i,!0):!1}),n}return function(){function r(){this.__entries__=[]}return Object.defineProperty(r.prototype,"size",{get:function(){return this.__entries__.length},enumerable:!0,configurable:!0}),r.prototype.get=function(t){var n=e(this.__entries__,t),o=this.__entries__[n];return o&&o[1]},r.prototype.set=function(t,n){var o=e(this.__entries__,t);~o?this.__entries__[o][1]=n:this.__entries__.push([t,n])},r.prototype.delete=function(t){var n=this.__entries__,o=e(n,t);~o&&n.splice(o,1)},r.prototype.has=function(t){return!!~e(this.__entries__,t)},r.prototype.clear=function(){this.__entries__.splice(0)},r.prototype.forEach=function(t,n){n===void 0&&(n=null);for(var o=0,i=this.__entries__;o0},e.prototype.connect_=function(){!Gr||this.connected_||(document.addEventListener("transitionend",this.onTransitionEnd_),window.addEventListener("resize",this.refresh),vo?(this.mutationsObserver_=new MutationObserver(this.refresh),this.mutationsObserver_.observe(document,{attributes:!0,childList:!0,characterData:!0,subtree:!0})):(document.addEventListener("DOMSubtreeModified",this.refresh),this.mutationEventsAdded_=!0),this.connected_=!0)},e.prototype.disconnect_=function(){!Gr||!this.connected_||(document.removeEventListener("transitionend",this.onTransitionEnd_),window.removeEventListener("resize",this.refresh),this.mutationsObserver_&&this.mutationsObserver_.disconnect(),this.mutationEventsAdded_&&document.removeEventListener("DOMSubtreeModified",this.refresh),this.mutationsObserver_=null,this.mutationEventsAdded_=!1,this.connected_=!1)},e.prototype.onTransitionEnd_=function(r){var t=r.propertyName,n=t===void 0?"":t,o=ho.some(function(i){return!!~n.indexOf(i)});o&&this.refresh()},e.getInstance=function(){return this.instance_||(this.instance_=new e),this.instance_},e.instance_=null,e}(),Yt=function(e,r){for(var t=0,n=Object.keys(r);t0},e}(),Bt=typeof WeakMap!="undefined"?new WeakMap:new Gt,Xt=function(){function e(r){if(!(this instanceof e))throw new TypeError("Cannot call a class as a function.");if(!arguments.length)throw new TypeError("1 argument required, but only 0 present.");var t=bo.getInstance(),n=new Ao(r,t,this);Bt.set(this,n)}return e}();["observe","unobserve","disconnect"].forEach(function(e){Xt.prototype[e]=function(){var r;return(r=Bt.get(this))[e].apply(r,arguments)}});var Mo=function(){return typeof gr.ResizeObserver!="undefined"?gr.ResizeObserver:Xt}(),Zt=Mo;var Co=new B,Yp=je(()=>Z(new Zt(e=>{for(let r of e)Co.next(r)}))).pipe(D(e=>N($e,Z(e)).pipe(Ee(()=>e.disconnect()))),Se(1));function en(e){return{width:e.offsetWidth,height:e.offsetHeight}}function rn(e){return{width:e.scrollWidth,height:e.scrollHeight}}var Io=new B,ol=je(()=>Z(new IntersectionObserver(e=>{for(let r of e)Io.next(r)},{threshold:0}))).pipe(D(e=>N($e,Z(e)).pipe(Ee(()=>e.disconnect()))),Se(1));function tn(e,r=16){return Qt(e).pipe(k(({y:t})=>{let n=en(e),o=rn(e);return t>=o.height-n.height-r}),le())}var ml={drawer:ee("[data-md-toggle=drawer]"),search:ee("[data-md-toggle=search]")};function nn(){return new URL(location.href)}function on(e,r){if(typeof r=="string"||typeof r=="number")e.innerHTML+=r.toString();else if(r instanceof Node)e.appendChild(r);else if(Array.isArray(r))for(let t of r)on(e,t)}function re(e,r,...t){let n=document.createElement(e);if(r)for(let o of Object.keys(r))typeof r[o]!="undefined"&&(typeof r[o]!="boolean"?n.setAttribute(o,r[o]):n.setAttribute(o,""));for(let o of t)on(n,o);return n}function an(e){if(e>999){let r=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(r)}k`}else return e.toString()}function Lo(e,r={credentials:"same-origin"}){return X(fetch(`${e}`,r)).pipe(br(()=>pe),D(t=>t.status!==200?Ur(()=>new Error(t.statusText)):Z(t)))}function Sr(e,r){return Lo(e,r).pipe(D(t=>t.json()),Se(1))}(()=>{function e(n,o){parent.postMessage(n,o||"*")}function r(...n){return n.reduce((o,i)=>o.then(()=>new Promise(a=>{let c=document.createElement("script");c.src=i,c.onload=a,document.body.appendChild(c)})),Promise.resolve())}var t=class extends EventTarget{constructor(n){super(),this.url=n,this.m=i=>{i.source===this.w&&(this.dispatchEvent(new MessageEvent("message",{data:i.data})),this.onmessage&&this.onmessage(i))},this.e=(i,a,c,u,s)=>{if(a===`${this.url}`){let f=new ErrorEvent("error",{message:i,filename:a,lineno:c,colno:u,error:s});this.dispatchEvent(f),this.onerror&&this.onerror(f)}};let o=document.createElement("iframe");o.hidden=!0,document.body.appendChild(this.iframe=o),this.w.document.open(),this.w.document.write(`
+
{% endblock %}
diff --git a/material/partials/integrations/analytics/google.html b/material/partials/integrations/analytics/google.html
deleted file mode 100644
index b7ea49478..000000000
--- a/material/partials/integrations/analytics/google.html
+++ /dev/null
@@ -1,11 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% if config.extra.analytics %}
- {% set property = config.extra.analytics.property | d("", true) %}
-{% endif %}
-{% if property.startswith("G-") %}
-
-{% elif property.startswith("UA-") %}
-
-{% endif %}
diff --git a/material/partials/languages/af.html b/material/partials/languages/af.html
deleted file mode 100644
index 358623e87..000000000
--- a/material/partials/languages/af.html
+++ /dev/null
@@ -1,24 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "af",
- "action.edit": "Wysig hierdie bladsy",
- "action.skip": "Slaan oor na inhoud",
- "clipboard.copy": "Kopieer na knipbord",
- "clipboard.copied": "gekopieer na knipbord",
- "footer.next": "Volgende",
- "footer.previous": "Vorige",
- "meta.comments": "Kommentaar",
- "meta.source": "Bron",
- "search.config.lang": "nl",
- "search.placeholder": "Soek",
- "search.result.placeholder": "Tik om te begin soek",
- "search.result.none": "Geen ooreenstemmende dokumente",
- "search.result.one": "1 ooreenstemmende dokument",
- "search.result.other": "# ooreenstemmende dokumente",
- "source": "Slaan oor na inhoud",
- "source.file.date.created": "Geskep",
- "source.file.date.updated": "Laaste opdatering",
- "toc": "Inhoudsopgawe"
-}[key] }}{% endmacro %}
diff --git a/material/partials/languages/bn.html b/material/partials/languages/bn.html
deleted file mode 100644
index ee55717b5..000000000
--- a/material/partials/languages/bn.html
+++ /dev/null
@@ -1,29 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "bn",
- "action.edit": "এই পেজ এডিট করুন",
- "action.skip": "কনটেন্টে যান",
- "clipboard.copy": "ক্লিপবোর্ডে কপি করুন",
- "clipboard.copied": "ক্লিপবোর্ডে কপি হয়েছে",
- "footer": "ফুটার",
- "footer.next": "পরে",
- "footer.previous": "পূর্ববর্তী",
- "header": "হেডার",
- "meta.comments": "কমেন্ট",
- "meta.source": "সোর্স",
- "nav": "ন্যাভিগেশন",
- "search.config.pipeline": " ",
- "search.placeholder": "সার্চ",
- "search.reset": "মুছে ফেলুন",
- "search.result.placeholder": "সার্চ টাইপ করুন",
- "search.result.none": "কিছু পাওয়া যায়নি",
- "search.result.one": "১ টা ডকুমেন্ট",
- "search.result.other": "# টা ডকুমেন্ট",
- "source": "রিপোজিটরিতে যান",
- "source.file.date.created": "তৈরি হয়েছে",
- "source.file.date.updated": "শেষ আপডেট",
- "tabs": "ট্যাব",
- "toc": "টেবিল অফ কনটেন্ট"
-}[key] }}{% endmacro %}
diff --git a/material/partials/languages/da.html b/material/partials/languages/da.html
deleted file mode 100644
index dd26a91a1..000000000
--- a/material/partials/languages/da.html
+++ /dev/null
@@ -1,24 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "da",
- "action.edit": "Redigér denne side",
- "action.skip": "Gå til indholdet",
- "clipboard.copy": "Kopiér til udklipsholderen",
- "clipboard.copied": "Kopieret til udklipsholderen",
- "footer.next": "Næste",
- "footer.previous": "Forrige",
- "meta.comments": "Kommentarer",
- "meta.source": "Kilde",
- "search.config.lang": "da",
- "search.placeholder": "Søg",
- "search.result.placeholder": "Indtast søgeord",
- "search.result.none": "Ingen resultater fundet",
- "search.result.one": "1 resultat",
- "search.result.other": "# resultater",
- "source": "Åbn arkiv",
- "source.file.date.created": "Oprettet",
- "source.file.date.updated": "Sidste ændring",
- "toc": "Indholdsfortegnelse"
-}[key] }}{% endmacro %}
diff --git a/material/partials/languages/fa.html b/material/partials/languages/fa.html
deleted file mode 100644
index e4ce6723c..000000000
--- a/material/partials/languages/fa.html
+++ /dev/null
@@ -1,25 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "fa",
- "direction": "rtl",
- "action.edit": "این صفحه را ویرایش کنید",
- "action.skip": "پرش به محتویات",
- "clipboard.copy": "کپی کردن",
- "clipboard.copied": "کپی شد",
- "footer.next": "بعدی",
- "footer.previous": "قبلی",
- "meta.comments": "نظرات",
- "meta.source": "منبع",
- "search.config.pipeline": " ",
- "search.placeholder": "جستجو",
- "search.result.placeholder": "برای شروع جستجو تایپ کنید",
- "search.result.none": "سندی یافت نشد",
- "search.result.one": "1 سند یافت شد",
- "search.result.other": "# سند یافت شد",
- "source": "رفتن به مخزن",
- "source.file.date.created": "ایجاد شده",
- "source.file.date.updated": "اخرین بروزرسانی",
- "toc": "فهرست موضوعات"
-}[key] }}{% endmacro %}
diff --git a/material/partials/languages/hy.html b/material/partials/languages/hy.html
deleted file mode 100644
index 4e92b5c0e..000000000
--- a/material/partials/languages/hy.html
+++ /dev/null
@@ -1,38 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "hy",
- "action.edit": "Խմբագրել այս էջը",
- "action.skip": "Անցնել պարունակությանը",
- "clipboard.copy": "Պատճենել",
- "clipboard.copied": "Պատճենված է",
- "footer": "Վերջնագիր",
- "footer.next": "Հաջորդը",
- "footer.previous": "Նախորդը",
- "header": "Գլխագիր",
- "meta.comments": "Մեկնաբանությունները",
- "meta.source": "Աղբյուր",
- "nav": "Տեղորոշում",
- "search": "Փնտրում",
- "search.config.pipeline": " ",
- "search.placeholder": "Փնտրել",
- "search.share": "Կիսվել",
- "search.reset": "Ջնջել",
- "search.result.initializer": "Փնտրում",
- "search.result.placeholder": "Մուտքագրեք փնտրելու համար",
- "search.result.none": "Համապատասխանություններ չկան",
- "search.result.one": "1 համապատասխանություն",
- "search.result.other": "# համապատասխանություններ",
- "search.result.more.one": "ևս 1-ը այս էջում",
- "search.result.more.other": "ևս #-ը այս էջում",
- "search.result.term.missing": "Բացակայում է",
- "select.language": "Ընտրել լեզուն",
- "select.version": "Ընտրել տարբերակը",
- "source": "Դեպի պահոց",
- "source.file.date.created": "Ստեղծված է",
- "source.file.date.updated": "Վերջին թարմացումը",
- "tabs": "Ներդիրներ",
- "toc": "Բովանդակություն",
- "top": "Վերադառնալ սկիզբ"
-}[key] }}{% endmacro %}
diff --git a/material/partials/languages/tr.html b/material/partials/languages/tr.html
deleted file mode 100644
index dbb274c09..000000000
--- a/material/partials/languages/tr.html
+++ /dev/null
@@ -1,24 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro t(key) %}{{ {
- "language": "tr",
- "action.edit": "Düzenle",
- "action.skip": "Ana içeriğe geç",
- "clipboard.copy": "Kopyala",
- "clipboard.copied": "Kopyalandı",
- "footer.next": "Sonraki",
- "footer.previous": "Önceki",
- "meta.comments": "Yorumlar",
- "meta.source": "Kaynak",
- "search.config.lang": "tr",
- "search.placeholder": "Ara",
- "search.result.placeholder": "Aramaya başlamak için yazın",
- "search.result.none": "Eşleşen doküman bulunamadı",
- "search.result.one": "1 doküman bulundu",
- "search.result.other": "# doküman bulundu",
- "source": "Depoya git",
- "source.file.date.created": "Oluşturuldu",
- "source.file.date.updated": "Son Güncelleme",
- "toc": "İçindekiler"
-}[key] }}{% endmacro %}
diff --git a/material/partials/nav-item.html b/material/partials/nav-item.html
deleted file mode 100644
index 90e615645..000000000
--- a/material/partials/nav-item.html
+++ /dev/null
@@ -1,91 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% macro render(nav_item, path, level) %}
- {% set class = "md-nav__item" %}
- {% if nav_item.active %}
- {% set class = class ~ " md-nav__item--active" %}
- {% endif %}
- {% if nav_item.children %}
- {% if "navigation.sections" in features and level == 1 + (
- "navigation.tabs" in features
- ) %}
- {% set class = class ~ " md-nav__item--section" %}
- {% endif %}
-
- {% set expanded = "navigation.expand" in features %}
- {% set active = nav_item.active or expanded %}
- {% set checked = "checked" if nav_item.active %}
- {% if expanded and not checked %}
- {% set indeterminate = "md-toggle--indeterminate" %}
- {% endif %}
-
- {{ nav_item.title }}
-
- {% else %}
- {% set index = indexes | first %}
- {% set class = "md-nav__link--active" if index == page %}
-
- {% endif %}
-
-
-
-
- {% for nav_item in nav_item.children %}
- {% if not indexes or nav_item != indexes | first %}
- {{ render(nav_item, path ~ "_" ~ loop.index, level + 1) }}
- {% endif %}
- {% endfor %}
-
-
-
- {% elif nav_item == page %}
-
- {% set toc = page.toc %}
-
- {{ nav_item.title }}
-
- {% endif %}
-
- {{ nav_item.title }}
-
- {% if toc %}
- {% include "partials/toc.html" %}
- {% endif %}
-
- {% else %}
-
-
- {{ nav_item.title }}
-
-
- {% endif %}
-{% endmacro %}
-{{ render(nav_item, path, level) }}
diff --git a/material/partials/tabs-item.html b/material/partials/tabs-item.html
deleted file mode 100644
index c05954986..000000000
--- a/material/partials/tabs-item.html
+++ /dev/null
@@ -1,28 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% if not class %}
- {% set class = "md-tabs__link" %}
- {% if nav_item.active %}
- {% set class = class ~ " md-tabs__link--active" %}
- {% endif %}
-{% endif %}
-{% if nav_item.children %}
- {% set title = title | d(nav_item.title) %}
- {% set nav_item = nav_item.children | first %}
- {% if nav_item.children %}
- {% include "partials/tabs-item.html" %}
- {% else %}
-
-
- {{ title }}
-
-
- {% endif %}
-{% else %}
-
-
- {{ nav_item.title }}
-
-
-{% endif %}
diff --git a/material/partials/tags.html b/material/partials/tags.html
deleted file mode 100644
index abf4a4c17..000000000
--- a/material/partials/tags.html
+++ /dev/null
@@ -1,27 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% if page.meta and page.meta.hide %}
- {% set hidden = "hidden" if "tags" in page.meta.hide %}
-{% endif %}
-{% if tags %}
-
- {% for tag in tags %}
- {% if config.extra.tags %}
- {% set icon = " md-tag-icon" %}
- {% if tag.type %}
- {% set icon = icon ~ " md-tag--" ~ tag.type %}
- {% endif %}
- {% endif %}
- {% if tag.url %}
-
- {{- tag.name -}}
-
- {% else %}
-
- {{- tag.name -}}
-
- {% endif %}
- {% endfor %}
-
-{% endif %}
diff --git a/material/plugins/__init__.py b/material/plugins/__init__.py
index e69de29bb..d18993785 100644
--- a/material/plugins/__init__.py
+++ b/material/plugins/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/blog/__init__.py b/material/plugins/blog/__init__.py
new file mode 100644
index 000000000..d18993785
--- /dev/null
+++ b/material/plugins/blog/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/blog/author.py b/material/plugins/blog/author.py
new file mode 100644
index 000000000..1dcfc2de2
--- /dev/null
+++ b/material/plugins/blog/author.py
@@ -0,0 +1,38 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.base import Config
+from mkdocs.config.config_options import DictOfItems, SubConfig, Type
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Author
+class Author(Config):
+ name = Type(str)
+ description = Type(str)
+ avatar = Type(str)
+
+# -----------------------------------------------------------------------------
+
+# Authors
+class Authors(Config):
+ authors = DictOfItems(SubConfig(Author), default = {})
diff --git a/material/plugins/blog/config.py b/material/plugins/blog/config.py
new file mode 100644
index 000000000..c7a850958
--- /dev/null
+++ b/material/plugins/blog/config.py
@@ -0,0 +1,88 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 functools import partial
+from markdown.extensions.toc import slugify
+from mkdocs.config.config_options import Choice, Deprecated, Optional, Type
+from mkdocs.config.base import Config
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Blog plugin configuration
+class BlogConfig(Config):
+ enabled = Type(bool, default = True)
+
+ # Settings for blog
+ blog_dir = Type(str, default = "blog")
+ blog_toc = Type(bool, default = False)
+
+ # Settings for posts
+ post_dir = Type(str, default = "{blog}/posts")
+ post_date_format = Type(str, default = "long")
+ post_url_date_format = Type(str, default = "yyyy/MM/dd")
+ post_url_format = Type(str, default = "{date}/{slug}")
+ post_url_max_categories = Type(int, default = 1)
+ post_slugify = Type((type(slugify), partial), default = slugify)
+ post_slugify_separator = Type(str, default = "-")
+ post_excerpt = Choice(["optional", "required"], default = "optional")
+ post_excerpt_max_authors = Type(int, default = 1)
+ post_excerpt_max_categories = Type(int, default = 5)
+ post_excerpt_separator = Type(str, default = "")
+ post_readtime = Type(bool, default = True)
+ post_readtime_words_per_minute = Type(int, default = 265)
+
+ # Settings for archive
+ archive = Type(bool, default = True)
+ archive_name = Type(str, default = "blog.archive")
+ archive_date_format = Type(str, default = "yyyy")
+ archive_url_date_format = Type(str, default = "yyyy")
+ archive_url_format = Type(str, default = "archive/{date}")
+ archive_toc = Optional(Type(bool))
+
+ # Settings for categories
+ categories = Type(bool, default = True)
+ categories_name = Type(str, default = "blog.categories")
+ categories_url_format = Type(str, default = "category/{slug}")
+ categories_slugify = Type((type(slugify), partial), default = slugify)
+ categories_slugify_separator = Type(str, default = "-")
+ categories_allowed = Type(list, default = [])
+ categories_toc = Optional(Type(bool))
+
+ # Settings for pagination
+ pagination = Type(bool, default = True)
+ pagination_per_page = Type(int, default = 10)
+ pagination_url_format = Type(str, default = "page/{page}")
+ pagination_format = Type(str, default = "~2~")
+ pagination_if_single_page = Type(bool, default = False)
+ pagination_keep_content = Type(bool, default = False)
+
+ # Settings for authors
+ authors = Type(bool, default = True)
+ authors_file = Type(str, default = "{blog}/.authors.yml")
+
+ # Settings for drafts
+ draft = Type(bool, default = False)
+ draft_on_serve = Type(bool, default = True)
+ draft_if_future_date = Type(bool, default = False)
+
+ # Deprecated settings
+ pagination_template = Deprecated(moved_to = "pagination_format")
diff --git a/material/plugins/blog/plugin.py b/material/plugins/blog/plugin.py
new file mode 100644
index 000000000..4f4d9c69c
--- /dev/null
+++ b/material/plugins/blog/plugin.py
@@ -0,0 +1,895 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 logging
+import os
+import posixpath
+import yaml
+
+from babel.dates import format_date
+from datetime import datetime
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin, event_priority
+from mkdocs.structure import StructureItem
+from mkdocs.structure.files import File, Files, InclusionLevel
+from mkdocs.structure.nav import Navigation, Section
+from mkdocs.structure.pages import Page
+from mkdocs.utils import copy_file, get_relative_url
+from paginate import Page as Pagination
+from shutil import rmtree
+from tempfile import mkdtemp
+from yaml import SafeLoader
+
+from .author import Authors
+from .config import BlogConfig
+from .readtime import readtime
+from .structure import Archive, Category, Excerpt, Post, View
+from .templates import url_filter
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Blog plugin
+class BlogPlugin(BasePlugin[BlogConfig]):
+ supports_multiple_instances = True
+
+ # Initialize plugin
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ # Initialize incremental builds
+ self.is_serve = False
+ self.is_dirty = False
+
+ # Initialize temporary directory
+ self.temp_dir = mkdtemp()
+
+ # Determine whether we're serving the site
+ def on_startup(self, *, command, dirty):
+ self.is_serve = command == "serve"
+ self.is_dirty = dirty
+
+ # Initialize authors and set defaults
+ def on_config(self, config):
+ if not self.config.enabled:
+ return
+
+ # Initialize entrypoint
+ self.blog: View
+
+ # Initialize and resolve authors, if enabled
+ if self.config.authors:
+ self.authors = self._resolve_authors(config)
+
+ # Initialize table of contents settings
+ if not isinstance(self.config.archive_toc, bool):
+ self.config.archive_toc = self.config.blog_toc
+ if not isinstance(self.config.categories_toc, bool):
+ self.config.categories_toc = self.config.blog_toc
+
+ # By default, drafts are rendered when the documentation is served,
+ # but not when it is built, for a better user experience
+ if self.is_serve and self.config.draft_on_serve:
+ self.config.draft = True
+
+ # Resolve and load posts and generate views (run later) - we want to allow
+ # other plugins to add generated posts or views, so we run this plugin as
+ # late as possible. We also need to remove the posts from the navigation
+ # before navigation is constructed, as the entrypoint should be considered
+ # to be the active page for each post. The URLs of posts are computed before
+ # Markdown processing, so that when linking to and from posts, behavior is
+ # exactly the same as with regular documentation pages. We create all pages
+ # related to posts as part of this plugin, so we control the entire process.
+ @event_priority(-50)
+ def on_files(self, files, *, config):
+ if not self.config.enabled:
+ return
+
+ # Resolve path to entrypoint and site directory
+ root = posixpath.normpath(self.config.blog_dir)
+ site = config.site_dir
+
+ # Compute path to posts directory
+ path = self.config.post_dir.format(blog = root)
+ path = posixpath.normpath(path)
+
+ # Adjust destination paths for media files
+ for file in files.media_files():
+ if not file.src_uri.startswith(path):
+ continue
+
+ # We need to adjust destination paths for assets to remove the
+ # purely functional posts directory prefix when building
+ file.dest_uri = file.dest_uri.replace(path, root)
+ file.abs_dest_path = os.path.join(site, file.dest_path)
+ file.url = file.url.replace(path, root)
+
+ # Resolve entrypoint and posts sorted by descending date - if the posts
+ # directory or entrypoint do not exist, they are automatically created
+ self.blog = self._resolve(files, config)
+ self.blog.posts = sorted(
+ self._resolve_posts(files, config),
+ key = lambda post: post.config.date.created,
+ reverse = True
+ )
+
+ # Generate views for archive
+ if self.config.archive:
+ views = self._generate_archive(config, files)
+ self.blog.views.extend(views)
+
+ # Generate views for categories
+ if self.config.categories:
+ views = self._generate_categories(config, files)
+ self.blog.views.extend(views)
+
+ # Generate pages for views
+ if self.config.pagination:
+ for view in self._resolve_views(self.blog):
+ for page in self._generate_pages(view, config, files):
+ page.file.inclusion = InclusionLevel.EXCLUDED
+ view.pages.append(page)
+
+ # Ensure that entrypoint is always included in navigation
+ self.blog.file.inclusion = InclusionLevel.INCLUDED
+
+ # Attach posts and views to navigation (run later) - again, we allow other
+ # plugins to alter the navigation before we start to attach posts and views
+ # generated by this plugin at the correct locations in the navigation. Also,
+ # we make sure to correct links to the parent and siblings of each page.
+ @event_priority(-50)
+ def on_nav(self, nav, *, config, files):
+ if not self.config.enabled:
+ return
+
+ # Hack: since MkDocs will always create a page for the entrypoint even
+ # though we already created it in `on_files`, we must replace the page
+ # that MkDocs created with the entrypoint we already have on our hands.
+ # Hopefully, this hack can be removed soon - see https://t.ly/9nehI
+ page = self.blog.file.page
+ self._attach_at(page.parent, page, self.blog)
+
+ # Hack: update page instances in navigation - this can also be removed
+ # once an already open pull request is merged - see https://t.ly/9C_Kz
+ for page in [self.blog, *self.blog.posts, *self.blog.views]:
+ assert isinstance(page, Page)
+
+ # Check if the page that we generated is identical to the page that
+ # is associated with the file - if it is, we're good
+ temp = page.file.page
+ if not temp or temp == page:
+ continue
+
+ # If not, MkDocs overwrote our page with a new instance, which we
+ # need to replace with the one we generated
+ page.file.page = page
+ for items in [self._resolve_siblings(page, nav), nav.pages]:
+ items[items.index(temp)] = page
+
+ # Attach posts to entrypoint without adding them to the navigation, so
+ # that the entrypoint is considered to be the active page for each post
+ self._attach(self.blog, [None, *reversed(self.blog.posts), None])
+ for post in self.blog.posts:
+ post.file.inclusion = InclusionLevel.NOT_IN_NAV
+
+ # Revert temporary exclusion of views from navigation
+ for view in self._resolve_views(self.blog):
+ for page in view.pages:
+ page.file.inclusion = InclusionLevel.INCLUDED
+
+ # Attach views for archive
+ if self.config.archive:
+ title = self._translate(self.config.archive_name, config)
+ views = [_ for _ in self.blog.views if isinstance(_, Archive)]
+
+ # Attach and link views for archive
+ self._attach_to(self.blog, Section(title, views), nav)
+
+ # Attach views for categories
+ if self.config.categories:
+ title = self._translate(self.config.categories_name, config)
+ views = [_ for _ in self.blog.views if isinstance(_, Category)]
+
+ # Attach and link views for categories, if any
+ if views:
+ self._attach_to(self.blog, Section(title, views), nav)
+
+ # Attach pages for views
+ if self.config.pagination:
+ for view in self._resolve_views(self.blog):
+ for at in range(1, len(view.pages)):
+ self._attach_at(view.parent, view, view.pages[at])
+
+ # Prepare post for rendering (run later) - allow other plugins to alter
+ # the contents or metadata of a post before it is rendered and make sure
+ # that the post includes a separator, which is essential for rendering
+ # excerpts that should be included in views
+ @event_priority(-50)
+ def on_page_markdown(self, markdown, *, page, config, files):
+ if not self.config.enabled:
+ return
+
+ # Skip if page is not a post managed by this instance - this plugin has
+ # support for multiple instances, which is why this check is necessary
+ if page not in self.blog.posts:
+ if not self.config.pagination:
+ return
+
+ # We set the contents of the view to its title if pagination should
+ # not keep the content of the original view on paginated views
+ if not self.config.pagination_keep_content:
+ view = self._resolve_original(page)
+ if view in self._resolve_views(self.blog):
+
+ # If the current view is paginated, use the rendered title
+ # of the original view in case the author set the title in
+ # the page's contents, or it would be overridden with the
+ # one set in mkdocs.yml, leading to inconsistent headings
+ assert isinstance(view, View)
+ if view != page:
+ name = view._title_from_render or view.title
+ return f"# {name}"
+
+ # Nothing more to be done for views
+ return
+
+ # Extract and assign authors to post, if enabled
+ if self.config.authors:
+ for name in page.config.authors:
+ if name not in self.authors:
+ raise PluginError(f"Couldn't find author '{name}'")
+
+ # Append to list of authors
+ page.authors.append(self.authors[name])
+
+ # Extract settings for excerpts
+ separator = self.config.post_excerpt_separator
+ max_authors = self.config.post_excerpt_max_authors
+ max_categories = self.config.post_excerpt_max_categories
+
+ # Ensure presence of separator and throw, if its absent and required -
+ # we append the separator to the end of the contents of the post, if it
+ # is not already present, so we can remove footnotes or other content
+ # from the excerpt without affecting the content of the excerpt
+ if separator not in page.markdown:
+ path = page.file.src_path
+ if self.config.post_excerpt == "required":
+ raise PluginError(
+ f"Couldn't find '{separator}' separator in '{path}'"
+ )
+ else:
+ page.markdown += f"\n\n{separator}"
+
+ # Create excerpt for post and inherit authors and categories - excerpts
+ # can contain a subset of the authors and categories of the post
+ page.excerpt = Excerpt(page, config, files)
+ page.excerpt.authors = page.authors[:max_authors]
+ page.excerpt.categories = page.categories[:max_categories]
+
+ # Process posts
+ def on_page_content(self, html, *, page, config, files):
+ if not self.config.enabled:
+ return
+
+ # Skip if page is not a post managed by this instance - this plugin has
+ # support for multiple instances, which is why this check is necessary
+ if page not in self.blog.posts:
+ return
+
+ # Compute readtime of post, if enabled and not explicitly set
+ if self.config.post_readtime:
+ words_per_minute = self.config.post_readtime_words_per_minute
+ if not page.config.readtime:
+ page.config.readtime = readtime(html, words_per_minute)
+
+ # Register template filters for plugin
+ def on_env(self, env, *, config, files):
+ if not self.config.enabled:
+ return
+
+ # Filter for formatting dates related to posts
+ def date_filter(date: datetime):
+ return self._format_date_for_post(date, config)
+
+ # Register custom template filters
+ env.filters["date"] = date_filter
+ env.filters["url"] = url_filter
+
+ # Prepare view for rendering (run latest) - views are rendered last, as we
+ # need to mutate the navigation to account for pagination. The main problem
+ # is that we need to replace the view in the navigation, because otherwise
+ # the view would not be considered active.
+ @event_priority(-100)
+ def on_page_context(self, context, *, page, config, nav):
+ if not self.config.enabled:
+ return
+
+ # Skip if page is not a view managed by this instance - this plugin has
+ # support for multiple instances, which is why this check is necessary
+ view = self._resolve_original(page)
+ if view not in self._resolve_views(self.blog):
+ return
+
+ # If the current view is paginated, replace and rewire it - the current
+ # view temporarily becomes the main view, and is reset after rendering
+ assert isinstance(view, View)
+ if view != page:
+ prev = view.pages[view.pages.index(page) - 1]
+
+ # Replace previous page with current page
+ items = self._resolve_siblings(view, nav)
+ items[items.index(prev)] = page
+
+ # Render excerpts and prepare pagination
+ posts, pagination = self._render(page)
+
+ # Render pagination links
+ def pager(args: object):
+ return pagination.pager(
+ format = self.config.pagination_format,
+ show_if_single_page = self.config.pagination_if_single_page,
+ **args
+ )
+
+ # Assign posts and pagination to context
+ context["posts"] = posts
+ context["pagination"] = pager if pagination else None
+
+ # After rendering a paginated view, replace the URL of the paginated view
+ # with the URL of the original view - since we need to replace the original
+ # view with a paginated view in `on_page_context` for correct resolution of
+ # the active state, we must fix the paginated view URLs after rendering
+ def on_post_page(self, output, *, page, config):
+ if not self.config.enabled:
+ return
+
+ # Skip if page is not a view managed by this instance - this plugin has
+ # support for multiple instances, which is why this check is necessary
+ view = self._resolve_original(page)
+ if view not in self._resolve_views(self.blog):
+ return
+
+ # If the current view is paginated, replace the URL of the paginated
+ # view with the URL of the original view - see https://t.ly/Yeh-P
+ assert isinstance(view, View)
+ if view != page:
+ page.file.url = view.file.url
+
+ # Remove temporary directory on shutdown
+ def on_shutdown(self):
+ rmtree(self.temp_dir)
+
+ # -------------------------------------------------------------------------
+
+ # Check if the given post is excluded
+ def _is_excluded(self, post: Post):
+ if self.config.draft:
+ return False
+
+ # If a post was not explicitly marked or unmarked as draft, and the
+ # date should be taken into account, we automatically mark it as draft
+ # if the publishing date is in the future. This, of course, is opt-in
+ # and must be explicitly enabled by the author.
+ if not isinstance(post.config.draft, bool):
+ if self.config.draft_if_future_date:
+ return post.config.date.created > datetime.now()
+
+ # Post might be a draft
+ return bool(post.config.draft)
+
+ # -------------------------------------------------------------------------
+
+ # Resolve entrypoint - the entrypoint of the blog must have been created
+ # if it did not exist before, and hosts all posts sorted by descending date
+ def _resolve(self, files: Files, config: MkDocsConfig):
+ path = os.path.join(self.config.blog_dir, "index.md")
+ path = os.path.normpath(path)
+
+ # Create entrypoint, if it does not exist - note that the entrypoint is
+ # created in the docs directory, not in the temporary directory
+ docs = os.path.relpath(config.docs_dir)
+ name = os.path.join(docs, path)
+ if not os.path.isfile(name):
+ file = self._path_to_file(path, config, temp = False)
+ files.append(file)
+
+ # Create file in docs directory
+ self._save_to_file(file.abs_src_path, "# Blog\n\n")
+
+ # Create and return entrypoint
+ file = files.get_file_from_path(path)
+ return View(None, file, config)
+
+ # Resolve post - the caller must make sure that the given file points to an
+ # actual post (and not a page), or behavior might be unpredictable
+ def _resolve_post(self, file: File, config: MkDocsConfig):
+ post = Post(file, config)
+
+ # Compute path and create a temporary file for path resolution
+ path = self._format_path_for_post(post, config)
+ temp = self._path_to_file(path, config, temp = False)
+
+ # Replace destination file system path and URL
+ file.dest_uri = temp.dest_uri
+ file.abs_dest_path = temp.abs_dest_path
+ file.url = temp.url
+
+ # Replace canonical URL and return post
+ post._set_canonical_url(config.site_url)
+ return post
+
+ # Resolve posts from directory - traverse all documentation pages and filter
+ # and yield those that are located in the posts directory
+ def _resolve_posts(self, files: Files, config: MkDocsConfig):
+ path = self.config.post_dir.format(blog = self.config.blog_dir)
+ path = os.path.normpath(path)
+
+ # Create posts directory, if it does not exist
+ docs = os.path.relpath(config.docs_dir)
+ name = os.path.join(docs, path)
+ if not os.path.isdir(name):
+ os.makedirs(name, exist_ok = True)
+
+ # Filter posts from pages
+ for file in files.documentation_pages():
+ if not file.src_path.startswith(path):
+ continue
+
+ # Temporarily remove post from navigation
+ file.inclusion = InclusionLevel.EXCLUDED
+
+ # Resolve post - in order to determine whether a post should be
+ # excluded, we must load it and analyze its metadata. All posts
+ # marked as drafts are excluded, except for when the author has
+ # configured drafts to be included in the navigation.
+ post = self._resolve_post(file, config)
+ if not self._is_excluded(post):
+ yield post
+
+ # Resolve authors - check if there's an authors file at the configured
+ # location, and if one was found, load and validate it
+ def _resolve_authors(self, config: MkDocsConfig):
+ path = self.config.authors_file.format(blog = self.config.blog_dir)
+ path = os.path.normpath(path)
+
+ # Resolve path relative to docs directory
+ docs = os.path.relpath(config.docs_dir)
+ file = os.path.join(docs, path)
+
+ # If the authors file does not exist, return here
+ config: Authors = Authors()
+ if not os.path.isfile(file):
+ return config.authors
+
+ # Open file and parse as YAML
+ with open(file, encoding = "utf-8") as f:
+ config.config_file_path = os.path.abspath(file)
+ try:
+ config.load_dict(yaml.load(f, SafeLoader) or {})
+
+ # The authors file could not be loaded because of a syntax error,
+ # which we display to the author with a nice error message
+ except Exception as e:
+ raise PluginError(
+ f"Error reading authors file '{path}' in '{docs}':\n"
+ f"{e}"
+ )
+
+ # Validate authors and throw if errors occurred
+ errors, warnings = config.validate()
+ if not config.authors and warnings:
+ log.warning(
+ f"Action required: the format of the authors file changed.\n"
+ f"All authors must now be located under the 'authors' key.\n"
+ f"Please adjust '{file}' to match:\n"
+ f"\n"
+ f"authors:\n"
+ f" squidfunk:\n"
+ f" avatar: https://avatars.githubusercontent.com/u/932156\n"
+ f" description: Creator\n"
+ f" name: Martin Donath\n"
+ f"\n"
+ )
+ for _, w in warnings:
+ log.warning(w)
+ for _, e in errors:
+ raise PluginError(
+ f"Error reading authors file '{path}' in '{docs}':\n"
+ f"{e}"
+ )
+
+ # Return authors
+ return config.authors
+
+ # Resolve views of the given view in pre-order
+ def _resolve_views(self, view: View):
+ yield view
+
+ # Resolve views recursively
+ for page in view.views:
+ for next in self._resolve_views(page):
+ assert isinstance(next, View)
+ yield next
+
+ # Resolve siblings of a navigation item
+ def _resolve_siblings(self, item: StructureItem, nav: Navigation):
+ if isinstance(item.parent, Section):
+ return item.parent.children
+ else:
+ return nav.items
+
+ # Resolve original page or view (e.g. for paginated views)
+ def _resolve_original(self, page: Page):
+ if isinstance(page, View):
+ return page.pages[0]
+ else:
+ return page
+
+ # -------------------------------------------------------------------------
+
+ # Generate views for archive - analyze posts and generate the necessary
+ # views, taking the date format provided by the author into account
+ def _generate_archive(self, config: MkDocsConfig, files: Files):
+ for post in self.blog.posts:
+ date = post.config.date.created
+
+ # Compute name and path of archive view
+ name = self._format_date_for_archive(date, config)
+ path = self._format_path_for_archive(post, config)
+
+ # Create file for view, if it does not exist
+ file = files.get_file_from_path(path)
+ if not file or self.temp_dir not in file.abs_src_path:
+ file = self._path_to_file(path, config)
+ files.append(file)
+
+ # Create file in temporary directory
+ self._save_to_file(file.abs_src_path, f"# {name}")
+
+ # Create and yield view - we don't explicitly set the title of
+ # the view, so authors can override them in the page's content
+ if not isinstance(file.page, Archive):
+ yield Archive(None, file, config)
+
+ # Assign post to archive
+ assert isinstance(file.page, Archive)
+ file.page.posts.append(post)
+
+ # Generate views for categories - analyze posts and generate the necessary
+ # views, taking the allowed categories as set by the author into account
+ def _generate_categories(self, config: MkDocsConfig, files: Files):
+ for post in self.blog.posts:
+ for name in post.config.categories:
+ path = self._format_path_for_category(name)
+
+ # Ensure category is in non-empty allow list
+ categories = self.config.categories_allowed or [name]
+ if name not in categories:
+ docs = os.path.relpath(config.docs_dir)
+ path = os.path.relpath(post.file.abs_src_path, docs)
+ raise PluginError(
+ f"Error reading categories of post '{path}' in "
+ f"'{docs}': category '{name}' not in allow list"
+ )
+
+ # Create file for view, if it does not exist
+ file = files.get_file_from_path(path)
+ if not file or self.temp_dir not in file.abs_src_path:
+ file = self._path_to_file(path, config)
+ files.append(file)
+
+ # Create file in temporary directory
+ self._save_to_file(file.abs_src_path, f"# {name}")
+
+ # Create and yield view - we don't explicitly set the title of
+ # the view, so authors can override them in the page's content
+ if not isinstance(file.page, Category):
+ yield Category(None, file, config)
+
+ # Assign post to category and vice versa
+ assert isinstance(file.page, Category)
+ file.page.posts.append(post)
+ post.categories.append(file.page)
+
+ # Generate pages for pagination - analyze view and generate the necessary
+ # pages, creating a chain of views for simple rendering and replacement
+ def _generate_pages(self, view: View, config: MkDocsConfig, files: Files):
+ yield view
+
+ # Compute base path for pagination - if the given view is an index file,
+ # we need to pop the file name from the base so it's not part of the URL
+ base, _ = posixpath.splitext(view.file.src_uri)
+ if view.file.name == "index":
+ base = posixpath.dirname(base)
+
+ # Compute pagination boundaries and create pages - pages are internally
+ # handled as copies of a view, as they map to the same source location
+ step = self.config.pagination_per_page
+ for at in range(step, len(view.posts), step):
+ path = self._format_path_for_pagination(base, 1 + at // step)
+
+ # Create file for view, if it does not exist
+ file = files.get_file_from_path(path)
+ if not file or self.temp_dir not in file.abs_src_path:
+ file = self._path_to_file(path, config)
+ files.append(file)
+
+ # Copy file to temporary directory
+ copy_file(view.file.abs_src_path, file.abs_src_path)
+
+ # Create view and attach to previous page
+ if not isinstance(file.page, View):
+ yield View(None, file, config)
+
+ # Assign pages and posts to view
+ assert isinstance(file.page, View)
+ file.page.pages = view.pages
+ file.page.posts = view.posts
+
+ # -------------------------------------------------------------------------
+
+ # Attach a list of pages to each other and to the given parent item without
+ # explicitly adding them to the navigation, which can be done by the caller
+ def _attach(self, parent: StructureItem, pages: list[Page]):
+ for tail, page, head in zip(pages, pages[1:], pages[2:]):
+
+ # Link page to parent and siblings
+ page.parent = parent
+ page.previous_page = tail
+ page.next_page = head
+
+ # If the page is a view, we know that we generated it and need to
+ # link its siblings back to the view
+ if isinstance(page, View):
+ view = self._resolve_original(page)
+ if tail: tail.next_page = view
+ if head: head.previous_page = view
+
+ # Attach a page to the given parent and link it to the previous and next
+ # page of the given host - this is exclusively used for paginated views
+ def _attach_at(self, parent: StructureItem, host: Page, page: Page):
+ self._attach(parent, [host.previous_page, page, host.next_page])
+
+ # Attach a section as a sibling to the given view, make sure it's pages are
+ # part of the navigation, and ensure all pages are linked correctly
+ def _attach_to(self, view: View, section: Section, nav: Navigation):
+ section.parent = view.parent
+
+ # Resolve siblings, which are the children of the parent section, or
+ # the top-level list of navigation items if the view is at the root of
+ # the project, and append the given section to it. It's currently not
+ # possible to chose the position of a section.
+ items = self._resolve_siblings(view, nav)
+ items.append(section)
+
+ # Find last sibling that is a page, skipping sections, as we need to
+ # append the given section after all other pages
+ tail = next(item for item in reversed(items) if isinstance(item, Page))
+ head = tail.next_page
+
+ # Attach section to navigation and pages to each other
+ nav.pages.extend(section.children)
+ self._attach(section, [tail, *section.children, head])
+
+ # -------------------------------------------------------------------------
+
+ # Render excerpts and pagination for the given view
+ def _render(self, view: View):
+ posts, pagination = view.posts, None
+
+ # Create pagination, if enabled
+ if self.config.pagination:
+ at = view.pages.index(view)
+
+ # Compute pagination boundaries
+ step = self.config.pagination_per_page
+ p, q = at * step, at * step + step
+
+ # Extract posts in pagination boundaries
+ posts = view.posts[p:q]
+ pagination = self._render_pagination(view, (p, q))
+
+ # Render excerpts for selected posts
+ posts = [
+ self._render_post(post.excerpt, view)
+ for post in posts if post.excerpt
+ ]
+
+ # Return posts and pagination
+ return posts, pagination
+
+ # Render excerpt in the context of the given view
+ def _render_post(self, excerpt: Excerpt, view: View):
+ excerpt.render(view, self.config.post_excerpt_separator)
+
+ # Determine whether to add posts to the table of contents of the view -
+ # note that those settings can be changed individually for each type of
+ # view, which is why we need to check the type of view and the table of
+ # contents setting for that type of view
+ toc = self.config.blog_toc
+ if isinstance(view, Archive):
+ toc = self.config.archive_toc
+ if isinstance(view, Category):
+ toc = self.config.categories_toc
+
+ # Attach top-level table of contents item to view if it should be added
+ # and both, the view and excerpt contain table of contents items
+ if toc and excerpt.toc.items and view.toc.items:
+ view.toc.items[0].children.append(excerpt.toc.items[0])
+
+ # Return excerpt
+ return excerpt
+
+ # Create pagination for the given view and range
+ def _render_pagination(self, view: View, range: tuple[int, int]):
+ p, q = range
+
+ # Create URL from the given page to another page
+ def url_maker(n: int):
+ return get_relative_url(view.pages[n - 1].url, view.url)
+
+ # Return pagination
+ return Pagination(
+ view.posts, page = q // (q - p),
+ items_per_page = q - p,
+ url_maker = url_maker
+ )
+
+ # -------------------------------------------------------------------------
+
+ # Format path for post
+ def _format_path_for_post(self, post: Post, config: MkDocsConfig):
+ categories = post.config.categories[:self.config.post_url_max_categories]
+ categories = [self._slugify_category(name) for name in categories]
+
+ # Replace placeholders in format string
+ date = post.config.date.created
+ path = self.config.post_url_format.format(
+ categories = "/".join(categories),
+ date = self._format_date_for_post_url(date, config),
+ file = post.file.name,
+ slug = post.config.slug or self._slugify_post(post)
+ )
+
+ # Normalize path and strip slashes at the beginning and end
+ path = posixpath.normpath(path.strip("/"))
+ return posixpath.join(self.config.blog_dir, f"{path}.md")
+
+ # Format path for archive
+ def _format_path_for_archive(self, post: Post, config: MkDocsConfig):
+ date = post.config.date.created
+ path = self.config.archive_url_format.format(
+ date = self._format_date_for_archive_url(date, config)
+ )
+
+ # Normalize path and strip slashes at the beginning and end
+ path = posixpath.normpath(path.strip("/"))
+ return posixpath.join(self.config.blog_dir, f"{path}.md")
+
+ # Format path for category
+ def _format_path_for_category(self, name: str):
+ path = self.config.categories_url_format.format(
+ slug = self._slugify_category(name)
+ )
+
+ # Normalize path and strip slashes at the beginning and end
+ path = posixpath.normpath(path.strip("/"))
+ return posixpath.join(self.config.blog_dir, f"{path}.md")
+
+ # Format path for pagination
+ def _format_path_for_pagination(self, base: str, page: int):
+ path = self.config.pagination_url_format.format(
+ page = page
+ )
+
+ # Normalize path and strip slashes at the beginning and end
+ path = posixpath.normpath(path.strip("/"))
+ return posixpath.join(base, f"{path}.md")
+
+ # -------------------------------------------------------------------------
+
+ # Format date
+ def _format_date(self, date: datetime, format: str, config: MkDocsConfig):
+ locale = config.theme["language"]
+ return format_date(date, format = format, locale = locale)
+
+ # Format date for post
+ def _format_date_for_post(self, date: datetime, config: MkDocsConfig):
+ format = self.config.post_date_format
+ return self._format_date(date, format, config)
+
+ # Format date for post URL
+ def _format_date_for_post_url(self, date: datetime, config: MkDocsConfig):
+ format = self.config.post_url_date_format
+ return self._format_date(date, format, config)
+
+ # Format date for archive
+ def _format_date_for_archive(self, date: datetime, config: MkDocsConfig):
+ format = self.config.archive_date_format
+ return self._format_date(date, format, config)
+
+ # Format date for archive URL
+ def _format_date_for_archive_url(self, date: datetime, config: MkDocsConfig):
+ format = self.config.archive_url_date_format
+ return self._format_date(date, format, config)
+
+ # -------------------------------------------------------------------------
+
+ # Slugify post title
+ def _slugify_post(self, post: Post):
+ separator = self.config.post_slugify_separator
+ return self.config.post_slugify(post.title, separator)
+
+ # Slugify category
+ def _slugify_category(self, name: str):
+ separator = self.config.categories_slugify_separator
+ return self.config.categories_slugify(name, separator)
+
+ # -------------------------------------------------------------------------
+
+ # Create a file for the given path, which must point to a valid source file,
+ # either inside the temporary directory or the docs directory
+ def _path_to_file(self, path: str, config: MkDocsConfig, *, temp = True):
+ assert path.endswith(".md")
+ file = File(
+ path,
+ config.docs_dir if not temp else self.temp_dir,
+ config.site_dir,
+ config.use_directory_urls
+ )
+
+ # Hack: mark file as generated, so other plugins don't think it's part
+ # of the file system. This is more or less a new quasi-standard that
+ # still needs to be adopted by MkDocs, and was introduced by the
+ # git-revision-date-localized-plugin - see https://bit.ly/3ZUmdBx
+ if temp:
+ file.generated_by = "material/blog"
+
+ # Return file
+ return file
+
+ # Create a file with the given content on disk
+ def _save_to_file(self, path: str, content: str):
+ os.makedirs(os.path.dirname(path), exist_ok = True)
+ with open(path, "w") as f:
+ f.write(content)
+
+ # -------------------------------------------------------------------------
+
+ # Translate the placeholder referenced by the given key
+ def _translate(self, key: str, config: MkDocsConfig) -> str:
+ env = config.theme.get_env()
+ template = env.get_template(
+ "partials/language.html", globals = { "config": config }
+ )
+
+ # Translate placeholder
+ return template.module.t(key)
+
+# -----------------------------------------------------------------------------
+# Data
+# -----------------------------------------------------------------------------
+
+# Set up logging
+log = logging.getLogger("mkdocs.material.blog")
diff --git a/material/plugins/blog/readtime/__init__.py b/material/plugins/blog/readtime/__init__.py
new file mode 100644
index 000000000..a0c149b98
--- /dev/null
+++ b/material/plugins/blog/readtime/__init__.py
@@ -0,0 +1,51 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
+
+import re
+
+from math import ceil
+
+from .parser import ReadtimeParser
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+# Compute readtime - we first used the original readtime library, but the list
+# of dependencies it brings with it increased the size of the Docker image by
+# 20 MB (packed), which is an increase of 50%. For this reason, we adapt the
+# original readtime algorithm to our needs - see https://t.ly/fPZ7L
+def readtime(html: str, words_per_minute: int):
+ parser = ReadtimeParser()
+ parser.feed(html)
+ parser.close()
+
+ # Extract words from text and compute readtime in seconds
+ words = len(re.split(r"\W+", "".join(parser.text)))
+ seconds = ceil(words / words_per_minute * 60)
+
+ # Account for additional images
+ delta = 12
+ for _ in range(parser.images):
+ seconds += delta
+ if delta > 3: delta -= 1
+
+ # Return readtime in minutes
+ return ceil(seconds / 60)
diff --git a/material/plugins/blog/readtime/parser.py b/material/plugins/blog/readtime/parser.py
new file mode 100644
index 000000000..b91a7b309
--- /dev/null
+++ b/material/plugins/blog/readtime/parser.py
@@ -0,0 +1,45 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 html.parser import HTMLParser
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Readtime parser
+class ReadtimeParser(HTMLParser):
+
+ # Initialize parser
+ def __init__(self):
+ super().__init__(convert_charrefs = True)
+
+ # Keep track of text and images
+ self.text = []
+ self.images = 0
+
+ # Collect images
+ def handle_starttag(self, tag, attrs):
+ if tag == "img":
+ self.images += 1
+
+ # Collect text
+ def handle_data(self, data):
+ self.text.append(data)
diff --git a/material/plugins/blog/structure/__init__.py b/material/plugins/blog/structure/__init__.py
new file mode 100644
index 000000000..2fc541fee
--- /dev/null
+++ b/material/plugins/blog/structure/__init__.py
@@ -0,0 +1,292 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 logging
+import os
+import yaml
+
+from copy import copy
+from markdown import Markdown
+from material.plugins.blog.author import Author
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.nav import Section
+from mkdocs.structure.pages import Page, _RelativePathTreeprocessor
+from mkdocs.structure.toc import get_toc
+from mkdocs.utils.meta import YAML_RE
+from re import Match
+from yaml import SafeLoader
+
+from .config import PostConfig
+from .markdown import ExcerptTreeprocessor
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Post
+class Post(Page):
+
+ # Initialize post - posts are never listed in the navigation, which is why
+ # they will never include a title that was manually set, so we can omit it
+ def __init__(self, file: File, config: MkDocsConfig):
+ super().__init__(None, file, config)
+
+ # Resolve path relative to docs directory
+ docs = os.path.relpath(config.docs_dir)
+ path = os.path.relpath(file.abs_src_path, docs)
+
+ # Read contents and metadata immediately
+ with open(file.abs_src_path, encoding = "utf-8") as f:
+ self.markdown = f.read()
+
+ # Sadly, MkDocs swallows any exceptions that occur during parsing.
+ # As we want to provide the best possible authoring experience, we
+ # need to catch errors early and display them nicely. We decided to
+ # drop support for MkDocs' MultiMarkdown syntax, because it is not
+ # correctly implemented anyway. When using MultiMarkdown syntax, all
+ # date formats are returned as strings and list are not properly
+ # supported. Thus, we just use the relevants parts of `get_data`.
+ match: Match = YAML_RE.match(self.markdown)
+ if not match:
+ raise PluginError(
+ f"Error reading metadata of post '{path}' in '{docs}':\n"
+ f"Expected metadata to be defined but found nothing"
+ )
+
+ # Extract metadata and parse as YAML
+ try:
+ self.meta = yaml.load(match.group(1), SafeLoader) or {}
+ self.markdown = self.markdown[match.end():].lstrip("\n")
+
+ # The post's metadata could not be parsed because of a syntax error,
+ # which we display to the user with a nice error message
+ except Exception as e:
+ raise PluginError(
+ f"Error reading metadata of post '{path}' in '{docs}':\n"
+ f"{e}"
+ )
+
+ # Initialize post configuration, but remove all keys that this plugin
+ # doesn't care about, or they will be reported as invalid configuration
+ self.config: PostConfig = PostConfig(file.abs_src_path)
+ self.config.load_dict({
+ key: self.meta[key] for key in (
+ set(self.meta.keys()) &
+ set(self.config.keys())
+ )
+ })
+
+ # Validate configuration and throw if errors occurred
+ errors, warnings = self.config.validate()
+ for _, w in warnings:
+ log.warning(w)
+ for k, e in errors:
+ raise PluginError(
+ f"Error reading metadata '{k}' of post '{path}' in '{docs}':\n"
+ f"{e}"
+ )
+
+ # Excerpts are subsets of posts that are used in pages like archive and
+ # category views. They are not rendered as standalone pages, but are
+ # rendered in the context of a view. Each post has a dedicated excerpt
+ # instance which is reused when rendering views.
+ self.excerpt: Excerpt = None
+
+ # Initialize authors and actegories
+ self.authors: list[Author] = []
+ self.categories: list[Category] = []
+
+ # Ensure template is set or use default
+ self.meta.setdefault("template", "blog-post.html")
+
+ # Ensure template hides navigation
+ self.meta["hide"] = self.meta.get("hide", [])
+ if "navigation" not in self.meta["hide"]:
+ self.meta["hide"].append("navigation")
+
+ # The contents and metadata were already read in the constructor (and not
+ # in `read_source` as for pages), so this function must be set to a no-op
+ def read_source(self, config: MkDocsConfig):
+ pass
+
+# -----------------------------------------------------------------------------
+
+# Excerpt
+class Excerpt(Page):
+
+ # Initialize an excerpt for the given post - we create the Markdown parser
+ # when intitializing the excerpt in order to improve rendering performance
+ # for excerpts, as they are reused across several different views, because
+ # posts might be referenced from multiple different locations
+ def __init__(self, post: Post, config: MkDocsConfig, files: Files):
+ self.file = copy(post.file)
+ self.post = post
+
+ # Set canonical URL, or we can't print excerpts when debugging the
+ # blog plugin, as the `abs_url` property would be missing
+ self._set_canonical_url(config.site_url)
+
+ # Initialize configuration and metadata
+ self.config = post.config
+ self.meta = post.meta
+
+ # Initialize authors and categories - note that views usually contain
+ # subsets of those lists, which is why we need to manage them here
+ self.authors: list[Author] = []
+ self.categories: list[Category] = []
+
+ # Initialize parser - note that we need to patch the configuration,
+ # more specifically the table of contents extension
+ config = _patch(config)
+ self.md = Markdown(
+ extensions = config.markdown_extensions,
+ extension_configs = config.mdx_configs,
+ )
+
+ # Register excerpt tree processor - this processor resolves anchors to
+ # posts from within views, so they point to the correct location
+ self.md.treeprocessors.register(
+ ExcerptTreeprocessor(post),
+ "excerpt",
+ 0
+ )
+
+ # Register relative path tree processor - this processor resolves links
+ # to other pages and assets, and is used by MkDocs itself
+ self.md.treeprocessors.register(
+ _RelativePathTreeprocessor(self.file, files, config),
+ "relpath",
+ 1
+ )
+
+ # Render an excerpt of the post on the given page - note that this is not
+ # thread-safe because excerpts are shared across views, as it cuts down on
+ # the cost of initialization. However, if in the future, we decide to render
+ # posts and views concurrently, we must change this behavior.
+ def render(self, page: Page, separator: str):
+ self.file.url = page.url
+
+ # Retrieve excerpt tree processor and set page as base
+ at = self.md.treeprocessors.get_index_for_name("excerpt")
+ processor: ExcerptTreeprocessor = self.md.treeprocessors[at]
+ processor.base = page
+
+ # Ensure that the excerpt includes a title in its content, since the
+ # title is linked to the post when rendering - see https://t.ly/5Gg2F
+ self.markdown = self.post.markdown
+ if not self.post._title_from_render:
+ self.markdown = "\n\n".join([f"# {self.post.title}", self.markdown])
+
+ # Convert Markdown to HTML and extract excerpt
+ self.content = self.md.convert(self.markdown)
+ self.content, *_ = self.content.split(separator, 1)
+
+ # Extract table of contents and reset post URL - if we wouldn't reset
+ # the excerpt URL, linking to the excerpt from the view would not work
+ self.toc = get_toc(getattr(self.md, "toc_tokens", []))
+ self.file.url = self.post.url
+
+# -----------------------------------------------------------------------------
+
+# View
+class View(Page):
+
+ # Initialize view
+ def __init__(self, title: str | None, file: File, config: MkDocsConfig):
+ super().__init__(title, file, config)
+ self.parent: View | Section
+
+ # Initialize posts and views
+ self.posts: list[Post] = []
+ self.views: list[View] = []
+
+ # Initialize pages for pagination
+ self.pages: list[View] = []
+
+ # Set necessary metadata
+ def read_source(self, config: MkDocsConfig):
+ super().read_source(config)
+
+ # Ensure template is set or use default
+ self.meta.setdefault("template", "blog.html")
+
+# -----------------------------------------------------------------------------
+
+# Archive view
+class Archive(View):
+ pass
+
+# -----------------------------------------------------------------------------
+
+# Category view
+class Category(View):
+ pass
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Patch configuration
+def _patch(config: MkDocsConfig):
+ config = copy(config)
+
+ # Copy parts of configuration that needs to be patched
+ config.validation = copy(config.validation)
+ config.validation.links = copy(config.validation.links)
+ config.markdown_extensions = copy(config.markdown_extensions)
+ config.mdx_configs = copy(config.mdx_configs)
+
+ # Make sure that the author did not add another instance of the table of
+ # contents extension to the configuration, as this leads to weird behavior
+ if "markdown.extensions.toc" in config.markdown_extensions:
+ config.markdown_extensions.remove("markdown.extensions.toc")
+
+ # In order to render excerpts for posts, we need to make sure that the
+ # table of contents extension is appropriately configured
+ config.mdx_configs["toc"] = {
+ **config.mdx_configs.get("toc", {}),
+ **{
+ "anchorlink": True, # Render headline as clickable
+ "baselevel": 2, # Render h1 as h2 and so forth
+ "permalink": False, # Remove permalinks
+ "toc_depth": 2 # Remove everything below h2
+ }
+ }
+
+ # Additionally, we disable link validation when rendering excerpts, because
+ # invalid links have already been reported when rendering the page
+ links = config.validation.links
+ links.not_found = logging.DEBUG
+ links.absolute_links = logging.DEBUG
+ links.unrecognized_links = logging.DEBUG
+
+ # Return patched configuration
+ return config
+
+# -----------------------------------------------------------------------------
+# Data
+# -----------------------------------------------------------------------------
+
+# Set up logging
+log = logging.getLogger("mkdocs.material.blog")
diff --git a/material/plugins/blog/structure/config.py b/material/plugins/blog/structure/config.py
new file mode 100644
index 000000000..129491b9e
--- /dev/null
+++ b/material/plugins/blog/structure/config.py
@@ -0,0 +1,37 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.base import Config
+from mkdocs.config.config_options import ListOfItems, Optional, Type
+
+from .options import PostDate
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Post configuration
+class PostConfig(Config):
+ authors = ListOfItems(Type(str), default = [])
+ categories = ListOfItems(Type(str), default = [])
+ date = PostDate()
+ draft = Optional(Type(bool))
+ readtime = Optional(Type(int))
+ slug = Optional(Type(str))
diff --git a/material/plugins/blog/structure/markdown.py b/material/plugins/blog/structure/markdown.py
new file mode 100644
index 000000000..64ade5549
--- /dev/null
+++ b/material/plugins/blog/structure/markdown.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 markdown.treeprocessors import Treeprocessor
+from mkdocs.structure.pages import Page
+from mkdocs.utils import get_relative_url
+from xml.etree.ElementTree import Element
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Excerpt tree processor
+class ExcerptTreeprocessor(Treeprocessor):
+
+ # Initialize excerpt tree processor
+ def __init__(self, page: Page, base: Page = None):
+ self.page = page
+ self.base = base
+
+ # Transform HTML after Markdown processing
+ def run(self, root: Element):
+ main = True
+
+ # We're only interested in anchors, which is why we continue when the
+ # link does not start with an anchor tag
+ for el in root.iter("a"):
+ anchor = el.get("href")
+ if not anchor.startswith("#"):
+ continue
+
+ # The main headline should link to the post page, not to a specific
+ # anchor, which is why we remove the anchor in that case
+ path = get_relative_url(self.page.url, self.base.url)
+ if main:
+ el.set("href", path)
+ else:
+ el.set("href", path + anchor)
+
+ # Main headline has been seen
+ main = False
diff --git a/material/plugins/blog/structure/options.py b/material/plugins/blog/structure/options.py
new file mode 100644
index 000000000..281dec9fb
--- /dev/null
+++ b/material/plugins/blog/structure/options.py
@@ -0,0 +1,87 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 datetime import date, datetime, time
+from mkdocs.config.base import BaseConfigOption, Config, ValidationError
+from typing import Dict
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Date dictionary
+class DateDict(Dict[str, datetime]):
+
+ # Initialize date dictionary
+ def __init__(self, data: dict):
+ super().__init__(data)
+
+ # Ensure presence of `date.created`
+ self.created: datetime = data["created"]
+
+ # Allow attribute access
+ def __getattr__(self, name: str):
+ if name in self:
+ return self[name]
+
+# -----------------------------------------------------------------------------
+
+# Post date option
+class PostDate(BaseConfigOption[DateDict]):
+
+ # Initialize post dates
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ # Normalize the supported types for post dates to datetime
+ def pre_validation(self, config: Config, key_name: str):
+
+ # If the date points to a scalar value, convert it to a dictionary,
+ # since we want to allow the user to specify custom and arbitrary date
+ # values for posts. Currently, only the `created` date is mandatory,
+ # because it's needed to sort posts for views.
+ if not isinstance(config[key_name], dict):
+ config[key_name] = { "created": config[key_name] }
+
+ # Convert all date values to datetime
+ for key, value in config[key_name].items():
+ if isinstance(value, date):
+ config[key_name][key] = datetime.combine(value, time())
+
+ # Initialize date dictionary
+ config[key_name] = DateDict(config[key_name])
+
+ # Ensure each date value is of type datetime
+ def run_validation(self, value: DateDict):
+ for key in value:
+ if not isinstance(value[key], datetime):
+ raise ValidationError(
+ f"Expected type: {date} or {datetime} "
+ f"but received: {type(value[key])}"
+ )
+
+ # Ensure presence of `date.created`
+ if not value.created:
+ raise ValidationError(
+ "Expected 'created' date when using dictionary syntax"
+ )
+
+ # Return date dictionary
+ return value
diff --git a/material/plugins/blog/templates/__init__.py b/material/plugins/blog/templates/__init__.py
new file mode 100644
index 000000000..9f7d794bb
--- /dev/null
+++ b/material/plugins/blog/templates/__init__.py
@@ -0,0 +1,42 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 jinja2 import pass_context
+from jinja2.runtime import Context
+from material.plugins.blog.structure import View
+from mkdocs.utils.templates import url_filter as _url_filter
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+# Filter for normalizing URLs with support for paginated views
+@pass_context
+def url_filter(context: Context, url: str):
+ page = context["page"]
+
+ # If the current page is a view, check if the URL links to the page
+ # itself, and replace it with the URL of the main view
+ if isinstance(page, View):
+ if page.url == url:
+ url = page.pages[0].url
+
+ # Forward to original template filter
+ return _url_filter(context, url)
diff --git a/material/plugins/group/__init__.py b/material/plugins/group/__init__.py
new file mode 100644
index 000000000..d18993785
--- /dev/null
+++ b/material/plugins/group/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/group/config.py b/material/plugins/group/config.py
new file mode 100644
index 000000000..fb19222ab
--- /dev/null
+++ b/material/plugins/group/config.py
@@ -0,0 +1,33 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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
+
+from mkdocs.config.config_options import Type
+from mkdocs.config.base import Config
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Group plugin configuration
+class GroupConfig(Config):
+ enabled = Type(bool, default = False)
+ plugins = Type(list | dict)
diff --git a/material/plugins/group/plugin.py b/material/plugins/group/plugin.py
new file mode 100644
index 000000000..4ab13dbf3
--- /dev/null
+++ b/material/plugins/group/plugin.py
@@ -0,0 +1,151 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
+
+import logging
+
+from collections.abc import Callable
+from mkdocs.config.config_options import Plugins
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin, event_priority
+
+from .config import GroupConfig
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Group plugin
+class GroupPlugin(BasePlugin[GroupConfig]):
+ supports_multiple_instances = True
+
+ # Determine whether we're serving the site
+ def on_startup(self, *, command, dirty):
+ self.is_serve = command == "serve"
+ self.is_dirty = dirty
+
+ # If the group is enabled, conditionally load plugins - at first, this might
+ # sound easier than it actually is, as we need to jump through some hoops to
+ # ensure correct ordering among plugins. We're effectively initializing the
+ # plugins that are part of the group after all MkDocs finished initializing
+ # all other plugins, so we need to patch the order of the methods. Moreover,
+ # we must use MkDocs existing plugin collection, or we might have collisions
+ # with other plugins that are not part of the group. As so often, this is a
+ # little hacky, but has huge potential making plugin configuration easier.
+ # There's one little caveat: the `__init__` and `on_startup` methods of the
+ # plugins that are part of the group are called after all other plugins, so
+ # the `event_priority` decorator for `on_startup` events and is effectively
+ # useless. However, the `on_startup` event is only intended to set up the
+ # plugin and doesn't receive anything else than the invoked command and
+ # whether we're running a dirty build, so there should be no problems.
+ @event_priority(150)
+ def on_config(self, config):
+ if not self.config.enabled:
+ return
+
+ # Retrieve plugin collection from configuration
+ option: Plugins = dict(config._schema)["plugins"]
+ assert isinstance(option, Plugins)
+
+ # Load all plugins in group
+ self.plugins: dict[str, BasePlugin] = {}
+ try:
+ for name, plugin in self._load(option):
+ self.plugins[name] = plugin
+
+ # The plugin could not be loaded, likely because it's not installed or
+ # misconfigured, so we raise a plugin error for a nicer error message
+ except Exception as e:
+ raise PluginError(str(e))
+
+ # Patch order of plugin methods
+ for events in option.plugins.events.values():
+ self._patch(events, config)
+
+ # Invoke `on_startup` event for plugins in group
+ command = "serve" if self.is_serve else "build"
+ for method in option.plugins.events["startup"]:
+ plugin = self._get_plugin(method)
+
+ # Ensure that we have a method bound to a plugin (and not a hook)
+ if plugin and plugin in self.plugins.values():
+ method(command = command, dirty = self.is_dirty)
+
+ # -------------------------------------------------------------------------
+
+ # Retrieve plugin instance for bound method or nothing
+ def _get_plugin(self, method: Callable):
+ return getattr(method, "__self__", None)
+
+ # Retrieve priority of plugin method
+ def _get_priority(self, method: Callable):
+ return getattr(method, "mkdocs_priority", 0)
+
+ # Retrieve position of plugin
+ def _get_position(self, plugin: BasePlugin, config: MkDocsConfig) -> int:
+ for at, (_, candidate) in enumerate(config.plugins.items()):
+ if plugin == candidate:
+ return at
+
+ # -------------------------------------------------------------------------
+
+ # Load plugins that are part of the group
+ def _load(self, option: Plugins):
+ for name, data in option._parse_configs(self.config.plugins):
+ yield option.load_plugin_with_namespace(name, data)
+
+ # -------------------------------------------------------------------------
+
+ # Patch order of plugin methods - all other plugin methods are already in
+ # the right order, so we only need to check those that are part of the group
+ # and bubble them up into the right location. Some plugin methods may define
+ # priorities, so we need to make sure to order correctly within those.
+ def _patch(self, methods: list[Callable], config: MkDocsConfig):
+ position = self._get_position(self, config)
+ for at in reversed(range(1, len(methods))):
+ tail = methods[at - 1]
+ head = methods[at]
+
+ # Skip if the plugin is not part of the group
+ plugin = self._get_plugin(head)
+ if not plugin or plugin not in self.plugins.values():
+ continue
+
+ # Skip if the previous method has a higher priority than the current
+ # one, because we know we can't swap them anyway
+ if self._get_priority(tail) > self._get_priority(head):
+ continue
+
+ # Ensure that we have a method bound to a plugin (and not a hook)
+ plugin = self._get_plugin(tail)
+ if not plugin:
+ continue
+
+ # Both methods have the same priority, so we check if the ordering
+ # of both methods is violated, and if it is, swap them
+ if (position < self._get_position(plugin, config)):
+ methods[at], methods[at - 1] = tail, head
+
+# -----------------------------------------------------------------------------
+# Data
+# -----------------------------------------------------------------------------
+
+# Set up logging
+log = logging.getLogger("mkdocs.material.group")
diff --git a/material/plugins/info/__init__.py b/material/plugins/info/__init__.py
index e69de29bb..d18993785 100644
--- a/material/plugins/info/__init__.py
+++ b/material/plugins/info/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/info/config.py b/material/plugins/info/config.py
new file mode 100644
index 000000000..cbd64d4c0
--- /dev/null
+++ b/material/plugins/info/config.py
@@ -0,0 +1,35 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.config_options import Type
+from mkdocs.config.base import Config
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Info plugin configuration
+class InfoConfig(Config):
+ enabled = Type(bool, default = True)
+ enabled_on_serve = Type(bool, default = False)
+
+ # Settings for archive
+ archive = Type(bool, default = True)
+ archive_stop_on_violation = Type(bool, default = True)
diff --git a/material/plugins/info/plugin.py b/material/plugins/info/plugin.py
index f8aadb590..7c6fdc17e 100644
--- a/material/plugins/info/plugin.py
+++ b/material/plugins/info/plugin.py
@@ -26,40 +26,38 @@ import requests
import sys
from colorama import Fore, Style
+from importlib.metadata import distributions, version
from io import BytesIO
-from mkdocs import utils
-from mkdocs.commands.build import DuplicateFilter
-from mkdocs.config import config_options as opt
-from mkdocs.config.base import Config
+from markdown.extensions.toc import slugify
from mkdocs.plugins import BasePlugin, event_priority
from mkdocs.structure.files import get_files
-from pkg_resources import get_distribution, working_set
+from mkdocs.utils import get_theme_dir
from zipfile import ZipFile, ZIP_DEFLATED
+from .config import InfoConfig
+
# -----------------------------------------------------------------------------
-# Class
-# -----------------------------------------------------------------------------
-
-# Info plugin configuration scheme
-class InfoPluginConfig(Config):
- enabled = opt.Type(bool, default = True)
- enabled_on_serve = opt.Type(bool, default = False)
-
- # Options for archive
- archive = opt.Type(bool, default = True)
- archive_name = opt.Type(str, default = "example")
- archive_stop_on_violation = opt.Type(bool, default = True)
-
+# Classes
# -----------------------------------------------------------------------------
# Info plugin
-class InfoPlugin(BasePlugin[InfoPluginConfig]):
+class InfoPlugin(BasePlugin[InfoConfig]):
- # Determine whether we're serving
+ # Initialize plugin
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ # Initialize incremental builds
+ self.is_serve = False
+
+ # Determine whether we're serving the site
def on_startup(self, *, command, dirty):
- self.is_serve = (command == "serve")
+ self.is_serve = command == "serve"
- # Initialize plugin (run earliest)
+ # Create a self-contained example (run earliest) - determine all files that
+ # are visible to MkDocs and are used to build the site, create an archive
+ # that contains all of them, and print a summary of the archive contents.
+ # The user must attach this archive to the bug report.
@event_priority(100)
def on_config(self, config):
if not self.config.enabled:
@@ -76,11 +74,15 @@ class InfoPlugin(BasePlugin[InfoPluginConfig]):
res = requests.get(url, allow_redirects = False)
# Check if we're running the latest version
- _, version = res.headers.get("location").rsplit("/", 1)
- package = get_distribution("mkdocs-material")
- if not package.version.startswith(version):
+ _, current = res.headers.get("location").rsplit("/", 1)
+ present = version("mkdocs-material")
+ if not present.startswith(current):
log.error("Please upgrade to the latest version.")
- self._help_on_versions_and_exit(package.version, 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")
@@ -89,8 +91,7 @@ class InfoPlugin(BasePlugin[InfoPluginConfig]):
# hack to detect whether the custom_dir setting was used without parsing
# mkdocs.yml again - we check at which position the directory provided
# by the theme resides, and if it's not the first one, abort.
- base = utils.get_theme_dir(config.theme.name)
- if config.theme.dirs.index(base):
+ if config.theme.dirs.index(get_theme_dir(config.theme.name)):
log.error("Please remove 'custom_dir' setting.")
self._help_on_customizations_and_exit()
@@ -102,33 +103,39 @@ class InfoPlugin(BasePlugin[InfoPluginConfig]):
log.error("Please remove 'hooks' setting.")
self._help_on_customizations_and_exit()
- # Create in-memory archive
+ # Create in-memory archive and prompt user to enter a short descriptive
+ # name for the archive, which is also used as the directory name. Note
+ # that the name is slugified for better readability and stripped of any
+ # file extension that the user might have entered.
archive = BytesIO()
- archive_name = self.config.archive_name
+ example = input("\nPlease name your bug report (2-4 words): ")
+ example, _ = os.path.splitext(example)
+ example = "-".join([present, slugify(example, "-")])
# Create self-contained example from project
- files = []
+ files: list[str] = []
with ZipFile(archive, "a", ZIP_DEFLATED, False) as f:
for path in ["mkdocs.yml", "requirements.txt"]:
if os.path.isfile(path):
- f.write(path, os.path.join(archive_name, path))
+ f.write(path, os.path.join(example, path))
# Append all files visible to MkDocs
for file in get_files(config):
path = os.path.relpath(file.abs_src_path, os.path.curdir)
- f.write(path, os.path.join(archive_name, path))
+ f.write(path, os.path.join(example, path))
# Add information on installed packages
f.writestr(
- os.path.join(archive_name, "requirements.lock.txt"),
+ os.path.join(example, "requirements.lock.txt"),
"\n".join(sorted([
- f"{dist.as_requirement()}" for dist in working_set
+ "==".join([package.name, package.version])
+ for package in distributions()
]))
)
- # Add information in platform
+ # Add information on platform
f.writestr(
- os.path.join(archive_name, "platform.json"),
+ os.path.join(example, "platform.json"),
json.dumps(
{
"system": platform.platform(),
@@ -148,7 +155,7 @@ class InfoPlugin(BasePlugin[InfoPluginConfig]):
# Finally, write archive to disk
buffer = archive.getbuffer()
- with open(f"{archive_name}.zip", "wb") as f:
+ with open(f"{example}.zip", "wb") as f:
f.write(archive.getvalue())
# Print summary
@@ -172,7 +179,7 @@ class InfoPlugin(BasePlugin[InfoPluginConfig]):
if buffer.nbytes > 1000000:
log.warning("Archive exceeds recommended maximum size of 1 MB")
- # Aaaaaand done.
+ # Aaaaaand done
sys.exit(1)
# -------------------------------------------------------------------------
@@ -235,5 +242,4 @@ def _size(value, factor = 1):
# -----------------------------------------------------------------------------
# Set up logging
-log = logging.getLogger("mkdocs")
-log.addFilter(DuplicateFilter())
+log = logging.getLogger("mkdocs.material.info")
diff --git a/material/plugins/offline/__init__.py b/material/plugins/offline/__init__.py
index e69de29bb..d18993785 100644
--- a/material/plugins/offline/__init__.py
+++ b/material/plugins/offline/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/offline/config.py b/material/plugins/offline/config.py
new file mode 100644
index 000000000..49f51a94f
--- /dev/null
+++ b/material/plugins/offline/config.py
@@ -0,0 +1,30 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.config_options import Type
+from mkdocs.config.base import Config
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Offline plugin configuration
+class OfflineConfig(Config):
+ enabled = Type(bool, default = True)
diff --git a/material/plugins/offline/plugin.py b/material/plugins/offline/plugin.py
index 799f6187f..abcb25984 100644
--- a/material/plugins/offline/plugin.py
+++ b/material/plugins/offline/plugin.py
@@ -20,50 +20,50 @@
import os
-from mkdocs import utils
-from mkdocs.config import config_options as opt
-from mkdocs.config.base import Config
from mkdocs.plugins import BasePlugin, event_priority
-# -----------------------------------------------------------------------------
-# Class
-# -----------------------------------------------------------------------------
-
-# Offline plugin configuration scheme
-class OfflinePluginConfig(Config):
- enabled = opt.Type(bool, default = True)
+from .config import OfflineConfig
+# -----------------------------------------------------------------------------
+# Classes
# -----------------------------------------------------------------------------
# Offline plugin
-class OfflinePlugin(BasePlugin[OfflinePluginConfig]):
+class OfflinePlugin(BasePlugin[OfflineConfig]):
- # Initialize plugin
+ # Set configuration for offline build
def on_config(self, config):
if not self.config.enabled:
return
- # Ensure correct resolution of links
+ # Ensure correct resolution of links when viewing the site from the
+ # file system by disabling directory URLs
config.use_directory_urls = False
- # Support offline search (run latest)
+ # Append iframe-worker to polyfills/shims
+ config.extra["polyfills"] = config.extra.get("polyfills", [])
+ if not any("iframe-worker" in url for url in config.extra["polyfills"]):
+ script = "https://unpkg.com/iframe-worker/shim"
+ config.extra["polyfills"].append(script)
+
+ # Add support for offline search (run latest) - the search index is copied
+ # and inlined into a script, so that it can be used without a server
@event_priority(-100)
def on_post_build(self, *, config):
if not self.config.enabled:
return
- # Check for existence of search index
- base = os.path.join(config.site_dir, "search")
- path = os.path.join(base, "search_index.json")
- if not os.path.exists(path):
+ # Ensure presence of search index
+ path = os.path.join(config.site_dir, "search")
+ file = os.path.join(path, "search_index.json")
+ if not os.path.isfile(file):
return
- # Retrieve search index
- with open(path, "r") as data:
- index = data.read()
+ # Obtain search index contents
+ with open(file, encoding = "utf-8") as f:
+ data = f.read()
- # Inline search index into script
- utils.write_file(
- f"var __index = {index}".encode("utf-8"),
- os.path.join(base, "search_index.js")
- )
+ # Inline search index contents into script
+ file = os.path.join(path, "search_index.js")
+ with open(file, "w", encoding = "utf-8") as f:
+ f.write(f"var __index = {data}")
diff --git a/material/plugins/search/__init__.py b/material/plugins/search/__init__.py
index e69de29bb..d18993785 100644
--- a/material/plugins/search/__init__.py
+++ b/material/plugins/search/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/search/config.py b/material/plugins/search/config.py
new file mode 100644
index 000000000..e150fbb36
--- /dev/null
+++ b/material/plugins/search/config.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.config_options import (
+ Choice,
+ Deprecated,
+ Optional,
+ ListOfItems,
+ Type
+)
+from mkdocs.config.base import Config
+from mkdocs.contrib.search import LangOption
+
+# -----------------------------------------------------------------------------
+# Options
+# -----------------------------------------------------------------------------
+
+# Options for search pipeline
+pipeline = ("stemmer", "stopWordFilter", "trimmer")
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# 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 = [])
+
+ # Settings for text segmentation (Chinese)
+ jieba_dict = Optional(Type(str))
+ jieba_dict_user = Optional(Type(str))
+
+ # Unsupported settings, originally implemented in MkDocs
+ indexing = Deprecated(message = "Unsupported option")
+ prebuild_index = Deprecated(message = "Unsupported option")
+ min_search_length = Deprecated(message = "Unsupported option")
diff --git a/material/plugins/search/plugin.py b/material/plugins/search/plugin.py
index 77ec503ff..cc88986b1 100644
--- a/material/plugins/search/plugin.py
+++ b/material/plugins/search/plugin.py
@@ -26,45 +26,42 @@ import regex as re
from html import escape
from html.parser import HTMLParser
from mkdocs import utils
-from mkdocs.commands.build import DuplicateFilter
-from mkdocs.config import config_options as opt
-from mkdocs.config.base import Config
-from mkdocs.contrib.search import LangOption
from mkdocs.plugins import BasePlugin
+from .config import SearchConfig
+
+try:
+ import jieba
+except ImportError:
+ jieba = None
+
# -----------------------------------------------------------------------------
-# Class
-# -----------------------------------------------------------------------------
-
-# Search plugin configuration scheme
-class SearchPluginConfig(Config):
- lang = opt.Optional(LangOption())
- separator = opt.Optional(opt.Type(str))
- pipeline = opt.ListOfItems(
- opt.Choice(("stemmer", "stopWordFilter", "trimmer")),
- default = []
- )
-
- # Deprecated options
- indexing = opt.Deprecated(message = "Unsupported option")
- prebuild_index = opt.Deprecated(message = "Unsupported option")
- min_search_length = opt.Deprecated(message = "Unsupported option")
-
+# Classes
# -----------------------------------------------------------------------------
# Search plugin
-class SearchPlugin(BasePlugin[SearchPluginConfig]):
+class SearchPlugin(BasePlugin[SearchConfig]):
- # Determine whether we're running under dirty reload
- def on_startup(self, *, command, dirty):
+ # Initialize plugin
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ # Initialize incremental builds
self.is_dirtyreload = False
- self.is_dirty = dirty
# Initialize search index cache
self.search_index_prev = None
+ # Determine whether we're serving the site
+ def on_startup(self, *, command, dirty):
+ self.is_dirty = dirty
+
# 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"
@@ -85,8 +82,36 @@ class SearchPlugin(BasePlugin[SearchPluginConfig]):
# Initialize search index
self.search_index = SearchIndex(**self.config)
+ # Set jieba dictionary, if given
+ if self.config.jieba_dict:
+ path = os.path.normpath(self.config.jieba_dict)
+ if os.path.isfile(path):
+ jieba.set_dictionary(path)
+ log.debug(f"Loading jieba dictionary: {path}")
+ else:
+ log.warning(
+ f"Configuration error for 'search.jieba_dict': "
+ f"'{self.config.jieba_dict}' does not exist."
+ )
+
+ # Set jieba user dictionary, if given
+ if self.config.jieba_dict_user:
+ path = os.path.normpath(self.config.jieba_dict_user)
+ if os.path.isfile(path):
+ jieba.load_userdict(path)
+ log.debug(f"Loading jieba user dictionary: {path}")
+ else:
+ log.warning(
+ f"Configuration error for 'search.jieba_dict_user': "
+ f"'{self.config.jieba_dict_user}' does not exist."
+ )
+
# 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+=\"[^\"]+\"",
@@ -96,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchPluginConfig]):
# 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")
@@ -167,9 +196,10 @@ class SearchIndex:
title = "".join(section.title).strip()
text = "".join(section.text).strip()
- # Reset text, if only titles should be indexed
- if self.config["indexing"] == "titles":
- text = ""
+ # Segment Chinese characters if jieba is available
+ if jieba:
+ title = self._segment_chinese(title)
+ text = self._segment_chinese(text)
# Create entry for section
entry = {
@@ -252,6 +282,25 @@ class SearchIndex:
# No item found
return None
+ # Find and segment Chinese characters in string
+ def _segment_chinese(self, data):
+ expr = re.compile(r"(\p{IsHan}+)", re.UNICODE)
+
+ # Replace callback
+ def replace(match):
+ value = match.group(0)
+
+ # Replace occurrence in original string with segmented version and
+ # surround with zero-width whitespace for efficient indexing
+ return "".join([
+ "\u200b",
+ "\u200b".join(jieba.cut(value.encode("utf-8"))),
+ "\u200b",
+ ])
+
+ # Return string with segmented occurrences
+ return expr.sub(replace, data).strip("\u200b")
+
# -----------------------------------------------------------------------------
# HTML element
@@ -262,7 +311,7 @@ class Element:
"""
# Initialize HTML element
- def __init__(self, tag, attrs = dict()):
+ def __init__(self, tag, attrs = {}):
self.tag = tag
self.attrs = attrs
@@ -341,7 +390,8 @@ class Parser(HTMLParser):
self.keep = set([
"p", # Paragraphs
"code", "pre", # Code blocks
- "li", "ol", "ul" # Lists
+ "li", "ol", "ul", # Lists
+ "sub", "sup" # Sub- and superscripts
])
# Current context and section
@@ -362,7 +412,7 @@ class Parser(HTMLParser):
else:
return
- # Handle headings
+ # Handle heading
if tag in ([f"h{x}" for x in range(1, 7)]):
depth = len(self.context)
if "id" in attrs:
@@ -507,23 +557,22 @@ class Parser(HTMLParser):
# -----------------------------------------------------------------------------
# Set up logging
-log = logging.getLogger("mkdocs")
-log.addFilter(DuplicateFilter())
+log = logging.getLogger("mkdocs.material.search")
# Tags that are self-closing
void = set([
- "area", # Image map areas
- "base", # Document base
- "br", # Line breaks
- "col", # Table columns
- "embed", # External content
- "hr", # Horizontal rules
- "img", # Images
- "input", # Input fields
- "link", # Links
- "meta", # Metadata
- "param", # External parameters
- "source", # Image source sets
- "track", # Text track
- "wbr" # Line break opportunities
+ "area", # Image map areas
+ "base", # Document base
+ "br", # Line breaks
+ "col", # Table columns
+ "embed", # External content
+ "hr", # Horizontal rules
+ "img", # Images
+ "input", # Input fields
+ "link", # Links
+ "meta", # Metadata
+ "param", # External parameters
+ "source", # Image source sets
+ "track", # Text track
+ "wbr" # Line break opportunities
])
diff --git a/material/plugins/social/__init__.py b/material/plugins/social/__init__.py
index e69de29bb..d18993785 100644
--- a/material/plugins/social/__init__.py
+++ b/material/plugins/social/__init__.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
diff --git a/material/plugins/social/config.py b/material/plugins/social/config.py
new file mode 100644
index 000000000..2d87c25e0
--- /dev/null
+++ b/material/plugins/social/config.py
@@ -0,0 +1,48 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 mkdocs.config.base import Config
+from mkdocs.config.config_options import Deprecated, Type
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Social plugin configuration
+class SocialConfig(Config):
+ enabled = Type(bool, default = True)
+ cache_dir = Type(str, default = ".cache/plugin/social")
+
+ # Settings for social cards
+ cards = Type(bool, default = True)
+ cards_dir = Type(str, default = "assets/images/social")
+ cards_layout_options = Type(dict, default = {})
+
+ # Deprecated settings
+ cards_color = Deprecated(
+ option_type = Type(dict, default = {}),
+ message =
+ "Deprecated, use 'cards_layout_options.background_color' "
+ "and 'cards_layout_options.color' with 'default' layout"
+ )
+ cards_font = Deprecated(
+ option_type = Type(str),
+ message = "Deprecated, use 'cards_layout_options.font_family'"
+ )
diff --git a/material/plugins/social/plugin.py b/material/plugins/social/plugin.py
index 06b43714e..3cdfa3ce2 100644
--- a/material/plugins/social/plugin.py
+++ b/material/plugins/social/plugin.py
@@ -18,6 +18,19 @@
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
+# -----------------------------------------------------------------------------
+# Disclaimer
+# -----------------------------------------------------------------------------
+# Please note: this version of the social plugin is not actively development
+# anymore. Instead, Material for MkDocs Insiders ships a complete rewrite of
+# the plugin which is much more powerful and addresses all shortcomings of
+# this implementation. Additionally, the new social plugin allows to create
+# entirely custom social cards. You can probably imagine, that this was a lot
+# of work to pull off. If you run into problems, or want to have additional
+# functionality, please consider sponsoring the project. You can then use the
+# new version of the plugin immediately.
+# -----------------------------------------------------------------------------
+
import concurrent.futures
import functools
import logging
@@ -31,39 +44,26 @@ from collections import defaultdict
from hashlib import md5
from io import BytesIO
from mkdocs.commands.build import DuplicateFilter
-from mkdocs.config import config_options as opt
-from mkdocs.config.base import Config
+from mkdocs.exceptions import PluginError
from mkdocs.plugins import BasePlugin
from shutil import copyfile
from tempfile import TemporaryFile
from zipfile import ZipFile
-
try:
from cairosvg import svg2png
from PIL import Image, ImageDraw, ImageFont
- dependencies = True
except ImportError:
- dependencies = False
+ pass
+
+from .config import SocialConfig
+
# -----------------------------------------------------------------------------
-# Class
-# -----------------------------------------------------------------------------
-
-# Social plugin configuration scheme
-class SocialPluginConfig(Config):
- enabled = opt.Type(bool, default = True)
- cache_dir = opt.Type(str, default = ".cache/plugin/social")
-
- # Options for social cards
- cards = opt.Type(bool, default = True)
- cards_dir = opt.Type(str, default = "assets/images/social")
- cards_color = opt.Type(dict, default = dict())
- cards_font = opt.Optional(opt.Type(str))
-
+# Classes
# -----------------------------------------------------------------------------
# Social plugin
-class SocialPlugin(BasePlugin[SocialPluginConfig]):
+class SocialPlugin(BasePlugin[SocialConfig]):
def __init__(self):
self._executor = concurrent.futures.ThreadPoolExecutor(4)
@@ -71,22 +71,40 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
# Retrieve configuration
def on_config(self, config):
self.color = colors.get("indigo")
+ self.config.cards = self.config.enabled
if not self.config.cards:
return
- # Check if required dependencies are installed
- if not dependencies:
- log.error(
+ # Check dependencies
+ 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]\""
)
- sys.exit(1)
+
+ # Move color options
+ if self.config.cards_color:
+
+ # Move background color to new option
+ value = self.config.cards_color.get("fill")
+ if value:
+ self.config.cards_layout_options["background_color"] = value
+
+ # Move color to new option
+ value = self.config.cards_color.get("text")
+ if value:
+ self.config.cards_layout_options["color"] = value
+
+ # Move font family to new option
+ if self.config.cards_font:
+ value = self.config.cards_font
+ self.config.cards_layout_options["font_family"] = value
# Check if site URL is defined
if not config.site_url:
log.warning(
- "The \"social\" plugin needs the \"site_url\" configuration "
- "option to be defined. It will likely not work correctly."
+ "The \"site_url\" option is not set. The cards are generated, "
+ "but not linked, so they won't be visible on social media."
)
# Ensure presence of cache directory
@@ -109,7 +127,11 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
self.color = colors.get(primary, self.color)
# Retrieve color overrides
- self.color = { **self.color, **self.config.cards_color }
+ options = self.config.cards_layout_options
+ self.color = {
+ "fill": options.get("background_color", self.color["fill"]),
+ "text": options.get("color", self.color["text"])
+ }
# Retrieve logo and font
self._resized_logo_promise = self._executor.submit(self._load_resized_logo, config)
@@ -147,7 +169,23 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
if "description" in page.meta:
description = page.meta["description"]
- # Generate social card if not in cache - TODO: values from mkdocs.yml
+ # Check type of meta title - see https://t.ly/m1Us
+ if not isinstance(title, str):
+ log.error(
+ f"Page meta title of page '{page.file.src_uri}' must be a "
+ f"string, but is of type \"{type(title)}\"."
+ )
+ sys.exit(1)
+
+ # Check type of meta description - see https://t.ly/m1Us
+ if not isinstance(description, str):
+ log.error(
+ f"Page meta description of '{page.file.src_uri}' must be a "
+ f"string, but is of type \"{type(description)}\"."
+ )
+ sys.exit(1)
+
+ # Generate social card if not in cache
hash = md5("".join([
site_name,
str(title),
@@ -255,17 +293,6 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
lines.append(words)
words = [word]
- # # Balance words on last line - TODO: overflows when broken word is too long
- # if len(lines) > 0:
- # prev = len(" ".join(lines[-1]))
- # last = len(" ".join(words))#
-
- # print(last, prev)
-
- # # Heuristic: try to find a good ratio
- # if last / prev < 0.6:
- # words.insert(0, lines[-1].pop())
-
# Join words for each line and create image
lines.append(words)
lines = [" ".join(line) for line in lines]
@@ -343,8 +370,15 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
if "logo" in theme:
_, extension = os.path.splitext(theme["logo"])
- # Load SVG and convert to PNG
path = os.path.join(config.docs_dir, theme["logo"])
+
+ # Allow users to put the logo inside their custom_dir (theme["logo"] case)
+ if theme.custom_dir:
+ custom_dir_logo = os.path.join(theme.custom_dir, theme["logo"])
+ if os.path.exists(custom_dir_logo):
+ path = custom_dir_logo
+
+ # Load SVG and convert to PNG
if extension == ".svg":
return self._load_logo_svg(path)
@@ -352,10 +386,11 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
return Image.open(path).convert("RGBA")
# Handle icons
- logo = "material/library"
icon = theme["icon"] or {}
if "logo" in icon and icon["logo"]:
logo = icon["logo"]
+ else:
+ logo = "material/library"
# Resolve path of package
base = os.path.abspath(os.path.join(
@@ -363,8 +398,15 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
"../.."
))
+ path = f"{base}/templates/.icons/{logo}.svg"
+
+ # Allow users to put the logo inside their custom_dir (theme["icon"]["logo"] case)
+ if theme.custom_dir:
+ custom_dir_logo = os.path.join(theme.custom_dir, ".icons", f"{logo}.svg")
+ if os.path.exists(custom_dir_logo):
+ path = custom_dir_logo
+
# Load icon data and fill with color
- path = f"{base}/.icons/{logo}.svg"
return self._load_logo_svg(path, self.color["text"])
# Load SVG file and convert to PNG
@@ -382,28 +424,41 @@ class SocialPlugin(BasePlugin[SocialPluginConfig]):
# Retrieve font
def _load_font(self, config):
- name = self.config.cards_font
+ name = self.config.cards_layout_options.get("font_family")
if not name:
# Retrieve from theme (default: Roboto)
theme = config.theme
- if theme["font"]:
+ if isinstance(theme["font"], dict) and "text" in theme["font"]:
name = theme["font"]["text"]
else:
name = "Roboto"
- # Retrieve font files, if not already done
- files = os.listdir(self.cache)
- files = [file for file in files if file.endswith(".ttf") or file.endswith(".otf")] or (
- self._load_font_from_google(name)
- )
+ # Google fonts can return varients like OpenSans_Condensed-Regular.ttf so
+ # we only use the font requested e.g. OpenSans-Regular.ttf
+ font_filename_base = name.replace(' ', '')
+ filename_regex = re.escape(font_filename_base)+r"-(\w+)\.[ot]tf$"
- # Map available font weights to file paths
- font = dict()
- for file in files:
- match = re.search(r"-(\w+)\.[ot]tf$", file)
- if match:
- font[match.group(1)] = os.path.join(self.cache, file)
+ font = {}
+ # Check for cached files - note these may be in subfolders
+ for currentpath, folders, files in os.walk(self.cache):
+ for file in files:
+ # Map available font weights to file paths
+ fname = os.path.join(currentpath, file)
+ match = re.search(filename_regex, fname)
+ if match:
+ font[match.group(1)] = fname
+
+ # If none found, fetch from Google and try again
+ if len(font) == 0:
+ self._load_font_from_google(name)
+ for currentpath, folders, files in os.walk(self.cache):
+ for file in files:
+ # Map available font weights to file paths
+ fname = os.path.join(currentpath, file)
+ match = re.search(filename_regex, fname)
+ if match:
+ font[match.group(1)] = fname
# Return available font weights with fallback
return defaultdict(lambda: font["Regular"], font)
diff --git a/material/plugins/tags/__init__.py b/material/plugins/tags/__init__.py
index e69de29bb..19994c95e 100644
--- a/material/plugins/tags/__init__.py
+++ b/material/plugins/tags/__init__.py
@@ -0,0 +1,27 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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.
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+# Casefold a string for comparison when sorting
+def casefold(tag: str):
+ return tag.casefold()
diff --git a/material/plugins/tags/config.py b/material/plugins/tags/config.py
new file mode 100644
index 000000000..f2d950845
--- /dev/null
+++ b/material/plugins/tags/config.py
@@ -0,0 +1,38 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# 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 functools import partial
+from markdown.extensions.toc import slugify
+from mkdocs.config.config_options import Optional, Type
+from mkdocs.config.base import Config
+
+from . import casefold
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+# Tags plugin configuration
+class TagsConfig(Config):
+ enabled = Type(bool, default = True)
+
+ # Settings for tags
+ tags = Type(bool, default = True)
+ tags_file = Optional(Type(str))
diff --git a/material/plugins/tags/plugin.py b/material/plugins/tags/plugin.py
index 6afbfe83f..e5ce6bdec 100644
--- a/material/plugins/tags/plugin.py
+++ b/material/plugins/tags/plugin.py
@@ -19,33 +19,36 @@
# IN THE SOFTWARE.
import logging
-import os
import sys
from collections import defaultdict
from markdown.extensions.toc import slugify
from mkdocs import utils
-from mkdocs.commands.build import DuplicateFilter
-from mkdocs.config.base import Config
-from mkdocs.config import config_options as opt
from mkdocs.plugins import BasePlugin
-# -----------------------------------------------------------------------------
-# Class
-# -----------------------------------------------------------------------------
-
-# Tags plugin configuration scheme
-class TagsPluginConfig(Config):
- tags_file = opt.Optional(opt.Type(str))
+# deprecated, but kept for downward compatibility. Use 'material.plugins.tags'
+# as an import source instead. This import is removed in the next major version.
+from . import casefold
+from .config import TagsConfig
+# -----------------------------------------------------------------------------
+# Classes
# -----------------------------------------------------------------------------
# Tags plugin
-class TagsPlugin(BasePlugin[TagsPluginConfig]):
+class TagsPlugin(BasePlugin[TagsConfig]):
supports_multiple_instances = True
# Initialize plugin
def on_config(self, config):
+ if not self.config.enabled:
+ return
+
+ # Skip if tags should not be built
+ if not self.config.tags:
+ return
+
+ # Initialize tags
self.tags = defaultdict(list)
self.tags_file = None
@@ -64,12 +67,32 @@ class TagsPlugin(BasePlugin[TagsPluginConfig]):
# Hack: 2nd pass for tags index page(s)
def on_nav(self, nav, config, files):
+ if not self.config.enabled:
+ return
+
+ # Skip if tags should not be built
+ if not self.config.tags:
+ return
+
+ # Resolve tags index page
file = self.config.tags_file
if file:
self.tags_file = self._get_tags_file(files, file)
# Build and render tags index page
def on_page_markdown(self, markdown, page, config, files):
+ if not self.config.enabled:
+ return
+
+ # Skip if tags should not be built
+ if not self.config.tags:
+ return
+
+ # Skip, if page is excluded
+ if page.file.inclusion.is_excluded():
+ return
+
+ # Render tags index page
if page.file == self.tags_file:
return self._render_tag_index(markdown)
@@ -79,6 +102,14 @@ class TagsPlugin(BasePlugin[TagsPluginConfig]):
# Inject tags into page (after search and before minification)
def on_page_context(self, context, page, config, nav):
+ if not self.config.enabled:
+ return
+
+ # Skip if tags should not be built
+ if not self.config.tags:
+ return
+
+ # Provide tags for page
if "tags" in page.meta:
context["tags"] = [
self._render_tag(tag)
@@ -148,5 +179,4 @@ class TagsPlugin(BasePlugin[TagsPluginConfig]):
# -----------------------------------------------------------------------------
# Set up logging
-log = logging.getLogger("mkdocs")
-log.addFilter(DuplicateFilter())
+log = logging.getLogger("mkdocs.material.tags")
diff --git a/material/.icons/fontawesome/LICENSE.txt b/material/templates/.icons/fontawesome/LICENSE.txt
similarity index 100%
rename from material/.icons/fontawesome/LICENSE.txt
rename to material/templates/.icons/fontawesome/LICENSE.txt
diff --git a/material/.icons/fontawesome/brands/42-group.svg b/material/templates/.icons/fontawesome/brands/42-group.svg
similarity index 88%
rename from material/.icons/fontawesome/brands/42-group.svg
rename to material/templates/.icons/fontawesome/brands/42-group.svg
index 05f3b3310..267c4fe1a 100644
--- a/material/.icons/fontawesome/brands/42-group.svg
+++ b/material/templates/.icons/fontawesome/brands/42-group.svg
@@ -1 +1 @@
-
+
+# 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.
diff --git a/material/assets/images/favicon.png b/material/templates/assets/images/favicon.png
similarity index 100%
rename from material/assets/images/favicon.png
rename to material/templates/assets/images/favicon.png
diff --git a/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js b/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js
new file mode 100644
index 000000000..328d22a91
--- /dev/null
+++ b/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js
@@ -0,0 +1,29 @@
+"use strict";(()=>{var gi=Object.create;var dr=Object.defineProperty;var xi=Object.getOwnPropertyDescriptor;var yi=Object.getOwnPropertyNames,Ht=Object.getOwnPropertySymbols,Ei=Object.getPrototypeOf,hr=Object.prototype.hasOwnProperty,Xr=Object.prototype.propertyIsEnumerable;var Jr=(e,t,r)=>t in e?dr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,I=(e,t)=>{for(var r in t||(t={}))hr.call(t,r)&&Jr(e,r,t[r]);if(Ht)for(var r of Ht(t))Xr.call(t,r)&&Jr(e,r,t[r]);return e};var Zr=(e,t)=>{var r={};for(var o in e)hr.call(e,o)&&t.indexOf(o)<0&&(r[o]=e[o]);if(e!=null&&Ht)for(var o of Ht(e))t.indexOf(o)<0&&Xr.call(e,o)&&(r[o]=e[o]);return r};var br=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var wi=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of yi(t))!hr.call(e,n)&&n!==r&&dr(e,n,{get:()=>t[n],enumerable:!(o=xi(t,n))||o.enumerable});return e};var $t=(e,t,r)=>(r=e!=null?gi(Ei(e)):{},wi(t||!e||!e.__esModule?dr(r,"default",{value:e,enumerable:!0}):r,e));var to=br((vr,eo)=>{(function(e,t){typeof vr=="object"&&typeof eo!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(vr,function(){"use strict";function e(r){var o=!0,n=!1,i=null,s={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function a(A){return!!(A&&A!==document&&A.nodeName!=="HTML"&&A.nodeName!=="BODY"&&"classList"in A&&"contains"in A.classList)}function c(A){var it=A.type,Ne=A.tagName;return!!(Ne==="INPUT"&&s[it]&&!A.readOnly||Ne==="TEXTAREA"&&!A.readOnly||A.isContentEditable)}function p(A){A.classList.contains("focus-visible")||(A.classList.add("focus-visible"),A.setAttribute("data-focus-visible-added",""))}function m(A){A.hasAttribute("data-focus-visible-added")&&(A.classList.remove("focus-visible"),A.removeAttribute("data-focus-visible-added"))}function f(A){A.metaKey||A.altKey||A.ctrlKey||(a(r.activeElement)&&p(r.activeElement),o=!0)}function u(A){o=!1}function d(A){a(A.target)&&(o||c(A.target))&&p(A.target)}function b(A){a(A.target)&&(A.target.classList.contains("focus-visible")||A.target.hasAttribute("data-focus-visible-added"))&&(n=!0,window.clearTimeout(i),i=window.setTimeout(function(){n=!1},100),m(A.target))}function _(A){document.visibilityState==="hidden"&&(n&&(o=!0),re())}function re(){document.addEventListener("mousemove",Y),document.addEventListener("mousedown",Y),document.addEventListener("mouseup",Y),document.addEventListener("pointermove",Y),document.addEventListener("pointerdown",Y),document.addEventListener("pointerup",Y),document.addEventListener("touchmove",Y),document.addEventListener("touchstart",Y),document.addEventListener("touchend",Y)}function Z(){document.removeEventListener("mousemove",Y),document.removeEventListener("mousedown",Y),document.removeEventListener("mouseup",Y),document.removeEventListener("pointermove",Y),document.removeEventListener("pointerdown",Y),document.removeEventListener("pointerup",Y),document.removeEventListener("touchmove",Y),document.removeEventListener("touchstart",Y),document.removeEventListener("touchend",Y)}function Y(A){A.target.nodeName&&A.target.nodeName.toLowerCase()==="html"||(o=!1,Z())}document.addEventListener("keydown",f,!0),document.addEventListener("mousedown",u,!0),document.addEventListener("pointerdown",u,!0),document.addEventListener("touchstart",u,!0),document.addEventListener("visibilitychange",_,!0),re(),r.addEventListener("focus",d,!0),r.addEventListener("blur",b,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var Vr=br((Mt,Dr)=>{/*!
+ * clipboard.js v2.0.11
+ * https://clipboardjs.com/
+ *
+ * Licensed MIT © Zeno Rocha
+ */(function(t,r){typeof Mt=="object"&&typeof Dr=="object"?Dr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Mt=="object"?Mt.ClipboardJS=r():t.ClipboardJS=r()})(Mt,function(){return function(){var e={686:function(o,n,i){"use strict";i.d(n,{default:function(){return vi}});var s=i(279),a=i.n(s),c=i(370),p=i.n(c),m=i(817),f=i.n(m);function u(F){try{return document.execCommand(F)}catch(S){return!1}}var d=function(S){var y=f()(S);return u("cut"),y},b=d;function _(F){var S=document.documentElement.getAttribute("dir")==="rtl",y=document.createElement("textarea");y.style.fontSize="12pt",y.style.border="0",y.style.padding="0",y.style.margin="0",y.style.position="absolute",y.style[S?"right":"left"]="-9999px";var R=window.pageYOffset||document.documentElement.scrollTop;return y.style.top="".concat(R,"px"),y.setAttribute("readonly",""),y.value=F,y}var re=function(S,y){var R=_(S);y.container.appendChild(R);var P=f()(R);return u("copy"),R.remove(),P},Z=function(S){var y=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},R="";return typeof S=="string"?R=re(S,y):S instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(S==null?void 0:S.type)?R=re(S.value,y):(R=f()(S),u("copy")),R},Y=Z;function A(F){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?A=function(y){return typeof y}:A=function(y){return y&&typeof Symbol=="function"&&y.constructor===Symbol&&y!==Symbol.prototype?"symbol":typeof y},A(F)}var it=function(){var S=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},y=S.action,R=y===void 0?"copy":y,P=S.container,q=S.target,Me=S.text;if(R!=="copy"&&R!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(q!==void 0)if(q&&A(q)==="object"&&q.nodeType===1){if(R==="copy"&&q.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(R==="cut"&&(q.hasAttribute("readonly")||q.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(Me)return Y(Me,{container:P});if(q)return R==="cut"?b(q):Y(q,{container:P})},Ne=it;function Ie(F){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?Ie=function(y){return typeof y}:Ie=function(y){return y&&typeof Symbol=="function"&&y.constructor===Symbol&&y!==Symbol.prototype?"symbol":typeof y},Ie(F)}function pi(F,S){if(!(F instanceof S))throw new TypeError("Cannot call a class as a function")}function Gr(F,S){for(var y=0;y0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof P.action=="function"?P.action:this.defaultAction,this.target=typeof P.target=="function"?P.target:this.defaultTarget,this.text=typeof P.text=="function"?P.text:this.defaultText,this.container=Ie(P.container)==="object"?P.container:document.body}},{key:"listenClick",value:function(P){var q=this;this.listener=p()(P,"click",function(Me){return q.onClick(Me)})}},{key:"onClick",value:function(P){var q=P.delegateTarget||P.currentTarget,Me=this.action(q)||"copy",kt=Ne({action:Me,container:this.container,target:this.target(q),text:this.text(q)});this.emit(kt?"success":"error",{action:Me,text:kt,trigger:q,clearSelection:function(){q&&q.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(P){return ur("action",P)}},{key:"defaultTarget",value:function(P){var q=ur("target",P);if(q)return document.querySelector(q)}},{key:"defaultText",value:function(P){return ur("text",P)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(P){var q=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return Y(P,q)}},{key:"cut",value:function(P){return b(P)}},{key:"isSupported",value:function(){var P=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],q=typeof P=="string"?[P]:P,Me=!!document.queryCommandSupported;return q.forEach(function(kt){Me=Me&&!!document.queryCommandSupported(kt)}),Me}}]),y}(a()),vi=bi},828:function(o){var n=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function s(a,c){for(;a&&a.nodeType!==n;){if(typeof a.matches=="function"&&a.matches(c))return a;a=a.parentNode}}o.exports=s},438:function(o,n,i){var s=i(828);function a(m,f,u,d,b){var _=p.apply(this,arguments);return m.addEventListener(u,_,b),{destroy:function(){m.removeEventListener(u,_,b)}}}function c(m,f,u,d,b){return typeof m.addEventListener=="function"?a.apply(null,arguments):typeof u=="function"?a.bind(null,document).apply(null,arguments):(typeof m=="string"&&(m=document.querySelectorAll(m)),Array.prototype.map.call(m,function(_){return a(_,f,u,d,b)}))}function p(m,f,u,d){return function(b){b.delegateTarget=s(b.target,f),b.delegateTarget&&d.call(m,b)}}o.exports=c},879:function(o,n){n.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},n.nodeList=function(i){var s=Object.prototype.toString.call(i);return i!==void 0&&(s==="[object NodeList]"||s==="[object HTMLCollection]")&&"length"in i&&(i.length===0||n.node(i[0]))},n.string=function(i){return typeof i=="string"||i instanceof String},n.fn=function(i){var s=Object.prototype.toString.call(i);return s==="[object Function]"}},370:function(o,n,i){var s=i(879),a=i(438);function c(u,d,b){if(!u&&!d&&!b)throw new Error("Missing required arguments");if(!s.string(d))throw new TypeError("Second argument must be a String");if(!s.fn(b))throw new TypeError("Third argument must be a Function");if(s.node(u))return p(u,d,b);if(s.nodeList(u))return m(u,d,b);if(s.string(u))return f(u,d,b);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function p(u,d,b){return u.addEventListener(d,b),{destroy:function(){u.removeEventListener(d,b)}}}function m(u,d,b){return Array.prototype.forEach.call(u,function(_){_.addEventListener(d,b)}),{destroy:function(){Array.prototype.forEach.call(u,function(_){_.removeEventListener(d,b)})}}}function f(u,d,b){return a(document.body,u,d,b)}o.exports=c},817:function(o){function n(i){var s;if(i.nodeName==="SELECT")i.focus(),s=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var a=i.hasAttribute("readonly");a||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),a||i.removeAttribute("readonly"),s=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var c=window.getSelection(),p=document.createRange();p.selectNodeContents(i),c.removeAllRanges(),c.addRange(p),s=c.toString()}return s}o.exports=n},279:function(o){function n(){}n.prototype={on:function(i,s,a){var c=this.e||(this.e={});return(c[i]||(c[i]=[])).push({fn:s,ctx:a}),this},once:function(i,s,a){var c=this;function p(){c.off(i,p),s.apply(a,arguments)}return p._=s,this.on(i,p,a)},emit:function(i){var s=[].slice.call(arguments,1),a=((this.e||(this.e={}))[i]||[]).slice(),c=0,p=a.length;for(c;c{"use strict";/*!
+ * escape-html
+ * Copyright(c) 2012-2013 TJ Holowaychuk
+ * Copyright(c) 2015 Andreas Lubbe
+ * Copyright(c) 2015 Tiancheng "Timothy" Gu
+ * MIT Licensed
+ */var _a=/["'&<>]/;Pn.exports=Aa;function Aa(e){var t=""+e,r=_a.exec(t);if(!r)return t;var o,n="",i=0,s=0;for(i=r.index;i0&&i[i.length-1])&&(p[0]===6||p[0]===2)){r=0;continue}if(p[0]===3&&(!i||p[1]>i[0]&&p[1]=e.length&&(e=void 0),{value:e&&e[o++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function U(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var o=r.call(e),n,i=[],s;try{for(;(t===void 0||t-- >0)&&!(n=o.next()).done;)i.push(n.value)}catch(a){s={error:a}}finally{try{n&&!n.done&&(r=o.return)&&r.call(o)}finally{if(s)throw s.error}}return i}function D(e,t,r){if(r||arguments.length===2)for(var o=0,n=t.length,i;o1||a(u,d)})})}function a(u,d){try{c(o[u](d))}catch(b){f(i[0][3],b)}}function c(u){u.value instanceof Ze?Promise.resolve(u.value.v).then(p,m):f(i[0][2],u)}function p(u){a("next",u)}function m(u){a("throw",u)}function f(u,d){u(d),i.shift(),i.length&&a(i[0][0],i[0][1])}}function no(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof Ee=="function"?Ee(e):e[Symbol.iterator](),r={},o("next"),o("throw"),o("return"),r[Symbol.asyncIterator]=function(){return this},r);function o(i){r[i]=e[i]&&function(s){return new Promise(function(a,c){s=e[i](s),n(a,c,s.done,s.value)})}}function n(i,s,a,c){Promise.resolve(c).then(function(p){i({value:p,done:a})},s)}}function C(e){return typeof e=="function"}function at(e){var t=function(o){Error.call(o),o.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var It=at(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription:
+`+r.map(function(o,n){return n+1+") "+o.toString()}).join(`
+ `):"",this.name="UnsubscriptionError",this.errors=r}});function De(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Pe=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,o,n,i;if(!this.closed){this.closed=!0;var s=this._parentage;if(s)if(this._parentage=null,Array.isArray(s))try{for(var a=Ee(s),c=a.next();!c.done;c=a.next()){var p=c.value;p.remove(this)}}catch(_){t={error:_}}finally{try{c&&!c.done&&(r=a.return)&&r.call(a)}finally{if(t)throw t.error}}else s.remove(this);var m=this.initialTeardown;if(C(m))try{m()}catch(_){i=_ instanceof It?_.errors:[_]}var f=this._finalizers;if(f){this._finalizers=null;try{for(var u=Ee(f),d=u.next();!d.done;d=u.next()){var b=d.value;try{io(b)}catch(_){i=i!=null?i:[],_ instanceof It?i=D(D([],U(i)),U(_.errors)):i.push(_)}}}catch(_){o={error:_}}finally{try{d&&!d.done&&(n=u.return)&&n.call(u)}finally{if(o)throw o.error}}}if(i)throw new It(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)io(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&De(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&De(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var xr=Pe.EMPTY;function Pt(e){return e instanceof Pe||e&&"closed"in e&&C(e.remove)&&C(e.add)&&C(e.unsubscribe)}function io(e){C(e)?e():e.unsubscribe()}var Le={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var st={setTimeout:function(e,t){for(var r=[],o=2;o0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var o=this,n=this,i=n.hasError,s=n.isStopped,a=n.observers;return i||s?xr:(this.currentObservers=null,a.push(r),new Pe(function(){o.currentObservers=null,De(a,r)}))},t.prototype._checkFinalizedStatuses=function(r){var o=this,n=o.hasError,i=o.thrownError,s=o.isStopped;n?r.error(i):s&&r.complete()},t.prototype.asObservable=function(){var r=new j;return r.source=this,r},t.create=function(r,o){return new uo(r,o)},t}(j);var uo=function(e){ie(t,e);function t(r,o){var n=e.call(this)||this;return n.destination=r,n.source=o,n}return t.prototype.next=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.next)===null||n===void 0||n.call(o,r)},t.prototype.error=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.error)===null||n===void 0||n.call(o,r)},t.prototype.complete=function(){var r,o;(o=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||o===void 0||o.call(r)},t.prototype._subscribe=function(r){var o,n;return(n=(o=this.source)===null||o===void 0?void 0:o.subscribe(r))!==null&&n!==void 0?n:xr},t}(x);var yt={now:function(){return(yt.delegate||Date).now()},delegate:void 0};var Et=function(e){ie(t,e);function t(r,o,n){r===void 0&&(r=1/0),o===void 0&&(o=1/0),n===void 0&&(n=yt);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=o,i._timestampProvider=n,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=o===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,o),i}return t.prototype.next=function(r){var o=this,n=o.isStopped,i=o._buffer,s=o._infiniteTimeWindow,a=o._timestampProvider,c=o._windowTime;n||(i.push(r),!s&&i.push(a.now()+c)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var o=this._innerSubscribe(r),n=this,i=n._infiniteTimeWindow,s=n._buffer,a=s.slice(),c=0;c0?e.prototype.requestAsyncId.call(this,r,o,n):(r.actions.push(this),r._scheduled||(r._scheduled=mt.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,o,n){var i;if(n===void 0&&(n=0),n!=null?n>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,o,n);var s=r.actions;o!=null&&((i=s[s.length-1])===null||i===void 0?void 0:i.id)!==o&&(mt.cancelAnimationFrame(o),r._scheduled=void 0)},t}(Wt);var vo=function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var o=this._scheduled;this._scheduled=void 0;var n=this.actions,i;r=r||n.shift();do if(i=r.execute(r.state,r.delay))break;while((r=n[0])&&r.id===o&&n.shift());if(this._active=!1,i){for(;(r=n[0])&&r.id===o&&n.shift();)r.unsubscribe();throw i}},t}(Ut);var Te=new vo(bo);var T=new j(function(e){return e.complete()});function Nt(e){return e&&C(e.schedule)}function Mr(e){return e[e.length-1]}function Qe(e){return C(Mr(e))?e.pop():void 0}function Oe(e){return Nt(Mr(e))?e.pop():void 0}function Dt(e,t){return typeof Mr(e)=="number"?e.pop():t}var lt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Vt(e){return C(e==null?void 0:e.then)}function zt(e){return C(e[pt])}function qt(e){return Symbol.asyncIterator&&C(e==null?void 0:e[Symbol.asyncIterator])}function Kt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function ki(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var Qt=ki();function Yt(e){return C(e==null?void 0:e[Qt])}function Bt(e){return oo(this,arguments,function(){var r,o,n,i;return Rt(this,function(s){switch(s.label){case 0:r=e.getReader(),s.label=1;case 1:s.trys.push([1,,9,10]),s.label=2;case 2:return[4,Ze(r.read())];case 3:return o=s.sent(),n=o.value,i=o.done,i?[4,Ze(void 0)]:[3,5];case 4:return[2,s.sent()];case 5:return[4,Ze(n)];case 6:return[4,s.sent()];case 7:return s.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function Gt(e){return C(e==null?void 0:e.getReader)}function W(e){if(e instanceof j)return e;if(e!=null){if(zt(e))return Hi(e);if(lt(e))return $i(e);if(Vt(e))return Ri(e);if(qt(e))return go(e);if(Yt(e))return Ii(e);if(Gt(e))return Pi(e)}throw Kt(e)}function Hi(e){return new j(function(t){var r=e[pt]();if(C(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function $i(e){return new j(function(t){for(var r=0;r=2;return function(o){return o.pipe(e?L(function(n,i){return e(n,i,o)}):de,ge(1),r?He(t):Io(function(){return new Xt}))}}function Po(){for(var e=[],t=0;t=2,!0))}function le(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new x}:t,o=e.resetOnError,n=o===void 0?!0:o,i=e.resetOnComplete,s=i===void 0?!0:i,a=e.resetOnRefCountZero,c=a===void 0?!0:a;return function(p){var m,f,u,d=0,b=!1,_=!1,re=function(){f==null||f.unsubscribe(),f=void 0},Z=function(){re(),m=u=void 0,b=_=!1},Y=function(){var A=m;Z(),A==null||A.unsubscribe()};return g(function(A,it){d++,!_&&!b&&re();var Ne=u=u!=null?u:r();it.add(function(){d--,d===0&&!_&&!b&&(f=kr(Y,c))}),Ne.subscribe(it),!m&&d>0&&(m=new tt({next:function(Ie){return Ne.next(Ie)},error:function(Ie){_=!0,re(),f=kr(Z,n,Ie),Ne.error(Ie)},complete:function(){b=!0,re(),f=kr(Z,s),Ne.complete()}}),W(A).subscribe(m))})(p)}}function kr(e,t){for(var r=[],o=2;oe.next(document)),e}function z(e,t=document){return Array.from(t.querySelectorAll(e))}function N(e,t=document){let r=ce(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function ce(e,t=document){return t.querySelector(e)||void 0}function Re(){return document.activeElement instanceof HTMLElement&&document.activeElement||void 0}var ea=M(h(document.body,"focusin"),h(document.body,"focusout")).pipe(ke(1),V(void 0),l(()=>Re()||document.body),B(1));function er(e){return ea.pipe(l(t=>e.contains(t)),G())}function Je(e){return{x:e.offsetLeft,y:e.offsetTop}}function Uo(e){return M(h(window,"load"),h(window,"resize")).pipe(Ae(0,Te),l(()=>Je(e)),V(Je(e)))}function tr(e){return{x:e.scrollLeft,y:e.scrollTop}}function dt(e){return M(h(e,"scroll"),h(window,"resize")).pipe(Ae(0,Te),l(()=>tr(e)),V(tr(e)))}function No(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)No(e,r)}function O(e,t,...r){let o=document.createElement(e);if(t)for(let n of Object.keys(t))typeof t[n]!="undefined"&&(typeof t[n]!="boolean"?o.setAttribute(n,t[n]):o.setAttribute(n,""));for(let n of r)No(o,n);return o}function rr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function ht(e){let t=O("script",{src:e});return $(()=>(document.head.appendChild(t),M(h(t,"load"),h(t,"error").pipe(v(()=>St(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(l(()=>{}),k(()=>document.head.removeChild(t)),ge(1))))}var Do=new x,ta=$(()=>typeof ResizeObserver=="undefined"?ht("https://unpkg.com/resize-observer-polyfill"):H(void 0)).pipe(l(()=>new ResizeObserver(e=>{for(let t of e)Do.next(t)})),v(e=>M(Ve,H(e)).pipe(k(()=>e.disconnect()))),B(1));function he(e){return{width:e.offsetWidth,height:e.offsetHeight}}function xe(e){return ta.pipe(w(t=>t.observe(e)),v(t=>Do.pipe(L(({target:r})=>r===e),k(()=>t.unobserve(e)),l(()=>he(e)))),V(he(e)))}function bt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function or(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}var Vo=new x,ra=$(()=>H(new IntersectionObserver(e=>{for(let t of e)Vo.next(t)},{threshold:0}))).pipe(v(e=>M(Ve,H(e)).pipe(k(()=>e.disconnect()))),B(1));function nr(e){return ra.pipe(w(t=>t.observe(e)),v(t=>Vo.pipe(L(({target:r})=>r===e),k(()=>t.unobserve(e)),l(({isIntersecting:r})=>r))))}function zo(e,t=16){return dt(e).pipe(l(({y:r})=>{let o=he(e),n=bt(e);return r>=n.height-o.height-t}),G())}var ir={drawer:N("[data-md-toggle=drawer]"),search:N("[data-md-toggle=search]")};function qo(e){return ir[e].checked}function Ke(e,t){ir[e].checked!==t&&ir[e].click()}function We(e){let t=ir[e];return h(t,"change").pipe(l(()=>t.checked),V(t.checked))}function oa(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function na(){return M(h(window,"compositionstart").pipe(l(()=>!0)),h(window,"compositionend").pipe(l(()=>!1))).pipe(V(!1))}function Ko(){let e=h(window,"keydown").pipe(L(t=>!(t.metaKey||t.ctrlKey)),l(t=>({mode:qo("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),L(({mode:t,type:r})=>{if(t==="global"){let o=Re();if(typeof o!="undefined")return!oa(o,r)}return!0}),le());return na().pipe(v(t=>t?T:e))}function fe(){return new URL(location.href)}function ot(e){location.href=e.href}function Qo(){return new x}function Yo(){return location.hash.slice(1)}function Pr(e){let t=O("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function ia(e){return M(h(window,"hashchange"),e).pipe(l(Yo),V(Yo()),L(t=>t.length>0),B(1))}function Bo(e){return ia(e).pipe(l(t=>ce(`[id="${t}"]`)),L(t=>typeof t!="undefined"))}function Fr(e){let t=matchMedia(e);return Zt(r=>t.addListener(()=>r(t.matches))).pipe(V(t.matches))}function Go(){let e=matchMedia("print");return M(h(window,"beforeprint").pipe(l(()=>!0)),h(window,"afterprint").pipe(l(()=>!1))).pipe(V(e.matches))}function jr(e,t){return e.pipe(v(r=>r?t():T))}function ar(e,t={credentials:"same-origin"}){return me(fetch(`${e}`,t)).pipe(pe(()=>T),v(r=>r.status!==200?St(()=>new Error(r.statusText)):H(r)))}function Ue(e,t){return ar(e,t).pipe(v(r=>r.json()),B(1))}function Jo(e,t){let r=new DOMParser;return ar(e,t).pipe(v(o=>o.text()),l(o=>r.parseFromString(o,"text/xml")),B(1))}function Xo(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function Zo(){return M(h(window,"scroll",{passive:!0}),h(window,"resize",{passive:!0})).pipe(l(Xo),V(Xo()))}function en(){return{width:innerWidth,height:innerHeight}}function tn(){return h(window,"resize",{passive:!0}).pipe(l(en),V(en()))}function rn(){return Q([Zo(),tn()]).pipe(l(([e,t])=>({offset:e,size:t})),B(1))}function sr(e,{viewport$:t,header$:r}){let o=t.pipe(X("size")),n=Q([o,r]).pipe(l(()=>Je(e)));return Q([r,t,n]).pipe(l(([{height:i},{offset:s,size:a},{x:c,y:p}])=>({offset:{x:s.x-c,y:s.y-p+i},size:a})))}function aa(e){return h(e,"message",t=>t.data)}function sa(e){let t=new x;return t.subscribe(r=>e.postMessage(r)),t}function on(e,t=new Worker(e)){let r=aa(t),o=sa(t),n=new x;n.subscribe(o);let i=o.pipe(J(),ee(!0));return n.pipe(J(),qe(r.pipe(K(i))),le())}var ca=N("#__config"),vt=JSON.parse(ca.textContent);vt.base=`${new URL(vt.base,fe())}`;function ue(){return vt}function te(e){return vt.features.includes(e)}function be(e,t){return typeof t!="undefined"?vt.translations[e].replace("#",t.toString()):vt.translations[e]}function ye(e,t=document){return N(`[data-md-component=${e}]`,t)}function ne(e,t=document){return z(`[data-md-component=${e}]`,t)}function pa(e){let t=N(".md-typeset > :first-child",e);return h(t,"click",{once:!0}).pipe(l(()=>N(".md-typeset",e)),l(r=>({hash:__md_hash(r.innerHTML)})))}function nn(e){if(!te("announce.dismiss")||!e.childElementCount)return T;if(!e.hidden){let t=N(".md-typeset",e);__md_hash(t.innerHTML)===__md_get("__announce")&&(e.hidden=!0)}return $(()=>{let t=new x;return t.subscribe(({hash:r})=>{e.hidden=!0,__md_set("__announce",r)}),pa(e).pipe(w(r=>t.next(r)),k(()=>t.complete()),l(r=>I({ref:e},r)))})}function ma(e,{target$:t}){return t.pipe(l(r=>({hidden:r!==e})))}function an(e,t){let r=new x;return r.subscribe(({hidden:o})=>{e.hidden=o}),ma(e,t).pipe(w(o=>r.next(o)),k(()=>r.complete()),l(o=>I({ref:e},o)))}function la(e,t){let r=$(()=>Q([Uo(e),dt(t)])).pipe(l(([{x:o,y:n},i])=>{let{width:s,height:a}=he(e);return{x:o-i.x+s/2,y:n-i.y+a/2}}));return er(e).pipe(v(o=>r.pipe(l(n=>({active:o,offset:n})),ge(+!o||1/0))))}function sn(e,t,{target$:r}){let[o,n]=Array.from(e.children);return $(()=>{let i=new x,s=i.pipe(J(),ee(!0));return i.subscribe({next({offset:a}){e.style.setProperty("--md-tooltip-x",`${a.x}px`),e.style.setProperty("--md-tooltip-y",`${a.y}px`)},complete(){e.style.removeProperty("--md-tooltip-x"),e.style.removeProperty("--md-tooltip-y")}}),nr(e).pipe(K(s)).subscribe(a=>{e.toggleAttribute("data-md-visible",a)}),M(i.pipe(L(({active:a})=>a)),i.pipe(ke(250),L(({active:a})=>!a))).subscribe({next({active:a}){a?e.prepend(o):o.remove()},complete(){e.prepend(o)}}),i.pipe(Ae(16,Te)).subscribe(({active:a})=>{o.classList.toggle("md-tooltip--active",a)}),i.pipe(Rr(125,Te),L(()=>!!e.offsetParent),l(()=>e.offsetParent.getBoundingClientRect()),l(({x:a})=>a)).subscribe({next(a){a?e.style.setProperty("--md-tooltip-0",`${-a}px`):e.style.removeProperty("--md-tooltip-0")},complete(){e.style.removeProperty("--md-tooltip-0")}}),h(n,"click").pipe(K(s),L(a=>!(a.metaKey||a.ctrlKey))).subscribe(a=>{a.stopPropagation(),a.preventDefault()}),h(n,"mousedown").pipe(K(s),oe(i)).subscribe(([a,{active:c}])=>{var p;if(a.button!==0||a.metaKey||a.ctrlKey)a.preventDefault();else if(c){a.preventDefault();let m=e.parentElement.closest(".md-annotation");m instanceof HTMLElement?m.focus():(p=Re())==null||p.blur()}}),r.pipe(K(s),L(a=>a===o),ze(125)).subscribe(()=>e.focus()),la(e,t).pipe(w(a=>i.next(a)),k(()=>i.complete()),l(a=>I({ref:e},a)))})}function Wr(e){return O("div",{class:"md-tooltip",id:e},O("div",{class:"md-tooltip__inner md-typeset"}))}function cn(e,t){if(t=t?`${t}_annotation_${e}`:void 0,t){let r=t?`#${t}`:void 0;return O("aside",{class:"md-annotation",tabIndex:0},Wr(t),O("a",{href:r,class:"md-annotation__index",tabIndex:-1},O("span",{"data-md-annotation-id":e})))}else return O("aside",{class:"md-annotation",tabIndex:0},Wr(t),O("span",{class:"md-annotation__index",tabIndex:-1},O("span",{"data-md-annotation-id":e})))}function pn(e){return O("button",{class:"md-clipboard md-icon",title:be("clipboard.copy"),"data-clipboard-target":`#${e} > code`})}function Ur(e,t){let r=t&2,o=t&1,n=Object.keys(e.terms).filter(c=>!e.terms[c]).reduce((c,p)=>[...c,O("del",null,p)," "],[]).slice(0,-1),i=ue(),s=new URL(e.location,i.base);te("search.highlight")&&s.searchParams.set("h",Object.entries(e.terms).filter(([,c])=>c).reduce((c,[p])=>`${c} ${p}`.trim(),""));let{tags:a}=ue();return O("a",{href:`${s}`,class:"md-search-result__link",tabIndex:-1},O("article",{class:"md-search-result__article md-typeset","data-md-score":e.score.toFixed(2)},r>0&&O("div",{class:"md-search-result__icon md-icon"}),r>0&&O("h1",null,e.title),r<=0&&O("h2",null,e.title),o>0&&e.text.length>0&&e.text,e.tags&&e.tags.map(c=>{let p=a?c in a?`md-tag-icon md-tag--${a[c]}`:"md-tag-icon":"";return O("span",{class:`md-tag ${p}`},c)}),o>0&&n.length>0&&O("p",{class:"md-search-result__terms"},be("search.result.term.missing"),": ",...n)))}function mn(e){let t=e[0].score,r=[...e],o=ue(),n=r.findIndex(m=>!`${new URL(m.location,o.base)}`.includes("#")),[i]=r.splice(n,1),s=r.findIndex(m=>m.scoreUr(m,1)),...c.length?[O("details",{class:"md-search-result__more"},O("summary",{tabIndex:-1},O("div",null,c.length>0&&c.length===1?be("search.result.more.one"):be("search.result.more.other",c.length))),...c.map(m=>Ur(m,1)))]:[]];return O("li",{class:"md-search-result__item"},p)}function ln(e){return O("ul",{class:"md-source__facts"},Object.entries(e).map(([t,r])=>O("li",{class:`md-source__fact md-source__fact--${t}`},typeof r=="number"?rr(r):r)))}function Nr(e){let t=`tabbed-control tabbed-control--${e}`;return O("div",{class:t,hidden:!0},O("button",{class:"tabbed-button",tabIndex:-1,"aria-hidden":"true"}))}function fn(e){return O("div",{class:"md-typeset__scrollwrap"},O("div",{class:"md-typeset__table"},e))}function fa(e){let t=ue(),r=new URL(`../${e.version}/`,t.base);return O("li",{class:"md-version__item"},O("a",{href:`${r}`,class:"md-version__link"},e.title))}function un(e,t){return O("div",{class:"md-version"},O("button",{class:"md-version__current","aria-label":be("select.version")},t.title),O("ul",{class:"md-version__list"},e.map(fa)))}function ua(e){return e.tagName==="CODE"?z(".c, .c1, .cm",e):[e]}function da(e){let t=[];for(let r of ua(e)){let o=[],n=document.createNodeIterator(r,NodeFilter.SHOW_TEXT);for(let i=n.nextNode();i;i=n.nextNode())o.push(i);for(let i of o){let s;for(;s=/(\(\d+\))(!)?/.exec(i.textContent);){let[,a,c]=s;if(typeof c=="undefined"){let p=i.splitText(s.index);i=p.splitText(a.length),t.push(p)}else{i.textContent=a,t.push(i);break}}}}return t}function dn(e,t){t.append(...Array.from(e.childNodes))}function cr(e,t,{target$:r,print$:o}){let n=t.closest("[id]"),i=n==null?void 0:n.id,s=new Map;for(let a of da(t)){let[,c]=a.textContent.match(/\((\d+)\)/);ce(`:scope > li:nth-child(${c})`,e)&&(s.set(c,cn(c,i)),a.replaceWith(s.get(c)))}return s.size===0?T:$(()=>{let a=new x,c=a.pipe(J(),ee(!0)),p=[];for(let[m,f]of s)p.push([N(".md-typeset",f),N(`:scope > li:nth-child(${m})`,e)]);return o.pipe(K(c)).subscribe(m=>{e.hidden=!m,e.classList.toggle("md-annotation-list",m);for(let[f,u]of p)m?dn(f,u):dn(u,f)}),M(...[...s].map(([,m])=>sn(m,t,{target$:r}))).pipe(k(()=>a.complete()),le())})}function hn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return hn(t)}}function bn(e,t){return $(()=>{let r=hn(e);return typeof r!="undefined"?cr(r,e,t):T})}var gn=$t(Vr());var ha=0;function xn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return xn(t)}}function vn(e){return xe(e).pipe(l(({width:t})=>({scrollable:bt(e).width>t})),X("scrollable"))}function yn(e,t){let{matches:r}=matchMedia("(hover)"),o=$(()=>{let n=new x;if(n.subscribe(({scrollable:s})=>{s&&r?e.setAttribute("tabindex","0"):e.removeAttribute("tabindex")}),gn.default.isSupported()&&(e.closest(".copy")||te("content.code.copy")&&!e.closest(".no-copy"))){let s=e.closest("pre");s.id=`__code_${ha++}`,s.insertBefore(pn(s.id),e)}let i=e.closest(".highlight");if(i instanceof HTMLElement){let s=xn(i);if(typeof s!="undefined"&&(i.classList.contains("annotate")||te("content.code.annotate"))){let a=cr(s,e,t);return vn(e).pipe(w(c=>n.next(c)),k(()=>n.complete()),l(c=>I({ref:e},c)),qe(xe(i).pipe(l(({width:c,height:p})=>c&&p),G(),v(c=>c?a:T))))}}return vn(e).pipe(w(s=>n.next(s)),k(()=>n.complete()),l(s=>I({ref:e},s)))});return te("content.lazy")?nr(e).pipe(L(n=>n),ge(1),v(()=>o)):o}function ba(e,{target$:t,print$:r}){let o=!0;return M(t.pipe(l(n=>n.closest("details:not([open])")),L(n=>e===n),l(()=>({action:"open",reveal:!0}))),r.pipe(L(n=>n||!o),w(()=>o=e.open),l(n=>({action:n?"open":"close"}))))}function En(e,t){return $(()=>{let r=new x;return r.subscribe(({action:o,reveal:n})=>{e.toggleAttribute("open",o==="open"),n&&e.scrollIntoView()}),ba(e,t).pipe(w(o=>r.next(o)),k(()=>r.complete()),l(o=>I({ref:e},o)))})}var wn=".node circle,.node ellipse,.node path,.node polygon,.node rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}marker{fill:var(--md-mermaid-edge-color)!important}.edgeLabel .label rect{fill:#0000}.label{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.label foreignObject{line-height:normal;overflow:visible}.label div .edgeLabel{color:var(--md-mermaid-label-fg-color)}.edgeLabel,.edgeLabel rect,.label div .edgeLabel{background-color:var(--md-mermaid-label-bg-color)}.edgeLabel,.edgeLabel rect{fill:var(--md-mermaid-label-bg-color);color:var(--md-mermaid-edge-color)}.edgePath .path,.flowchart-link{stroke:var(--md-mermaid-edge-color);stroke-width:.05rem}.edgePath .arrowheadPath{fill:var(--md-mermaid-edge-color);stroke:none}.cluster rect{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}.cluster span{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}g #flowchart-circleEnd,g #flowchart-circleStart,g #flowchart-crossEnd,g #flowchart-crossStart,g #flowchart-pointEnd,g #flowchart-pointStart{stroke:none}g.classGroup line,g.classGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.classGroup text{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.classLabel .box{fill:var(--md-mermaid-label-bg-color);background-color:var(--md-mermaid-label-bg-color);opacity:1}.classLabel .label{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node .divider{stroke:var(--md-mermaid-node-fg-color)}.relation{stroke:var(--md-mermaid-edge-color)}.cardinality{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.cardinality text{fill:inherit!important}defs #classDiagram-compositionEnd,defs #classDiagram-compositionStart,defs #classDiagram-dependencyEnd,defs #classDiagram-dependencyStart,defs #classDiagram-extensionEnd,defs #classDiagram-extensionStart{fill:var(--md-mermaid-edge-color)!important;stroke:var(--md-mermaid-edge-color)!important}defs #classDiagram-aggregationEnd,defs #classDiagram-aggregationStart{fill:var(--md-mermaid-label-bg-color)!important;stroke:var(--md-mermaid-edge-color)!important}g.stateGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.stateGroup .state-title{fill:var(--md-mermaid-label-fg-color)!important;font-family:var(--md-mermaid-font-family)}g.stateGroup .composit{fill:var(--md-mermaid-label-bg-color)}.nodeLabel{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node circle.state-end,.node circle.state-start,.start-state{fill:var(--md-mermaid-edge-color);stroke:none}.end-state-inner,.end-state-outer{fill:var(--md-mermaid-edge-color)}.end-state-inner,.node circle.state-end{stroke:var(--md-mermaid-label-bg-color)}.transition{stroke:var(--md-mermaid-edge-color)}[id^=state-fork] rect,[id^=state-join] rect{fill:var(--md-mermaid-edge-color)!important;stroke:none!important}.statediagram-cluster.statediagram-cluster .inner{fill:var(--md-default-bg-color)}.statediagram-cluster rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.statediagram-state rect.divider{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}defs #statediagram-barbEnd{stroke:var(--md-mermaid-edge-color)}.attributeBoxEven,.attributeBoxOdd{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityBox{fill:var(--md-mermaid-label-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityLabel{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.relationshipLabelBox{fill:var(--md-mermaid-label-bg-color);fill-opacity:1;background-color:var(--md-mermaid-label-bg-color);opacity:1}.relationshipLabel{fill:var(--md-mermaid-label-fg-color)}.relationshipLine{stroke:var(--md-mermaid-edge-color)}defs #ONE_OR_MORE_END *,defs #ONE_OR_MORE_START *,defs #ONLY_ONE_END *,defs #ONLY_ONE_START *,defs #ZERO_OR_MORE_END *,defs #ZERO_OR_MORE_START *,defs #ZERO_OR_ONE_END *,defs #ZERO_OR_ONE_START *{stroke:var(--md-mermaid-edge-color)!important}defs #ZERO_OR_MORE_END circle,defs #ZERO_OR_MORE_START circle{fill:var(--md-mermaid-label-bg-color)}.actor{fill:var(--md-mermaid-sequence-actor-bg-color);stroke:var(--md-mermaid-sequence-actor-border-color)}text.actor>tspan{fill:var(--md-mermaid-sequence-actor-fg-color);font-family:var(--md-mermaid-font-family)}line{stroke:var(--md-mermaid-sequence-actor-line-color)}.actor-man circle,.actor-man line{fill:var(--md-mermaid-sequence-actorman-bg-color);stroke:var(--md-mermaid-sequence-actorman-line-color)}.messageLine0,.messageLine1{stroke:var(--md-mermaid-sequence-message-line-color)}.note{fill:var(--md-mermaid-sequence-note-bg-color);stroke:var(--md-mermaid-sequence-note-border-color)}.loopText,.loopText>tspan,.messageText,.noteText>tspan{stroke:none;font-family:var(--md-mermaid-font-family)!important}.messageText{fill:var(--md-mermaid-sequence-message-fg-color)}.loopText,.loopText>tspan{fill:var(--md-mermaid-sequence-loop-fg-color)}.noteText>tspan{fill:var(--md-mermaid-sequence-note-fg-color)}#arrowhead path{fill:var(--md-mermaid-sequence-message-line-color);stroke:none}.loopLine{fill:var(--md-mermaid-sequence-loop-bg-color);stroke:var(--md-mermaid-sequence-loop-border-color)}.labelBox{fill:var(--md-mermaid-sequence-label-bg-color);stroke:none}.labelText,.labelText>span{fill:var(--md-mermaid-sequence-label-fg-color);font-family:var(--md-mermaid-font-family)}.sequenceNumber{fill:var(--md-mermaid-sequence-number-fg-color)}rect.rect{fill:var(--md-mermaid-sequence-box-bg-color);stroke:none}rect.rect+text.text{fill:var(--md-mermaid-sequence-box-fg-color)}defs #sequencenumber{fill:var(--md-mermaid-sequence-number-bg-color)!important}";var zr,ga=0;function xa(){return typeof mermaid=="undefined"||mermaid instanceof Element?ht("https://unpkg.com/mermaid@9.4.3/dist/mermaid.min.js"):H(void 0)}function Sn(e){return e.classList.remove("mermaid"),zr||(zr=xa().pipe(w(()=>mermaid.initialize({startOnLoad:!1,themeCSS:wn,sequence:{actorFontSize:"16px",messageFontSize:"16px",noteFontSize:"16px"}})),l(()=>{}),B(1))),zr.subscribe(()=>{e.classList.add("mermaid");let t=`__mermaid_${ga++}`,r=O("div",{class:"mermaid"}),o=e.textContent;mermaid.mermaidAPI.render(t,o,(n,i)=>{let s=r.attachShadow({mode:"closed"});s.innerHTML=n,e.replaceWith(r),i==null||i(s)})}),zr.pipe(l(()=>({ref:e})))}var Tn=O("table");function On(e){return e.replaceWith(Tn),Tn.replaceWith(fn(e)),H({ref:e})}function ya(e){let t=z(":scope > input",e),r=t.find(o=>o.checked)||t[0];return M(...t.map(o=>h(o,"change").pipe(l(()=>N(`label[for="${o.id}"]`))))).pipe(V(N(`label[for="${r.id}"]`)),l(o=>({active:o})))}function Mn(e,{viewport$:t}){let r=Nr("prev");e.append(r);let o=Nr("next");e.append(o);let n=N(".tabbed-labels",e);return $(()=>{let i=new x,s=i.pipe(J(),ee(!0));return Q([i,xe(e)]).pipe(Ae(1,Te),K(s)).subscribe({next([{active:a},c]){let p=Je(a),{width:m}=he(a);e.style.setProperty("--md-indicator-x",`${p.x}px`),e.style.setProperty("--md-indicator-width",`${m}px`);let f=tr(n);(p.xf.x+c.width)&&n.scrollTo({left:Math.max(0,p.x-16),behavior:"smooth"})},complete(){e.style.removeProperty("--md-indicator-x"),e.style.removeProperty("--md-indicator-width")}}),Q([dt(n),xe(n)]).pipe(K(s)).subscribe(([a,c])=>{let p=bt(n);r.hidden=a.x<16,o.hidden=a.x>p.width-c.width-16}),M(h(r,"click").pipe(l(()=>-1)),h(o,"click").pipe(l(()=>1))).pipe(K(s)).subscribe(a=>{let{width:c}=he(n);n.scrollBy({left:c*a,behavior:"smooth"})}),te("content.tabs.link")&&i.pipe(je(1),oe(t)).subscribe(([{active:a},{offset:c}])=>{let p=a.innerText.trim();if(a.hasAttribute("data-md-switching"))a.removeAttribute("data-md-switching");else{let m=e.offsetTop-c.y;for(let u of z("[data-tabs]"))for(let d of z(":scope > input",u)){let b=N(`label[for="${d.id}"]`);if(b!==a&&b.innerText.trim()===p){b.setAttribute("data-md-switching",""),d.click();break}}window.scrollTo({top:e.offsetTop-m});let f=__md_get("__tabs")||[];__md_set("__tabs",[...new Set([p,...f])])}}),i.pipe(K(s)).subscribe(()=>{for(let a of z("audio, video",e))a.pause()}),ya(e).pipe(w(a=>i.next(a)),k(()=>i.complete()),l(a=>I({ref:e},a)))}).pipe(rt(ae))}function Ln(e,{viewport$:t,target$:r,print$:o}){return M(...z(".annotate:not(.highlight)",e).map(n=>bn(n,{target$:r,print$:o})),...z("pre:not(.mermaid) > code",e).map(n=>yn(n,{target$:r,print$:o})),...z("pre.mermaid",e).map(n=>Sn(n)),...z("table:not([class])",e).map(n=>On(n)),...z("details",e).map(n=>En(n,{target$:r,print$:o})),...z("[data-tabs]",e).map(n=>Mn(n,{viewport$:t})))}function Ea(e,{alert$:t}){return t.pipe(v(r=>M(H(!0),H(!1).pipe(ze(2e3))).pipe(l(o=>({message:r,active:o})))))}function _n(e,t){let r=N(".md-typeset",e);return $(()=>{let o=new x;return o.subscribe(({message:n,active:i})=>{e.classList.toggle("md-dialog--active",i),r.textContent=n}),Ea(e,t).pipe(w(n=>o.next(n)),k(()=>o.complete()),l(n=>I({ref:e},n)))})}function wa({viewport$:e}){if(!te("header.autohide"))return H(!1);let t=e.pipe(l(({offset:{y:n}})=>n),Ce(2,1),l(([n,i])=>[nMath.abs(i-n.y)>100),l(([,[n]])=>n),G()),o=We("search");return Q([e,o]).pipe(l(([{offset:n},i])=>n.y>400&&!i),G(),v(n=>n?r:H(!1)),V(!1))}function An(e,t){return $(()=>Q([xe(e),wa(t)])).pipe(l(([{height:r},o])=>({height:r,hidden:o})),G((r,o)=>r.height===o.height&&r.hidden===o.hidden),B(1))}function Cn(e,{header$:t,main$:r}){return $(()=>{let o=new x,n=o.pipe(J(),ee(!0));return o.pipe(X("active"),Ge(t)).subscribe(([{active:i},{hidden:s}])=>{e.classList.toggle("md-header--shadow",i&&!s),e.hidden=s}),r.subscribe(o),t.pipe(K(n),l(i=>I({ref:e},i)))})}function Sa(e,{viewport$:t,header$:r}){return sr(e,{viewport$:t,header$:r}).pipe(l(({offset:{y:o}})=>{let{height:n}=he(e);return{active:o>=n}}),X("active"))}function kn(e,t){return $(()=>{let r=new x;r.subscribe({next({active:n}){e.classList.toggle("md-header__title--active",n)},complete(){e.classList.remove("md-header__title--active")}});let o=ce(".md-content h1");return typeof o=="undefined"?T:Sa(o,t).pipe(w(n=>r.next(n)),k(()=>r.complete()),l(n=>I({ref:e},n)))})}function Hn(e,{viewport$:t,header$:r}){let o=r.pipe(l(({height:i})=>i),G()),n=o.pipe(v(()=>xe(e).pipe(l(({height:i})=>({top:e.offsetTop,bottom:e.offsetTop+i})),X("bottom"))));return Q([o,n,t]).pipe(l(([i,{top:s,bottom:a},{offset:{y:c},size:{height:p}}])=>(p=Math.max(0,p-Math.max(0,s-c,i)-Math.max(0,p+c-a)),{offset:s-i,height:p,active:s-i<=c})),G((i,s)=>i.offset===s.offset&&i.height===s.height&&i.active===s.active))}function Ta(e){let t=__md_get("__palette")||{index:e.findIndex(r=>matchMedia(r.getAttribute("data-md-color-media")).matches)};return H(...e).pipe(se(r=>h(r,"change").pipe(l(()=>r))),V(e[Math.max(0,t.index)]),l(r=>({index:e.indexOf(r),color:{scheme:r.getAttribute("data-md-color-scheme"),primary:r.getAttribute("data-md-color-primary"),accent:r.getAttribute("data-md-color-accent")}})),B(1))}function $n(e){let t=O("meta",{name:"theme-color"});document.head.appendChild(t);let r=O("meta",{name:"color-scheme"});return document.head.appendChild(r),$(()=>{let o=new x;o.subscribe(i=>{document.body.setAttribute("data-md-color-switching","");for(let[s,a]of Object.entries(i.color))document.body.setAttribute(`data-md-color-${s}`,a);for(let s=0;s{let i=ye("header"),s=window.getComputedStyle(i);return r.content=s.colorScheme,s.backgroundColor.match(/\d+/g).map(a=>(+a).toString(16).padStart(2,"0")).join("")})).subscribe(i=>t.content=`#${i}`),o.pipe(_e(ae)).subscribe(()=>{document.body.removeAttribute("data-md-color-switching")});let n=z("input",e);return Ta(n).pipe(w(i=>o.next(i)),k(()=>o.complete()),l(i=>I({ref:e},i)))})}var qr=$t(Vr());function Oa(e){e.setAttribute("data-md-copying","");let t=e.innerText;return e.removeAttribute("data-md-copying"),t}function Rn({alert$:e}){qr.default.isSupported()&&new j(t=>{new qr.default("[data-clipboard-target], [data-clipboard-text]",{text:r=>r.getAttribute("data-clipboard-text")||Oa(N(r.getAttribute("data-clipboard-target")))}).on("success",r=>t.next(r))}).pipe(w(t=>{t.trigger.focus()}),l(()=>be("clipboard.copied"))).subscribe(e)}function Ma(e){if(e.length<2)return[""];let[t,r]=[...e].sort((n,i)=>n.length-i.length).map(n=>n.replace(/[^/]+$/,"")),o=0;if(t===r)o=t.length;else for(;t.charCodeAt(o)===r.charCodeAt(o);)o++;return e.map(n=>n.replace(t.slice(0,o),""))}function pr(e){let t=__md_get("__sitemap",sessionStorage,e);if(t)return H(t);{let r=ue();return Jo(new URL("sitemap.xml",e||r.base)).pipe(l(o=>Ma(z("loc",o).map(n=>n.textContent))),pe(()=>T),He([]),w(o=>__md_set("__sitemap",o,sessionStorage,e)))}}function In({location$:e,viewport$:t}){let r=ue();if(location.protocol==="file:")return T;let o=pr().pipe(l(p=>p.map(m=>`${new URL(m,r.base)}`))),n=h(document.body,"click").pipe(oe(o),v(([p,m])=>{if(!(p.target instanceof Element))return T;let f=p.target.closest("a");if(f===null)return T;if(f.target||p.metaKey||p.ctrlKey)return T;let u=new URL(f.href);return u.search=u.hash="",m.includes(`${u}`)?(p.preventDefault(),H(new URL(f.href))):T}),le());n.pipe(ge(1)).subscribe(()=>{let p=ce("link[rel=icon]");typeof p!="undefined"&&(p.href=p.href)}),h(window,"beforeunload").subscribe(()=>{history.scrollRestoration="auto"}),n.pipe(oe(t)).subscribe(([p,{offset:m}])=>{history.scrollRestoration="manual",history.replaceState(m,""),history.pushState(null,"",p)}),n.subscribe(e);let i=e.pipe(V(fe()),X("pathname"),je(1),v(p=>ar(p).pipe(pe(()=>(ot(p),T))))),s=new DOMParser,a=i.pipe(v(p=>p.text()),v(p=>{let m=s.parseFromString(p,"text/html");for(let u of["title","link[rel=canonical]","meta[name=author]","meta[name=description]","[data-md-component=announce]","[data-md-component=container]","[data-md-component=header-topic]","[data-md-component=outdated]","[data-md-component=logo]","[data-md-component=skip]",...te("navigation.tabs.sticky")?["[data-md-component=tabs]"]:[]]){let d=ce(u),b=ce(u,m);typeof d!="undefined"&&typeof b!="undefined"&&d.replaceWith(b)}let f=ye("container");return Fe(z("script",f)).pipe(v(u=>{let d=m.createElement("script");if(u.src){for(let b of u.getAttributeNames())d.setAttribute(b,u.getAttribute(b));return u.replaceWith(d),new j(b=>{d.onload=()=>b.complete()})}else return d.textContent=u.textContent,u.replaceWith(d),T}),J(),ee(m))}),le());return h(window,"popstate").pipe(l(fe)).subscribe(e),e.pipe(V(fe()),Ce(2,1),v(([p,m])=>p.pathname===m.pathname&&p.hash!==m.hash?H(m):T)).subscribe(p=>{var m,f;history.state!==null||!p.hash?window.scrollTo(0,(f=(m=history.state)==null?void 0:m.y)!=null?f:0):(history.scrollRestoration="auto",Pr(p.hash),history.scrollRestoration="manual")}),a.pipe(oe(e)).subscribe(([,p])=>{var m,f;history.state!==null||!p.hash?window.scrollTo(0,(f=(m=history.state)==null?void 0:m.y)!=null?f:0):Pr(p.hash)}),a.pipe(v(()=>t),X("offset"),ke(100)).subscribe(({offset:p})=>{history.replaceState(p,"")}),a}var jn=$t(Fn());function Wn(e){let t=e.separator.split("|").map(n=>n.replace(/(\(\?[!=<][^)]+\))/g,"").length===0?"\uFFFD":n).join("|"),r=new RegExp(t,"img"),o=(n,i,s)=>`${i}${s} `;return n=>{n=n.replace(/[\s*+\-:~^]+/g," ").trim();let i=new RegExp(`(^|${e.separator}|)(${n.replace(/[|\\{}()[\]^$+*?.-]/g,"\\$&").replace(r,"|")})`,"img");return s=>(0,jn.default)(s).replace(i,o).replace(/<\/mark>(\s+)]*>/img,"$1")}}function Lt(e){return e.type===1}function mr(e){return e.type===3}function Un(e,t){let r=on(e);return M(H(location.protocol!=="file:"),We("search")).pipe($e(o=>o),v(()=>t)).subscribe(({config:o,docs:n})=>r.next({type:0,data:{config:o,docs:n,options:{suggest:te("search.suggest")}}})),r}function Nn({document$:e}){let t=ue(),r=Ue(new URL("../versions.json",t.base)).pipe(pe(()=>T)),o=r.pipe(l(n=>{let[,i]=t.base.match(/([^/]+)\/?$/);return n.find(({version:s,aliases:a})=>s===i||a.includes(i))||n[0]}));r.pipe(l(n=>new Map(n.map(i=>[`${new URL(`../${i.version}/`,t.base)}`,i]))),v(n=>h(document.body,"click").pipe(L(i=>!i.metaKey&&!i.ctrlKey),oe(o),v(([i,s])=>{if(i.target instanceof Element){let a=i.target.closest("a");if(a&&!a.target&&n.has(a.href)){let c=a.href;return!i.target.closest(".md-version")&&n.get(c)===s?T:(i.preventDefault(),H(c))}}return T}),v(i=>{let{version:s}=n.get(i);return pr(new URL(i)).pipe(l(a=>{let p=fe().href.replace(t.base,"");return a.includes(p.split("#")[0])?new URL(`../${s}/${p}`,t.base):new URL(i)}))})))).subscribe(n=>ot(n)),Q([r,o]).subscribe(([n,i])=>{N(".md-header__topic").appendChild(un(n,i))}),e.pipe(v(()=>o)).subscribe(n=>{var s;let i=__md_get("__outdated",sessionStorage);if(i===null){i=!0;let a=((s=t.version)==null?void 0:s.default)||"latest";Array.isArray(a)||(a=[a]);e:for(let c of a)for(let p of n.aliases)if(new RegExp(c,"i").test(p)){i=!1;break e}__md_set("__outdated",i,sessionStorage)}if(i)for(let a of ne("outdated"))a.hidden=!1})}function ka(e,{worker$:t}){let{searchParams:r}=fe();r.has("q")&&(Ke("search",!0),e.value=r.get("q"),e.focus(),We("search").pipe($e(i=>!i)).subscribe(()=>{let i=new URL(location.href);i.searchParams.delete("q"),history.replaceState({},"",`${i}`)}));let o=er(e),n=M(t.pipe($e(Lt)),h(e,"keyup"),o).pipe(l(()=>e.value),G());return Q([n,o]).pipe(l(([i,s])=>({value:i,focus:s})),B(1))}function Dn(e,{worker$:t}){let r=new x,o=r.pipe(J(),ee(!0));Q([t.pipe($e(Lt)),r],(i,s)=>s).pipe(X("value")).subscribe(({value:i})=>t.next({type:2,data:i})),r.pipe(X("focus")).subscribe(({focus:i})=>{i&&Ke("search",i)}),h(e.form,"reset").pipe(K(o)).subscribe(()=>e.focus());let n=N("header [for=__search]");return h(n,"click").subscribe(()=>e.focus()),ka(e,{worker$:t}).pipe(w(i=>r.next(i)),k(()=>r.complete()),l(i=>I({ref:e},i)),B(1))}function Vn(e,{worker$:t,query$:r}){let o=new x,n=zo(e.parentElement).pipe(L(Boolean)),i=e.parentElement,s=N(":scope > :first-child",e),a=N(":scope > :last-child",e);We("search").subscribe(m=>a.setAttribute("role",m?"list":"presentation")),o.pipe(oe(r),Hr(t.pipe($e(Lt)))).subscribe(([{items:m},{value:f}])=>{switch(m.length){case 0:s.textContent=f.length?be("search.result.none"):be("search.result.placeholder");break;case 1:s.textContent=be("search.result.one");break;default:let u=rr(m.length);s.textContent=be("search.result.other",u)}});let c=o.pipe(w(()=>a.innerHTML=""),v(({items:m})=>M(H(...m.slice(0,10)),H(...m.slice(10)).pipe(Ce(4),Ir(n),v(([f])=>f)))),l(mn),le());return c.subscribe(m=>a.appendChild(m)),c.pipe(se(m=>{let f=ce("details",m);return typeof f=="undefined"?T:h(f,"toggle").pipe(K(o),l(()=>f))})).subscribe(m=>{m.open===!1&&m.offsetTop<=i.scrollTop&&i.scrollTo({top:m.offsetTop})}),t.pipe(L(mr),l(({data:m})=>m)).pipe(w(m=>o.next(m)),k(()=>o.complete()),l(m=>I({ref:e},m)))}function Ha(e,{query$:t}){return t.pipe(l(({value:r})=>{let o=fe();return o.hash="",r=r.replace(/\s+/g,"+").replace(/&/g,"%26").replace(/=/g,"%3D"),o.search=`q=${r}`,{url:o}}))}function zn(e,t){let r=new x,o=r.pipe(J(),ee(!0));return r.subscribe(({url:n})=>{e.setAttribute("data-clipboard-text",e.href),e.href=`${n}`}),h(e,"click").pipe(K(o)).subscribe(n=>n.preventDefault()),Ha(e,t).pipe(w(n=>r.next(n)),k(()=>r.complete()),l(n=>I({ref:e},n)))}function qn(e,{worker$:t,keyboard$:r}){let o=new x,n=ye("search-query"),i=M(h(n,"keydown"),h(n,"focus")).pipe(_e(ae),l(()=>n.value),G());return o.pipe(Ge(i),l(([{suggest:a},c])=>{let p=c.split(/([\s-]+)/);if(a!=null&&a.length&&p[p.length-1]){let m=a[a.length-1];m.startsWith(p[p.length-1])&&(p[p.length-1]=m)}else p.length=0;return p})).subscribe(a=>e.innerHTML=a.join("").replace(/\s/g," ")),r.pipe(L(({mode:a})=>a==="search")).subscribe(a=>{switch(a.type){case"ArrowRight":e.innerText.length&&n.selectionStart===n.value.length&&(n.value=e.innerText);break}}),t.pipe(L(mr),l(({data:a})=>a)).pipe(w(a=>o.next(a)),k(()=>o.complete()),l(()=>({ref:e})))}function Kn(e,{index$:t,keyboard$:r}){let o=ue();try{let n=Un(o.search,t),i=ye("search-query",e),s=ye("search-result",e);h(e,"click").pipe(L(({target:c})=>c instanceof Element&&!!c.closest("a"))).subscribe(()=>Ke("search",!1)),r.pipe(L(({mode:c})=>c==="search")).subscribe(c=>{let p=Re();switch(c.type){case"Enter":if(p===i){let m=new Map;for(let f of z(":first-child [href]",s)){let u=f.firstElementChild;m.set(f,parseFloat(u.getAttribute("data-md-score")))}if(m.size){let[[f]]=[...m].sort(([,u],[,d])=>d-u);f.click()}c.claim()}break;case"Escape":case"Tab":Ke("search",!1),i.blur();break;case"ArrowUp":case"ArrowDown":if(typeof p=="undefined")i.focus();else{let m=[i,...z(":not(details) > [href], summary, details[open] [href]",s)],f=Math.max(0,(Math.max(0,m.indexOf(p))+m.length+(c.type==="ArrowUp"?-1:1))%m.length);m[f].focus()}c.claim();break;default:i!==Re()&&i.focus()}}),r.pipe(L(({mode:c})=>c==="global")).subscribe(c=>{switch(c.type){case"f":case"s":case"/":i.focus(),i.select(),c.claim();break}});let a=Dn(i,{worker$:n});return M(a,Vn(s,{worker$:n,query$:a})).pipe(qe(...ne("search-share",e).map(c=>zn(c,{query$:a})),...ne("search-suggest",e).map(c=>qn(c,{worker$:n,keyboard$:r}))))}catch(n){return e.hidden=!0,Ve}}function Qn(e,{index$:t,location$:r}){return Q([t,r.pipe(V(fe()),L(o=>!!o.searchParams.get("h")))]).pipe(l(([o,n])=>Wn(o.config)(n.searchParams.get("h"))),l(o=>{var s;let n=new Map,i=document.createNodeIterator(e,NodeFilter.SHOW_TEXT);for(let a=i.nextNode();a;a=i.nextNode())if((s=a.parentElement)!=null&&s.offsetHeight){let c=a.textContent,p=o(c);p.length>c.length&&n.set(a,p)}for(let[a,c]of n){let{childNodes:p}=O("span",null,c);a.replaceWith(...Array.from(p))}return{ref:e,nodes:n}}))}function $a(e,{viewport$:t,main$:r}){let o=e.closest(".md-grid"),n=o.offsetTop-o.parentElement.offsetTop;return Q([r,t]).pipe(l(([{offset:i,height:s},{offset:{y:a}}])=>(s=s+Math.min(n,Math.max(0,a-i))-n,{height:s,locked:a>=i+n})),G((i,s)=>i.height===s.height&&i.locked===s.locked))}function Kr(e,o){var n=o,{header$:t}=n,r=Zr(n,["header$"]);let i=N(".md-sidebar__scrollwrap",e),{y:s}=Je(i);return $(()=>{let a=new x,c=a.pipe(J(),ee(!0)),p=a.pipe(Ae(0,Te));return p.pipe(oe(t)).subscribe({next([{height:m},{height:f}]){i.style.height=`${m-2*s}px`,e.style.top=`${f}px`},complete(){i.style.height="",e.style.top=""}}),p.pipe($e()).subscribe(()=>{for(let m of z(".md-nav__link--active[href]",e)){let f=or(m);if(typeof f!="undefined"){let u=m.offsetTop-f.offsetTop,{height:d}=he(f);f.scrollTo({top:u-d/2})}}}),me(z("label[tabindex]",e)).pipe(se(m=>h(m,"click").pipe(l(()=>m),K(c)))).subscribe(m=>{let f=N(`[id="${m.htmlFor}"]`);N(`[aria-labelledby="${m.id}"]`).setAttribute("aria-expanded",`${f.checked}`)}),$a(e,r).pipe(w(m=>a.next(m)),k(()=>a.complete()),l(m=>I({ref:e},m)))})}function Yn(e,t){if(typeof t!="undefined"){let r=`https://api.github.com/repos/${e}/${t}`;return Tt(Ue(`${r}/releases/latest`).pipe(pe(()=>T),l(o=>({version:o.tag_name})),He({})),Ue(r).pipe(pe(()=>T),l(o=>({stars:o.stargazers_count,forks:o.forks_count})),He({}))).pipe(l(([o,n])=>I(I({},o),n)))}else{let r=`https://api.github.com/users/${e}`;return Ue(r).pipe(l(o=>({repositories:o.public_repos})),He({}))}}function Bn(e,t){let r=`https://${e}/api/v4/projects/${encodeURIComponent(t)}`;return Ue(r).pipe(pe(()=>T),l(({star_count:o,forks_count:n})=>({stars:o,forks:n})),He({}))}function Gn(e){let t=e.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i);if(t){let[,r,o]=t;return Yn(r,o)}if(t=e.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i),t){let[,r,o]=t;return Bn(r,o)}return T}var Ra;function Ia(e){return Ra||(Ra=$(()=>{let t=__md_get("__source",sessionStorage);if(t)return H(t);if(ne("consent").length){let o=__md_get("__consent");if(!(o&&o.github))return T}return Gn(e.href).pipe(w(o=>__md_set("__source",o,sessionStorage)))}).pipe(pe(()=>T),L(t=>Object.keys(t).length>0),l(t=>({facts:t})),B(1)))}function Jn(e){let t=N(":scope > :last-child",e);return $(()=>{let r=new x;return r.subscribe(({facts:o})=>{t.appendChild(ln(o)),t.classList.add("md-source__repository--active")}),Ia(e).pipe(w(o=>r.next(o)),k(()=>r.complete()),l(o=>I({ref:e},o)))})}function Pa(e,{viewport$:t,header$:r}){return xe(document.body).pipe(v(()=>sr(e,{header$:r,viewport$:t})),l(({offset:{y:o}})=>({hidden:o>=10})),X("hidden"))}function Xn(e,t){return $(()=>{let r=new x;return r.subscribe({next({hidden:o}){e.hidden=o},complete(){e.hidden=!1}}),(te("navigation.tabs.sticky")?H({hidden:!1}):Pa(e,t)).pipe(w(o=>r.next(o)),k(()=>r.complete()),l(o=>I({ref:e},o)))})}function Fa(e,{viewport$:t,header$:r}){let o=new Map,n=z("[href^=\\#]",e);for(let a of n){let c=decodeURIComponent(a.hash.substring(1)),p=ce(`[id="${c}"]`);typeof p!="undefined"&&o.set(a,p)}let i=r.pipe(X("height"),l(({height:a})=>{let c=ye("main"),p=N(":scope > :first-child",c);return a+.8*(p.offsetTop-c.offsetTop)}),le());return xe(document.body).pipe(X("height"),v(a=>$(()=>{let c=[];return H([...o].reduce((p,[m,f])=>{for(;c.length&&o.get(c[c.length-1]).tagName>=f.tagName;)c.pop();let u=f.offsetTop;for(;!u&&f.parentElement;)f=f.parentElement,u=f.offsetTop;let d=f.offsetParent;for(;d;d=d.offsetParent)u+=d.offsetTop;return p.set([...c=[...c,m]].reverse(),u)},new Map))}).pipe(l(c=>new Map([...c].sort(([,p],[,m])=>p-m))),Ge(i),v(([c,p])=>t.pipe(Cr(([m,f],{offset:{y:u},size:d})=>{let b=u+d.height>=Math.floor(a.height);for(;f.length;){let[,_]=f[0];if(_-p=u&&!b)f=[m.pop(),...f];else break}return[m,f]},[[],[...c]]),G((m,f)=>m[0]===f[0]&&m[1]===f[1])))))).pipe(l(([a,c])=>({prev:a.map(([p])=>p),next:c.map(([p])=>p)})),V({prev:[],next:[]}),Ce(2,1),l(([a,c])=>a.prev.length{let i=new x,s=i.pipe(J(),ee(!0));if(i.subscribe(({prev:a,next:c})=>{for(let[p]of c)p.classList.remove("md-nav__link--passed"),p.classList.remove("md-nav__link--active");for(let[p,[m]]of a.entries())m.classList.add("md-nav__link--passed"),m.classList.toggle("md-nav__link--active",p===a.length-1)}),te("toc.follow")){let a=M(t.pipe(ke(1),l(()=>{})),t.pipe(ke(250),l(()=>"smooth")));i.pipe(L(({prev:c})=>c.length>0),Ge(o.pipe(_e(ae))),oe(a)).subscribe(([[{prev:c}],p])=>{let[m]=c[c.length-1];if(m.offsetHeight){let f=or(m);if(typeof f!="undefined"){let u=m.offsetTop-f.offsetTop,{height:d}=he(f);f.scrollTo({top:u-d/2,behavior:p})}}})}return te("navigation.tracking")&&t.pipe(K(s),X("offset"),ke(250),je(1),K(n.pipe(je(1))),Ot({delay:250}),oe(i)).subscribe(([,{prev:a}])=>{let c=fe(),p=a[a.length-1];if(p&&p.length){let[m]=p,{hash:f}=new URL(m.href);c.hash!==f&&(c.hash=f,history.replaceState({},"",`${c}`))}else c.hash="",history.replaceState({},"",`${c}`)}),Fa(e,{viewport$:t,header$:r}).pipe(w(a=>i.next(a)),k(()=>i.complete()),l(a=>I({ref:e},a)))})}function ja(e,{viewport$:t,main$:r,target$:o}){let n=t.pipe(l(({offset:{y:s}})=>s),Ce(2,1),l(([s,a])=>s>a&&a>0),G()),i=r.pipe(l(({active:s})=>s));return Q([i,n]).pipe(l(([s,a])=>!(s&&a)),G(),K(o.pipe(je(1))),ee(!0),Ot({delay:250}),l(s=>({hidden:s})))}function ei(e,{viewport$:t,header$:r,main$:o,target$:n}){let i=new x,s=i.pipe(J(),ee(!0));return i.subscribe({next({hidden:a}){e.hidden=a,a?(e.setAttribute("tabindex","-1"),e.blur()):e.removeAttribute("tabindex")},complete(){e.style.top="",e.hidden=!0,e.removeAttribute("tabindex")}}),r.pipe(K(s),X("height")).subscribe(({height:a})=>{e.style.top=`${a+16}px`}),h(e,"click").subscribe(a=>{a.preventDefault(),window.scrollTo({top:0})}),ja(e,{viewport$:t,main$:o,target$:n}).pipe(w(a=>i.next(a)),k(()=>i.complete()),l(a=>I({ref:e},a)))}function ti({document$:e,tablet$:t}){e.pipe(v(()=>z(".md-toggle--indeterminate")),w(r=>{r.indeterminate=!0,r.checked=!1}),se(r=>h(r,"change").pipe($r(()=>r.classList.contains("md-toggle--indeterminate")),l(()=>r))),oe(t)).subscribe(([r,o])=>{r.classList.remove("md-toggle--indeterminate"),o&&(r.checked=!1)})}function Wa(){return/(iPad|iPhone|iPod)/.test(navigator.userAgent)}function ri({document$:e}){e.pipe(v(()=>z("[data-md-scrollfix]")),w(t=>t.removeAttribute("data-md-scrollfix")),L(Wa),se(t=>h(t,"touchstart").pipe(l(()=>t)))).subscribe(t=>{let r=t.scrollTop;r===0?t.scrollTop=1:r+t.offsetHeight===t.scrollHeight&&(t.scrollTop=r-1)})}function oi({viewport$:e,tablet$:t}){Q([We("search"),t]).pipe(l(([r,o])=>r&&!o),v(r=>H(r).pipe(ze(r?400:100))),oe(e)).subscribe(([r,{offset:{y:o}}])=>{if(r)document.body.setAttribute("data-md-scrolllock",""),document.body.style.top=`-${o}px`;else{let n=-1*parseInt(document.body.style.top,10);document.body.removeAttribute("data-md-scrolllock"),document.body.style.top="",n&&window.scrollTo(0,n)}})}Object.entries||(Object.entries=function(e){let t=[];for(let r of Object.keys(e))t.push([r,e[r]]);return t});Object.values||(Object.values=function(e){let t=[];for(let r of Object.keys(e))t.push(e[r]);return t});typeof Element!="undefined"&&(Element.prototype.scrollTo||(Element.prototype.scrollTo=function(e,t){typeof e=="object"?(this.scrollLeft=e.left,this.scrollTop=e.top):(this.scrollLeft=e,this.scrollTop=t)}),Element.prototype.replaceWith||(Element.prototype.replaceWith=function(...e){let t=this.parentNode;if(t){e.length===0&&t.removeChild(this);for(let r=e.length-1;r>=0;r--){let o=e[r];typeof o=="string"?o=document.createTextNode(o):o.parentNode&&o.parentNode.removeChild(o),r?t.insertBefore(this.previousSibling,o):t.replaceChild(o,this)}}}));function Ua(){return location.protocol==="file:"?ht(`${new URL("search/search_index.js",Qr.base)}`).pipe(l(()=>__index),B(1)):Ue(new URL("search/search_index.json",Qr.base))}document.documentElement.classList.remove("no-js");document.documentElement.classList.add("js");var nt=Wo(),At=Qo(),gt=Bo(At),Yr=Ko(),Se=rn(),lr=Fr("(min-width: 960px)"),ii=Fr("(min-width: 1220px)"),ai=Go(),Qr=ue(),si=document.forms.namedItem("search")?Ua():Ve,Br=new x;Rn({alert$:Br});te("navigation.instant")&&In({location$:At,viewport$:Se}).subscribe(nt);var ni;((ni=Qr.version)==null?void 0:ni.provider)==="mike"&&Nn({document$:nt});M(At,gt).pipe(ze(125)).subscribe(()=>{Ke("drawer",!1),Ke("search",!1)});Yr.pipe(L(({mode:e})=>e==="global")).subscribe(e=>{switch(e.type){case"p":case",":let t=ce("link[rel=prev]");typeof t!="undefined"&&ot(t);break;case"n":case".":let r=ce("link[rel=next]");typeof r!="undefined"&&ot(r);break;case"Enter":let o=Re();o instanceof HTMLLabelElement&&o.click()}});ti({document$:nt,tablet$:lr});ri({document$:nt});oi({viewport$:Se,tablet$:lr});var Xe=An(ye("header"),{viewport$:Se}),_t=nt.pipe(l(()=>ye("main")),v(e=>Hn(e,{viewport$:Se,header$:Xe})),B(1)),Na=M(...ne("consent").map(e=>an(e,{target$:gt})),...ne("dialog").map(e=>_n(e,{alert$:Br})),...ne("header").map(e=>Cn(e,{viewport$:Se,header$:Xe,main$:_t})),...ne("palette").map(e=>$n(e)),...ne("search").map(e=>Kn(e,{index$:si,keyboard$:Yr})),...ne("source").map(e=>Jn(e))),Da=$(()=>M(...ne("announce").map(e=>nn(e)),...ne("content").map(e=>Ln(e,{viewport$:Se,target$:gt,print$:ai})),...ne("content").map(e=>te("search.highlight")?Qn(e,{index$:si,location$:At}):T),...ne("header-title").map(e=>kn(e,{viewport$:Se,header$:Xe})),...ne("sidebar").map(e=>e.getAttribute("data-md-type")==="navigation"?jr(ii,()=>Kr(e,{viewport$:Se,header$:Xe,main$:_t})):jr(lr,()=>Kr(e,{viewport$:Se,header$:Xe,main$:_t}))),...ne("tabs").map(e=>Xn(e,{viewport$:Se,header$:Xe})),...ne("toc").map(e=>Zn(e,{viewport$:Se,header$:Xe,main$:_t,target$:gt})),...ne("top").map(e=>ei(e,{viewport$:Se,header$:Xe,main$:_t,target$:gt})))),ci=nt.pipe(v(()=>Da),qe(Na),B(1));ci.subscribe();window.document$=nt;window.location$=At;window.target$=gt;window.keyboard$=Yr;window.viewport$=Se;window.tablet$=lr;window.screen$=ii;window.print$=ai;window.alert$=Br;window.component$=ci;})();
+//# sourceMappingURL=bundle.4e0fa4ba.min.js.map
+
diff --git a/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js.map b/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js.map
new file mode 100644
index 000000000..b3e2c4ef6
--- /dev/null
+++ b/material/templates/assets/javascripts/bundle.4e0fa4ba.min.js.map
@@ -0,0 +1,8 @@
+{
+ "version": 3,
+ "sources": ["node_modules/focus-visible/dist/focus-visible.js", "node_modules/clipboard/dist/clipboard.js", "node_modules/escape-html/index.js", "src/templates/assets/javascripts/bundle.ts", "node_modules/rxjs/node_modules/tslib/tslib.es6.js", "node_modules/rxjs/src/internal/util/isFunction.ts", "node_modules/rxjs/src/internal/util/createErrorClass.ts", "node_modules/rxjs/src/internal/util/UnsubscriptionError.ts", "node_modules/rxjs/src/internal/util/arrRemove.ts", "node_modules/rxjs/src/internal/Subscription.ts", "node_modules/rxjs/src/internal/config.ts", "node_modules/rxjs/src/internal/scheduler/timeoutProvider.ts", "node_modules/rxjs/src/internal/util/reportUnhandledError.ts", "node_modules/rxjs/src/internal/util/noop.ts", "node_modules/rxjs/src/internal/NotificationFactories.ts", "node_modules/rxjs/src/internal/util/errorContext.ts", "node_modules/rxjs/src/internal/Subscriber.ts", "node_modules/rxjs/src/internal/symbol/observable.ts", "node_modules/rxjs/src/internal/util/identity.ts", "node_modules/rxjs/src/internal/util/pipe.ts", "node_modules/rxjs/src/internal/Observable.ts", "node_modules/rxjs/src/internal/util/lift.ts", "node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts", "node_modules/rxjs/src/internal/scheduler/animationFrameProvider.ts", "node_modules/rxjs/src/internal/util/ObjectUnsubscribedError.ts", "node_modules/rxjs/src/internal/Subject.ts", "node_modules/rxjs/src/internal/scheduler/dateTimestampProvider.ts", "node_modules/rxjs/src/internal/ReplaySubject.ts", "node_modules/rxjs/src/internal/scheduler/Action.ts", "node_modules/rxjs/src/internal/scheduler/intervalProvider.ts", "node_modules/rxjs/src/internal/scheduler/AsyncAction.ts", "node_modules/rxjs/src/internal/Scheduler.ts", "node_modules/rxjs/src/internal/scheduler/AsyncScheduler.ts", "node_modules/rxjs/src/internal/scheduler/async.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameAction.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameScheduler.ts", "node_modules/rxjs/src/internal/scheduler/animationFrame.ts", "node_modules/rxjs/src/internal/observable/empty.ts", "node_modules/rxjs/src/internal/util/isScheduler.ts", "node_modules/rxjs/src/internal/util/args.ts", "node_modules/rxjs/src/internal/util/isArrayLike.ts", "node_modules/rxjs/src/internal/util/isPromise.ts", "node_modules/rxjs/src/internal/util/isInteropObservable.ts", "node_modules/rxjs/src/internal/util/isAsyncIterable.ts", "node_modules/rxjs/src/internal/util/throwUnobservableError.ts", "node_modules/rxjs/src/internal/symbol/iterator.ts", "node_modules/rxjs/src/internal/util/isIterable.ts", "node_modules/rxjs/src/internal/util/isReadableStreamLike.ts", "node_modules/rxjs/src/internal/observable/innerFrom.ts", "node_modules/rxjs/src/internal/util/executeSchedule.ts", "node_modules/rxjs/src/internal/operators/observeOn.ts", "node_modules/rxjs/src/internal/operators/subscribeOn.ts", "node_modules/rxjs/src/internal/scheduled/scheduleObservable.ts", "node_modules/rxjs/src/internal/scheduled/schedulePromise.ts", "node_modules/rxjs/src/internal/scheduled/scheduleArray.ts", "node_modules/rxjs/src/internal/scheduled/scheduleIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleAsyncIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleReadableStreamLike.ts", "node_modules/rxjs/src/internal/scheduled/scheduled.ts", "node_modules/rxjs/src/internal/observable/from.ts", "node_modules/rxjs/src/internal/observable/of.ts", "node_modules/rxjs/src/internal/observable/throwError.ts", "node_modules/rxjs/src/internal/util/EmptyError.ts", "node_modules/rxjs/src/internal/util/isDate.ts", "node_modules/rxjs/src/internal/operators/map.ts", "node_modules/rxjs/src/internal/util/mapOneOrManyArgs.ts", "node_modules/rxjs/src/internal/util/argsArgArrayOrObject.ts", "node_modules/rxjs/src/internal/util/createObject.ts", "node_modules/rxjs/src/internal/observable/combineLatest.ts", "node_modules/rxjs/src/internal/operators/mergeInternals.ts", "node_modules/rxjs/src/internal/operators/mergeMap.ts", "node_modules/rxjs/src/internal/operators/mergeAll.ts", "node_modules/rxjs/src/internal/operators/concatAll.ts", "node_modules/rxjs/src/internal/observable/concat.ts", "node_modules/rxjs/src/internal/observable/defer.ts", "node_modules/rxjs/src/internal/observable/fromEvent.ts", "node_modules/rxjs/src/internal/observable/fromEventPattern.ts", "node_modules/rxjs/src/internal/observable/timer.ts", "node_modules/rxjs/src/internal/observable/merge.ts", "node_modules/rxjs/src/internal/observable/never.ts", "node_modules/rxjs/src/internal/util/argsOrArgArray.ts", "node_modules/rxjs/src/internal/operators/filter.ts", "node_modules/rxjs/src/internal/observable/zip.ts", "node_modules/rxjs/src/internal/operators/audit.ts", "node_modules/rxjs/src/internal/operators/auditTime.ts", "node_modules/rxjs/src/internal/operators/bufferCount.ts", "node_modules/rxjs/src/internal/operators/catchError.ts", "node_modules/rxjs/src/internal/operators/scanInternals.ts", "node_modules/rxjs/src/internal/operators/combineLatest.ts", "node_modules/rxjs/src/internal/operators/combineLatestWith.ts", "node_modules/rxjs/src/internal/operators/debounceTime.ts", "node_modules/rxjs/src/internal/operators/defaultIfEmpty.ts", "node_modules/rxjs/src/internal/operators/take.ts", "node_modules/rxjs/src/internal/operators/ignoreElements.ts", "node_modules/rxjs/src/internal/operators/mapTo.ts", "node_modules/rxjs/src/internal/operators/delayWhen.ts", "node_modules/rxjs/src/internal/operators/delay.ts", "node_modules/rxjs/src/internal/operators/distinctUntilChanged.ts", "node_modules/rxjs/src/internal/operators/distinctUntilKeyChanged.ts", "node_modules/rxjs/src/internal/operators/throwIfEmpty.ts", "node_modules/rxjs/src/internal/operators/endWith.ts", "node_modules/rxjs/src/internal/operators/finalize.ts", "node_modules/rxjs/src/internal/operators/first.ts", "node_modules/rxjs/src/internal/operators/merge.ts", "node_modules/rxjs/src/internal/operators/mergeWith.ts", "node_modules/rxjs/src/internal/operators/repeat.ts", "node_modules/rxjs/src/internal/operators/scan.ts", "node_modules/rxjs/src/internal/operators/share.ts", "node_modules/rxjs/src/internal/operators/shareReplay.ts", "node_modules/rxjs/src/internal/operators/skip.ts", "node_modules/rxjs/src/internal/operators/skipUntil.ts", "node_modules/rxjs/src/internal/operators/startWith.ts", "node_modules/rxjs/src/internal/operators/switchMap.ts", "node_modules/rxjs/src/internal/operators/takeUntil.ts", "node_modules/rxjs/src/internal/operators/takeWhile.ts", "node_modules/rxjs/src/internal/operators/tap.ts", "node_modules/rxjs/src/internal/operators/throttle.ts", "node_modules/rxjs/src/internal/operators/throttleTime.ts", "node_modules/rxjs/src/internal/operators/withLatestFrom.ts", "node_modules/rxjs/src/internal/operators/zip.ts", "node_modules/rxjs/src/internal/operators/zipWith.ts", "src/templates/assets/javascripts/browser/document/index.ts", "src/templates/assets/javascripts/browser/element/_/index.ts", "src/templates/assets/javascripts/browser/element/focus/index.ts", "src/templates/assets/javascripts/browser/element/offset/_/index.ts", "src/templates/assets/javascripts/browser/element/offset/content/index.ts", "src/templates/assets/javascripts/utilities/h/index.ts", "src/templates/assets/javascripts/utilities/round/index.ts", "src/templates/assets/javascripts/browser/script/index.ts", "src/templates/assets/javascripts/browser/element/size/_/index.ts", "src/templates/assets/javascripts/browser/element/size/content/index.ts", "src/templates/assets/javascripts/browser/element/visibility/index.ts", "src/templates/assets/javascripts/browser/toggle/index.ts", "src/templates/assets/javascripts/browser/keyboard/index.ts", "src/templates/assets/javascripts/browser/location/_/index.ts", "src/templates/assets/javascripts/browser/location/hash/index.ts", "src/templates/assets/javascripts/browser/media/index.ts", "src/templates/assets/javascripts/browser/request/index.ts", "src/templates/assets/javascripts/browser/viewport/offset/index.ts", "src/templates/assets/javascripts/browser/viewport/size/index.ts", "src/templates/assets/javascripts/browser/viewport/_/index.ts", "src/templates/assets/javascripts/browser/viewport/at/index.ts", "src/templates/assets/javascripts/browser/worker/index.ts", "src/templates/assets/javascripts/_/index.ts", "src/templates/assets/javascripts/components/_/index.ts", "src/templates/assets/javascripts/components/announce/index.ts", "src/templates/assets/javascripts/components/consent/index.ts", "src/templates/assets/javascripts/components/content/annotation/_/index.ts", "src/templates/assets/javascripts/templates/tooltip/index.tsx", "src/templates/assets/javascripts/templates/annotation/index.tsx", "src/templates/assets/javascripts/templates/clipboard/index.tsx", "src/templates/assets/javascripts/templates/search/index.tsx", "src/templates/assets/javascripts/templates/source/index.tsx", "src/templates/assets/javascripts/templates/tabbed/index.tsx", "src/templates/assets/javascripts/templates/table/index.tsx", "src/templates/assets/javascripts/templates/version/index.tsx", "src/templates/assets/javascripts/components/content/annotation/list/index.ts", "src/templates/assets/javascripts/components/content/annotation/block/index.ts", "src/templates/assets/javascripts/components/content/code/_/index.ts", "src/templates/assets/javascripts/components/content/details/index.ts", "src/templates/assets/javascripts/components/content/mermaid/index.css", "src/templates/assets/javascripts/components/content/mermaid/index.ts", "src/templates/assets/javascripts/components/content/table/index.ts", "src/templates/assets/javascripts/components/content/tabs/index.ts", "src/templates/assets/javascripts/components/content/_/index.ts", "src/templates/assets/javascripts/components/dialog/index.ts", "src/templates/assets/javascripts/components/header/_/index.ts", "src/templates/assets/javascripts/components/header/title/index.ts", "src/templates/assets/javascripts/components/main/index.ts", "src/templates/assets/javascripts/components/palette/index.ts", "src/templates/assets/javascripts/integrations/clipboard/index.ts", "src/templates/assets/javascripts/integrations/sitemap/index.ts", "src/templates/assets/javascripts/integrations/instant/index.ts", "src/templates/assets/javascripts/integrations/search/highlighter/index.ts", "src/templates/assets/javascripts/integrations/search/worker/message/index.ts", "src/templates/assets/javascripts/integrations/search/worker/_/index.ts", "src/templates/assets/javascripts/integrations/version/index.ts", "src/templates/assets/javascripts/components/search/query/index.ts", "src/templates/assets/javascripts/components/search/result/index.ts", "src/templates/assets/javascripts/components/search/share/index.ts", "src/templates/assets/javascripts/components/search/suggest/index.ts", "src/templates/assets/javascripts/components/search/_/index.ts", "src/templates/assets/javascripts/components/search/highlight/index.ts", "src/templates/assets/javascripts/components/sidebar/index.ts", "src/templates/assets/javascripts/components/source/facts/github/index.ts", "src/templates/assets/javascripts/components/source/facts/gitlab/index.ts", "src/templates/assets/javascripts/components/source/facts/_/index.ts", "src/templates/assets/javascripts/components/source/_/index.ts", "src/templates/assets/javascripts/components/tabs/index.ts", "src/templates/assets/javascripts/components/toc/index.ts", "src/templates/assets/javascripts/components/top/index.ts", "src/templates/assets/javascripts/patches/indeterminate/index.ts", "src/templates/assets/javascripts/patches/scrollfix/index.ts", "src/templates/assets/javascripts/patches/scrolllock/index.ts", "src/templates/assets/javascripts/polyfills/index.ts"],
+ "sourceRoot": "../../../..",
+ "sourcesContent": ["(function (global, factory) {\n typeof exports === 'object' && typeof module !== 'undefined' ? factory() :\n typeof define === 'function' && define.amd ? define(factory) :\n (factory());\n}(this, (function () { 'use strict';\n\n /**\n * Applies the :focus-visible polyfill at the given scope.\n * A scope in this case is either the top-level Document or a Shadow Root.\n *\n * @param {(Document|ShadowRoot)} scope\n * @see https://github.com/WICG/focus-visible\n */\n function applyFocusVisiblePolyfill(scope) {\n var hadKeyboardEvent = true;\n var hadFocusVisibleRecently = false;\n var hadFocusVisibleRecentlyTimeout = null;\n\n var inputTypesAllowlist = {\n text: true,\n search: true,\n url: true,\n tel: true,\n email: true,\n password: true,\n number: true,\n date: true,\n month: true,\n week: true,\n time: true,\n datetime: true,\n 'datetime-local': true\n };\n\n /**\n * Helper function for legacy browsers and iframes which sometimes focus\n * elements like document, body, and non-interactive SVG.\n * @param {Element} el\n */\n function isValidFocusTarget(el) {\n if (\n el &&\n el !== document &&\n el.nodeName !== 'HTML' &&\n el.nodeName !== 'BODY' &&\n 'classList' in el &&\n 'contains' in el.classList\n ) {\n return true;\n }\n return false;\n }\n\n /**\n * Computes whether the given element should automatically trigger the\n * `focus-visible` class being added, i.e. whether it should always match\n * `:focus-visible` when focused.\n * @param {Element} el\n * @return {boolean}\n */\n function focusTriggersKeyboardModality(el) {\n var type = el.type;\n var tagName = el.tagName;\n\n if (tagName === 'INPUT' && inputTypesAllowlist[type] && !el.readOnly) {\n return true;\n }\n\n if (tagName === 'TEXTAREA' && !el.readOnly) {\n return true;\n }\n\n if (el.isContentEditable) {\n return true;\n }\n\n return false;\n }\n\n /**\n * Add the `focus-visible` class to the given element if it was not added by\n * the author.\n * @param {Element} el\n */\n function addFocusVisibleClass(el) {\n if (el.classList.contains('focus-visible')) {\n return;\n }\n el.classList.add('focus-visible');\n el.setAttribute('data-focus-visible-added', '');\n }\n\n /**\n * Remove the `focus-visible` class from the given element if it was not\n * originally added by the author.\n * @param {Element} el\n */\n function removeFocusVisibleClass(el) {\n if (!el.hasAttribute('data-focus-visible-added')) {\n return;\n }\n el.classList.remove('focus-visible');\n el.removeAttribute('data-focus-visible-added');\n }\n\n /**\n * If the most recent user interaction was via the keyboard;\n * and the key press did not include a meta, alt/option, or control key;\n * then the modality is keyboard. Otherwise, the modality is not keyboard.\n * Apply `focus-visible` to any current active element and keep track\n * of our keyboard modality state with `hadKeyboardEvent`.\n * @param {KeyboardEvent} e\n */\n function onKeyDown(e) {\n if (e.metaKey || e.altKey || e.ctrlKey) {\n return;\n }\n\n if (isValidFocusTarget(scope.activeElement)) {\n addFocusVisibleClass(scope.activeElement);\n }\n\n hadKeyboardEvent = true;\n }\n\n /**\n * If at any point a user clicks with a pointing device, ensure that we change\n * the modality away from keyboard.\n * This avoids the situation where a user presses a key on an already focused\n * element, and then clicks on a different element, focusing it with a\n * pointing device, while we still think we're in keyboard modality.\n * @param {Event} e\n */\n function onPointerDown(e) {\n hadKeyboardEvent = false;\n }\n\n /**\n * On `focus`, add the `focus-visible` class to the target if:\n * - the target received focus as a result of keyboard navigation, or\n * - the event target is an element that will likely require interaction\n * via the keyboard (e.g. a text box)\n * @param {Event} e\n */\n function onFocus(e) {\n // Prevent IE from focusing the document or HTML element.\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target)) {\n addFocusVisibleClass(e.target);\n }\n }\n\n /**\n * On `blur`, remove the `focus-visible` class from the target.\n * @param {Event} e\n */\n function onBlur(e) {\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (\n e.target.classList.contains('focus-visible') ||\n e.target.hasAttribute('data-focus-visible-added')\n ) {\n // To detect a tab/window switch, we look for a blur event followed\n // rapidly by a visibility change.\n // If we don't see a visibility change within 100ms, it's probably a\n // regular focus change.\n hadFocusVisibleRecently = true;\n window.clearTimeout(hadFocusVisibleRecentlyTimeout);\n hadFocusVisibleRecentlyTimeout = window.setTimeout(function() {\n hadFocusVisibleRecently = false;\n }, 100);\n removeFocusVisibleClass(e.target);\n }\n }\n\n /**\n * If the user changes tabs, keep track of whether or not the previously\n * focused element had .focus-visible.\n * @param {Event} e\n */\n function onVisibilityChange(e) {\n if (document.visibilityState === 'hidden') {\n // If the tab becomes active again, the browser will handle calling focus\n // on the element (Safari actually calls it twice).\n // If this tab change caused a blur on an element with focus-visible,\n // re-apply the class when the user switches back to the tab.\n if (hadFocusVisibleRecently) {\n hadKeyboardEvent = true;\n }\n addInitialPointerMoveListeners();\n }\n }\n\n /**\n * Add a group of listeners to detect usage of any pointing devices.\n * These listeners will be added when the polyfill first loads, and anytime\n * the window is blurred, so that they are active when the window regains\n * focus.\n */\n function addInitialPointerMoveListeners() {\n document.addEventListener('mousemove', onInitialPointerMove);\n document.addEventListener('mousedown', onInitialPointerMove);\n document.addEventListener('mouseup', onInitialPointerMove);\n document.addEventListener('pointermove', onInitialPointerMove);\n document.addEventListener('pointerdown', onInitialPointerMove);\n document.addEventListener('pointerup', onInitialPointerMove);\n document.addEventListener('touchmove', onInitialPointerMove);\n document.addEventListener('touchstart', onInitialPointerMove);\n document.addEventListener('touchend', onInitialPointerMove);\n }\n\n function removeInitialPointerMoveListeners() {\n document.removeEventListener('mousemove', onInitialPointerMove);\n document.removeEventListener('mousedown', onInitialPointerMove);\n document.removeEventListener('mouseup', onInitialPointerMove);\n document.removeEventListener('pointermove', onInitialPointerMove);\n document.removeEventListener('pointerdown', onInitialPointerMove);\n document.removeEventListener('pointerup', onInitialPointerMove);\n document.removeEventListener('touchmove', onInitialPointerMove);\n document.removeEventListener('touchstart', onInitialPointerMove);\n document.removeEventListener('touchend', onInitialPointerMove);\n }\n\n /**\n * When the polfyill first loads, assume the user is in keyboard modality.\n * If any event is received from a pointing device (e.g. mouse, pointer,\n * touch), turn off keyboard modality.\n * This accounts for situations where focus enters the page from the URL bar.\n * @param {Event} e\n */\n function onInitialPointerMove(e) {\n // Work around a Safari quirk that fires a mousemove on whenever the\n // window blurs, even if you're tabbing out of the page. \u00AF\\_(\u30C4)_/\u00AF\n if (e.target.nodeName && e.target.nodeName.toLowerCase() === 'html') {\n return;\n }\n\n hadKeyboardEvent = false;\n removeInitialPointerMoveListeners();\n }\n\n // For some kinds of state, we are interested in changes at the global scope\n // only. For example, global pointer input, global key presses and global\n // visibility change should affect the state at every scope:\n document.addEventListener('keydown', onKeyDown, true);\n document.addEventListener('mousedown', onPointerDown, true);\n document.addEventListener('pointerdown', onPointerDown, true);\n document.addEventListener('touchstart', onPointerDown, true);\n document.addEventListener('visibilitychange', onVisibilityChange, true);\n\n addInitialPointerMoveListeners();\n\n // For focus and blur, we specifically care about state changes in the local\n // scope. This is because focus / blur events that originate from within a\n // shadow root are not re-dispatched from the host element if it was already\n // the active element in its own scope:\n scope.addEventListener('focus', onFocus, true);\n scope.addEventListener('blur', onBlur, true);\n\n // We detect that a node is a ShadowRoot by ensuring that it is a\n // DocumentFragment and also has a host property. This check covers native\n // implementation and polyfill implementation transparently. If we only cared\n // about the native implementation, we could just check if the scope was\n // an instance of a ShadowRoot.\n if (scope.nodeType === Node.DOCUMENT_FRAGMENT_NODE && scope.host) {\n // Since a ShadowRoot is a special kind of DocumentFragment, it does not\n // have a root element to add a class to. So, we add this attribute to the\n // host element instead:\n scope.host.setAttribute('data-js-focus-visible', '');\n } else if (scope.nodeType === Node.DOCUMENT_NODE) {\n document.documentElement.classList.add('js-focus-visible');\n document.documentElement.setAttribute('data-js-focus-visible', '');\n }\n }\n\n // It is important to wrap all references to global window and document in\n // these checks to support server-side rendering use cases\n // @see https://github.com/WICG/focus-visible/issues/199\n if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n // Make the polyfill helper globally available. This can be used as a signal\n // to interested libraries that wish to coordinate with the polyfill for e.g.,\n // applying the polyfill to a shadow root:\n window.applyFocusVisiblePolyfill = applyFocusVisiblePolyfill;\n\n // Notify interested libraries of the polyfill's presence, in case the\n // polyfill was loaded lazily:\n var event;\n\n try {\n event = new CustomEvent('focus-visible-polyfill-ready');\n } catch (error) {\n // IE11 does not support using CustomEvent as a constructor directly:\n event = document.createEvent('CustomEvent');\n event.initCustomEvent('focus-visible-polyfill-ready', false, false, {});\n }\n\n window.dispatchEvent(event);\n }\n\n if (typeof document !== 'undefined') {\n // Apply the polyfill to the global document, so that no JavaScript\n // coordination is required to use the polyfill in the top-level document:\n applyFocusVisiblePolyfill(document);\n }\n\n})));\n", "/*!\n * clipboard.js v2.0.11\n * https://clipboardjs.com/\n *\n * Licensed MIT \u00A9 Zeno Rocha\n */\n(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"ClipboardJS\"] = factory();\n\telse\n\t\troot[\"ClipboardJS\"] = factory();\n})(this, function() {\nreturn /******/ (function() { // webpackBootstrap\n/******/ \tvar __webpack_modules__ = ({\n\n/***/ 686:\n/***/ (function(__unused_webpack_module, __webpack_exports__, __webpack_require__) {\n\n\"use strict\";\n\n// EXPORTS\n__webpack_require__.d(__webpack_exports__, {\n \"default\": function() { return /* binding */ clipboard; }\n});\n\n// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js\nvar tiny_emitter = __webpack_require__(279);\nvar tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);\n// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js\nvar listen = __webpack_require__(370);\nvar listen_default = /*#__PURE__*/__webpack_require__.n(listen);\n// EXTERNAL MODULE: ./node_modules/select/src/select.js\nvar src_select = __webpack_require__(817);\nvar select_default = /*#__PURE__*/__webpack_require__.n(src_select);\n;// CONCATENATED MODULE: ./src/common/command.js\n/**\n * Executes a given operation type.\n * @param {String} type\n * @return {Boolean}\n */\nfunction command(type) {\n try {\n return document.execCommand(type);\n } catch (err) {\n return false;\n }\n}\n;// CONCATENATED MODULE: ./src/actions/cut.js\n\n\n/**\n * Cut action wrapper.\n * @param {String|HTMLElement} target\n * @return {String}\n */\n\nvar ClipboardActionCut = function ClipboardActionCut(target) {\n var selectedText = select_default()(target);\n command('cut');\n return selectedText;\n};\n\n/* harmony default export */ var actions_cut = (ClipboardActionCut);\n;// CONCATENATED MODULE: ./src/common/create-fake-element.js\n/**\n * Creates a fake textarea element with a value.\n * @param {String} value\n * @return {HTMLElement}\n */\nfunction createFakeElement(value) {\n var isRTL = document.documentElement.getAttribute('dir') === 'rtl';\n var fakeElement = document.createElement('textarea'); // Prevent zooming on iOS\n\n fakeElement.style.fontSize = '12pt'; // Reset box model\n\n fakeElement.style.border = '0';\n fakeElement.style.padding = '0';\n fakeElement.style.margin = '0'; // Move element out of screen horizontally\n\n fakeElement.style.position = 'absolute';\n fakeElement.style[isRTL ? 'right' : 'left'] = '-9999px'; // Move element to the same position vertically\n\n var yPosition = window.pageYOffset || document.documentElement.scrollTop;\n fakeElement.style.top = \"\".concat(yPosition, \"px\");\n fakeElement.setAttribute('readonly', '');\n fakeElement.value = value;\n return fakeElement;\n}\n;// CONCATENATED MODULE: ./src/actions/copy.js\n\n\n\n/**\n * Create fake copy action wrapper using a fake element.\n * @param {String} target\n * @param {Object} options\n * @return {String}\n */\n\nvar fakeCopyAction = function fakeCopyAction(value, options) {\n var fakeElement = createFakeElement(value);\n options.container.appendChild(fakeElement);\n var selectedText = select_default()(fakeElement);\n command('copy');\n fakeElement.remove();\n return selectedText;\n};\n/**\n * Copy action wrapper.\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @return {String}\n */\n\n\nvar ClipboardActionCopy = function ClipboardActionCopy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n var selectedText = '';\n\n if (typeof target === 'string') {\n selectedText = fakeCopyAction(target, options);\n } else if (target instanceof HTMLInputElement && !['text', 'search', 'url', 'tel', 'password'].includes(target === null || target === void 0 ? void 0 : target.type)) {\n // If input type doesn't support `setSelectionRange`. Simulate it. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange\n selectedText = fakeCopyAction(target.value, options);\n } else {\n selectedText = select_default()(target);\n command('copy');\n }\n\n return selectedText;\n};\n\n/* harmony default export */ var actions_copy = (ClipboardActionCopy);\n;// CONCATENATED MODULE: ./src/actions/default.js\nfunction _typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return _typeof(obj); }\n\n\n\n/**\n * Inner function which performs selection from either `text` or `target`\n * properties and then executes copy or cut operations.\n * @param {Object} options\n */\n\nvar ClipboardActionDefault = function ClipboardActionDefault() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n // Defines base properties passed from constructor.\n var _options$action = options.action,\n action = _options$action === void 0 ? 'copy' : _options$action,\n container = options.container,\n target = options.target,\n text = options.text; // Sets the `action` to be performed which can be either 'copy' or 'cut'.\n\n if (action !== 'copy' && action !== 'cut') {\n throw new Error('Invalid \"action\" value, use either \"copy\" or \"cut\"');\n } // Sets the `target` property using an element that will be have its content copied.\n\n\n if (target !== undefined) {\n if (target && _typeof(target) === 'object' && target.nodeType === 1) {\n if (action === 'copy' && target.hasAttribute('disabled')) {\n throw new Error('Invalid \"target\" attribute. Please use \"readonly\" instead of \"disabled\" attribute');\n }\n\n if (action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {\n throw new Error('Invalid \"target\" attribute. You can\\'t cut text from elements with \"readonly\" or \"disabled\" attributes');\n }\n } else {\n throw new Error('Invalid \"target\" value, use a valid Element');\n }\n } // Define selection strategy based on `text` property.\n\n\n if (text) {\n return actions_copy(text, {\n container: container\n });\n } // Defines which selection strategy based on `target` property.\n\n\n if (target) {\n return action === 'cut' ? actions_cut(target) : actions_copy(target, {\n container: container\n });\n }\n};\n\n/* harmony default export */ var actions_default = (ClipboardActionDefault);\n;// CONCATENATED MODULE: ./src/clipboard.js\nfunction clipboard_typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { clipboard_typeof = function _typeof(obj) { return typeof obj; }; } else { clipboard_typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return clipboard_typeof(obj); }\n\nfunction _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError(\"Cannot call a class as a function\"); } }\n\nfunction _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if (\"value\" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }\n\nfunction _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }\n\nfunction _inherits(subClass, superClass) { if (typeof superClass !== \"function\" && superClass !== null) { throw new TypeError(\"Super expression must either be null or a function\"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }\n\nfunction _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }\n\nfunction _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }\n\nfunction _possibleConstructorReturn(self, call) { if (call && (clipboard_typeof(call) === \"object\" || typeof call === \"function\")) { return call; } return _assertThisInitialized(self); }\n\nfunction _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError(\"this hasn't been initialised - super() hasn't been called\"); } return self; }\n\nfunction _isNativeReflectConstruct() { if (typeof Reflect === \"undefined\" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === \"function\") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }\n\nfunction _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }\n\n\n\n\n\n\n/**\n * Helper function to retrieve attribute value.\n * @param {String} suffix\n * @param {Element} element\n */\n\nfunction getAttributeValue(suffix, element) {\n var attribute = \"data-clipboard-\".concat(suffix);\n\n if (!element.hasAttribute(attribute)) {\n return;\n }\n\n return element.getAttribute(attribute);\n}\n/**\n * Base class which takes one or more elements, adds event listeners to them,\n * and instantiates a new `ClipboardAction` on each click.\n */\n\n\nvar Clipboard = /*#__PURE__*/function (_Emitter) {\n _inherits(Clipboard, _Emitter);\n\n var _super = _createSuper(Clipboard);\n\n /**\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n * @param {Object} options\n */\n function Clipboard(trigger, options) {\n var _this;\n\n _classCallCheck(this, Clipboard);\n\n _this = _super.call(this);\n\n _this.resolveOptions(options);\n\n _this.listenClick(trigger);\n\n return _this;\n }\n /**\n * Defines if attributes would be resolved using internal setter functions\n * or custom functions that were passed in the constructor.\n * @param {Object} options\n */\n\n\n _createClass(Clipboard, [{\n key: \"resolveOptions\",\n value: function resolveOptions() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n this.action = typeof options.action === 'function' ? options.action : this.defaultAction;\n this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;\n this.text = typeof options.text === 'function' ? options.text : this.defaultText;\n this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;\n }\n /**\n * Adds a click event listener to the passed trigger.\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n */\n\n }, {\n key: \"listenClick\",\n value: function listenClick(trigger) {\n var _this2 = this;\n\n this.listener = listen_default()(trigger, 'click', function (e) {\n return _this2.onClick(e);\n });\n }\n /**\n * Defines a new `ClipboardAction` on each click event.\n * @param {Event} e\n */\n\n }, {\n key: \"onClick\",\n value: function onClick(e) {\n var trigger = e.delegateTarget || e.currentTarget;\n var action = this.action(trigger) || 'copy';\n var text = actions_default({\n action: action,\n container: this.container,\n target: this.target(trigger),\n text: this.text(trigger)\n }); // Fires an event based on the copy operation result.\n\n this.emit(text ? 'success' : 'error', {\n action: action,\n text: text,\n trigger: trigger,\n clearSelection: function clearSelection() {\n if (trigger) {\n trigger.focus();\n }\n\n window.getSelection().removeAllRanges();\n }\n });\n }\n /**\n * Default `action` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultAction\",\n value: function defaultAction(trigger) {\n return getAttributeValue('action', trigger);\n }\n /**\n * Default `target` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultTarget\",\n value: function defaultTarget(trigger) {\n var selector = getAttributeValue('target', trigger);\n\n if (selector) {\n return document.querySelector(selector);\n }\n }\n /**\n * Allow fire programmatically a copy action\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @returns Text copied.\n */\n\n }, {\n key: \"defaultText\",\n\n /**\n * Default `text` lookup function.\n * @param {Element} trigger\n */\n value: function defaultText(trigger) {\n return getAttributeValue('text', trigger);\n }\n /**\n * Destroy lifecycle.\n */\n\n }, {\n key: \"destroy\",\n value: function destroy() {\n this.listener.destroy();\n }\n }], [{\n key: \"copy\",\n value: function copy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n return actions_copy(target, options);\n }\n /**\n * Allow fire programmatically a cut action\n * @param {String|HTMLElement} target\n * @returns Text cutted.\n */\n\n }, {\n key: \"cut\",\n value: function cut(target) {\n return actions_cut(target);\n }\n /**\n * Returns the support of the given action, or all actions if no action is\n * given.\n * @param {String} [action]\n */\n\n }, {\n key: \"isSupported\",\n value: function isSupported() {\n var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];\n var actions = typeof action === 'string' ? [action] : action;\n var support = !!document.queryCommandSupported;\n actions.forEach(function (action) {\n support = support && !!document.queryCommandSupported(action);\n });\n return support;\n }\n }]);\n\n return Clipboard;\n}((tiny_emitter_default()));\n\n/* harmony default export */ var clipboard = (Clipboard);\n\n/***/ }),\n\n/***/ 828:\n/***/ (function(module) {\n\nvar DOCUMENT_NODE_TYPE = 9;\n\n/**\n * A polyfill for Element.matches()\n */\nif (typeof Element !== 'undefined' && !Element.prototype.matches) {\n var proto = Element.prototype;\n\n proto.matches = proto.matchesSelector ||\n proto.mozMatchesSelector ||\n proto.msMatchesSelector ||\n proto.oMatchesSelector ||\n proto.webkitMatchesSelector;\n}\n\n/**\n * Finds the closest parent that matches a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @return {Function}\n */\nfunction closest (element, selector) {\n while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {\n if (typeof element.matches === 'function' &&\n element.matches(selector)) {\n return element;\n }\n element = element.parentNode;\n }\n}\n\nmodule.exports = closest;\n\n\n/***/ }),\n\n/***/ 438:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar closest = __webpack_require__(828);\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction _delegate(element, selector, type, callback, useCapture) {\n var listenerFn = listener.apply(this, arguments);\n\n element.addEventListener(type, listenerFn, useCapture);\n\n return {\n destroy: function() {\n element.removeEventListener(type, listenerFn, useCapture);\n }\n }\n}\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element|String|Array} [elements]\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction delegate(elements, selector, type, callback, useCapture) {\n // Handle the regular Element usage\n if (typeof elements.addEventListener === 'function') {\n return _delegate.apply(null, arguments);\n }\n\n // Handle Element-less usage, it defaults to global delegation\n if (typeof type === 'function') {\n // Use `document` as the first parameter, then apply arguments\n // This is a short way to .unshift `arguments` without running into deoptimizations\n return _delegate.bind(null, document).apply(null, arguments);\n }\n\n // Handle Selector-based usage\n if (typeof elements === 'string') {\n elements = document.querySelectorAll(elements);\n }\n\n // Handle Array-like based usage\n return Array.prototype.map.call(elements, function (element) {\n return _delegate(element, selector, type, callback, useCapture);\n });\n}\n\n/**\n * Finds closest match and invokes callback.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Function}\n */\nfunction listener(element, selector, type, callback) {\n return function(e) {\n e.delegateTarget = closest(e.target, selector);\n\n if (e.delegateTarget) {\n callback.call(element, e);\n }\n }\n}\n\nmodule.exports = delegate;\n\n\n/***/ }),\n\n/***/ 879:\n/***/ (function(__unused_webpack_module, exports) {\n\n/**\n * Check if argument is a HTML element.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.node = function(value) {\n return value !== undefined\n && value instanceof HTMLElement\n && value.nodeType === 1;\n};\n\n/**\n * Check if argument is a list of HTML elements.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.nodeList = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return value !== undefined\n && (type === '[object NodeList]' || type === '[object HTMLCollection]')\n && ('length' in value)\n && (value.length === 0 || exports.node(value[0]));\n};\n\n/**\n * Check if argument is a string.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.string = function(value) {\n return typeof value === 'string'\n || value instanceof String;\n};\n\n/**\n * Check if argument is a function.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.fn = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return type === '[object Function]';\n};\n\n\n/***/ }),\n\n/***/ 370:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar is = __webpack_require__(879);\nvar delegate = __webpack_require__(438);\n\n/**\n * Validates all params and calls the right\n * listener function based on its target type.\n *\n * @param {String|HTMLElement|HTMLCollection|NodeList} target\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listen(target, type, callback) {\n if (!target && !type && !callback) {\n throw new Error('Missing required arguments');\n }\n\n if (!is.string(type)) {\n throw new TypeError('Second argument must be a String');\n }\n\n if (!is.fn(callback)) {\n throw new TypeError('Third argument must be a Function');\n }\n\n if (is.node(target)) {\n return listenNode(target, type, callback);\n }\n else if (is.nodeList(target)) {\n return listenNodeList(target, type, callback);\n }\n else if (is.string(target)) {\n return listenSelector(target, type, callback);\n }\n else {\n throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');\n }\n}\n\n/**\n * Adds an event listener to a HTML element\n * and returns a remove listener function.\n *\n * @param {HTMLElement} node\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNode(node, type, callback) {\n node.addEventListener(type, callback);\n\n return {\n destroy: function() {\n node.removeEventListener(type, callback);\n }\n }\n}\n\n/**\n * Add an event listener to a list of HTML elements\n * and returns a remove listener function.\n *\n * @param {NodeList|HTMLCollection} nodeList\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNodeList(nodeList, type, callback) {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.addEventListener(type, callback);\n });\n\n return {\n destroy: function() {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.removeEventListener(type, callback);\n });\n }\n }\n}\n\n/**\n * Add an event listener to a selector\n * and returns a remove listener function.\n *\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenSelector(selector, type, callback) {\n return delegate(document.body, selector, type, callback);\n}\n\nmodule.exports = listen;\n\n\n/***/ }),\n\n/***/ 817:\n/***/ (function(module) {\n\nfunction select(element) {\n var selectedText;\n\n if (element.nodeName === 'SELECT') {\n element.focus();\n\n selectedText = element.value;\n }\n else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {\n var isReadOnly = element.hasAttribute('readonly');\n\n if (!isReadOnly) {\n element.setAttribute('readonly', '');\n }\n\n element.select();\n element.setSelectionRange(0, element.value.length);\n\n if (!isReadOnly) {\n element.removeAttribute('readonly');\n }\n\n selectedText = element.value;\n }\n else {\n if (element.hasAttribute('contenteditable')) {\n element.focus();\n }\n\n var selection = window.getSelection();\n var range = document.createRange();\n\n range.selectNodeContents(element);\n selection.removeAllRanges();\n selection.addRange(range);\n\n selectedText = selection.toString();\n }\n\n return selectedText;\n}\n\nmodule.exports = select;\n\n\n/***/ }),\n\n/***/ 279:\n/***/ (function(module) {\n\nfunction E () {\n // Keep this empty so it's easier to inherit from\n // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)\n}\n\nE.prototype = {\n on: function (name, callback, ctx) {\n var e = this.e || (this.e = {});\n\n (e[name] || (e[name] = [])).push({\n fn: callback,\n ctx: ctx\n });\n\n return this;\n },\n\n once: function (name, callback, ctx) {\n var self = this;\n function listener () {\n self.off(name, listener);\n callback.apply(ctx, arguments);\n };\n\n listener._ = callback\n return this.on(name, listener, ctx);\n },\n\n emit: function (name) {\n var data = [].slice.call(arguments, 1);\n var evtArr = ((this.e || (this.e = {}))[name] || []).slice();\n var i = 0;\n var len = evtArr.length;\n\n for (i; i < len; i++) {\n evtArr[i].fn.apply(evtArr[i].ctx, data);\n }\n\n return this;\n },\n\n off: function (name, callback) {\n var e = this.e || (this.e = {});\n var evts = e[name];\n var liveEvents = [];\n\n if (evts && callback) {\n for (var i = 0, len = evts.length; i < len; i++) {\n if (evts[i].fn !== callback && evts[i].fn._ !== callback)\n liveEvents.push(evts[i]);\n }\n }\n\n // Remove event from queue to prevent memory leak\n // Suggested by https://github.com/lazd\n // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910\n\n (liveEvents.length)\n ? e[name] = liveEvents\n : delete e[name];\n\n return this;\n }\n};\n\nmodule.exports = E;\nmodule.exports.TinyEmitter = E;\n\n\n/***/ })\n\n/******/ \t});\n/************************************************************************/\n/******/ \t// The module cache\n/******/ \tvar __webpack_module_cache__ = {};\n/******/ \t\n/******/ \t// The require function\n/******/ \tfunction __webpack_require__(moduleId) {\n/******/ \t\t// Check if module is in cache\n/******/ \t\tif(__webpack_module_cache__[moduleId]) {\n/******/ \t\t\treturn __webpack_module_cache__[moduleId].exports;\n/******/ \t\t}\n/******/ \t\t// Create a new module (and put it into the cache)\n/******/ \t\tvar module = __webpack_module_cache__[moduleId] = {\n/******/ \t\t\t// no module.id needed\n/******/ \t\t\t// no module.loaded needed\n/******/ \t\t\texports: {}\n/******/ \t\t};\n/******/ \t\n/******/ \t\t// Execute the module function\n/******/ \t\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n/******/ \t\n/******/ \t\t// Return the exports of the module\n/******/ \t\treturn module.exports;\n/******/ \t}\n/******/ \t\n/************************************************************************/\n/******/ \t/* webpack/runtime/compat get default export */\n/******/ \t!function() {\n/******/ \t\t// getDefaultExport function for compatibility with non-harmony modules\n/******/ \t\t__webpack_require__.n = function(module) {\n/******/ \t\t\tvar getter = module && module.__esModule ?\n/******/ \t\t\t\tfunction() { return module['default']; } :\n/******/ \t\t\t\tfunction() { return module; };\n/******/ \t\t\t__webpack_require__.d(getter, { a: getter });\n/******/ \t\t\treturn getter;\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/define property getters */\n/******/ \t!function() {\n/******/ \t\t// define getter functions for harmony exports\n/******/ \t\t__webpack_require__.d = function(exports, definition) {\n/******/ \t\t\tfor(var key in definition) {\n/******/ \t\t\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n/******/ \t\t\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n/******/ \t\t\t\t}\n/******/ \t\t\t}\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/hasOwnProperty shorthand */\n/******/ \t!function() {\n/******/ \t\t__webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }\n/******/ \t}();\n/******/ \t\n/************************************************************************/\n/******/ \t// module exports must be returned from runtime so entry inlining is disabled\n/******/ \t// startup\n/******/ \t// Load entry module and return exports\n/******/ \treturn __webpack_require__(686);\n/******/ })()\n.default;\n});", "/*!\n * escape-html\n * Copyright(c) 2012-2013 TJ Holowaychuk\n * Copyright(c) 2015 Andreas Lubbe\n * Copyright(c) 2015 Tiancheng \"Timothy\" Gu\n * MIT Licensed\n */\n\n'use strict';\n\n/**\n * Module variables.\n * @private\n */\n\nvar matchHtmlRegExp = /[\"'&<>]/;\n\n/**\n * Module exports.\n * @public\n */\n\nmodule.exports = escapeHtml;\n\n/**\n * Escape special characters in the given string of html.\n *\n * @param {string} string The string to escape for inserting into HTML\n * @return {string}\n * @public\n */\n\nfunction escapeHtml(string) {\n var str = '' + string;\n var match = matchHtmlRegExp.exec(str);\n\n if (!match) {\n return str;\n }\n\n var escape;\n var html = '';\n var index = 0;\n var lastIndex = 0;\n\n for (index = match.index; index < str.length; index++) {\n switch (str.charCodeAt(index)) {\n case 34: // \"\n escape = '"';\n break;\n case 38: // &\n escape = '&';\n break;\n case 39: // '\n escape = ''';\n break;\n case 60: // <\n escape = '<';\n break;\n case 62: // >\n escape = '>';\n break;\n default:\n continue;\n }\n\n if (lastIndex !== index) {\n html += str.substring(lastIndex, index);\n }\n\n lastIndex = index + 1;\n html += escape;\n }\n\n return lastIndex !== index\n ? html + str.substring(lastIndex, index)\n : html;\n}\n", "/*\n * Copyright (c) 2016-2023 Martin Donath \n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\nimport \"focus-visible\"\n\nimport {\n EMPTY,\n NEVER,\n Observable,\n Subject,\n defer,\n delay,\n filter,\n map,\n merge,\n mergeWith,\n shareReplay,\n switchMap\n} from \"rxjs\"\n\nimport { configuration, feature } from \"./_\"\nimport {\n at,\n getActiveElement,\n getOptionalElement,\n requestJSON,\n setLocation,\n setToggle,\n watchDocument,\n watchKeyboard,\n watchLocation,\n watchLocationTarget,\n watchMedia,\n watchPrint,\n watchScript,\n watchViewport\n} from \"./browser\"\nimport {\n getComponentElement,\n getComponentElements,\n mountAnnounce,\n mountBackToTop,\n mountConsent,\n mountContent,\n mountDialog,\n mountHeader,\n mountHeaderTitle,\n mountPalette,\n mountSearch,\n mountSearchHiglight,\n mountSidebar,\n mountSource,\n mountTableOfContents,\n mountTabs,\n watchHeader,\n watchMain\n} from \"./components\"\nimport {\n SearchIndex,\n setupClipboardJS,\n setupInstantLoading,\n setupVersionSelector\n} from \"./integrations\"\nimport {\n patchIndeterminate,\n patchScrollfix,\n patchScrolllock\n} from \"./patches\"\nimport \"./polyfills\"\n\n/* ----------------------------------------------------------------------------\n * Functions - @todo refactor\n * ------------------------------------------------------------------------- */\n\n/**\n * Fetch search index\n *\n * @returns Search index observable\n */\nfunction fetchSearchIndex(): Observable {\n if (location.protocol === \"file:\") {\n return watchScript(\n `${new URL(\"search/search_index.js\", config.base)}`\n )\n .pipe(\n // @ts-ignore - @todo fix typings\n map(() => __index),\n shareReplay(1)\n )\n } else {\n return requestJSON(\n new URL(\"search/search_index.json\", config.base)\n )\n }\n}\n\n/* ----------------------------------------------------------------------------\n * Application\n * ------------------------------------------------------------------------- */\n\n/* Yay, JavaScript is available */\ndocument.documentElement.classList.remove(\"no-js\")\ndocument.documentElement.classList.add(\"js\")\n\n/* Set up navigation observables and subjects */\nconst document$ = watchDocument()\nconst location$ = watchLocation()\nconst target$ = watchLocationTarget(location$)\nconst keyboard$ = watchKeyboard()\n\n/* Set up media observables */\nconst viewport$ = watchViewport()\nconst tablet$ = watchMedia(\"(min-width: 960px)\")\nconst screen$ = watchMedia(\"(min-width: 1220px)\")\nconst print$ = watchPrint()\n\n/* Retrieve search index, if search is enabled */\nconst config = configuration()\nconst index$ = document.forms.namedItem(\"search\")\n ? fetchSearchIndex()\n : NEVER\n\n/* Set up Clipboard.js integration */\nconst alert$ = new Subject()\nsetupClipboardJS({ alert$ })\n\n/* Set up instant loading, if enabled */\nif (feature(\"navigation.instant\"))\n setupInstantLoading({ location$, viewport$ })\n .subscribe(document$)\n\n/* Set up version selector */\nif (config.version?.provider === \"mike\")\n setupVersionSelector({ document$ })\n\n/* Always close drawer and search on navigation */\nmerge(location$, target$)\n .pipe(\n delay(125)\n )\n .subscribe(() => {\n setToggle(\"drawer\", false)\n setToggle(\"search\", false)\n })\n\n/* Set up global keyboard handlers */\nkeyboard$\n .pipe(\n filter(({ mode }) => mode === \"global\")\n )\n .subscribe(key => {\n switch (key.type) {\n\n /* Go to previous page */\n case \"p\":\n case \",\":\n const prev = getOptionalElement(\"link[rel=prev]\")\n if (typeof prev !== \"undefined\")\n setLocation(prev)\n break\n\n /* Go to next page */\n case \"n\":\n case \".\":\n const next = getOptionalElement(\"link[rel=next]\")\n if (typeof next !== \"undefined\")\n setLocation(next)\n break\n\n /* Expand navigation, see https://bit.ly/3ZjG5io */\n case \"Enter\":\n const active = getActiveElement()\n if (active instanceof HTMLLabelElement)\n active.click()\n }\n })\n\n/* Set up patches */\npatchIndeterminate({ document$, tablet$ })\npatchScrollfix({ document$ })\npatchScrolllock({ viewport$, tablet$ })\n\n/* Set up header and main area observable */\nconst header$ = watchHeader(getComponentElement(\"header\"), { viewport$ })\nconst main$ = document$\n .pipe(\n map(() => getComponentElement(\"main\")),\n switchMap(el => watchMain(el, { viewport$, header$ })),\n shareReplay(1)\n )\n\n/* Set up control component observables */\nconst control$ = merge(\n\n /* Consent */\n ...getComponentElements(\"consent\")\n .map(el => mountConsent(el, { target$ })),\n\n /* Dialog */\n ...getComponentElements(\"dialog\")\n .map(el => mountDialog(el, { alert$ })),\n\n /* Header */\n ...getComponentElements(\"header\")\n .map(el => mountHeader(el, { viewport$, header$, main$ })),\n\n /* Color palette */\n ...getComponentElements(\"palette\")\n .map(el => mountPalette(el)),\n\n /* Search */\n ...getComponentElements(\"search\")\n .map(el => mountSearch(el, { index$, keyboard$ })),\n\n /* Repository information */\n ...getComponentElements(\"source\")\n .map(el => mountSource(el))\n)\n\n/* Set up content component observables */\nconst content$ = defer(() => merge(\n\n /* Announcement bar */\n ...getComponentElements(\"announce\")\n .map(el => mountAnnounce(el)),\n\n /* Content */\n ...getComponentElements(\"content\")\n .map(el => mountContent(el, { viewport$, target$, print$ })),\n\n /* Search highlighting */\n ...getComponentElements(\"content\")\n .map(el => feature(\"search.highlight\")\n ? mountSearchHiglight(el, { index$, location$ })\n : EMPTY\n ),\n\n /* Header title */\n ...getComponentElements(\"header-title\")\n .map(el => mountHeaderTitle(el, { viewport$, header$ })),\n\n /* Sidebar */\n ...getComponentElements(\"sidebar\")\n .map(el => el.getAttribute(\"data-md-type\") === \"navigation\"\n ? at(screen$, () => mountSidebar(el, { viewport$, header$, main$ }))\n : at(tablet$, () => mountSidebar(el, { viewport$, header$, main$ }))\n ),\n\n /* Navigation tabs */\n ...getComponentElements(\"tabs\")\n .map(el => mountTabs(el, { viewport$, header$ })),\n\n /* Table of contents */\n ...getComponentElements(\"toc\")\n .map(el => mountTableOfContents(el, {\n viewport$, header$, main$, target$\n })),\n\n /* Back-to-top button */\n ...getComponentElements(\"top\")\n .map(el => mountBackToTop(el, { viewport$, header$, main$, target$ }))\n))\n\n/* Set up component observables */\nconst component$ = document$\n .pipe(\n switchMap(() => content$),\n mergeWith(control$),\n shareReplay(1)\n )\n\n/* Subscribe to all components */\ncomponent$.subscribe()\n\n/* ----------------------------------------------------------------------------\n * Exports\n * ------------------------------------------------------------------------- */\n\nwindow.document$ = document$ /* Document observable */\nwindow.location$ = location$ /* Location subject */\nwindow.target$ = target$ /* Location target observable */\nwindow.keyboard$ = keyboard$ /* Keyboard observable */\nwindow.viewport$ = viewport$ /* Viewport observable */\nwindow.tablet$ = tablet$ /* Media tablet observable */\nwindow.screen$ = screen$ /* Media screen observable */\nwindow.print$ = print$ /* Media print observable */\nwindow.alert$ = alert$ /* Alert subject */\nwindow.component$ = component$ /* Component observable */\n", "/*! *****************************************************************************\r\nCopyright (c) Microsoft Corporation.\r\n\r\nPermission to use, copy, modify, and/or distribute this software for any\r\npurpose with or without fee is hereby granted.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\r\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\r\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\r\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\r\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\r\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\r\nPERFORMANCE OF THIS SOFTWARE.\r\n***************************************************************************** */\r\n/* global Reflect, Promise */\r\n\r\nvar extendStatics = function(d, b) {\r\n extendStatics = Object.setPrototypeOf ||\r\n ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||\r\n function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };\r\n return extendStatics(d, b);\r\n};\r\n\r\nexport function __extends(d, b) {\r\n if (typeof b !== \"function\" && b !== null)\r\n throw new TypeError(\"Class extends value \" + String(b) + \" is not a constructor or null\");\r\n extendStatics(d, b);\r\n function __() { this.constructor = d; }\r\n d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());\r\n}\r\n\r\nexport var __assign = function() {\r\n __assign = Object.assign || function __assign(t) {\r\n for (var s, i = 1, n = arguments.length; i < n; i++) {\r\n s = arguments[i];\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];\r\n }\r\n return t;\r\n }\r\n return __assign.apply(this, arguments);\r\n}\r\n\r\nexport function __rest(s, e) {\r\n var t = {};\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)\r\n t[p] = s[p];\r\n if (s != null && typeof Object.getOwnPropertySymbols === \"function\")\r\n for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {\r\n if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))\r\n t[p[i]] = s[p[i]];\r\n }\r\n return t;\r\n}\r\n\r\nexport function __decorate(decorators, target, key, desc) {\r\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\r\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\r\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\r\n return c > 3 && r && Object.defineProperty(target, key, r), r;\r\n}\r\n\r\nexport function __param(paramIndex, decorator) {\r\n return function (target, key) { decorator(target, key, paramIndex); }\r\n}\r\n\r\nexport function __metadata(metadataKey, metadataValue) {\r\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(metadataKey, metadataValue);\r\n}\r\n\r\nexport function __awaiter(thisArg, _arguments, P, generator) {\r\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\r\n return new (P || (P = Promise))(function (resolve, reject) {\r\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\r\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\r\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\r\n step((generator = generator.apply(thisArg, _arguments || [])).next());\r\n });\r\n}\r\n\r\nexport function __generator(thisArg, body) {\r\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;\r\n return g = { next: verb(0), \"throw\": verb(1), \"return\": verb(2) }, typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\r\n function verb(n) { return function (v) { return step([n, v]); }; }\r\n function step(op) {\r\n if (f) throw new TypeError(\"Generator is already executing.\");\r\n while (_) try {\r\n if (f = 1, y && (t = op[0] & 2 ? y[\"return\"] : op[0] ? y[\"throw\"] || ((t = y[\"return\"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;\r\n if (y = 0, t) op = [op[0] & 2, t.value];\r\n switch (op[0]) {\r\n case 0: case 1: t = op; break;\r\n case 4: _.label++; return { value: op[1], done: false };\r\n case 5: _.label++; y = op[1]; op = [0]; continue;\r\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\r\n default:\r\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\r\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\r\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\r\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\r\n if (t[2]) _.ops.pop();\r\n _.trys.pop(); continue;\r\n }\r\n op = body.call(thisArg, _);\r\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\r\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\r\n }\r\n}\r\n\r\nexport var __createBinding = Object.create ? (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });\r\n}) : (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n o[k2] = m[k];\r\n});\r\n\r\nexport function __exportStar(m, o) {\r\n for (var p in m) if (p !== \"default\" && !Object.prototype.hasOwnProperty.call(o, p)) __createBinding(o, m, p);\r\n}\r\n\r\nexport function __values(o) {\r\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\r\n if (m) return m.call(o);\r\n if (o && typeof o.length === \"number\") return {\r\n next: function () {\r\n if (o && i >= o.length) o = void 0;\r\n return { value: o && o[i++], done: !o };\r\n }\r\n };\r\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\r\n}\r\n\r\nexport function __read(o, n) {\r\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\r\n if (!m) return o;\r\n var i = m.call(o), r, ar = [], e;\r\n try {\r\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\r\n }\r\n catch (error) { e = { error: error }; }\r\n finally {\r\n try {\r\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\r\n }\r\n finally { if (e) throw e.error; }\r\n }\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spread() {\r\n for (var ar = [], i = 0; i < arguments.length; i++)\r\n ar = ar.concat(__read(arguments[i]));\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spreadArrays() {\r\n for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;\r\n for (var r = Array(s), k = 0, i = 0; i < il; i++)\r\n for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)\r\n r[k] = a[j];\r\n return r;\r\n}\r\n\r\nexport function __spreadArray(to, from, pack) {\r\n if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {\r\n if (ar || !(i in from)) {\r\n if (!ar) ar = Array.prototype.slice.call(from, 0, i);\r\n ar[i] = from[i];\r\n }\r\n }\r\n return to.concat(ar || Array.prototype.slice.call(from));\r\n}\r\n\r\nexport function __await(v) {\r\n return this instanceof __await ? (this.v = v, this) : new __await(v);\r\n}\r\n\r\nexport function __asyncGenerator(thisArg, _arguments, generator) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var g = generator.apply(thisArg, _arguments || []), i, q = [];\r\n return i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i;\r\n function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }\r\n function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }\r\n function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }\r\n function fulfill(value) { resume(\"next\", value); }\r\n function reject(value) { resume(\"throw\", value); }\r\n function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }\r\n}\r\n\r\nexport function __asyncDelegator(o) {\r\n var i, p;\r\n return i = {}, verb(\"next\"), verb(\"throw\", function (e) { throw e; }), verb(\"return\"), i[Symbol.iterator] = function () { return this; }, i;\r\n function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: n === \"return\" } : f ? f(v) : v; } : f; }\r\n}\r\n\r\nexport function __asyncValues(o) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var m = o[Symbol.asyncIterator], i;\r\n return m ? m.call(o) : (o = typeof __values === \"function\" ? __values(o) : o[Symbol.iterator](), i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i);\r\n function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }\r\n function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }\r\n}\r\n\r\nexport function __makeTemplateObject(cooked, raw) {\r\n if (Object.defineProperty) { Object.defineProperty(cooked, \"raw\", { value: raw }); } else { cooked.raw = raw; }\r\n return cooked;\r\n};\r\n\r\nvar __setModuleDefault = Object.create ? (function(o, v) {\r\n Object.defineProperty(o, \"default\", { enumerable: true, value: v });\r\n}) : function(o, v) {\r\n o[\"default\"] = v;\r\n};\r\n\r\nexport function __importStar(mod) {\r\n if (mod && mod.__esModule) return mod;\r\n var result = {};\r\n if (mod != null) for (var k in mod) if (k !== \"default\" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);\r\n __setModuleDefault(result, mod);\r\n return result;\r\n}\r\n\r\nexport function __importDefault(mod) {\r\n return (mod && mod.__esModule) ? mod : { default: mod };\r\n}\r\n\r\nexport function __classPrivateFieldGet(receiver, state, kind, f) {\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a getter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot read private member from an object whose class did not declare it\");\r\n return kind === \"m\" ? f : kind === \"a\" ? f.call(receiver) : f ? f.value : state.get(receiver);\r\n}\r\n\r\nexport function __classPrivateFieldSet(receiver, state, value, kind, f) {\r\n if (kind === \"m\") throw new TypeError(\"Private method is not writable\");\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a setter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot write private member to an object whose class did not declare it\");\r\n return (kind === \"a\" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;\r\n}\r\n", "/**\n * Returns true if the object is a function.\n * @param value The value to check\n */\nexport function isFunction(value: any): value is (...args: any[]) => any {\n return typeof value === 'function';\n}\n", "/**\n * Used to create Error subclasses until the community moves away from ES5.\n *\n * This is because compiling from TypeScript down to ES5 has issues with subclassing Errors\n * as well as other built-in types: https://github.com/Microsoft/TypeScript/issues/12123\n *\n * @param createImpl A factory function to create the actual constructor implementation. The returned\n * function should be a named function that calls `_super` internally.\n */\nexport function createErrorClass(createImpl: (_super: any) => any): T {\n const _super = (instance: any) => {\n Error.call(instance);\n instance.stack = new Error().stack;\n };\n\n const ctorFunc = createImpl(_super);\n ctorFunc.prototype = Object.create(Error.prototype);\n ctorFunc.prototype.constructor = ctorFunc;\n return ctorFunc;\n}\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface UnsubscriptionError extends Error {\n readonly errors: any[];\n}\n\nexport interface UnsubscriptionErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (errors: any[]): UnsubscriptionError;\n}\n\n/**\n * An error thrown when one or more errors have occurred during the\n * `unsubscribe` of a {@link Subscription}.\n */\nexport const UnsubscriptionError: UnsubscriptionErrorCtor = createErrorClass(\n (_super) =>\n function UnsubscriptionErrorImpl(this: any, errors: (Error | string)[]) {\n _super(this);\n this.message = errors\n ? `${errors.length} errors occurred during unsubscription:\n${errors.map((err, i) => `${i + 1}) ${err.toString()}`).join('\\n ')}`\n : '';\n this.name = 'UnsubscriptionError';\n this.errors = errors;\n }\n);\n", "/**\n * Removes an item from an array, mutating it.\n * @param arr The array to remove the item from\n * @param item The item to remove\n */\nexport function arrRemove(arr: T[] | undefined | null, item: T) {\n if (arr) {\n const index = arr.indexOf(item);\n 0 <= index && arr.splice(index, 1);\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { UnsubscriptionError } from './util/UnsubscriptionError';\nimport { SubscriptionLike, TeardownLogic, Unsubscribable } from './types';\nimport { arrRemove } from './util/arrRemove';\n\n/**\n * Represents a disposable resource, such as the execution of an Observable. A\n * Subscription has one important method, `unsubscribe`, that takes no argument\n * and just disposes the resource held by the subscription.\n *\n * Additionally, subscriptions may be grouped together through the `add()`\n * method, which will attach a child Subscription to the current Subscription.\n * When a Subscription is unsubscribed, all its children (and its grandchildren)\n * will be unsubscribed as well.\n *\n * @class Subscription\n */\nexport class Subscription implements SubscriptionLike {\n /** @nocollapse */\n public static EMPTY = (() => {\n const empty = new Subscription();\n empty.closed = true;\n return empty;\n })();\n\n /**\n * A flag to indicate whether this Subscription has already been unsubscribed.\n */\n public closed = false;\n\n private _parentage: Subscription[] | Subscription | null = null;\n\n /**\n * The list of registered finalizers to execute upon unsubscription. Adding and removing from this\n * list occurs in the {@link #add} and {@link #remove} methods.\n */\n private _finalizers: Exclude[] | null = null;\n\n /**\n * @param initialTeardown A function executed first as part of the finalization\n * process that is kicked off when {@link #unsubscribe} is called.\n */\n constructor(private initialTeardown?: () => void) {}\n\n /**\n * Disposes the resources held by the subscription. May, for instance, cancel\n * an ongoing Observable execution or cancel any other type of work that\n * started when the Subscription was created.\n * @return {void}\n */\n unsubscribe(): void {\n let errors: any[] | undefined;\n\n if (!this.closed) {\n this.closed = true;\n\n // Remove this from it's parents.\n const { _parentage } = this;\n if (_parentage) {\n this._parentage = null;\n if (Array.isArray(_parentage)) {\n for (const parent of _parentage) {\n parent.remove(this);\n }\n } else {\n _parentage.remove(this);\n }\n }\n\n const { initialTeardown: initialFinalizer } = this;\n if (isFunction(initialFinalizer)) {\n try {\n initialFinalizer();\n } catch (e) {\n errors = e instanceof UnsubscriptionError ? e.errors : [e];\n }\n }\n\n const { _finalizers } = this;\n if (_finalizers) {\n this._finalizers = null;\n for (const finalizer of _finalizers) {\n try {\n execFinalizer(finalizer);\n } catch (err) {\n errors = errors ?? [];\n if (err instanceof UnsubscriptionError) {\n errors = [...errors, ...err.errors];\n } else {\n errors.push(err);\n }\n }\n }\n }\n\n if (errors) {\n throw new UnsubscriptionError(errors);\n }\n }\n }\n\n /**\n * Adds a finalizer to this subscription, so that finalization will be unsubscribed/called\n * when this subscription is unsubscribed. If this subscription is already {@link #closed},\n * because it has already been unsubscribed, then whatever finalizer is passed to it\n * will automatically be executed (unless the finalizer itself is also a closed subscription).\n *\n * Closed Subscriptions cannot be added as finalizers to any subscription. Adding a closed\n * subscription to a any subscription will result in no operation. (A noop).\n *\n * Adding a subscription to itself, or adding `null` or `undefined` will not perform any\n * operation at all. (A noop).\n *\n * `Subscription` instances that are added to this instance will automatically remove themselves\n * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove\n * will need to be removed manually with {@link #remove}\n *\n * @param teardown The finalization logic to add to this subscription.\n */\n add(teardown: TeardownLogic): void {\n // Only add the finalizer if it's not undefined\n // and don't add a subscription to itself.\n if (teardown && teardown !== this) {\n if (this.closed) {\n // If this subscription is already closed,\n // execute whatever finalizer is handed to it automatically.\n execFinalizer(teardown);\n } else {\n if (teardown instanceof Subscription) {\n // We don't add closed subscriptions, and we don't add the same subscription\n // twice. Subscription unsubscribe is idempotent.\n if (teardown.closed || teardown._hasParent(this)) {\n return;\n }\n teardown._addParent(this);\n }\n (this._finalizers = this._finalizers ?? []).push(teardown);\n }\n }\n }\n\n /**\n * Checks to see if a this subscription already has a particular parent.\n * This will signal that this subscription has already been added to the parent in question.\n * @param parent the parent to check for\n */\n private _hasParent(parent: Subscription) {\n const { _parentage } = this;\n return _parentage === parent || (Array.isArray(_parentage) && _parentage.includes(parent));\n }\n\n /**\n * Adds a parent to this subscription so it can be removed from the parent if it\n * unsubscribes on it's own.\n *\n * NOTE: THIS ASSUMES THAT {@link _hasParent} HAS ALREADY BEEN CHECKED.\n * @param parent The parent subscription to add\n */\n private _addParent(parent: Subscription) {\n const { _parentage } = this;\n this._parentage = Array.isArray(_parentage) ? (_parentage.push(parent), _parentage) : _parentage ? [_parentage, parent] : parent;\n }\n\n /**\n * Called on a child when it is removed via {@link #remove}.\n * @param parent The parent to remove\n */\n private _removeParent(parent: Subscription) {\n const { _parentage } = this;\n if (_parentage === parent) {\n this._parentage = null;\n } else if (Array.isArray(_parentage)) {\n arrRemove(_parentage, parent);\n }\n }\n\n /**\n * Removes a finalizer from this subscription that was previously added with the {@link #add} method.\n *\n * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves\n * from every other `Subscription` they have been added to. This means that using the `remove` method\n * is not a common thing and should be used thoughtfully.\n *\n * If you add the same finalizer instance of a function or an unsubscribable object to a `Subscription` instance\n * more than once, you will need to call `remove` the same number of times to remove all instances.\n *\n * All finalizer instances are removed to free up memory upon unsubscription.\n *\n * @param teardown The finalizer to remove from this subscription\n */\n remove(teardown: Exclude): void {\n const { _finalizers } = this;\n _finalizers && arrRemove(_finalizers, teardown);\n\n if (teardown instanceof Subscription) {\n teardown._removeParent(this);\n }\n }\n}\n\nexport const EMPTY_SUBSCRIPTION = Subscription.EMPTY;\n\nexport function isSubscription(value: any): value is Subscription {\n return (\n value instanceof Subscription ||\n (value && 'closed' in value && isFunction(value.remove) && isFunction(value.add) && isFunction(value.unsubscribe))\n );\n}\n\nfunction execFinalizer(finalizer: Unsubscribable | (() => void)) {\n if (isFunction(finalizer)) {\n finalizer();\n } else {\n finalizer.unsubscribe();\n }\n}\n", "import { Subscriber } from './Subscriber';\nimport { ObservableNotification } from './types';\n\n/**\n * The {@link GlobalConfig} object for RxJS. It is used to configure things\n * like how to react on unhandled errors.\n */\nexport const config: GlobalConfig = {\n onUnhandledError: null,\n onStoppedNotification: null,\n Promise: undefined,\n useDeprecatedSynchronousErrorHandling: false,\n useDeprecatedNextContext: false,\n};\n\n/**\n * The global configuration object for RxJS, used to configure things\n * like how to react on unhandled errors. Accessible via {@link config}\n * object.\n */\nexport interface GlobalConfig {\n /**\n * A registration point for unhandled errors from RxJS. These are errors that\n * cannot were not handled by consuming code in the usual subscription path. For\n * example, if you have this configured, and you subscribe to an observable without\n * providing an error handler, errors from that subscription will end up here. This\n * will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onUnhandledError: ((err: any) => void) | null;\n\n /**\n * A registration point for notifications that cannot be sent to subscribers because they\n * have completed, errored or have been explicitly unsubscribed. By default, next, complete\n * and error notifications sent to stopped subscribers are noops. However, sometimes callers\n * might want a different behavior. For example, with sources that attempt to report errors\n * to stopped subscribers, a caller can configure RxJS to throw an unhandled error instead.\n * This will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onStoppedNotification: ((notification: ObservableNotification, subscriber: Subscriber) => void) | null;\n\n /**\n * The promise constructor used by default for {@link Observable#toPromise toPromise} and {@link Observable#forEach forEach}\n * methods.\n *\n * @deprecated As of version 8, RxJS will no longer support this sort of injection of a\n * Promise constructor. If you need a Promise implementation other than native promises,\n * please polyfill/patch Promise as you see appropriate. Will be removed in v8.\n */\n Promise?: PromiseConstructorLike;\n\n /**\n * If true, turns on synchronous error rethrowing, which is a deprecated behavior\n * in v6 and higher. This behavior enables bad patterns like wrapping a subscribe\n * call in a try/catch block. It also enables producer interference, a nasty bug\n * where a multicast can be broken for all observers by a downstream consumer with\n * an unhandled error. DO NOT USE THIS FLAG UNLESS IT'S NEEDED TO BUY TIME\n * FOR MIGRATION REASONS.\n *\n * @deprecated As of version 8, RxJS will no longer support synchronous throwing\n * of unhandled errors. All errors will be thrown on a separate call stack to prevent bad\n * behaviors described above. Will be removed in v8.\n */\n useDeprecatedSynchronousErrorHandling: boolean;\n\n /**\n * If true, enables an as-of-yet undocumented feature from v5: The ability to access\n * `unsubscribe()` via `this` context in `next` functions created in observers passed\n * to `subscribe`.\n *\n * This is being removed because the performance was severely problematic, and it could also cause\n * issues when types other than POJOs are passed to subscribe as subscribers, as they will likely have\n * their `this` context overwritten.\n *\n * @deprecated As of version 8, RxJS will no longer support altering the\n * context of next functions provided as part of an observer to Subscribe. Instead,\n * you will have access to a subscription or a signal or token that will allow you to do things like\n * unsubscribe and test closed status. Will be removed in v8.\n */\n useDeprecatedNextContext: boolean;\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetTimeoutFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearTimeoutFunction = (handle: TimerHandle) => void;\n\ninterface TimeoutProvider {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n delegate:\n | {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n }\n | undefined;\n}\n\nexport const timeoutProvider: TimeoutProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setTimeout(handler: () => void, timeout?: number, ...args) {\n const { delegate } = timeoutProvider;\n if (delegate?.setTimeout) {\n return delegate.setTimeout(handler, timeout, ...args);\n }\n return setTimeout(handler, timeout, ...args);\n },\n clearTimeout(handle) {\n const { delegate } = timeoutProvider;\n return (delegate?.clearTimeout || clearTimeout)(handle as any);\n },\n delegate: undefined,\n};\n", "import { config } from '../config';\nimport { timeoutProvider } from '../scheduler/timeoutProvider';\n\n/**\n * Handles an error on another job either with the user-configured {@link onUnhandledError},\n * or by throwing it on that new job so it can be picked up by `window.onerror`, `process.on('error')`, etc.\n *\n * This should be called whenever there is an error that is out-of-band with the subscription\n * or when an error hits a terminal boundary of the subscription and no error handler was provided.\n *\n * @param err the error to report\n */\nexport function reportUnhandledError(err: any) {\n timeoutProvider.setTimeout(() => {\n const { onUnhandledError } = config;\n if (onUnhandledError) {\n // Execute the user-configured error handler.\n onUnhandledError(err);\n } else {\n // Throw so it is picked up by the runtime's uncaught error mechanism.\n throw err;\n }\n });\n}\n", "/* tslint:disable:no-empty */\nexport function noop() { }\n", "import { CompleteNotification, NextNotification, ErrorNotification } from './types';\n\n/**\n * A completion object optimized for memory use and created to be the\n * same \"shape\" as other notifications in v8.\n * @internal\n */\nexport const COMPLETE_NOTIFICATION = (() => createNotification('C', undefined, undefined) as CompleteNotification)();\n\n/**\n * Internal use only. Creates an optimized error notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function errorNotification(error: any): ErrorNotification {\n return createNotification('E', undefined, error) as any;\n}\n\n/**\n * Internal use only. Creates an optimized next notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function nextNotification(value: T) {\n return createNotification('N', value, undefined) as NextNotification;\n}\n\n/**\n * Ensures that all notifications created internally have the same \"shape\" in v8.\n *\n * TODO: This is only exported to support a crazy legacy test in `groupBy`.\n * @internal\n */\nexport function createNotification(kind: 'N' | 'E' | 'C', value: any, error: any) {\n return {\n kind,\n value,\n error,\n };\n}\n", "import { config } from '../config';\n\nlet context: { errorThrown: boolean; error: any } | null = null;\n\n/**\n * Handles dealing with errors for super-gross mode. Creates a context, in which\n * any synchronously thrown errors will be passed to {@link captureError}. Which\n * will record the error such that it will be rethrown after the call back is complete.\n * TODO: Remove in v8\n * @param cb An immediately executed function.\n */\nexport function errorContext(cb: () => void) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n const isRoot = !context;\n if (isRoot) {\n context = { errorThrown: false, error: null };\n }\n cb();\n if (isRoot) {\n const { errorThrown, error } = context!;\n context = null;\n if (errorThrown) {\n throw error;\n }\n }\n } else {\n // This is the general non-deprecated path for everyone that\n // isn't crazy enough to use super-gross mode (useDeprecatedSynchronousErrorHandling)\n cb();\n }\n}\n\n/**\n * Captures errors only in super-gross mode.\n * @param err the error to capture\n */\nexport function captureError(err: any) {\n if (config.useDeprecatedSynchronousErrorHandling && context) {\n context.errorThrown = true;\n context.error = err;\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { Observer, ObservableNotification } from './types';\nimport { isSubscription, Subscription } from './Subscription';\nimport { config } from './config';\nimport { reportUnhandledError } from './util/reportUnhandledError';\nimport { noop } from './util/noop';\nimport { nextNotification, errorNotification, COMPLETE_NOTIFICATION } from './NotificationFactories';\nimport { timeoutProvider } from './scheduler/timeoutProvider';\nimport { captureError } from './util/errorContext';\n\n/**\n * Implements the {@link Observer} interface and extends the\n * {@link Subscription} class. While the {@link Observer} is the public API for\n * consuming the values of an {@link Observable}, all Observers get converted to\n * a Subscriber, in order to provide Subscription-like capabilities such as\n * `unsubscribe`. Subscriber is a common type in RxJS, and crucial for\n * implementing operators, but it is rarely used as a public API.\n *\n * @class Subscriber\n */\nexport class Subscriber extends Subscription implements Observer {\n /**\n * A static factory for a Subscriber, given a (potentially partial) definition\n * of an Observer.\n * @param next The `next` callback of an Observer.\n * @param error The `error` callback of an\n * Observer.\n * @param complete The `complete` callback of an\n * Observer.\n * @return A Subscriber wrapping the (partially defined)\n * Observer represented by the given arguments.\n * @nocollapse\n * @deprecated Do not use. Will be removed in v8. There is no replacement for this\n * method, and there is no reason to be creating instances of `Subscriber` directly.\n * If you have a specific use case, please file an issue.\n */\n static create(next?: (x?: T) => void, error?: (e?: any) => void, complete?: () => void): Subscriber {\n return new SafeSubscriber(next, error, complete);\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected isStopped: boolean = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected destination: Subscriber | Observer; // this `any` is the escape hatch to erase extra type param (e.g. R)\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * There is no reason to directly create an instance of Subscriber. This type is exported for typings reasons.\n */\n constructor(destination?: Subscriber | Observer) {\n super();\n if (destination) {\n this.destination = destination;\n // Automatically chain subscriptions together here.\n // if destination is a Subscription, then it is a Subscriber.\n if (isSubscription(destination)) {\n destination.add(this);\n }\n } else {\n this.destination = EMPTY_OBSERVER;\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `next` from\n * the Observable, with a value. The Observable may call this method 0 or more\n * times.\n * @param {T} [value] The `next` value.\n * @return {void}\n */\n next(value?: T): void {\n if (this.isStopped) {\n handleStoppedNotification(nextNotification(value), this);\n } else {\n this._next(value!);\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `error` from\n * the Observable, with an attached `Error`. Notifies the Observer that\n * the Observable has experienced an error condition.\n * @param {any} [err] The `error` exception.\n * @return {void}\n */\n error(err?: any): void {\n if (this.isStopped) {\n handleStoppedNotification(errorNotification(err), this);\n } else {\n this.isStopped = true;\n this._error(err);\n }\n }\n\n /**\n * The {@link Observer} callback to receive a valueless notification of type\n * `complete` from the Observable. Notifies the Observer that the Observable\n * has finished sending push-based notifications.\n * @return {void}\n */\n complete(): void {\n if (this.isStopped) {\n handleStoppedNotification(COMPLETE_NOTIFICATION, this);\n } else {\n this.isStopped = true;\n this._complete();\n }\n }\n\n unsubscribe(): void {\n if (!this.closed) {\n this.isStopped = true;\n super.unsubscribe();\n this.destination = null!;\n }\n }\n\n protected _next(value: T): void {\n this.destination.next(value);\n }\n\n protected _error(err: any): void {\n try {\n this.destination.error(err);\n } finally {\n this.unsubscribe();\n }\n }\n\n protected _complete(): void {\n try {\n this.destination.complete();\n } finally {\n this.unsubscribe();\n }\n }\n}\n\n/**\n * This bind is captured here because we want to be able to have\n * compatibility with monoid libraries that tend to use a method named\n * `bind`. In particular, a library called Monio requires this.\n */\nconst _bind = Function.prototype.bind;\n\nfunction bind any>(fn: Fn, thisArg: any): Fn {\n return _bind.call(fn, thisArg);\n}\n\n/**\n * Internal optimization only, DO NOT EXPOSE.\n * @internal\n */\nclass ConsumerObserver implements Observer {\n constructor(private partialObserver: Partial>) {}\n\n next(value: T): void {\n const { partialObserver } = this;\n if (partialObserver.next) {\n try {\n partialObserver.next(value);\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n\n error(err: any): void {\n const { partialObserver } = this;\n if (partialObserver.error) {\n try {\n partialObserver.error(err);\n } catch (error) {\n handleUnhandledError(error);\n }\n } else {\n handleUnhandledError(err);\n }\n }\n\n complete(): void {\n const { partialObserver } = this;\n if (partialObserver.complete) {\n try {\n partialObserver.complete();\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n}\n\nexport class SafeSubscriber extends Subscriber {\n constructor(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((e?: any) => void) | null,\n complete?: (() => void) | null\n ) {\n super();\n\n let partialObserver: Partial>;\n if (isFunction(observerOrNext) || !observerOrNext) {\n // The first argument is a function, not an observer. The next\n // two arguments *could* be observers, or they could be empty.\n partialObserver = {\n next: (observerOrNext ?? undefined) as (((value: T) => void) | undefined),\n error: error ?? undefined,\n complete: complete ?? undefined,\n };\n } else {\n // The first argument is a partial observer.\n let context: any;\n if (this && config.useDeprecatedNextContext) {\n // This is a deprecated path that made `this.unsubscribe()` available in\n // next handler functions passed to subscribe. This only exists behind a flag\n // now, as it is *very* slow.\n context = Object.create(observerOrNext);\n context.unsubscribe = () => this.unsubscribe();\n partialObserver = {\n next: observerOrNext.next && bind(observerOrNext.next, context),\n error: observerOrNext.error && bind(observerOrNext.error, context),\n complete: observerOrNext.complete && bind(observerOrNext.complete, context),\n };\n } else {\n // The \"normal\" path. Just use the partial observer directly.\n partialObserver = observerOrNext;\n }\n }\n\n // Wrap the partial observer to ensure it's a full observer, and\n // make sure proper error handling is accounted for.\n this.destination = new ConsumerObserver(partialObserver);\n }\n}\n\nfunction handleUnhandledError(error: any) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n captureError(error);\n } else {\n // Ideal path, we report this as an unhandled error,\n // which is thrown on a new call stack.\n reportUnhandledError(error);\n }\n}\n\n/**\n * An error handler used when no error handler was supplied\n * to the SafeSubscriber -- meaning no error handler was supplied\n * do the `subscribe` call on our observable.\n * @param err The error to handle\n */\nfunction defaultErrorHandler(err: any) {\n throw err;\n}\n\n/**\n * A handler for notifications that cannot be sent to a stopped subscriber.\n * @param notification The notification being sent\n * @param subscriber The stopped subscriber\n */\nfunction handleStoppedNotification(notification: ObservableNotification, subscriber: Subscriber) {\n const { onStoppedNotification } = config;\n onStoppedNotification && timeoutProvider.setTimeout(() => onStoppedNotification(notification, subscriber));\n}\n\n/**\n * The observer used as a stub for subscriptions where the user did not\n * pass any arguments to `subscribe`. Comes with the default error handling\n * behavior.\n */\nexport const EMPTY_OBSERVER: Readonly> & { closed: true } = {\n closed: true,\n next: noop,\n error: defaultErrorHandler,\n complete: noop,\n};\n", "/**\n * Symbol.observable or a string \"@@observable\". Used for interop\n *\n * @deprecated We will no longer be exporting this symbol in upcoming versions of RxJS.\n * Instead polyfill and use Symbol.observable directly *or* use https://www.npmjs.com/package/symbol-observable\n */\nexport const observable: string | symbol = (() => (typeof Symbol === 'function' && Symbol.observable) || '@@observable')();\n", "/**\n * This function takes one parameter and just returns it. Simply put,\n * this is like `(x: T): T => x`.\n *\n * ## Examples\n *\n * This is useful in some cases when using things like `mergeMap`\n *\n * ```ts\n * import { interval, take, map, range, mergeMap, identity } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(5));\n *\n * const result$ = source$.pipe(\n * map(i => range(i)),\n * mergeMap(identity) // same as mergeMap(x => x)\n * );\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * Or when you want to selectively apply an operator\n *\n * ```ts\n * import { interval, take, identity } from 'rxjs';\n *\n * const shouldLimit = () => Math.random() < 0.5;\n *\n * const source$ = interval(1000);\n *\n * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * @param x Any value that is returned by this function\n * @returns The value passed as the first parameter to this function\n */\nexport function identity(x: T): T {\n return x;\n}\n", "import { identity } from './identity';\nimport { UnaryFunction } from '../types';\n\nexport function pipe(): typeof identity;\nexport function pipe(fn1: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction, fn3: UnaryFunction): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction,\n ...fns: UnaryFunction[]\n): UnaryFunction;\n\n/**\n * pipe() can be called on one or more functions, each of which can take one argument (\"UnaryFunction\")\n * and uses it to return a value.\n * It returns a function that takes one argument, passes it to the first UnaryFunction, and then\n * passes the result to the next one, passes that result to the next one, and so on. \n */\nexport function pipe(...fns: Array>): UnaryFunction {\n return pipeFromArray(fns);\n}\n\n/** @internal */\nexport function pipeFromArray(fns: Array>): UnaryFunction {\n if (fns.length === 0) {\n return identity as UnaryFunction;\n }\n\n if (fns.length === 1) {\n return fns[0];\n }\n\n return function piped(input: T): R {\n return fns.reduce((prev: any, fn: UnaryFunction) => fn(prev), input as any);\n };\n}\n", "import { Operator } from './Operator';\nimport { SafeSubscriber, Subscriber } from './Subscriber';\nimport { isSubscription, Subscription } from './Subscription';\nimport { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';\nimport { observable as Symbol_observable } from './symbol/observable';\nimport { pipeFromArray } from './util/pipe';\nimport { config } from './config';\nimport { isFunction } from './util/isFunction';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A representation of any set of values over any amount of time. This is the most basic building block\n * of RxJS.\n *\n * @class Observable\n */\nexport class Observable implements Subscribable {\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n source: Observable | undefined;\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n operator: Operator | undefined;\n\n /**\n * @constructor\n * @param {Function} subscribe the function that is called when the Observable is\n * initially subscribed to. This function is given a Subscriber, to which new values\n * can be `next`ed, or an `error` method can be called to raise an error, or\n * `complete` can be called to notify of a successful completion.\n */\n constructor(subscribe?: (this: Observable, subscriber: Subscriber) => TeardownLogic) {\n if (subscribe) {\n this._subscribe = subscribe;\n }\n }\n\n // HACK: Since TypeScript inherits static properties too, we have to\n // fight against TypeScript here so Subject can have a different static create signature\n /**\n * Creates a new Observable by calling the Observable constructor\n * @owner Observable\n * @method create\n * @param {Function} subscribe? the subscriber function to be passed to the Observable constructor\n * @return {Observable} a new observable\n * @nocollapse\n * @deprecated Use `new Observable()` instead. Will be removed in v8.\n */\n static create: (...args: any[]) => any = (subscribe?: (subscriber: Subscriber) => TeardownLogic) => {\n return new Observable(subscribe);\n };\n\n /**\n * Creates a new Observable, with this Observable instance as the source, and the passed\n * operator defined as the new observable's operator.\n * @method lift\n * @param operator the operator defining the operation to take on the observable\n * @return a new observable with the Operator applied\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * If you have implemented an operator using `lift`, it is recommended that you create an\n * operator by simply returning `new Observable()` directly. See \"Creating new operators from\n * scratch\" section here: https://rxjs.dev/guide/operators\n */\n lift(operator?: Operator): Observable {\n const observable = new Observable();\n observable.source = this;\n observable.operator = operator;\n return observable;\n }\n\n subscribe(observerOrNext?: Partial> | ((value: T) => void)): Subscription;\n /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */\n subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;\n /**\n * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.\n *\n * Use it when you have all these Observables, but still nothing is happening. \n *\n * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It\n * might be for example a function that you passed to Observable's constructor, but most of the time it is\n * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means\n * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often\n * the thought.\n *\n * Apart from starting the execution of an Observable, this method allows you to listen for values\n * that an Observable emits, as well as for when it completes or errors. You can achieve this in two\n * of the following ways.\n *\n * The first way is creating an object that implements {@link Observer} interface. It should have methods\n * defined by that interface, but note that it should be just a regular JavaScript object, which you can create\n * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do\n * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also\n * that your object does not have to implement all methods. If you find yourself creating a method that doesn't\n * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,\n * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,\n * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or\n * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide\n * an `error` method to avoid missing thrown errors.\n *\n * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.\n * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent\n * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,\n * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,\n * since `subscribe` recognizes these functions by where they were placed in function call. When it comes\n * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.\n *\n * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events\n * and you also handled emissions internally by using operators (e.g. using `tap`).\n *\n * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.\n * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean\n * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback\n * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.\n *\n * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.\n * It is an Observable itself that decides when these functions will be called. For example {@link of}\n * by default emits all its values synchronously. Always check documentation for how given Observable\n * will behave when subscribed and if its default behavior can be modified with a `scheduler`.\n *\n * #### Examples\n *\n * Subscribe with an {@link guide/observer Observer}\n *\n * ```ts\n * import { of } from 'rxjs';\n *\n * const sumObserver = {\n * sum: 0,\n * next(value) {\n * console.log('Adding: ' + value);\n * this.sum = this.sum + value;\n * },\n * error() {\n * // We actually could just remove this method,\n * // since we do not really care about errors right now.\n * },\n * complete() {\n * console.log('Sum equals: ' + this.sum);\n * }\n * };\n *\n * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.\n * .subscribe(sumObserver);\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})\n *\n * ```ts\n * import { of } from 'rxjs'\n *\n * let sum = 0;\n *\n * of(1, 2, 3).subscribe(\n * value => {\n * console.log('Adding: ' + value);\n * sum = sum + value;\n * },\n * undefined,\n * () => console.log('Sum equals: ' + sum)\n * );\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Cancel a subscription\n *\n * ```ts\n * import { interval } from 'rxjs';\n *\n * const subscription = interval(1000).subscribe({\n * next(num) {\n * console.log(num)\n * },\n * complete() {\n * // Will not be called, even when cancelling subscription.\n * console.log('completed!');\n * }\n * });\n *\n * setTimeout(() => {\n * subscription.unsubscribe();\n * console.log('unsubscribed!');\n * }, 2500);\n *\n * // Logs:\n * // 0 after 1s\n * // 1 after 2s\n * // 'unsubscribed!' after 2.5s\n * ```\n *\n * @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,\n * or the first of three possible handlers, which is the handler for each value emitted from the subscribed\n * Observable.\n * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,\n * the error will be thrown asynchronously as unhandled.\n * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.\n * @return {Subscription} a subscription reference to the registered handlers\n * @method subscribe\n */\n subscribe(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((error: any) => void) | null,\n complete?: (() => void) | null\n ): Subscription {\n const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);\n\n errorContext(() => {\n const { operator, source } = this;\n subscriber.add(\n operator\n ? // We're dealing with a subscription in the\n // operator chain to one of our lifted operators.\n operator.call(subscriber, source)\n : source\n ? // If `source` has a value, but `operator` does not, something that\n // had intimate knowledge of our API, like our `Subject`, must have\n // set it. We're going to just call `_subscribe` directly.\n this._subscribe(subscriber)\n : // In all other cases, we're likely wrapping a user-provided initializer\n // function, so we need to catch errors and handle them appropriately.\n this._trySubscribe(subscriber)\n );\n });\n\n return subscriber;\n }\n\n /** @internal */\n protected _trySubscribe(sink: Subscriber): TeardownLogic {\n try {\n return this._subscribe(sink);\n } catch (err) {\n // We don't need to return anything in this case,\n // because it's just going to try to `add()` to a subscription\n // above.\n sink.error(err);\n }\n }\n\n /**\n * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with\n * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * #### Example\n *\n * ```ts\n * import { interval, take } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(4));\n *\n * async function getTotal() {\n * let total = 0;\n *\n * await source$.forEach(value => {\n * total += value;\n * console.log('observable -> ' + value);\n * });\n *\n * return total;\n * }\n *\n * getTotal().then(\n * total => console.log('Total: ' + total)\n * );\n *\n * // Expected:\n * // 'observable -> 0'\n * // 'observable -> 1'\n * // 'observable -> 2'\n * // 'observable -> 3'\n * // 'Total: 6'\n * ```\n *\n * @param next a handler for each value emitted by the observable\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n */\n forEach(next: (value: T) => void): Promise;\n\n /**\n * @param next a handler for each value emitted by the observable\n * @param promiseCtor a constructor function used to instantiate the Promise\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n * @deprecated Passing a Promise constructor will no longer be available\n * in upcoming versions of RxJS. This is because it adds weight to the library, for very\n * little benefit. If you need this functionality, it is recommended that you either\n * polyfill Promise, or you create an adapter to convert the returned native promise\n * to whatever promise implementation you wanted. Will be removed in v8.\n */\n forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise;\n\n forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n const subscriber = new SafeSubscriber({\n next: (value) => {\n try {\n next(value);\n } catch (err) {\n reject(err);\n subscriber.unsubscribe();\n }\n },\n error: reject,\n complete: resolve,\n });\n this.subscribe(subscriber);\n }) as Promise;\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): TeardownLogic {\n return this.source?.subscribe(subscriber);\n }\n\n /**\n * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable\n * @method Symbol.observable\n * @return {Observable} this instance of the observable\n */\n [Symbol_observable]() {\n return this;\n }\n\n /* tslint:disable:max-line-length */\n pipe(): Observable;\n pipe(op1: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction, op3: OperatorFunction): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction
- 
- 
@@ -122,18 +113,15 @@
- 
- 
+ /> -->
@@ -143,6 +131,36 @@
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 