` must be set to an identifier for associating authors\n with posts, e.g., a GitHub username like `squidfunk`. This identifier can\n then be used in the [`authors`][meta.authors] metadata property of\n a post. Multiple authors are supported. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable automatically generated author profiles.\nAn author profile shows all posts by an author in reverse chronological order.\nYou can enable author profiles with:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the authors section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_name: Authors\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\nauthor profile URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/author/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"author/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]\n- `name` – Author name from [`authors_file`][config.authors_file]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for author profiles. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\nauthor profiles. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_toc: true\n```\n\n### Pagination\n\nThe following settings are available for pagination:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination in views – generated pages\nthat show posts or subsets of posts in reverse chronological order. If you want\nto disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per page. If you have\nrather long post excerpts, it can be a good idea to reduce the number of posts\nper page:\n\n``` yaml\nplugins:\n - blog:\n pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\npaginated view URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/page/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"page/{page}\"\n ```\n\n=== \":material-link: blog/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"{page}\"\n ```\n\nThe following placeholders are available:\n\n- `page` – Page number\n\n---\n\n#### \n\n\n\n\nThe plugin uses the [paginate] module to generate the pagination markup using a\nspecial syntax. Use this setting to customize how pagination is constructed.\nSome popular choices:\n\n=== \"1 2 3 .. n\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"~2~\"\n ```\n\n=== \"1 2 3 .. n :material-chevron-right: :material-chevron-double-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_first $link_previous ~2~ $link_next $link_last\"\n ```\n\n=== \"1 :material-chevron-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_previous $page $link_next\"\n ```\n\nThe following placeholders are supported by [paginate]:\n\n- `#!css $first_page` – Number of first reachable page\n- `#!css $last_page` – Number of last reachable page\n- `#!css $page` – Number of currently selected page\n- `#!css $page_count` – Number of reachable pages\n- `#!css $items_per_page` – Maximal number of items per page\n- `#!css $first_item` – Index of first item on the current page\n- `#!css $last_item` – Index of last item on the current page\n- `#!css $item_count` – Total number of items\n- `#!css $link_first` – Link to first page (unless on first page)\n- `#!css $link_last` – Link to last page (unless on last page)\n- `#!css $link_previous` – Link to previous page (unless on first page)\n- `#!css $link_next` – Link to next page (unless on last page)\n\n [paginate]: https://pypi.org/project/paginate/\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether pagination should be automatically disabled\nwhen the view only consists of a single page. If you want to always render\npagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_if_single_page: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable persistence of content, i.e., if paginated\nviews should also display the content of their containing view. If you want to\nenable this behavior, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_keep_content: true\n```\n\n### Drafts\n\nThe following settings are available for drafts:\n\n---\n\n#### \n\n\n\n\nRendering [draft posts][meta.draft] can be useful in deploy previews. Use this\nsetting to specify whether the plugin should include posts marked as drafts when\n[building your project]:\n\n=== \"Render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: true\n ```\n\n=== \"Don't render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include posts marked as\ndrafts when [previewing your site]. If you don't wish to include draft posts\nwhen previewing, use:\n\n``` yaml\nplugins:\n - blog:\n draft_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin can automatically mark posts with future dates as drafts. When the\ndate is past today, the post is automatically included when\n[building your project], unless explicitly marked as draft:\n\n``` yaml\nplugins:\n - blog:\n draft_if_future_date: true\n```\n\n## Usage\n\n### Metadata\n\nPosts can define a handful of metadata properties that specify how the plugin\nrenders them, in which views they are integrated, and how they are linked to\neach other. The metadata of each post is validated against a schema to allow for\na quicker discovery of syntax errors.\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with [authors] by providing a list of\nidentifiers as defined in the [`authors_file`][config.authors_file]. If an\nauthor can't be resolved, the plugin will terminate with an error:\n\n``` yaml\n---\nauthors:\n - squidfunk # (1)!\n---\n\n# Post title\n...\n```\n\n1. Authors are linked by using their identifiers. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [authors]: #authors\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with one or more [categories][category],\nmaking the post a part of the generated category page. Categories are defined\nas a list of strings (whitespaces are allowed):\n\n``` yaml\n---\ncategories:\n - Search\n - Performance\n---\n\n# Post title\n...\n```\n\nIf you want to prevent accidental typos assigning categories to posts, you\ncan set a predefined list of allowed categories in `mkdocs.yml` by using\nthe [`categories_allowed`][config.categories_allowed] setting.\n\n---\n\n#### \n\n\n\n\n\nUse this property to specify a post's date. Note that this property is required,\nwhich means the build fails when it's not set. Additional dates can be set by\nusing a slightly different syntax:\n\n=== \"Date\"\n\n ``` yaml\n ---\n date: 2024-01-31\n ---\n\n # Post title\n ...\n ```\n\n=== \"Update date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31 # (1)!\n updated: 2024-02-01\n ---\n\n # Post title\n ...\n ```\n\n 1. Each post must have a creation date set.\n\n=== \"Custom date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31\n my_custom_date: 2024-02-01 # (1)!\n ---\n\n # Post title\n ...\n ```\n\n 1. The blog plugin validates all dates and allows to format them with\n [babel]'s [pattern syntax] in templates. When using theme extension,\n authors can add custom dates to templates.\n\n This was first requested in #5733.\n\nThe following date formats are supported:\n\n- `2024-01-31`\n- `2024-01-31T12:00:00`\n\n---\n\n#### \n\n\n\n\n\nUse this property to mark a post as draft. The plugin allows to include or\nexclude posts marked as drafts when [building your project] using the\n[`draft`][config.draft] setting. Mark a post as draft with:\n\n``` yaml\n---\ndraft: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to pin a post to the top of a view. In case multiple posts are\npinned, the pinned posts are sorted by descending order and appear before all\nother posts. Pin a post with:\n\n``` yaml\n---\npin: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to define a list of links that are rendered in the sidebar of\na post. The property follows the same syntax as [`nav`][mkdocs.nav] in\n`mkdocs.yml`, supporting sections and even anchors:\n\n=== \"Links\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - insiders/index.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with sections\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - Insiders:\n - insiders/index.md\n - insiders/getting-started.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with anchors\"\n\n ``` yaml\n ---\n links:\n - plugins/search.md # (1)!\n - Insiders:\n - insiders/how-to-sponsor.md\n - insiders/getting-started.md#requirements\n ---\n\n # Post title\n ...\n ```\n\n 1. If a link defines an anchor, the plugin resolves the anchor from the\n linked page and sets the anchor title as a [subtitle].\n\nAll relative links are resolved from the [`docs` directory][mkdocs.docs_dir].\n\n [subtitle]: ../reference/index.md#setting-the-page-subtitle\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the reading time of a post in minutes. When\n[`post_readtime`][config.post_readtime] is enabled, the plugin computes the\nreading time of a post, which can be overridden with:\n\n``` yaml\n---\nreadtime: 15\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the slug of a post. By default, the slug of\na post is automatically computed by the [`post_slugify`][config.post_slugify]\nfunction from the post's title, which can be overridden with:\n\n``` yaml\n---\nslug: help-im-trapped-in-a-universe-factory\n---\n\n# Post title\n...\n```\n\nSlugs are passed to [`post_url_format`][config.post_url_format].\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up your blog or migrating from another blog framework, you\n might discover that you're missing specific functionality – we're happy to\n consider adding it to the plugin! You can [open a discussion] to\n ask a question, or create a [change request] on our [issue tracker], so we\n can find out if it might be a good fit for the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","docs/plugins/group.md":"---\ntitle: Built-in group plugin\nicon: material/format-list-group\n---\n\n# Built-in group plugin\n\nThe group plugin allows to group plugins into logical units to conditionally\nenable or disable them for specific environments with the use of\n[environment variables][mkdocs.env], e.g., to only enable a subset of\nplugins when [building your project] during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin conditionally and lazily loads all plugins that are part of a group\nif and only if the group is enabled, which means that the plugin doesn't add any\noverhead when the group is disabled. It also means that the grouped plugins\nonly need to be installed when the group is enabled.\n\nThe plugins that are part of the group are executed in the same order as if\nthey were defined at the top-level in the list of [`plugins`][mkdocs.plugins].\nThus, order is preserved and deterministic.\n\n### When to use it\n\nWhenever you're using multiple plugins that are only required in specific\nenvironments, e.g., when building your project during continuous integration\n(CI), the plugin is the perfect utility for making configuration simpler, as it\nremoves the need for splitting configuration into multiple files.\n\nIt can be used with any built-in or third-party plugin.\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the group plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nsplitting plugins into logical units:\n\n``` yaml\nplugins:\n - group\n```\n\nThe group plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [group]: group.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nThe plugin behaves differently than all other built-in plugins – __it is\ndisabled by default__. To enable a group, use:\n\n``` yaml\nplugins:\n - group:\n enabled: !ENV CI # (1)!\n```\n\n1. If you only want to use the group plugin for better organization and\n always want to enable the plugins that are part of it, use:\n\n ``` yaml\n plugins:\n - group:\n enabled: true\n ```\n\nThe decision to disable the plugin by default was made to simplify the usage\nof environment variables, as it removes the need to provide a default value for\nan environment variable.\n\nNow, when [building your project], you can enable a group by setting the\n[environment variable][mkdocs.env]:\n\n``` sh\nCI=true mkdocs build\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to list the plugins that are part of the group. The syntax is\nexactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can\nsimply copy the list of plugins that you want to group, e.g:\n\n``` yaml\nplugins:\n - group:\n plugins:\n - optimize\n - minify\n```\n\nThe plugins mentioned here are just used for illustration purposes.\n","docs/plugins/offline.md":"---\ntitle: Built-in offline plugin\nicon: material/connection\n---\n\n\n# Built-in offline plugin\n\n[MkDocs][mkdocs] is one of the few frameworks that supports building\noffline-capable documentation that can be directly viewed by the user – no\nserver needed. With the offline plugin, you can distribute the\n[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while\nretaining most interactive functionality.\n\n## Objective\n\n### How it works\n\nAfter [building your project], switch to the [`site` directory][mkdocs.site_dir]\nand open `index.html` in your browser – you're now viewing your documentation\nfrom your local file system! Most browsers will denote this by showing `file://`\nin the address bar. However, you'll realize that the site search is gone.\n\nMaterial for MkDocs offers many interactive features, some of which will not\nwork from the local file system due to the restrictions of modern browsers. More\nspecifically and technically, all calls to the [Fetch API] will error with a\nmessage like:\n\n```\nCross origin requests are only supported for protocol schemes: http, [...]\n```\n\nWhile browsers impose those restriction for security reasons, it reduces the\ninteractivity of your project. The offline plugin makes sure that site search\nkeeps working by moving the search index to a JavaScript file, and leveraging\n@squidfunk's [iframe-worker] shim.\n\nAdditionally, the plugin automatically disables the [`use_directory_urls`]\n[mkdocs.use_directory_urls] setting, ensuring that users can open your\ndocumentation directly from the local file system.\n\nThere are some [limitations].\n\n [building your project]: ../creating-your-site.md#building-your-site\n [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API\n [iframe-worker]: https://github.com/squidfunk/iframe-worker\n [limitations]: #limitations\n\n### When to use it\n\nAs the name already indicates, the plugin should only be used when you're\n[building your project] for offline distribution. It's also good to know, that\nthe offline plugin plays nicely with the following other plugins, helping to\ncreate even better offline-capable documentation:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use external assets when building for\n offline usage, as it automatically downloads them for distribution with\n your documentation.\n\n ---\n\n __Your documentation can work without connectivity to the internet[^1]__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [^1]:\n You might wonder why the [privacy plugin][privacy] is necessary to build\n truly offline-capable documentation with the offline plugin. While it's\n certainly possible to also add support for downloading external assets to\n the offline plugin, this functionality is already fully implemented in the\n privacy plugin and is its very raison d'être.\n\n Material for MkDocs follows a modular approach for its plugin system – many\n of the plugins work perfectly together and enhance each others\n functionalities, allowing to solve complex problems with a few lines\n of configuration.\n\n [privacy]: privacy.md\n [optimize]: optimize.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the offline plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nbuilding offline-capable documentation:\n\n``` yaml\nplugins:\n - offline\n```\n\nThe offline plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [offline]: offline.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to build online- as well as offline-capable documentation, it's a\ngood idea to use an [environment variable][mkdocs.env]:\n\n``` yaml\nplugins:\n - offline:\n enabled: !ENV [OFFLINE, false]\n```\n\n## Limitations\n\nWhen enabling the offline plugin, make sure to disable the following settings,\nas they make use of the [Fetch API] which will error when invoked from the local\nfile system:\n\n- [Instant loading]\n- [Site analytics]\n- [Versioning]\n- [Comment systems]\n\n [Instant loading]: ../setup/setting-up-navigation.md#instant-loading\n [Site analytics]: ../setup/setting-up-site-analytics.md\n [Versioning]: ../setup/setting-up-versioning.md\n [Comment systems]: ../setup/adding-a-comment-system.md\n","docs/plugins/index.md":"# Built-in plugins\n\nMaterial for MkDocs started out as a theme for [MkDocs][mkdocs], but has since\nevolved into a full-fledged framework for building and maintaining documentation.\nThe theme is still the core of the project, but it's now accompanied by a\ngrowing number of complementary built-in plugins.\n\nWe strive to make those plugins as modular and generic as possible, so that they\ncan be used in a wide variety of projects and use cases. By providing useful\ndefault settings, we also try to make them as easy to use as possible, so that\nyou can get started quickly, tweaking their settings later on. When\ndeveloping built-in plugins, we always adhere to the following design principles:\n\n- **Modularity:** Built-in plugins are designed to be modular, so that they can\n be easily combined to implement sophisticated pipelines. For example, the\n [offline], [optimize] and [privacy] plugins can be used together to build\n truly [offline-capable documentation].\n\n- **Interoperability:** Built-in plugins are designed to be as compatible as\n possible, so they can be used in combination with other plugins, including\n third-party plugins. We strive to make it simple to integrate with the vast\n ecosystem that has evolved around [MkDocs][mkdocs].\n\n- **Performance:** Built-in plugins are designed to be as fast and\n memory-efficient as possible, so that they don't unnecessarily slow down\n builds. This is particularly important for large documentation projects with\n thousands of pages.\n\n [mkdocs]: https://www.mkdocs.org/\n [design principles]: ../design-principles.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Categories\n\n### Management\n\nThe following plugins greatly improve the authoring experience when working on\ndocumentation projects by providing better management capabilities, from the\nmanagement of plugins, multiple projects, and metadata, to the creation of\nminimal reproductions for bug reports:\n\n\n\n- :material-format-list-group: __[Built-in group plugin][group]__\n\n ---\n\n The group plugin allows to group plugins into logical units to conditionally\n enable or disable them for specific environments with the use of\n [environment variables][mkdocs.env].\n\n ---\n\n __Optimal management of plugins when building in different environments__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to manage metadata (front matter) for all\n pages in a folder, so a certain subset of pages uses specific tags or a\n custom template.\n\n ---\n\n __Simpler organization, categorization and management of metadata__\n\n- :material-folder-open: __[Built-in projects plugin][projects]__\n\n ---\n\n The projects plugin allows to split your main project into multiple distinct\n projects, build them concurrently and preview them together as one.\n\n ---\n\n __Connect multiple projects together, and build them separately or as one__\n\n- :material-information: __[Built-in info plugin][info]__\n\n ---\n\n The info plugin is a small and useful utility that helps to create\n self-contained minimal reproductions, so we maintainers can fix reported\n bugs more quickly.\n\n ---\n\n __Your bug reports are of the highest quality, so we can fix them as fast as\n possible__\n\n\n
\n\n [group]: group.md\n [info]: info.md\n [meta]: meta.md\n [projects]: projects.md\n\n### Optimization\n\nThe following plugins are designed to help you build optimized documentation,\nmaking it more accessible to your users through faster loading times, better\nsearch engine rankings, beautiful preview images on social media, and GDPR\ncompliance with a few lines of configuration:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each page of your documentation, showing as previews on\n social media.\n\n ---\n\n __Links to your site render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your site loads faster as smaller images are served to your users__\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin downloads external assets automatically for easy\n self-hosting, allowing for GDPR compliance with a single line of\n configuration.\n\n ---\n\n __Your documentation can be made GDPR compliant with minimal effort__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [offline]: offline.md\n [optimize]: optimize.md\n [privacy]: privacy.md\n [social]: social.md\n\n### Content\n\nThe following plugins are designed to help you set up a blog, provide search\nfunctionality to your users, add tags to pages and posts, and use the same\ntypesetting capabilities in specific parts of the documentation exactly as in\nthe main content:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The blog plugin adds first-class support for blogging to Material for\n MkDocs, either as a sidecar to your documentation or as a standalone\n installation.\n\n ---\n\n __Your blog is built with the same powerful engine as your documentation__\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The search plugin adds a search bar to the header, allowing users to search\n the entire documentation, so it's easier for them to find what they're\n looking for.\n\n ---\n\n __Your documentation is searchable without any external services, even\n offline__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin adds first-class support for categorizing pages with tags,\n adding the ability to group related pages to improve the discovery of\n related content.\n\n ---\n\n __Your pages are categorized with tags, yielding additional context__\n\n- :material-format-title: __[Built-in typeset plugin][typeset]__\n\n ---\n\n The typeset plugin allows to preserve the enriched presentation of titles\n and headlines within the navigation and table of contents.\n\n ---\n\n __Sidebars preserve the same formatting as section titles in pages__\n\n
\n\n [blog]: blog.md\n [search]: search.md\n [tags]: tags.md\n [typeset]: typeset.md\n\n## Architecture\n\n### Multiple instances\n\nSeveral built-in plugins have support for multiple instances, which means that\nthey can be used multiple times in the same configuration file, allowing to\nfine-tune behavior for separate sections of your project. Currently, the\nfollowing plugins have support for multiple instances:\n\n\n\n- [Built-in blog plugin][blog]\n- [Built-in group plugin][group]\n- [Built-in optimize plugin][optimize]\n- [Built-in privacy plugin][privacy]\n- [Built-in social plugin][social]\n\n
\n","docs/plugins/info.md":"---\ntitle: Built-in info plugin\nicon: material/information\n---\n\n# Built-in info plugin\n\nThe info plugin is a utility that is solely intended to create self-contained\n[minimal reproductions] as `.zip` files when [reporting bugs] or proposing\n[change requests], making communication between us maintainers and you much\neasier, as we have a common ground to work on.\n\n [minimal reproductions]: ../guides/creating-a-reproduction.md\n [reporting bugs]: ../contributing/reporting-a-bug.md\n [change requests]: ../contributing/requesting-a-change.md\n\n## Objective\n\n### How it works\n\nThe plugin helps you to prepare a minimal reproduction by collecting the\nnecessary information about the environment and configuration of your project.\nThis makes it easier for us to fix bugs, as it requires that you\n[upgrade to the latest version] and [remove your customizations].\n\nWhen following these principles, you can be confident that you don't report a\nbug that has already been fixed in a subsequent release, or which is caused by\none of your customizations. Even more importantly, you actively help\nus to fix the bug as quickly as possible.\n\nThe output of the plugin is a `.zip` file that you can share with us maintainers.\n\n [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version\n [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations\n\n\n### When to use it\n\nWhenever you're [reporting a bug][reporting bugs] or have something to discuss,\nlike a question or [change request][change requests], you should attach\na small, self-contained minimal reproduction. Runnable examples help to make\ncommunication much more efficient, giving us maintainers more time to benefit\nmore users by pushing the project forward. Minimal reproductions are mandatory\nfor bug reports.\n\n## Configuration\n\n\n\n\nIn order to get started with the built-in info plugin, just add the following\nlines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share\nwith us maintainers:\n\n``` yaml\nplugins:\n - info\n```\n\nThe info plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [info]: info.md\n [create a minimal reproduction]: ../guides/creating-a-reproduction.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - info:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should be enabled when\n[previewing your site]. It's normally not necessary to specify this setting,\nbut if you want to change this behavior, use:\n\n``` yaml\nplugins:\n - info:\n enabled_on_serve: true\n```\n\nThis setting streamlines the process of creating and inspecting minimal\nreproductions, as it allows to quickly iterate on the reproduction without\nhaving to disable the plugin first.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n### Archive\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should create a `.zip` file\nfrom the project or exit after the version check. This setting is solely\nintended for debugging the plugin itself:\n\n``` yaml\nplugins:\n - info:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should stop creating the `.zip`\nfile when one of the [requirements] is not satisfied. This setting must only be\nused when [reporting a bug][reporting bugs] that is related to a customization\n[explicitly mentioned in our documentation]. You can change it with:\n\n``` yaml\nplugins:\n - info:\n archive_stop_on_violation: false\n```\n\nIf you're using this setting when [reporting a bug][reporting bugs], please\nexplain why you think it is necessary to include customizations. If you're\nunsure, please ask us first by [creating a discussion].\n\n [requirements]: #how-it-works\n [explicitly mentioned in our documentation]: ?q=%22extends+base%22\n [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n","docs/plugins/meta.md":"---\ntitle: Built-in meta plugin\nicon: material/file-tree\n---\n\n# Built-in meta plugin\n\nThe meta plugin solves the problem of setting metadata (front matter) for all\npages in a folder, i.e., a subsection of your project, which is particularly\nuseful to ensure that a certain subset of pages features specific tags, uses a\ncustom template, or is attributed to an author.\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,\nand recursively merges the contents of those files with the metadata (front\nmatter) of all pages that are contained in the same folder and all subfolders.\nFor example, if you want to add the tag Example to\nmultiple pages, use:\n\n``` yaml title=\".meta.yml\"\ntags:\n - Example\n```\n\nNow, given the following directory layout, if you store the file in the folder\nnamed `example`, all pages in that folder receive the tag, while all pages\noutside of the folder remain unaffected:\n\n``` { .sh .no-copy hl_lines=\"4-8\" }\n.\n├─ docs/\n│ ├─ ...\n│ ├─ example/\n│ │ ├─ .meta.yml\n│ │ ├─ a.md\n│ │ ├─ ...\n│ │ └─ z.md\n│ └─ ...\n└─ mkdocs.yml\n```\n\nWhen combining metadata, lists and dictionaries are recursively merged, which\nmeans you can append values to a list and add or set specific properties in a\ndictionary on arbitrary levels.\n\n### When to use it\n\nWhile the plugin itself doesn't offer much functionality beyond adding and\nmerging metadata, it is a perfect companion for many of the other built-in\nplugins that Material for MkDocs offers. Some of the most powerful combinations\nof the meta plugin and other built-in plugins are:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The meta plugin can be used to [change the layout] for social cards or\n [change specific layout options] like [background] or [color]\n for a subset of pages.\n\n ``` yaml title=\".meta.yml\"\n social:\n cards_layout: default/variant\n ```\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The meta plugin allows to automatically associate blog posts with specific\n [authors] and [categories], ensuring that blog posts are always correctly\n annotated.\n\n ``` yaml title=\".meta.yml\"\n authors:\n - squidfunk\n ```\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags], so they can't be forgotten when\n adding pages.\n\n ``` yaml title=\".meta.yml\"\n tags:\n - Example\n ```\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The meta plugin makes it easy to [boost] specific sections in search results\n or to [exclude] them entirely from being indexed, giving more granular\n control over search.\n\n ``` yaml title=\".meta.yml\"\n search:\n exclude: true\n ```\n\n
\n\n [social]: social.md\n [change the layout]: social.md#meta.social.cards_layout\n [change specific layout options]: social.md#meta.social.cards_layout_options\n [background]: social.md#option.background_color\n [color]: social.md#option.color\n [blog]: blog.md\n [authors]: blog.md#meta.authors\n [categories]: blog.md#meta.categories\n [tags]: tags.md\n [specific tags]: tags.md#meta.tags\n [search]: search.md\n [exclude]: search.md#meta.search.exclude\n [boost]: search.md#meta.search.boost\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the meta plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\napplying metadata for multiple pages at once:\n\n``` yaml\nplugins:\n - meta\n```\n\nThe meta plugin is included with Material for MkDocs and doesn't need to be\ninstalled.\n\n [meta]: meta.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - meta:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Meta file\n\nThe following settings are available for meta files:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the meta file name the plugin will look for when\nscanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to\nchange this setting, but if you want to change it, use:\n\n``` yaml\nplugins:\n - meta:\n meta_file: .meta.yml\n```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir]\nrecursively.\n","docs/plugins/optimize.md":"---\ntitle: Built-in optimize plugin\nicon: material/rabbit\n---\n\n# Built-in optimize plugin\n\nThe optimize plugin automatically identifies and optimizes all media files when\n[building your project] by using common compression and conversion techniques.\nAs a result, your site loads significantly faster and yields better rankings in\nsearch engines.\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and\nassets, optimizing them automatically in order to reduce the final size of the\n[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you\nship less bytes to your users, as well as a smaller download for\n[offline-capable documentation].\n\nOptimized images are [intelligently cached][intelligent caching], which is why\nthe plugin will only optimize media files that changed since the last build.\nThis makes it possible to swap out or update images, without having to worry\nabout optimizing them, or even worse, forgetting to do so.\n\nIn order to optimize media files, a few [dependencies] need to be available on\nyour system.\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [dependencies]: #configuration\n\n### When to use it\n\nIt's generally recommended to use the plugin, as media files are optimized\nautomatically without the need for intervention, ensuring that your site loads\nas fast as possible. Optimized media files are one of the key components for a\nhigh and consistent ranking in search engines.\n\nAdditionally, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated\nbuild pipelines tailored to your project:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use unoptimized external assets, passing\n them to the optimize plugin before copying them to the [`site` directory]\n [mkdocs.site_dir].\n\n ---\n\n __External media files can be automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [privacy]: privacy.md\n [offline]: offline.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the optimize plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and observe how\nmedia files are optimized automatically:\n\n``` yaml\nplugins:\n - optimize\n```\n\nThe optimize plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to optimize all media files, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [optimize]: optimize.md\n [built-in plugins]: index.md\n [image processing]: requirements/image-processing.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - optimize:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete media file optimization faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - optimize:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a media\nfile or asset is only passed through the optimization pipeline when its contents\nchange. If you swap out or update an image, the plugin detects it and updates\nthe optimized version of the media file.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-optimize all media files, even though the cache may not be stale. It's\nnormally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - optimize:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where media files are cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - optimize:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Optimization\n\nDocumentation often makes use of screenshots or diagrams for better\nvisualization of things, both of which are prime candidates for optimization.\nThe plugin automatically optimizes images using [pngquant] for `.png` files,\nand [Pillow] for `.jpg` files.\n\nThe following settings are available for optimization:\n\n [pngquant]: https://pngquant.org/\n [Pillow]: https://pillow.readthedocs.io/\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable media file optimization. Currently,\nthe plugin's sole purpose is to optimize media files, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the near future, other features\nmight be added. If you want to disable optimization, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.png` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.png` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the speed/quality tradeoff that [pngquant] applies\nwhen optimizing `.png` files. The lower the number, the more aggressively\n[pngquant] will try to optimize:\n\n=== \"Slower smaller \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 1\n ```\n\n=== \"Faster larger \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 10\n ```\n\nA factor of `10` has 5% lower quality, but is 8x faster than the default `3`.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [pngquant] should strip optional metadata\nfrom `.png` files that are not required to display the image, e.g., [EXIF].\nIf you want to preserve metadata, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png_strip: false\n```\n\n [EXIF]: https://en.wikipedia.org/wiki/Exif\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.jpg` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.jpg` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the image quality that [Pillow] applies when\noptimizing `.jpg` files. If the images look blurry, it's a good idea to\nfine-tune and change this setting:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_quality: 75\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [Pillow] should use progressive encoding\nwhen optimizing `.jpg` files, rendering faster on slow connections. If you want\nto disable progressive encoding, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_progressive: false\n```\n\n [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339\n\n---\n\n#### \n\n\n\n\nUse this setting to enable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - optimize:\n optimize_include:\n - screenshots/*\n```\n\nThis configuration enables optimization for all media files that are contained\nin the `screenshots` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - social:\n optimize_exclude:\n - vendor/*\n```\n\nThis configuration disables optimization for all media files that are contained\nin the `vendor` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n### Reporting\n\nThe following settings are available for reporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the number of bytes\ngained after optimizing each file. If you want to disable this behavior, use:\n\n``` yaml\nplugins:\n - optimize:\n print_gain: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the total number of\nbytes gained after optimizing all files. If you want to disable this behavior,\nuse:\n\n``` yaml\nplugins:\n - optimize:\n print_gain_summary: false\n```\n","docs/plugins/search.md":"---\ntitle: Built-in search plugin\nicon: material/magnify\n---\n\n# Built-in search plugin\n\nThe search plugin adds a search bar to the header, allowing users to search your\ndocumentation. It's powered by [lunr.js], a lightweight full-text search engine\nfor the browser, elimininating the need for external services, and even works\nwhen building [offline-capable documentation].\n\n [lunr.js]: https://lunrjs.com/\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML and builds a search index from all pages and\nsections by extracting the section titles and contents. It preserves some inline\nformatting like code blocks and lists, but removes all other formatting, so the\nsearch index is as small as possible.\n\nWhen a user visits your site, the search index is shipped to the browser,\nindexed with [lunr.js] and made available for fast and simple querying – no\nserver needed. This ensures that the search index is always up to date with\nyour documentation, yielding accurate results.\n\n### When to use it\n\nIt's generally recommended to use the plugin, as interactive search functionality\nis a vital part of every good documentation. Additionally, the plugin integrates\nperfectly with several of the other [built-in plugins] that Material for MkDocs\noffers:\n\n\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to [boost][meta.search.boost] specific\n sections in search results or to [exclude][meta.search.exclude] them\n entirely from being indexed, giving more granular control over search.\n\n ---\n\n __Simpler organization and management of search in different subsections__\n\n
\n\n [offline]: offline.md\n [meta]: meta.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the search plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and your users\nwill be able to search your documentation:\n\n``` yaml\nplugins:\n - search\n```\n\nThe search plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [search]: search.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - search:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Search\n\nThe following settings are available for search:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the language of the search index, enabling [stemming]\nsupport for other languages than English. The default value is automatically\ncomputed from the [site language], but can be explicitly set to another language\nor even multiple languages with:\n\n=== \"Set language\"\n\n ``` yaml\n plugins:\n - search:\n lang: en\n ```\n\n=== \"Add further languages\"\n\n ``` yaml\n plugins:\n - search:\n lang: # (1)!\n - en\n - de\n ```\n\n 1. Be aware that including support for further languages increases the\n base JavaScript payload by around 20kb and by another 15-30kb per\n language, all before `gzip`.\n\n [stemming]: https://en.wikipedia.org/wiki/Stemming\n [site language]: ../setup/changing-the-language.md#site-language\n [lunr languages]: https://github.com/MihaiValentin/lunr-languages\n\nLanguage support is provided by [lunr languages], a collection of\nlanguage-specific stemmers and stop words for [lunr.js] maintained by the\nOpen Source community.\n\n---\n\nThe following languages are currently supported by [lunr languages]:\n\n\n\n- `ar` – Arabic\n- `da` – Danish\n- `de` – German\n- `du` – Dutch\n- `en` – English\n- `es` – Spanish\n- `fi` – Finnish\n- `fr` – French\n- `hi` – Hindi\n- `hu` – Hungarian\n- `hy` – Armenian\n- `it` – Italian\n- `ja` – Japanese\n- `kn` - Kannada\n- `ko` – Korean\n- `no` – Norwegian\n- `pt` – Portuguese\n- `ro` – Romanian\n- `ru` – Russian\n- `sa` – Sanskrit\n- `sv` – Swedish\n- `ta` – Tamil\n- `te` – Telugu\n- `th` – Thai\n- `tr` – Turkish\n- `vi` – Vietnamese\n- `zh` – Chinese\n\n
\n\nIf [lunr languages] doesn't provide support for the selected [site language],\nthe plugin falls back to another language that yields the best stemming results.\nIf you discover that the search results are not satisfactory, you can contribute\nto [lunr languages] by adding support for your language.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the separator used to split words when building the\nsearch index on the client side. The default value is automatically computed\nfrom the [site language], but can also be explicitly set to another value with:\n\n``` yaml\nplugins:\n - search:\n separator: '[\\s\\-,:!=\\[\\]()\"/]+|(?!\\b)(?=[A-Z][a-z])|\\.(?!\\d)|&[lg]t;'\n```\n\nSeparators support [positive and negative lookahead assertions], which allows\nfor rather complex expressions that yield precise control over how words are\nsplit when building the search index.\n\nBroken into its parts, this separator induces the following behavior:\n\n=== \"Special characters\"\n\n ```\n [\\s\\-,:!=\\[\\]()\"/]+\n ```\n\n The first part of the expression inserts token boundaries for each\n document before and after whitespace, hyphens, commas, brackets and\n other special characters. If several of those special characters are\n adjacent, they are treated as one.\n\n=== \"Case changes\"\n\n ```\n (?!\\b)(?=[A-Z][a-z])\n ```\n\n Many programming languages have naming conventions like `PascalCase` or\n `camelCase`. By adding this subexpression to the separator,\n [words are split at case changes], tokenizing the word `PascalCase`\n into `Pascal` and `Case`.\n\n=== \"Version strings\"\n\n ```\n \\.(?!\\d)\n ```\n\n When adding `.` to the separator, version strings like `1.2.3` are split\n into `1`, `2` and `3`, which makes them undiscoverable via search. When\n using this subexpression, a small lookahead is introduced which will\n [preserve version strings] and keep them discoverable.\n\n=== \"HTML/XML tags\"\n\n ```\n &[lg]t;\n ```\n\n If your documentation includes HTML/XML code examples, you may want to allow\n users to find [specific tag names]. Unfortunately, the `<` and `>` control\n characters are encoded in code blocks as `<` and `>`. Adding this\n subexpression to the separator allows for just that.\n\n [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html\n [words are split at case changes]: ?q=searchHighlight\n [preserve version strings]: ?q=9.0.0\n [specific tag names]: ?q=script\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify the [pipeline functions] that are used to filter and\nexpand tokens after tokenizing them with the [`separator`][config.separator] and\nbefore adding them to the search index. The default value is automatically\ncomputed from the [site language], but can also be explicitly set with:\n\n``` yaml\nplugins:\n - search:\n pipeline:\n - stemmer\n - stopWordFilter\n - trimmer\n```\n\nThe following pipeline functions can be used:\n\n- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`\n- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.\n- `trimmer` – Trim whitespace from tokens\n\n [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions\n\n### Segmentation\n\nThe plugin supports text segmentation of Chinese via [jieba], a popular\nChinese text segmentation library. Other languages like Japanese and Korean are\ncurrently segmented on the client side, but we're considering to move this\nfunctionality into the plugin in the future.\n\nThe following settings are available for segmentation:\n\n [jieba]: https://pypi.org/project/jieba/\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify a [custom dictionary] to be used by [jieba] for\nsegmenting text, replacing the default dictionary. [jieba] comes with\nseveral dictionaries, which can be used with:\n\n``` yaml\nplugins:\n - search:\n jieba_dict: dict.txt\n```\n\nThe following dictionaries are provided by [jieba]:\n\n- [dict.txt.small] – 占用内存较小的词典文件\n- [dict.txt.big] – 支持繁体分词更好的词典文件\n\nThe provided path is resolved from the root directory.\n\n [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8\n [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small\n [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify an additional [user dictionary] to be used by\n[jieba] for segmenting text, augmenting the default dictionary. User\ndictionaries are ideal for tuning the segmenter:\n\n``` yaml\nplugins:\n - search:\n jieba_dict_user: user_dict.txt\n```\n\nThe provided path is resolved from the root directory.\n\n [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to increase or decrease the relevance of a page in the search\nresults, giving more weight to them. Use values above `1` to rank up and values\nbelow `1` to rank down:\n\n=== \":material-arrow-up-circle: Rank up\"\n\n ``` yaml\n ---\n search:\n boost: 2 # (1)!\n ---\n\n # Page title\n ...\n ```\n\n 1. When boosting pages, always start with low values.\n\n=== \":material-arrow-down-circle: Rank down\"\n\n ``` yaml\n ---\n search:\n boost: 0.5\n ---\n\n # Page title\n ...\n ```\n\n---\n\n#### \n\n\n\n\n\nUse this property to exclude a page from the search results. Note that this will\nnot only remove the page, but also all subsections of the page from the search\nresults:\n\n``` yaml\n---\nsearch:\n exclude: true\n---\n\n# Page title\n...\n```\n","docs/plugins/privacy.md":"---\ntitle: Built-in privacy plugin\nicon: material/shield-account\n---\n\n\n# Built-in privacy plugin\n\nThe privacy plugin offers a streamlined solution for automatically self-hosting\nexternal assets. With just a single line of configuration, the plugin can\nautomatically identify and download external assets, making GDPR compliance\nas effortless as it can possibly be.\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML for external assets, i.e., scripts, style\nsheets, images, and web fonts, downloads them, stores them in the\n[`site` directory][mkdocs.site_dir] and replaces all references with links to\nthe downloaded copies for effortless self-hosting. For example:\n\n``` html\n\n```\n\nThis external script is downloaded, and the link is replaced with:\n\n``` html\n\n```\n\nOf course, scripts and style sheets can reference further external assets,\nwhich is why this process is repeated recursively until no further external\nassets are detected:\n\n- Scripts are scanned for further scripts, style sheets and JSON files\n- Style sheets are scanned for images and web fonts\n\nAdditionally, hints like [`preconnect`][preconnect], used to reduce latency when\nrequesting external assets, are removed from the output, as they're not\nnecessary when self-hosting. After the plugin has done its work, your project\nwill be free of requests to external services.\n\nThere are some [limitations].\n\n [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin was developed to make compliance with the 2018 European\n__General Data Protection Regulation__ (GDPR) as simple as possible, while\nretaining the flexibility and power that Material for MkDocs offers, like for\nexample its tight integration with [Google Fonts].\n\nBut, that's only the start. For example, if your project includes a lot of\nimages, enabling the plugin allows to move them outside of your repository, as\nthe plugin will automatically download and store them in the [`site` directory]\n[mkdocs.site_dir] when [building your project].\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin allows to optimize all downloaded external assets\n detected by the privacy plugin by using compression and conversion\n techniques.\n\n ---\n\n __External media files are automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [Google Fonts]: ../setup/changing-the-fonts.md\n [building your project]: ../creating-your-site.md#building-your-site\n [optimize]: optimize.md\n [offline]: offline.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the privacy plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\neffortlessly self-hosting external assets:\n\n``` yaml\nplugins:\n - privacy\n```\n\nThe privacy plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [privacy]: privacy.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - privacy:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete handling of external assets faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - privacy:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that external\nassets are only downloaded when they're not already contained in the cache.\nWhile the initial build might take some time, it's a good idea to use caching,\nas it will speed up consecutive builds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-schedule downloads for all external assets, even though the cache may not be\nstale. It's normally not necessary to specify this setting, except for when\ndebugging the plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - privacy:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where downloaded copies are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages when\nbuilding your site. While not being recommended, you can disable logging with:\n\n``` yaml\nplugins:\n - privacy:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot\n be created due to a lack of permissions on Windows systems (#6550).\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported, including which\n assets were successfully downloaded by the plugin.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: debug\n ```\n\n All messages are reported, including debug messages, if and only if MkDocs\n was started with the `--verbose` flag. Note that this will print a lot of\n messages and is only useful for debugging.\n\n### External assets\n\nThe following settings are available for external assets:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should download external\nassets. If you only want the plugin to process [external links], you can disable\nhandling of external assets with:\n\n``` yaml\nplugins:\n - privacy:\n assets: false\n```\n\n [external links]: #external-links\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should downloads or only report\nexternal assets when they're encountered. If you already self-host all external\nassets, this setting can be used as a safety net to detect links to external\nassets placed by the author in pages:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch: true\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nexternal assets are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch_dir: my/custom/dir\n```\n\nThis configuration stores the downloaded copies at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to enable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_include:\n - unsplash.com/*\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to disable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_exclude: # (1)!\n - unpkg.com/mathjax@3/*\n - giscus.app/*\n```\n\n1. [MathJax] loads web fonts for typesetting of mathematical content\n through relative URLs, and thus cannot be automatically bundled by the\n privacy plugin. [MathJax can be self-hosted].\n\n [Giscus], which we recommend to use as a [comment system], uses a technique\n called code-splitting to load only the code that is necessary, which\n is implemented via relative URLs. [Giscus can be self-hosted] as well.\n\n [MathJax]: ../reference/math.md\n [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html\n [Giscus]: https://giscus.app/\n [comment system]: ../setup/adding-a-comment-system.md\n [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md\n\n---\n\n### External links\n\nThe following settings are available for external links:\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to parse and process external links to\nannotate them for [improved security], or to automatically add additional\nattributes to external links. If you want to disable processing of external\nlinks, use:\n\n``` yaml\nplugins:\n - privacy:\n links: false\n```\n\n [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/\n\n---\n\n#### \n\n\n\n\nUse this setting to specify additional attributes that should be added to\nexternal links, for example, to add `target=\"_blank\"` to all external links\nso they open in a new tab:\n\n``` yaml\nplugins:\n - privacy:\n links_attr_map:\n target: _blank\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not recommended to change this setting, as it will automatically\nannotate external links that open in a new window with `rel=\"noopener\"` for\n[improved security]:\n\n``` yaml\nplugins:\n - privacy:\n links_noopener: true\n```\n\n## Limitations\n\n### Dynamic URLs\n\nDynamically created URLs as part of scripts are not detected, and thus cannot be\ndownloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:\n\n``` js\nconst host = \"https://example.com\"\nconst path = `${host}/script.js`\n```\n\nInstead, always use fully qualified URLs:\n\n``` js\nconst url =\"https://example.com/script.js\"\n```\n\n### Embedded HTML\n\nBy default, embedded HTML files (e.g. in iframes) are not scanned for external\nassets. This is a limitation of MkDocs, as it considers `.html` files to be\ntemplates, which must be explicitly listed under\n[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets\nof an embedded HTML file:\n\n``` yaml\nextra_templates:\n - iframe.html\n```\n\nNote that the path to `iframe.html` is relative to the\n[`docs_dir`][mkdocs.docs_dir] directory.\n","docs/plugins/projects.md":"---\ntitle: Built-in projects plugin\nicon: material/folder-open\nstatus: deprecated\n---\n\n# Built-in projects plugin\n\nThe projects plugin adds the ability to split your main project into multiple\ndistinct projects, build them concurrently and preview them together as one.\nThis is particularly useful when creating a multi-language project, but can also\nbe used to split very large projects into smaller parts.\n\n!!! bug \"The built-in projects plugin is deprecated\"\n\n [Material for MkDocs is in maintenance mode]. The projects plugin, which was\n formerly part of the [Insiders] edition, was released in , the last release that includes all features from the Insiders edition.\n Unfortunately, the projects plugin turned out impossible to maintain, and\n was one of the key motivators to create [Zensical].\n\n ---\n\n __If you're considering the projects plugin, please be aware that known issues will not be fixed.__\n\n [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523\n [Zensical]: ../blog/posts/zensical.md\n [Insiders]: ../blog/posts/insiders-now-free-for-everyone.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`projects` directory][config.projects_dir] for\n`mkdocs.yml` files, identifies all nested projects and builds them concurrently.\nIf not configured otherwise, the plugin expects that your project has\nthe following directory layout, e.g. for a multi-language project:\n\n``` { .sh .no-copy }\n.\n├─ docs/\n├─ projects/\n│ ├─ en/\n│ │ ├─ docs/\n│ │ └─ mkdocs.yml\n│ └─ de/\n│ ├─ docs/\n│ └─ mkdocs.yml\n└─ mkdocs.yml\n```\n\nOne of the most useful and interesting features of the plugin is that it allows\n[previewing your site] from the main project, while still being able to preview\nand build each project individually. This is especially useful for\nmulti-language projects.\n\nIf, when [previewing your site], you change a file in one of the projects, the\nplugin only rebuilds this project and makes sure that MkDocs will also reload\nthe associated files. This also creates the opportunity for splitting your\nmain project into several projects for a better editing experience.\n\nThere are some [limitations], but we're working hard to remove them.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin came into existence because we needed a convenient and scalable\nmethod to build our [examples] repository, which features many self-contained\nand runnable projects that users can download and use as a basis when\nbootstrapping a new project or [creating a reproduction].\n\nWhen you want to create a multi-language project, or have a very large existing\nproject, you might consider using the plugin, as it makes managing, editing\nand building more comfortable.\n\n [examples]: https://github.com/mkdocs-material/examples\n [creating a reproduction]: ../guides/creating-a-reproduction.md\n\n## Configuration\n\n\n\n\n\nIn order to get started with the projects plugin, just add the following lines\nto `mkdocs.yml`, and split your main project into several distinct projects that\ncan be built concurrently:\n\n``` yaml\nplugins:\n - projects\n```\n\nThe projects plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [projects]: projects.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\nbuild projects faster. If you want to disable concurrent processing completely,\nuse:\n\n``` yaml\nplugins:\n - projects:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a\nproject is only rebuilt when its contents change. While the initial build might\ntake some time, it's a good idea to use caching, as it will speed up consecutive\nbuilds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nrebuild all projects, even though the cache may not be stale. It's normally not\nnecessary to specify this setting, except for when debugging the plugin itself.\nCaching can be disabled with:\n\n``` yaml\nplugins:\n - projects:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where the metadata is cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - projects:\n cache_dir: my/custom/dir\n```\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages from\nprojects when building your site. While not being recommended, you can disable\nlogging with:\n\n``` yaml\nplugins:\n - projects:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: debug\n ```\n\n All messages are reported, including debug messages.\n\n### Projects\n\nThe following settings are available for projects:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable building of projects. Currently, the\nplugin's sole purpose is to build projects, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable building of projects, use:\n\n``` yaml\nplugins:\n - projects:\n projects: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your projects are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - projects:\n projects_dir: projects\n```\n\nNote that the [`projects` directory][config.projects_dir] is solely used for\nproject organization – it is not included in project URLs, since projects are\nautomatically hoisted by the plugin.\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the location or name of configuration files the\nplugin will look for when scanning the [`projects` directory]\n[config.projects_dir]. Adjusting this setting can be necessary when the\nconfiguration files are located in subdirectories of projects, e.g.\n`docs/mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n projects_config_files: \"**/mkdocs.yml\" # (1)!\n```\n\n1. If all projects share the same location for their configuration files, e.g.,\n `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster\n to resolve than a `**` glob pattern.\n\n ``` yaml\n plugins:\n - projects:\n projects_config_files: \"*/docs/mkdocs.yml\"\n ```\n\n This configuration fits the following directory structure, which is quite\n common for projects using git submodules:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n ├─ projects/\n │ ├─ git-submodule-a/\n │ │ └─ docs/\n │ │ └─ mkdocs.yml\n │ └─ git-submodule-b/\n │ └─ docs/\n │ └─ mkdocs.yml\n └─ mkdocs.yml\n ```\n\nThe provided path is resolved from the [`projects` directory]\n[config.projects_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to transform the configuration of each project as read from\n`mkdocs.yml` before it is built, which allows for adjusting the configuration\nof each project when building them together, but leave them untouched when\nbuilding them individually:\n\n``` yaml\nplugins:\n - projects:\n projects_config_transform: !!python/name:projects.transform\n```\n\nThe provided module and function name are looked up in Python's [module search\npath]. You need to add your root directory to the search path when building\nyour site, so Python can resolve it. The easiest way is to add the working\ndirectory to the [`PYTHONPATH`][PYTHONPATH] environment variable:\n\n``` .sh\nexport PYTHONPATH=.\n```\n\n!!! tip \"How to define a configuration transformation function\"\n\n The [`python/name`][python-name] tag is provided by [PyYAML] and must point\n to a valid module and function name within Python's [module search path].\n The plugin passes the `project` and top-level `config` objects to the\n function.\n\n As an example, we can inherit the [`use_directory_urls`]\n [mkdocs.use_directory_urls] setting for all projects from the top-level\n configuration:\n\n ``` py title=\"projects/__init__.py\"\n from mkdocs.config.defaults import MkDocsConfig\n\n # Transform project configuration\n def transform(project: MkDocsConfig, config: MkDocsConfig):\n project.use_directory_urls = config.use_directory_urls\n ```\n\n [module search path]: https://docs.python.org/3/library/sys_path_init.html\n [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH\n [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types\n [PyYAML]: https://pyyaml.org/\n\n### Hoisting\n\nThe following settings are available for hoisting:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable hoisting of themes files to the main\nproject. If you disable this setting, each project receives a copy of the\ntheme's files, which can be considered redundant:\n\n``` yaml\nplugins:\n - projects:\n hoisting: false\n```\n\nIt's generally advisable to enable hoisting, as it yields faster deployments\nand faster loading of your project's sites, because the files are the same for\nall projects and can be deduplicated.\n\n### Limitations\n\nThe plugin is one of the latest additions to Material for MkDocs, which means it\nis rather young and has some limitations. We're working hard to remove them, and\nwe're happy to receive feedback and learn about your requirements in ?5800.\nCurrent limitations are:\n\n- __Basic multi-language support only__: we'll be investigating how to provide\n better support for multi-language projects, allowing to easier interlink\n projects and switch between them.\n\n- __Separate search indexes and sitemaps__: currently, the projects are entirely\n separate, which means they will have separate search indexes and sitemaps.\n","docs/plugins/tags.md":"---\ntitle: Built-in tags plugin\nicon: material/tag-text\n---\n\n# Built-in tags plugin\n\nThe tags plugin adds first-class support for categorizing pages with the use\nof tags, adding the possibility to group related pages and make them\ndiscoverable via search and dedicated tags indexes. If your documentation is\nlarge, tags can help to discover relevant information faster.\n\n## Objective\n\n### How it works\n\nThe plugin scans all pages for the [`tags`][meta.tags] metadata property and\ngenerates a tags index, which is an inverted list of tags and the pages they\nappear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],\nallowing for maximum flexibility when adding tags to your project.\n\n### When to use it\n\nIf you want to add one or multiple tags indexes to your project, the tags\nplugin is a perfect choice as it makes this process ridiculously simple.\nAdditionally, it integrates perfectly with several of the other\n[built-in plugins] that Material for MkDocs offers:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags][meta.tags], so they can't be\n forgotten when adding pages.\n\n ---\n\n __Simpler organization and management of tags in different subsections__\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [blog]: blog.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the tags plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start using\n[tags][meta.tags] to categorize your pages:\n\n``` yaml\nplugins:\n - tags\n```\n\nThe tags plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [tags]: tags.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - tags:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Tags\n\nThe following settings are available for tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable rendering of tags. The plugin still\nextracts tags from all pages, e.g., for [exporting tags] without rendering them.\nRendering can be disabled with:\n\n``` yaml\nplugins:\n - tags:\n tags: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\n!!! warning \"This setting is deprecated\"\n\n As of version , this setting is deprecated, as this\n version ships a __ground up rewrite of the tags plugin__ which is much more\n powerful than the previous version. Tags [listings] can be used on any page\n now.\n\n\n\nUse this setting to specify the location of the tags index, which is the page\nused to render a list of all tags and their associated pages. If this setting is\nspecified, tags become clickable, pointing to the corresponding section in the\ntags index:\n\n``` yaml\nplugins:\n - tags:\n tags_file: tags.md\n```\n\nThe page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]\nsection of `mkdocs.yml`. This setting is not required – you should only use it\nif you want to have a tags index.\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n
\n\n [listings]: ../setup/setting-up-tags.md#adding-a-tags-index\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`tags_slugify`][config.tags_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating tag\nslugs. It is a good idea to prefix tag slugs with a string that makes them\nunique, the default being:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_format: \"tag:{slug}\"\n```\n\nThe following placeholders are available:\n\n- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]\n\n---\n\n#### \n\n\n\n\n\nUse this setting to enable support for tag hierarchies (nested tags, e.g.,\n`foo/bar`). If you intend to create hierarchical listings of tags, you can\nenable this setting in `mkdocs.yml` with:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy: true\n```\n\n---\n\n#### \n\n\n\n\n\nUse this setting to change the separator that is used when creating tag\nhierarchies. By default, tags are separated by a forward slash `/`, but you\ncan change this to any string, e.g., `.`:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy_separator: .\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags. By default,\ntag comparison is case-sensitive, but you can use `tag_name_casefold` for\ncase-insensitive comparison:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the front matter property that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_property: tags\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the template variable that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_variable: tags\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check tags against a predefined list, in order to catch\ntypos or make sure that tags are not arbitrarily added. Specify the tags you\nwant to allow with:\n\n``` yaml\nplugins:\n - tags:\n tags_allowed:\n - HTML5\n - JavaScript\n - CSS\n```\n\nThe plugin stops the build if a page references a tag that is not part of\nthis list. Pages can be assigned to tags by using the [`tags`][meta.tags]\nmetadata property.\n\n### Listings\n\nThe following settings are available for listings:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable listings. It is normally not necessary to\nchange this setting, as listings are created entirely by inline comments, but\nyou can disable them if necessary with:\n\n``` yaml\nplugins:\n - tags:\n listings: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\nUse this define listing configurations that you can then reference in listings\nwith a custom identifier. Sharing configurations is a good idea, especially\nwhen you have many tag listings:\n\n``` yaml\nplugins:\n - tags:\n listings_map:\n custom-id:\n scope: true\n exclude: Internal\n```\n\nThen, just reference the listing identifier:\n\n``` html\n\n```\n\nSee the [listings section] for a list of all available settings.\n\n [listings section]: #listing-configuration\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing listing items. By\ndefault, items are ordered by their titles, but you can change the sorting\ncriterion with the following configuration:\n\n=== \"Sort by item title\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_title\n ```\n\n=== \"Sort by item URL\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_url\n ```\n\nYou can also define your own comparison function, which must return a string\nor number representing the item, that is used for sorting, and reference it in\n[`listings_sort_by`][config.listings_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which items are sorted when comparing\nthem. By default, items are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n listings_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags in listings. By\ndefault, tag comparison is case-sensitive, but you can use `tag_name_casefold`\nfor case-insensitivity:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the directive the plugin will look for\nwhen processing pages. If you want to use a shorter directive than\n`material/tags`, you could use:\n\n``` yaml\nplugins:\n - tags:\n listings_directive: $tags\n```\n\nUsing this setting, listings must now be referenced as such:\n\n``` html\n\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable tags showing up in the table of contents.\nIf you don't want tags to show up in the table of contents, you can disable this\nbehavior with:\n\n``` yaml\nplugins:\n - tags:\n listings_toc: false\n```\n\n### Shadow tags\n\nThe following settings are available for shadow tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether the plugin should include shadow tags on\npages and in listings when [building your project], which might be useful for\ndeploy previews:\n\n=== \"Show shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: true\n ```\n\n=== \"Hide shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include shadow tags on\npages and in listings when [previewing your site]. If you don't wish to include\nthem when previewing, use:\n\n``` yaml\nplugins:\n - tags:\n shadow_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin allows to specify a predefined list of shadow tags which can be\nincluded and excluded from builds by using the [`shadow`][config.shadow]\nsetting. Shadow tags must be specified as a list:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags:\n - Draft\n - Internal\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a prefix for each tag.\nIf the tag starts with this string, the tag is marked as a shadow tag. A common\npractice is to use `_` as a prefix:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_prefix: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a suffix for each tag.\nIf the tag ends with this string, the tag is marked as a shadow tag. One option\ncan be to use `Internal` as a suffix:\n\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_suffix: Internal\n```\n\n### Export\n\nThe following settings are available for exporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin creates a `tags.json` file\ninside your [`site` directory][mkdocs.site_dir], which can then be consumed by\nother plugins and projects:\n\n``` yaml\nplugins:\n - tags:\n export: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the exported tags are\nstored. It's normally not necessary to change this setting, but if you need to,\nuse:\n\n``` yaml\nplugins:\n - tags:\n export_file: tags.json\n```\n\nThe provided path is resolved from the [`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nThis setting is solely provided for convenience to disable the rendering of tags\nand listings with a single setting (e.g. by using an environment variable),\nwhile keeping the export functionality:\n\n``` yaml\nplugins:\n - tags:\n export_only: true\n```\n\nThis will automatically disable the [`tags`][config.tags] and\n[`listings`][config.listings] settings.\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a page with one or more tags, making the page\nappear in the generated tags index. Tags are defined as a list of strings\n(whitespaces are allowed):\n\n``` yaml\n---\ntags:\n - HTML5\n - JavaScript\n - CSS\n---\n\n# Page title\n...\n```\n\nIf you want to prevent accidental typos when assigning tags to pages, you can\nset a predefined list of allowed tags in `mkdocs.yml` by using the\n[`tags_allowed`][config.tags_allowed] setting.\n\n### Listing configuration\n\nThe listings configuration controls which tags are included in or excluded from\na listing and whether a listing only includes pages in the current scope.\nFurthermore, listings can override some values from the global configuration.\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should only consider pages that are\nwithin the current subsection of the documentation of the page the listing is\nembedded in:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n scope: false\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should include shadow tags, which\nallows to override the global [`shadow`][config.shadow] setting on a per-listing\nbasis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n shadow: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should render tags inside the table\nof contents, allowing to override the global [`listings_toc`][config.listings_toc]\nsetting on a per-listing basis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n toc: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be included in the listing. Each\npage that features a tag that is part of this setting, is listed under the\nrespective tag:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n include:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, all tags and pages are included.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be excluded from the listing. Each\npage that features a tag that is part of this setting, is excluded from the\nlisting entirely:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n exclude:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, no tags or pages are excluded.\n\n## Limitations\n\nThe implementation of the tags plugin is tricky due to MkDocs architecture.\nNotably, tag listing markers cannot appear within code blocks. For technical\ndetails, refer to #8114.\n","docs/plugins/social.md":"---\ntitle: Built-in social plugin\nicon: material/share-circle\n---\n\n# Built-in social plugin\n\nThe social plugin automatically and intelligently generates beautiful and highly\ncustomizable social cards in different [layouts][default layouts] for each page\nof your project, rendering as preview images whenever you or somebody else share\na link to your project on social media.\n\n## Objective\n\n### How it works\n\nThe plugin automatically generates a customizable social card for each page\nof your project, which appears as a preview image when sharing a link to your\nproject on social media, without the use of external services and just\n[a single line of configuration][configuration].\n\nWith the use of an efficient [image processing] library, the plugin allows to\ndefine [custom layouts] for social cards, which can be adapted to match your\nproject's style and branding. While it would technically be much simpler to\ngenerate social cards by using a web browser and an automation framework like\n[Puppeteer][^1], it would add further liabilities to your toolchain, with the\npotential to make build pipelines more complex, much more resource intense,\nand significantly slower.\n\n [^1]:\n [GitHub wrote in their blog] that they use [Puppeteer] to generate social\n card images for repositories, issues, commits, discussions, and basically\n everything else that appear as preview images when shared on social media.\n\nThe generated social cards are [cached] and stored in the\n[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your\nproject doesn't depend on external services. In order to generate social cards\nimages, a few [dependencies] need to be available on your system.\n\n [configuration]: #configuration\n [image processing]: requirements/image-processing.md\n [custom layouts]: ../setup/setting-up-social-cards.md#customization\n [Puppeteer]: https://github.com/puppeteer/puppeteer\n [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/\n [cached]: #caching\n [dependencies]: #configuration\n\n### When to use it\n\nThere's one particular case when we don't recommend to use the plugin: when you\nbuild [offline-capable documentation] to offer it as a download. Otherwise, it\nalways makes sense to enable the plugin, as links to your documentation shared\non social media will appear much more appealing.\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social media__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin can be used to [change the layout][meta.social.cards_layout]\n for social cards or [change specific layout options]\n [meta.social.cards_layout_options] like [background][option.background_color]\n or [color][option.color] for a subset of pages.\n\n ---\n\n __Your documentation can use completely different social cards per section__\n\n
\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [blog]: blog.md\n [meta]: meta.md\n\n## Configuration\n\n\n\n\n\n\nIn order to get started with the social plugin, just add the following lines to\n`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social\ncards for you:\n\n``` yaml\nplugins:\n - social\n```\n\nThe social plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to generate social card images, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [social]: social.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - social:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete social card generation faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - social:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that social\ncards are only regenerated when their contents change or they're not already\ncontained in the cache. If any of the variables used in a layout changes, the\nplugin detects it and regenerates the social card.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-generate social cards for all pages, even though the cache may not be stale.\nIt's normally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - social:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where social card images are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should only log errors when\ngenerating social cards without terminating the build, e.g., invalid references\nto icons. To terminate the build, use:\n\n``` yaml\nplugins:\n - social:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: warn\n ```\n\n Errors are reported as warnings, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: info\n ```\n\n Errors are only reported as informational messages.\n\n=== \"`ignore`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: ignore\n ```\n\n Errors are only reported when using the `--verbose` flag.\n\n### Social cards\n\nThe following settings are available for social card generation:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable social card generation. Currently, the\nplugin's sole purpose is to generate social cards, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable social card generation, use:\n\n``` yaml\nplugins:\n - social:\n cards: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nsocial cards are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cards_dir: my/custom/dir\n```\n\nThis configuration stores the generated images at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nIf you want to build a [custom social card layout][custom layouts], use this\nsetting to change the folder where you store your custom layouts, the default\nbeing a folder called `layouts` in your root directory:\n\n``` yaml\nplugins:\n - social:\n cards_layout_dir: layouts\n```\n\nThe provided path is resolved from the root directory.\n\n!!! tip \"Where to store custom layouts\"\n\n Our recommendation is to locate the folder outside of the\n [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]\n are not copied to the [`site` directory][mkdocs.site_dir] when\n [building your project], e.g., by adhering to the following directory\n layout:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ *.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nThe plugin ships a growing list of [`default` layouts][default layouts] for\nsocial cards. If you've created a [custom social card layout][custom layouts],\nyou can instruct the plugin to use it exactly as one of the included layouts:\n\n``` yaml\nplugins:\n - social:\n cards_layout: my-custom-layout\n```\n\nThe provided path is resolved from the[\n`layouts` directory][config.cards_layout_dir].\n\n!!! tip \"How custom layouts are resolved\"\n\n By default, the plugin will load your [custom layouts] from a folder named\n `layouts` in your root directory. If your layout is called\n `my-custom-layout`, the directory layout must adhere to:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ my-custom-layout.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to set options for the layout specified via [`cards_layout`]\n[config.cards_layout] (if the layout supports it), which allows for making\nlayouts easily and entirely configurable:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n : \n```\n\nWhen creating a [custom layout][custom layouts], you are completely free in\ndefining which parts of your layout can be parametrized. The [`default` layouts]\n[default layouts] included with the plugin support the following options:\n\n\n\n- [`background_color`][option.background_color]\n- [`background_image`][option.background_image]\n- [`color`][option.color]\n- [`font_family`][option.font_family]\n- [`font_variant`][option.font_variant]\n- [`logo`][option.logo]\n- [`title`][option.title]\n- [`description`][option.description]\n\n
\n\n\n [default layouts]: #layouts\n\n---\n\n#### \n\n\n\n\nUse this setting to enable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_include:\n - blog/*\n```\n\nThis configuration enables social card generation for all pages that are\ncontained in the `blog` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_exclude:\n - changelog/*\n```\n\nThis configuration disables social card generation for all pages that are\ncontained in the `changelog` folder and its subfolders inside the\n[`docs` directory][mkdocs.docs_dir].\n\n### Debugging\n\nThe plugin includes a special mode for debugging layouts, which is very useful\nwhen creating [custom layouts], as it allows for quicker iteration and better\nunderstanding of composition.\n\nThe following settings are available for debugging:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable a special mode for debugging your layout, which\nrenders each layer with a colored outline and its `x` and `y` offsets, and\noverlays a dot grid for alignment, so it's easier to understand how the\ndistinct layers of your layout are composed together:\n\n``` yaml\nplugins:\n - social:\n debug: true\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin automatically disables [`debug`][config.debug] mode when\n[building your project], so you can be sure that debug overlays are never\ndeployed to production. If you want to change that, use:\n\n``` yaml\nplugins:\n - social:\n debug_on_build: true\n```\n\nIt's normally not necessary to change this setting, as it's just intended to\nbe a safety net.\n\n---\n\n#### \n\n\n\n\nWhen [`debug`][config.debug] mode is enabled, this setting specifies whether a\ndot grid is rendered on top of all layers, to allow for better alignment. If you\nwant to switch the grid off, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the step size of the dot grid in pixels, if enabled,\nwhich can be useful to create perfectly aligned layers for ideal composition.\nIt you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid_step: 64\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the color of the outlines that are added to each\nlayer and the dot grid that is rendered on top of all layers. If you need to\nchange it, use:\n\n``` yaml\nplugins:\n - social:\n debug_color: yellow\n```\n\nIn rare cases, it might be necessary to change this setting if the dot grid or\nthe outlines are hard to distinguish, as the plugin will automatically adjust\nthe color if not explicitly set.\n\n## Usage\n\n### Metadata\n\nThe plugin allows to override a subset of settings through metadata (front\nmatter) in order to customize social card generation, e.g., to set [options for\nthe included `default` layouts][default layouts] for a single page, or even\n[for an entire subsection] of your project by leveraging the [meta] plugin.\n\nThe following properties are available:\n\n [for an entire subsection]: meta.md#how-it-works\n [meta]: meta.md\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards`][config.cards] setting for the given\npage:\n\n``` yaml\n---\nsocial:\n cards: false\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to override the [`cards_layout`][config.cards_layout] setting\nfor the given page:\n\n``` yaml\n---\nsocial:\n cards_layout: my-custom-layout\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards_layout_options`]\n[config.cards_layout_options] setting for the given page:\n\n``` yaml\n---\nsocial:\n cards_layout_options:\n background_color: blue # Change background color\n background_image: null # Remove background image\n---\n\n# Page title\n...\n```\n\nSetting an option to `#!yaml null` resets the option.\n\n### Layouts\n\n\n\nWhile it is possible and simple to build [custom layouts], the plugin ships\nseveral predefined layouts, all of which are prefixed with `default`. The\nfollowing layouts are included:\n\n=== \"`default`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default\n ```\n\n \n\n ![Layout default]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/variant`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/variant\n ```\n\n \n\n ![Layout default variant]\n\n This layout includes the [page icon] and sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/accent`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/accent\n ```\n\n \n\n ![Layout default accent]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/invert`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/invert\n ```\n\n \n\n ![Layout default invert]\n\n This layout sets the following defaults:\n\n - [`color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/only/image`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/only/image\n cards_layout_options:\n background_image: layouts/background.png\n\n ```\n\n \n\n This layout only shows the given background image and scales it to cover.\n\n
\n\nThe [`default` layouts][default layouts] are very flexible and comfortable to\nuse, as they replicate the original behavior of the plugin, sourcing default\nvalues for all options from other `theme` settings.\n\nThe following options are available:\n\n [Layout default]: ../assets/screenshots/social-cards.png\n [Layout default variant]: ../assets/screenshots/social-cards-variant.png\n [Layout default accent]: ../assets/screenshots/social-cards-accent.png\n [Layout default invert]: ../assets/screenshots/social-cards-invert.png\n\n [primary color]: ../setup/changing-the-colors.md#primary-color\n [page icon]: ../reference/index.md#setting-the-page-icon\n [accent color]: ../setup/changing-the-colors.md#accent-color\n [font]: ../setup/changing-the-fonts.md#regular-font\n\n---\n\n#### \n\n\n\n\nUse this option to change the background color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: \"#ff1493\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: rgb(255, 20, 147) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: deeppink # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\nIf this options is used together with [`background_image`]\n[option.background_image], the color is rendered on top of the image which\nallows for tinting images. If you want to remove the background color, use:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n background_color: transparent\n```\n\n [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names\n [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color\n\n---\n\n#### \n\n\n\n\nUse this option to define a background image for the generated social card. Note\nthat the image is tinted with the [`background_color`][option.background_color],\nwhich can also be set to `transparent`:\n\n=== \"Image\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: transparent\n ```\n\n=== \"Image with tint\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: \"#ff149366\"\n ```\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this option to change the foreground color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: \"#ffffff\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: rgb(255, 255, 255) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: white # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\n---\n\n#### \n\n\n\n\nUse this option to change the font family of the generated social card. The\nplugin automatically downloads the font from [Google Fonts], so the font must\npoint to an existing Google Font:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_family: Ubuntu\n```\n\nWhen you've found a font that you like on [Google Fonts], you can just copy the\nname from the font's specimen page and use it as the value for this option –\nno further configuration needed.\n\n [Google Fonts]: https://fonts.google.com/\n\n---\n\n#### \n\n\n\n\nUse this option to change the font variant used to generate the social card.\nIf the downloaded font has variants like `Condensed` or `Expanded`, you can set\nthem with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_variant: Condensed\n```\n\nThe variant is combined with the style as used in the custom layout, so the\nplugin is instructed to use combinations like `Condensed Regular` or\n`Expanded Bold`.\n\n---\n\n#### \n\n\n\n\nUse this option to change the logo that is used in the generated social card.\nBy default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]\n[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n logo: layouts/logo.png\n```\n\nThe provided path is resolved from the root directory.\n\n [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image\n [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled\n\n---\n\n#### \n\n\n\n\nUse this option to change the title of the generated social card. This overrides\nthe computed page title as assigned by MkDocs, as well as the [`title`]\n[meta.title] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n title: My custom title\n```\n\n [meta.title]: ../reference/index.md#setting-the-page-title\n\n---\n\n#### \n\n\n\n\nUse this option to change the description of the generated social card. This\noverrides the set [`site_description`][mkdocs.site_description], if defined, as\nwell as the [`description`][meta.description] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n description: My custom description\n```\n\n [meta.description]: ../reference/index.md#setting-the-page-description\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up social cards, you might discover that you're missing\n specific functionality – we're happy to consider adding it to the plugin!\n You can [open a discussion] to ask a question, or create a [change request]\n on our [issue tracker], so we can find out if it might be a good fit for\n the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","docs/plugins/typeset.md":"# Plugins Skill\n\nPath: `docs/plugins/typeset.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/typeset.md)","docs/plugins/requirements/caching.md":"# Requirements Skill\n\nPath: `docs/plugins/requirements/caching.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/caching.md)","docs/plugins/requirements/image-processing.md":"# Requirements Skill\n\nPath: `docs/plugins/requirements/image-processing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/image-processing.md)","docs/schema/extensions/markdown.json":"# Extensions Skill\n\nPath: `docs/schema/extensions/markdown.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/markdown.json)","docs/schema/extensions/pymdownx.json":"# Extensions Skill\n\nPath: `docs/schema/extensions/pymdownx.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/pymdownx.json)","docs/schema/plugins/blog.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/blog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/blog.json)","docs/schema/plugins/group.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/group.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/group.json)","docs/schema/plugins/info.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/info.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/info.json)","docs/schema/plugins/meta.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/meta.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/meta.json)","docs/schema/plugins/offline.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/offline.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/offline.json)","docs/schema/plugins/optimize.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/optimize.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/optimize.json)","docs/schema/plugins/privacy.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/privacy.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/privacy.json)","docs/schema/plugins/projects.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/projects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/projects.json)","docs/schema/plugins/search.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/search.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/search.json)","docs/schema/plugins/social.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/social.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/social.json)","docs/schema/plugins/tags.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/tags.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/tags.json)","docs/schema/plugins/typeset.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/typeset.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/typeset.json)","docs/setup/extensions/index.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/index.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/index.md)","docs/setup/extensions/python-markdown.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown.md)","docs/setup/extensions/python-markdown-extensions.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown-extensions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown-extensions.md)","docs/schema/plugins/external/awesome-nav.json":"# External Skill\n\nPath: `docs/schema/plugins/external/awesome-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/awesome-nav.json)","docs/schema/plugins/external/gen-files.json":"# External Skill\n\nPath: `docs/schema/plugins/external/gen-files.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/gen-files.json)","docs/schema/plugins/external/git-authors.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-authors.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-authors.json)","docs/schema/plugins/external/git-committers.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-committers.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-committers.json)","docs/schema/plugins/external/git-revision-date.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-revision-date.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-revision-date.json)","docs/schema/plugins/external/literate-nav.json":"# External Skill\n\nPath: `docs/schema/plugins/external/literate-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/literate-nav.json)","docs/schema/plugins/external/macros.json":"# External Skill\n\nPath: `docs/schema/plugins/external/macros.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/macros.json)","docs/schema/plugins/external/minify.json":"# External Skill\n\nPath: `docs/schema/plugins/external/minify.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/minify.json)","docs/schema/plugins/external/redirects.json":"# External Skill\n\nPath: `docs/schema/plugins/external/redirects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/redirects.json)","docs/schema/plugins/external/section-index.json":"# External Skill\n\nPath: `docs/schema/plugins/external/section-index.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/section-index.json)"},"files":{"docs/plugins/blog.md":"---\ntitle: Built-in blog plugin\nicon: material/newspaper-variant-outline\n---\n\n# Built-in blog plugin\n\nThe blog plugin makes it very easy to build a blog, either as a sidecar to\nyour documentation or as the main thing. Focus on your content while the plugin\ndoes all the heavy lifting, generating a view of all latest posts, [archive] and\n[category] pages, configurable [pagination] and much more.\n\n [archive]: #archive\n [category]: #categories\n [pagination]: #pagination\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`posts` directory][config.post_dir] for\n`.md` files from which paginated views[^1] are automatically generated. If not\nconfigured otherwise, the plugin expects that your project has the following\ndirectory layout, and will create any missing directories or files for you:\n\n [^1]:\n Views are pages that are automatically generated, i.e., the entry point to\n your blog listing all latest posts, as well as [archive] and [category]\n pages that list all posts associated with them through [metadata] in\n chronological order.\n\n``` { .sh .no-copy }\n.\n├─ docs/\n│ └─ blog/\n│ ├─ posts/\n│ └─ index.md\n└─ mkdocs.yml\n```\n\nThe `index.md` file in the [`blog` directory][config.blog_dir] is the entry\npoint to your blog – a paginated view listing all posts in reverse chronological\norder. Besides that, the plugin supports automatically creating [archive] and\n[category] pages that list a subset of posts for a time interval or category.\n\n[Post URLs][config.post_url_format] are completely configurable, no matter if\nyou want your URLs to include the post's date or not. Rendered dates always\ndisplay in the locale of the [site language] of your project. Like in other\nstatic blog frameworks, posts can be annotated with a variety of [metadata],\nallowing for easy integration with other [built-in plugins], e.g., the\n[social] and [tags] plugin.\n\nPosts can be organized in nested folders with a directory layout that suits your\nspecific needs, and can make use of all components and syntax that Material for\nMkDocs offers, including [admonitions], [annotations], [code blocks],\n[content tabs], [diagrams], [icons], [math], and more.\n\n [metadata]: #metadata\n [admonitions]: ../reference/admonitions.md\n [annotations]: ../reference/annotations.md\n [code blocks]: ../reference/code-blocks.md\n [content tabs]: ../reference/content-tabs.md\n [diagrams]: ../reference/diagrams.md\n [icons]: ../reference/icons-emojis.md\n [math]: ../reference/math.md\n\n### When to use it\n\nIf you want to add a blog to your project, or migrate from another blog\nframework to Material for MkDocs because of its excellent technical writing\ncapabilities, this plugin is a great choice, as it integrates perfectly with\nmany other built-in plugins:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to apply [metadata] to a subset of posts,\n including authors, tags, categories, draft status, as well as social card\n layouts.\n\n ---\n\n __Simpler organization, categorization and management of post metadata__\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your blog loads faster as smaller images are served to your users__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [social]: social.md\n [optimize]: optimize.md\n [tags]: tags.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the blog plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and you can\nstart writing your first post:\n\n``` yaml\nplugins:\n - blog\n```\n\nThe blog plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [blog]: blog.md\n [built-in plugins]: index.md\n\n### Navigation\n\nIf you do not have site navigation configured in your `mkdocs.yml` then there is\nnothing more to do. The blog [archive] and [category] pages will automatically\nappear underneath the automatically generated navigation.\n\nIf you do have a navigation structure defined then you will need to specify\nwhere the blog should appear in this. Create a [navigation section with an index\npage] for the blog:\n\n```yaml\ntheme:\n name: material\n features:\n - navigation.indexes\nnav:\n - ...\n - Blog:\n - blog/index.md\n```\n\nThe [archive] and [category] pages will appear within that section as\nsubsections beneath pages in the blog section. In this case, they would appear\nafter `index.md`. The path to the `index.md` file must match\n[blog_dir][config.blog_dir]. This means that you can name the blog navigation\nentry anything you like: 'Blog' or 'News' or perhaps 'Tips'.\n\n[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - blog:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path where your blog is located in the\n[`docs` directory][mkdocs.docs_dir]. The path is included in the generated\nURLs as a prefix for all posts and views. You can change it with:\n\n=== \"Documentation + Blog\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: blog\n ```\n\n=== \"Blog only\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: .\n ```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles in\nviews. This might be useful, if your post excerpts are rather long. If you want\nto enable it, use:\n\n``` yaml\nplugins:\n - blog:\n blog_toc: true\n```\n\n### Posts\n\nThe following settings are available for posts:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your posts are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - blog:\n post_dir: \"{blog}/articles\"\n```\n\nNote that the [`posts` directory][config.post_dir] is solely used for post\norganization – it is not included in post URLs, since they are automatically\nand comfortably generated by this plugin.\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format of posts. This plugin uses [babel]\nto render dates in the configured [site language]. You can use [babel]'s\n[pattern syntax] or the following shortcodes:\n\n=== \"Monday, January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: full\n ```\n\n=== \"January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: long\n ```\n\n=== \"Jan 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: medium\n ```\n\n=== \"1/31/24\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: short\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n [babel]: https://pypi.org/project/Babel/\n [site language]: ../setup/changing-the-language.md#site-language\n [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used in post URLs. The format string\nmust adhere to [babel]'s [pattern syntax] and should not contain whitespace.\nSome popular choices:\n\n=== \":material-link: blog/2024/01/31/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM/dd\n ```\n\n=== \":material-link: blog/2024/01/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM\n ```\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy\n ```\n\nIf you want to remove the date from post URLs, e.g., when your blog features\nmostly evergreen content, you can remove the `date` placeholder from the\n[`post_url_format`][config.post_url_format] format string.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating post\nURLs. You can freely combine placeholders, and join them with slashes or other\ncharacters:\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{date}/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `categories` – Post categories, slugified with [`categories_slugify`][config.categories_slugify]\n- `date` – Post date, formatted with [`post_url_date_format`][config.post_url_date_format]\n- `slug` – Post title, slugified with [`post_slugify`][config.post_slugify], or explicitly set via [`slug`][meta.slug] metadata property\n- `file` – Post filename without `.md` file extension\n\nIf you remove the `date` placeholder, make sure that post URLs don't collide\nwith URLs of other pages hosted under the [`blog` directory][config.blog_dir],\nas this leads to undefined behavior.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories included in\npost URLs if the `categories` placeholder is part of [`post_url_format`]\n[config.post_url_format] and the post defines categories:\n\n``` yaml\nplugins:\n - blog:\n post_url_format: \"{categories}/{slug}\"\n post_url_max_categories: 2\n```\n\nIf more than one category is given, they are joined with `/` after slugifying.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n post_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`post_slugify`][config.post_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n post_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)\noptional. When a post doesn't define an excerpt, views include the entire post.\nThis setting can be used to make post excerpts required:\n\n=== \"Optional\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: optional\n ```\n\n=== \"Required\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: required\n ```\n\nWhen post excerpts are required, posts without excerpt separators raise an\nerror. Thus, this setting is useful when you want to make sure that all posts\nhave excerpts defined.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of authors rendered in\npost excerpts. While each post may be written by multiple authors, this setting\nallows to limit the display to just a few or even a single author, or disable\nauthors in post excerpts:\n\n=== \"Render up to 2 authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 2\n ```\n\n=== \"Disable authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all authors.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories rendered in\npost excerpts. While each post may be assigned to multiple categories, this\nsetting allows to limit the display to just a few or even a single category, or\ndisable categories in post excerpts:\n\n=== \"Render up to 2 categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 2\n ```\n\n=== \"Disable categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all categories.\n\n---\n\n#### \n\n\n\n\nUse this setting to set the separator the plugin will look for in a post's\ncontent when generating post excerpts. All content __before__ the separator is\nconsidered to be part of the excerpt:\n\n``` yaml\nplugins:\n - blog:\n post_excerpt_separator: \n```\n\nIt is common practice to use an HTML comment as a separator.\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should automatically compute the\nreading time of a post, which is then rendered in post excerpts, as well as in\nposts themselves:\n\n``` yaml\nplugins:\n - blog:\n post_readtime: false\n```\n\n!!! warning \"Chinese, Japanese and Korean characters\"\n\n Reading time computation currently does not take segmentation of Chinese,\n Japanese and Korean characters into account. This means that the reading\n time for posts in these languages may be inaccurate. We're planning on\n adding support in the future. In the meantime, please use the `readtime`\n front matter property to set the reading time.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of words that a reader is expected to read\nper minute when computing the reading time of a post. If you want to fine-tune\nit, use:\n\n``` yaml\nplugins:\n - blog:\n post_readtime_words_per_minute: 300\n```\n\nA reading time of 265 words per minute is considered to be the\n[average reading time of an adult].\n\n [average reading time of an adult]: https://help.medium.com/hc/en-us/articles/214991667-Read-time\n\n### Archive\n\nThe following settings are available for archive pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable archive pages. An archive page shows all\nposts for a specific interval (e.g. year, month, etc.) in reverse order. If you\nwant to disable archive pages, use:\n\n``` yaml\nplugins:\n - blog:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the archive section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_name: Archive\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page titles. The\nformat string must adhere to [babel]'s [pattern syntax]. Some popular choices:\n\n=== \"2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: yyyy\n ```\n\n=== \"January 2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: MMMM yyyy\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page URLs. The\nformat string must adhere to [babel]'s [pattern syntax] and should not contain\nwhitespace. Some popular choices:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy\n ```\n\n=== \":material-link: blog/archive/2024/01/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy/MM\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\narchive page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"archive/{date}\"\n ```\n\n=== \":material-link: blog/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"{date}\"\n ```\n\nThe following placeholders are available:\n\n- `date` – Archive date, formatted with [`archive_url_date_format`][config.archive_url_date_format]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for archive pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\narchive pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use\n\n``` yaml\nplugins:\n - blog:\n archive_toc: true\n```\n\n### Categories\n\nThe following settings are available for category pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable category pages. A category page shows all\nposts for a specific category in reverse chronological order. If you want to\ndisable category pages, use:\n\n``` yaml\nplugins:\n - blog:\n categories: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the category section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_name: Categories\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\ncategory page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/category/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"category/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Category, slugified with [`categories_slugify`][config.categories_slugify]\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom categories. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`categories_slugify`][config.categories_slugify]. While\nthe default is a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for sorting categories. For\nexample, if you want to sort categories by the number of posts they contain,\nuse the following configuration:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_by: !!python/name:material.plugins.blog.view_post_count\n```\n\nDon't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].\nYou can define your own comparison function, which must return something\nthat can be compared while sorting, i.e., a string or number.\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which categories are sorted. By\ndefault, categories are sorted in ascending order, but you can reverse ordering\nas follows:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check categories against a predefined list, in order to\ncatch typos or make sure that categories are not arbitrarily added. Specify the\ncategories you want to allow with:\n\n``` yaml\nplugins:\n - blog:\n categories_allowed:\n - Search\n - Performance\n```\n\nThe plugin stops the build if a post references a category that is not part of\nthis list. Posts can be assigned to categories by using the [`categories`]\n[meta.categories] metadata property.\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for category pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per category page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\ncategory pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_toc: true\n```\n\n### Authors\n\nThe following settings are available for authors:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable post authors. If this setting is enabled,\nthe plugin will look for a file named [`.authors.yml`][config.authors_file] and\nrender authors in posts and views. Disable this behavior with:\n\n``` yaml\nplugins:\n - blog:\n authors: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the author information for\nyour posts resides. It's normally not necessary to change this setting, but if\nyou need to, use:\n\n``` yaml\nplugins:\n - blog:\n authors_file: \"{blog}/.authors.yml\"\n```\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n!!! info \"Format of author information\"\n\n The `.authors.yml` file must adhere to the following format:\n\n ``` yaml title=\".authors.yml\"\n authors:\n :\n name: string # Author name\n description: string # Author description\n avatar: url # Author avatar\n slug: url # Author profile slug\n url: url # Author website URL\n ```\n\n Note that `` must be set to an identifier for associating authors\n with posts, e.g., a GitHub username like `squidfunk`. This identifier can\n then be used in the [`authors`][meta.authors] metadata property of\n a post. Multiple authors are supported. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable automatically generated author profiles.\nAn author profile shows all posts by an author in reverse chronological order.\nYou can enable author profiles with:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the authors section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_name: Authors\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\nauthor profile URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/author/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"author/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]\n- `name` – Author name from [`authors_file`][config.authors_file]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for author profiles. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\nauthor profiles. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_toc: true\n```\n\n### Pagination\n\nThe following settings are available for pagination:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination in views – generated pages\nthat show posts or subsets of posts in reverse chronological order. If you want\nto disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per page. If you have\nrather long post excerpts, it can be a good idea to reduce the number of posts\nper page:\n\n``` yaml\nplugins:\n - blog:\n pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\npaginated view URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/page/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"page/{page}\"\n ```\n\n=== \":material-link: blog/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"{page}\"\n ```\n\nThe following placeholders are available:\n\n- `page` – Page number\n\n---\n\n#### \n\n\n\n\nThe plugin uses the [paginate] module to generate the pagination markup using a\nspecial syntax. Use this setting to customize how pagination is constructed.\nSome popular choices:\n\n=== \"1 2 3 .. n\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"~2~\"\n ```\n\n=== \"1 2 3 .. n :material-chevron-right: :material-chevron-double-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_first $link_previous ~2~ $link_next $link_last\"\n ```\n\n=== \"1 :material-chevron-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_previous $page $link_next\"\n ```\n\nThe following placeholders are supported by [paginate]:\n\n- `#!css $first_page` – Number of first reachable page\n- `#!css $last_page` – Number of last reachable page\n- `#!css $page` – Number of currently selected page\n- `#!css $page_count` – Number of reachable pages\n- `#!css $items_per_page` – Maximal number of items per page\n- `#!css $first_item` – Index of first item on the current page\n- `#!css $last_item` – Index of last item on the current page\n- `#!css $item_count` – Total number of items\n- `#!css $link_first` – Link to first page (unless on first page)\n- `#!css $link_last` – Link to last page (unless on last page)\n- `#!css $link_previous` – Link to previous page (unless on first page)\n- `#!css $link_next` – Link to next page (unless on last page)\n\n [paginate]: https://pypi.org/project/paginate/\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether pagination should be automatically disabled\nwhen the view only consists of a single page. If you want to always render\npagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_if_single_page: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable persistence of content, i.e., if paginated\nviews should also display the content of their containing view. If you want to\nenable this behavior, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_keep_content: true\n```\n\n### Drafts\n\nThe following settings are available for drafts:\n\n---\n\n#### \n\n\n\n\nRendering [draft posts][meta.draft] can be useful in deploy previews. Use this\nsetting to specify whether the plugin should include posts marked as drafts when\n[building your project]:\n\n=== \"Render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: true\n ```\n\n=== \"Don't render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include posts marked as\ndrafts when [previewing your site]. If you don't wish to include draft posts\nwhen previewing, use:\n\n``` yaml\nplugins:\n - blog:\n draft_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin can automatically mark posts with future dates as drafts. When the\ndate is past today, the post is automatically included when\n[building your project], unless explicitly marked as draft:\n\n``` yaml\nplugins:\n - blog:\n draft_if_future_date: true\n```\n\n## Usage\n\n### Metadata\n\nPosts can define a handful of metadata properties that specify how the plugin\nrenders them, in which views they are integrated, and how they are linked to\neach other. The metadata of each post is validated against a schema to allow for\na quicker discovery of syntax errors.\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with [authors] by providing a list of\nidentifiers as defined in the [`authors_file`][config.authors_file]. If an\nauthor can't be resolved, the plugin will terminate with an error:\n\n``` yaml\n---\nauthors:\n - squidfunk # (1)!\n---\n\n# Post title\n...\n```\n\n1. Authors are linked by using their identifiers. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [authors]: #authors\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with one or more [categories][category],\nmaking the post a part of the generated category page. Categories are defined\nas a list of strings (whitespaces are allowed):\n\n``` yaml\n---\ncategories:\n - Search\n - Performance\n---\n\n# Post title\n...\n```\n\nIf you want to prevent accidental typos assigning categories to posts, you\ncan set a predefined list of allowed categories in `mkdocs.yml` by using\nthe [`categories_allowed`][config.categories_allowed] setting.\n\n---\n\n#### \n\n\n\n\n\nUse this property to specify a post's date. Note that this property is required,\nwhich means the build fails when it's not set. Additional dates can be set by\nusing a slightly different syntax:\n\n=== \"Date\"\n\n ``` yaml\n ---\n date: 2024-01-31\n ---\n\n # Post title\n ...\n ```\n\n=== \"Update date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31 # (1)!\n updated: 2024-02-01\n ---\n\n # Post title\n ...\n ```\n\n 1. Each post must have a creation date set.\n\n=== \"Custom date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31\n my_custom_date: 2024-02-01 # (1)!\n ---\n\n # Post title\n ...\n ```\n\n 1. The blog plugin validates all dates and allows to format them with\n [babel]'s [pattern syntax] in templates. When using theme extension,\n authors can add custom dates to templates.\n\n This was first requested in #5733.\n\nThe following date formats are supported:\n\n- `2024-01-31`\n- `2024-01-31T12:00:00`\n\n---\n\n#### \n\n\n\n\n\nUse this property to mark a post as draft. The plugin allows to include or\nexclude posts marked as drafts when [building your project] using the\n[`draft`][config.draft] setting. Mark a post as draft with:\n\n``` yaml\n---\ndraft: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to pin a post to the top of a view. In case multiple posts are\npinned, the pinned posts are sorted by descending order and appear before all\nother posts. Pin a post with:\n\n``` yaml\n---\npin: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to define a list of links that are rendered in the sidebar of\na post. The property follows the same syntax as [`nav`][mkdocs.nav] in\n`mkdocs.yml`, supporting sections and even anchors:\n\n=== \"Links\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - insiders/index.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with sections\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - Insiders:\n - insiders/index.md\n - insiders/getting-started.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with anchors\"\n\n ``` yaml\n ---\n links:\n - plugins/search.md # (1)!\n - Insiders:\n - insiders/how-to-sponsor.md\n - insiders/getting-started.md#requirements\n ---\n\n # Post title\n ...\n ```\n\n 1. If a link defines an anchor, the plugin resolves the anchor from the\n linked page and sets the anchor title as a [subtitle].\n\nAll relative links are resolved from the [`docs` directory][mkdocs.docs_dir].\n\n [subtitle]: ../reference/index.md#setting-the-page-subtitle\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the reading time of a post in minutes. When\n[`post_readtime`][config.post_readtime] is enabled, the plugin computes the\nreading time of a post, which can be overridden with:\n\n``` yaml\n---\nreadtime: 15\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the slug of a post. By default, the slug of\na post is automatically computed by the [`post_slugify`][config.post_slugify]\nfunction from the post's title, which can be overridden with:\n\n``` yaml\n---\nslug: help-im-trapped-in-a-universe-factory\n---\n\n# Post title\n...\n```\n\nSlugs are passed to [`post_url_format`][config.post_url_format].\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up your blog or migrating from another blog framework, you\n might discover that you're missing specific functionality – we're happy to\n consider adding it to the plugin! You can [open a discussion] to\n ask a question, or create a [change request] on our [issue tracker], so we\n can find out if it might be a good fit for the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","docs/plugins/group.md":"---\ntitle: Built-in group plugin\nicon: material/format-list-group\n---\n\n# Built-in group plugin\n\nThe group plugin allows to group plugins into logical units to conditionally\nenable or disable them for specific environments with the use of\n[environment variables][mkdocs.env], e.g., to only enable a subset of\nplugins when [building your project] during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin conditionally and lazily loads all plugins that are part of a group\nif and only if the group is enabled, which means that the plugin doesn't add any\noverhead when the group is disabled. It also means that the grouped plugins\nonly need to be installed when the group is enabled.\n\nThe plugins that are part of the group are executed in the same order as if\nthey were defined at the top-level in the list of [`plugins`][mkdocs.plugins].\nThus, order is preserved and deterministic.\n\n### When to use it\n\nWhenever you're using multiple plugins that are only required in specific\nenvironments, e.g., when building your project during continuous integration\n(CI), the plugin is the perfect utility for making configuration simpler, as it\nremoves the need for splitting configuration into multiple files.\n\nIt can be used with any built-in or third-party plugin.\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the group plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nsplitting plugins into logical units:\n\n``` yaml\nplugins:\n - group\n```\n\nThe group plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [group]: group.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nThe plugin behaves differently than all other built-in plugins – __it is\ndisabled by default__. To enable a group, use:\n\n``` yaml\nplugins:\n - group:\n enabled: !ENV CI # (1)!\n```\n\n1. If you only want to use the group plugin for better organization and\n always want to enable the plugins that are part of it, use:\n\n ``` yaml\n plugins:\n - group:\n enabled: true\n ```\n\nThe decision to disable the plugin by default was made to simplify the usage\nof environment variables, as it removes the need to provide a default value for\nan environment variable.\n\nNow, when [building your project], you can enable a group by setting the\n[environment variable][mkdocs.env]:\n\n``` sh\nCI=true mkdocs build\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to list the plugins that are part of the group. The syntax is\nexactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can\nsimply copy the list of plugins that you want to group, e.g:\n\n``` yaml\nplugins:\n - group:\n plugins:\n - optimize\n - minify\n```\n\nThe plugins mentioned here are just used for illustration purposes.\n","docs/plugins/offline.md":"---\ntitle: Built-in offline plugin\nicon: material/connection\n---\n\n\n# Built-in offline plugin\n\n[MkDocs][mkdocs] is one of the few frameworks that supports building\noffline-capable documentation that can be directly viewed by the user – no\nserver needed. With the offline plugin, you can distribute the\n[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while\nretaining most interactive functionality.\n\n## Objective\n\n### How it works\n\nAfter [building your project], switch to the [`site` directory][mkdocs.site_dir]\nand open `index.html` in your browser – you're now viewing your documentation\nfrom your local file system! Most browsers will denote this by showing `file://`\nin the address bar. However, you'll realize that the site search is gone.\n\nMaterial for MkDocs offers many interactive features, some of which will not\nwork from the local file system due to the restrictions of modern browsers. More\nspecifically and technically, all calls to the [Fetch API] will error with a\nmessage like:\n\n```\nCross origin requests are only supported for protocol schemes: http, [...]\n```\n\nWhile browsers impose those restriction for security reasons, it reduces the\ninteractivity of your project. The offline plugin makes sure that site search\nkeeps working by moving the search index to a JavaScript file, and leveraging\n@squidfunk's [iframe-worker] shim.\n\nAdditionally, the plugin automatically disables the [`use_directory_urls`]\n[mkdocs.use_directory_urls] setting, ensuring that users can open your\ndocumentation directly from the local file system.\n\nThere are some [limitations].\n\n [building your project]: ../creating-your-site.md#building-your-site\n [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API\n [iframe-worker]: https://github.com/squidfunk/iframe-worker\n [limitations]: #limitations\n\n### When to use it\n\nAs the name already indicates, the plugin should only be used when you're\n[building your project] for offline distribution. It's also good to know, that\nthe offline plugin plays nicely with the following other plugins, helping to\ncreate even better offline-capable documentation:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use external assets when building for\n offline usage, as it automatically downloads them for distribution with\n your documentation.\n\n ---\n\n __Your documentation can work without connectivity to the internet[^1]__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [^1]:\n You might wonder why the [privacy plugin][privacy] is necessary to build\n truly offline-capable documentation with the offline plugin. While it's\n certainly possible to also add support for downloading external assets to\n the offline plugin, this functionality is already fully implemented in the\n privacy plugin and is its very raison d'être.\n\n Material for MkDocs follows a modular approach for its plugin system – many\n of the plugins work perfectly together and enhance each others\n functionalities, allowing to solve complex problems with a few lines\n of configuration.\n\n [privacy]: privacy.md\n [optimize]: optimize.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the offline plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nbuilding offline-capable documentation:\n\n``` yaml\nplugins:\n - offline\n```\n\nThe offline plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [offline]: offline.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to build online- as well as offline-capable documentation, it's a\ngood idea to use an [environment variable][mkdocs.env]:\n\n``` yaml\nplugins:\n - offline:\n enabled: !ENV [OFFLINE, false]\n```\n\n## Limitations\n\nWhen enabling the offline plugin, make sure to disable the following settings,\nas they make use of the [Fetch API] which will error when invoked from the local\nfile system:\n\n- [Instant loading]\n- [Site analytics]\n- [Versioning]\n- [Comment systems]\n\n [Instant loading]: ../setup/setting-up-navigation.md#instant-loading\n [Site analytics]: ../setup/setting-up-site-analytics.md\n [Versioning]: ../setup/setting-up-versioning.md\n [Comment systems]: ../setup/adding-a-comment-system.md\n","docs/plugins/index.md":"# Built-in plugins\n\nMaterial for MkDocs started out as a theme for [MkDocs][mkdocs], but has since\nevolved into a full-fledged framework for building and maintaining documentation.\nThe theme is still the core of the project, but it's now accompanied by a\ngrowing number of complementary built-in plugins.\n\nWe strive to make those plugins as modular and generic as possible, so that they\ncan be used in a wide variety of projects and use cases. By providing useful\ndefault settings, we also try to make them as easy to use as possible, so that\nyou can get started quickly, tweaking their settings later on. When\ndeveloping built-in plugins, we always adhere to the following design principles:\n\n- **Modularity:** Built-in plugins are designed to be modular, so that they can\n be easily combined to implement sophisticated pipelines. For example, the\n [offline], [optimize] and [privacy] plugins can be used together to build\n truly [offline-capable documentation].\n\n- **Interoperability:** Built-in plugins are designed to be as compatible as\n possible, so they can be used in combination with other plugins, including\n third-party plugins. We strive to make it simple to integrate with the vast\n ecosystem that has evolved around [MkDocs][mkdocs].\n\n- **Performance:** Built-in plugins are designed to be as fast and\n memory-efficient as possible, so that they don't unnecessarily slow down\n builds. This is particularly important for large documentation projects with\n thousands of pages.\n\n [mkdocs]: https://www.mkdocs.org/\n [design principles]: ../design-principles.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Categories\n\n### Management\n\nThe following plugins greatly improve the authoring experience when working on\ndocumentation projects by providing better management capabilities, from the\nmanagement of plugins, multiple projects, and metadata, to the creation of\nminimal reproductions for bug reports:\n\n\n\n- :material-format-list-group: __[Built-in group plugin][group]__\n\n ---\n\n The group plugin allows to group plugins into logical units to conditionally\n enable or disable them for specific environments with the use of\n [environment variables][mkdocs.env].\n\n ---\n\n __Optimal management of plugins when building in different environments__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to manage metadata (front matter) for all\n pages in a folder, so a certain subset of pages uses specific tags or a\n custom template.\n\n ---\n\n __Simpler organization, categorization and management of metadata__\n\n- :material-folder-open: __[Built-in projects plugin][projects]__\n\n ---\n\n The projects plugin allows to split your main project into multiple distinct\n projects, build them concurrently and preview them together as one.\n\n ---\n\n __Connect multiple projects together, and build them separately or as one__\n\n- :material-information: __[Built-in info plugin][info]__\n\n ---\n\n The info plugin is a small and useful utility that helps to create\n self-contained minimal reproductions, so we maintainers can fix reported\n bugs more quickly.\n\n ---\n\n __Your bug reports are of the highest quality, so we can fix them as fast as\n possible__\n\n\n
\n\n [group]: group.md\n [info]: info.md\n [meta]: meta.md\n [projects]: projects.md\n\n### Optimization\n\nThe following plugins are designed to help you build optimized documentation,\nmaking it more accessible to your users through faster loading times, better\nsearch engine rankings, beautiful preview images on social media, and GDPR\ncompliance with a few lines of configuration:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each page of your documentation, showing as previews on\n social media.\n\n ---\n\n __Links to your site render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your site loads faster as smaller images are served to your users__\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin downloads external assets automatically for easy\n self-hosting, allowing for GDPR compliance with a single line of\n configuration.\n\n ---\n\n __Your documentation can be made GDPR compliant with minimal effort__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [offline]: offline.md\n [optimize]: optimize.md\n [privacy]: privacy.md\n [social]: social.md\n\n### Content\n\nThe following plugins are designed to help you set up a blog, provide search\nfunctionality to your users, add tags to pages and posts, and use the same\ntypesetting capabilities in specific parts of the documentation exactly as in\nthe main content:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The blog plugin adds first-class support for blogging to Material for\n MkDocs, either as a sidecar to your documentation or as a standalone\n installation.\n\n ---\n\n __Your blog is built with the same powerful engine as your documentation__\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The search plugin adds a search bar to the header, allowing users to search\n the entire documentation, so it's easier for them to find what they're\n looking for.\n\n ---\n\n __Your documentation is searchable without any external services, even\n offline__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin adds first-class support for categorizing pages with tags,\n adding the ability to group related pages to improve the discovery of\n related content.\n\n ---\n\n __Your pages are categorized with tags, yielding additional context__\n\n- :material-format-title: __[Built-in typeset plugin][typeset]__\n\n ---\n\n The typeset plugin allows to preserve the enriched presentation of titles\n and headlines within the navigation and table of contents.\n\n ---\n\n __Sidebars preserve the same formatting as section titles in pages__\n\n
\n\n [blog]: blog.md\n [search]: search.md\n [tags]: tags.md\n [typeset]: typeset.md\n\n## Architecture\n\n### Multiple instances\n\nSeveral built-in plugins have support for multiple instances, which means that\nthey can be used multiple times in the same configuration file, allowing to\nfine-tune behavior for separate sections of your project. Currently, the\nfollowing plugins have support for multiple instances:\n\n\n\n- [Built-in blog plugin][blog]\n- [Built-in group plugin][group]\n- [Built-in optimize plugin][optimize]\n- [Built-in privacy plugin][privacy]\n- [Built-in social plugin][social]\n\n
\n","docs/plugins/info.md":"---\ntitle: Built-in info plugin\nicon: material/information\n---\n\n# Built-in info plugin\n\nThe info plugin is a utility that is solely intended to create self-contained\n[minimal reproductions] as `.zip` files when [reporting bugs] or proposing\n[change requests], making communication between us maintainers and you much\neasier, as we have a common ground to work on.\n\n [minimal reproductions]: ../guides/creating-a-reproduction.md\n [reporting bugs]: ../contributing/reporting-a-bug.md\n [change requests]: ../contributing/requesting-a-change.md\n\n## Objective\n\n### How it works\n\nThe plugin helps you to prepare a minimal reproduction by collecting the\nnecessary information about the environment and configuration of your project.\nThis makes it easier for us to fix bugs, as it requires that you\n[upgrade to the latest version] and [remove your customizations].\n\nWhen following these principles, you can be confident that you don't report a\nbug that has already been fixed in a subsequent release, or which is caused by\none of your customizations. Even more importantly, you actively help\nus to fix the bug as quickly as possible.\n\nThe output of the plugin is a `.zip` file that you can share with us maintainers.\n\n [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version\n [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations\n\n\n### When to use it\n\nWhenever you're [reporting a bug][reporting bugs] or have something to discuss,\nlike a question or [change request][change requests], you should attach\na small, self-contained minimal reproduction. Runnable examples help to make\ncommunication much more efficient, giving us maintainers more time to benefit\nmore users by pushing the project forward. Minimal reproductions are mandatory\nfor bug reports.\n\n## Configuration\n\n\n\n\nIn order to get started with the built-in info plugin, just add the following\nlines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share\nwith us maintainers:\n\n``` yaml\nplugins:\n - info\n```\n\nThe info plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [info]: info.md\n [create a minimal reproduction]: ../guides/creating-a-reproduction.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - info:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should be enabled when\n[previewing your site]. It's normally not necessary to specify this setting,\nbut if you want to change this behavior, use:\n\n``` yaml\nplugins:\n - info:\n enabled_on_serve: true\n```\n\nThis setting streamlines the process of creating and inspecting minimal\nreproductions, as it allows to quickly iterate on the reproduction without\nhaving to disable the plugin first.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n### Archive\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should create a `.zip` file\nfrom the project or exit after the version check. This setting is solely\nintended for debugging the plugin itself:\n\n``` yaml\nplugins:\n - info:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should stop creating the `.zip`\nfile when one of the [requirements] is not satisfied. This setting must only be\nused when [reporting a bug][reporting bugs] that is related to a customization\n[explicitly mentioned in our documentation]. You can change it with:\n\n``` yaml\nplugins:\n - info:\n archive_stop_on_violation: false\n```\n\nIf you're using this setting when [reporting a bug][reporting bugs], please\nexplain why you think it is necessary to include customizations. If you're\nunsure, please ask us first by [creating a discussion].\n\n [requirements]: #how-it-works\n [explicitly mentioned in our documentation]: ?q=%22extends+base%22\n [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n","docs/plugins/meta.md":"---\ntitle: Built-in meta plugin\nicon: material/file-tree\n---\n\n# Built-in meta plugin\n\nThe meta plugin solves the problem of setting metadata (front matter) for all\npages in a folder, i.e., a subsection of your project, which is particularly\nuseful to ensure that a certain subset of pages features specific tags, uses a\ncustom template, or is attributed to an author.\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,\nand recursively merges the contents of those files with the metadata (front\nmatter) of all pages that are contained in the same folder and all subfolders.\nFor example, if you want to add the tag Example to\nmultiple pages, use:\n\n``` yaml title=\".meta.yml\"\ntags:\n - Example\n```\n\nNow, given the following directory layout, if you store the file in the folder\nnamed `example`, all pages in that folder receive the tag, while all pages\noutside of the folder remain unaffected:\n\n``` { .sh .no-copy hl_lines=\"4-8\" }\n.\n├─ docs/\n│ ├─ ...\n│ ├─ example/\n│ │ ├─ .meta.yml\n│ │ ├─ a.md\n│ │ ├─ ...\n│ │ └─ z.md\n│ └─ ...\n└─ mkdocs.yml\n```\n\nWhen combining metadata, lists and dictionaries are recursively merged, which\nmeans you can append values to a list and add or set specific properties in a\ndictionary on arbitrary levels.\n\n### When to use it\n\nWhile the plugin itself doesn't offer much functionality beyond adding and\nmerging metadata, it is a perfect companion for many of the other built-in\nplugins that Material for MkDocs offers. Some of the most powerful combinations\nof the meta plugin and other built-in plugins are:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The meta plugin can be used to [change the layout] for social cards or\n [change specific layout options] like [background] or [color]\n for a subset of pages.\n\n ``` yaml title=\".meta.yml\"\n social:\n cards_layout: default/variant\n ```\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The meta plugin allows to automatically associate blog posts with specific\n [authors] and [categories], ensuring that blog posts are always correctly\n annotated.\n\n ``` yaml title=\".meta.yml\"\n authors:\n - squidfunk\n ```\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags], so they can't be forgotten when\n adding pages.\n\n ``` yaml title=\".meta.yml\"\n tags:\n - Example\n ```\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The meta plugin makes it easy to [boost] specific sections in search results\n or to [exclude] them entirely from being indexed, giving more granular\n control over search.\n\n ``` yaml title=\".meta.yml\"\n search:\n exclude: true\n ```\n\n
\n\n [social]: social.md\n [change the layout]: social.md#meta.social.cards_layout\n [change specific layout options]: social.md#meta.social.cards_layout_options\n [background]: social.md#option.background_color\n [color]: social.md#option.color\n [blog]: blog.md\n [authors]: blog.md#meta.authors\n [categories]: blog.md#meta.categories\n [tags]: tags.md\n [specific tags]: tags.md#meta.tags\n [search]: search.md\n [exclude]: search.md#meta.search.exclude\n [boost]: search.md#meta.search.boost\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the meta plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\napplying metadata for multiple pages at once:\n\n``` yaml\nplugins:\n - meta\n```\n\nThe meta plugin is included with Material for MkDocs and doesn't need to be\ninstalled.\n\n [meta]: meta.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - meta:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Meta file\n\nThe following settings are available for meta files:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the meta file name the plugin will look for when\nscanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to\nchange this setting, but if you want to change it, use:\n\n``` yaml\nplugins:\n - meta:\n meta_file: .meta.yml\n```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir]\nrecursively.\n","docs/plugins/optimize.md":"---\ntitle: Built-in optimize plugin\nicon: material/rabbit\n---\n\n# Built-in optimize plugin\n\nThe optimize plugin automatically identifies and optimizes all media files when\n[building your project] by using common compression and conversion techniques.\nAs a result, your site loads significantly faster and yields better rankings in\nsearch engines.\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and\nassets, optimizing them automatically in order to reduce the final size of the\n[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you\nship less bytes to your users, as well as a smaller download for\n[offline-capable documentation].\n\nOptimized images are [intelligently cached][intelligent caching], which is why\nthe plugin will only optimize media files that changed since the last build.\nThis makes it possible to swap out or update images, without having to worry\nabout optimizing them, or even worse, forgetting to do so.\n\nIn order to optimize media files, a few [dependencies] need to be available on\nyour system.\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [dependencies]: #configuration\n\n### When to use it\n\nIt's generally recommended to use the plugin, as media files are optimized\nautomatically without the need for intervention, ensuring that your site loads\nas fast as possible. Optimized media files are one of the key components for a\nhigh and consistent ranking in search engines.\n\nAdditionally, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated\nbuild pipelines tailored to your project:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use unoptimized external assets, passing\n them to the optimize plugin before copying them to the [`site` directory]\n [mkdocs.site_dir].\n\n ---\n\n __External media files can be automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [privacy]: privacy.md\n [offline]: offline.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the optimize plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and observe how\nmedia files are optimized automatically:\n\n``` yaml\nplugins:\n - optimize\n```\n\nThe optimize plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to optimize all media files, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [optimize]: optimize.md\n [built-in plugins]: index.md\n [image processing]: requirements/image-processing.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - optimize:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete media file optimization faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - optimize:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a media\nfile or asset is only passed through the optimization pipeline when its contents\nchange. If you swap out or update an image, the plugin detects it and updates\nthe optimized version of the media file.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-optimize all media files, even though the cache may not be stale. It's\nnormally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - optimize:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where media files are cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - optimize:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Optimization\n\nDocumentation often makes use of screenshots or diagrams for better\nvisualization of things, both of which are prime candidates for optimization.\nThe plugin automatically optimizes images using [pngquant] for `.png` files,\nand [Pillow] for `.jpg` files.\n\nThe following settings are available for optimization:\n\n [pngquant]: https://pngquant.org/\n [Pillow]: https://pillow.readthedocs.io/\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable media file optimization. Currently,\nthe plugin's sole purpose is to optimize media files, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the near future, other features\nmight be added. If you want to disable optimization, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.png` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.png` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the speed/quality tradeoff that [pngquant] applies\nwhen optimizing `.png` files. The lower the number, the more aggressively\n[pngquant] will try to optimize:\n\n=== \"Slower smaller \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 1\n ```\n\n=== \"Faster larger \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 10\n ```\n\nA factor of `10` has 5% lower quality, but is 8x faster than the default `3`.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [pngquant] should strip optional metadata\nfrom `.png` files that are not required to display the image, e.g., [EXIF].\nIf you want to preserve metadata, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png_strip: false\n```\n\n [EXIF]: https://en.wikipedia.org/wiki/Exif\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.jpg` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.jpg` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the image quality that [Pillow] applies when\noptimizing `.jpg` files. If the images look blurry, it's a good idea to\nfine-tune and change this setting:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_quality: 75\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [Pillow] should use progressive encoding\nwhen optimizing `.jpg` files, rendering faster on slow connections. If you want\nto disable progressive encoding, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_progressive: false\n```\n\n [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339\n\n---\n\n#### \n\n\n\n\nUse this setting to enable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - optimize:\n optimize_include:\n - screenshots/*\n```\n\nThis configuration enables optimization for all media files that are contained\nin the `screenshots` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - social:\n optimize_exclude:\n - vendor/*\n```\n\nThis configuration disables optimization for all media files that are contained\nin the `vendor` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n### Reporting\n\nThe following settings are available for reporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the number of bytes\ngained after optimizing each file. If you want to disable this behavior, use:\n\n``` yaml\nplugins:\n - optimize:\n print_gain: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the total number of\nbytes gained after optimizing all files. If you want to disable this behavior,\nuse:\n\n``` yaml\nplugins:\n - optimize:\n print_gain_summary: false\n```\n","docs/plugins/search.md":"---\ntitle: Built-in search plugin\nicon: material/magnify\n---\n\n# Built-in search plugin\n\nThe search plugin adds a search bar to the header, allowing users to search your\ndocumentation. It's powered by [lunr.js], a lightweight full-text search engine\nfor the browser, elimininating the need for external services, and even works\nwhen building [offline-capable documentation].\n\n [lunr.js]: https://lunrjs.com/\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML and builds a search index from all pages and\nsections by extracting the section titles and contents. It preserves some inline\nformatting like code blocks and lists, but removes all other formatting, so the\nsearch index is as small as possible.\n\nWhen a user visits your site, the search index is shipped to the browser,\nindexed with [lunr.js] and made available for fast and simple querying – no\nserver needed. This ensures that the search index is always up to date with\nyour documentation, yielding accurate results.\n\n### When to use it\n\nIt's generally recommended to use the plugin, as interactive search functionality\nis a vital part of every good documentation. Additionally, the plugin integrates\nperfectly with several of the other [built-in plugins] that Material for MkDocs\noffers:\n\n\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to [boost][meta.search.boost] specific\n sections in search results or to [exclude][meta.search.exclude] them\n entirely from being indexed, giving more granular control over search.\n\n ---\n\n __Simpler organization and management of search in different subsections__\n\n
\n\n [offline]: offline.md\n [meta]: meta.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the search plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and your users\nwill be able to search your documentation:\n\n``` yaml\nplugins:\n - search\n```\n\nThe search plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [search]: search.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - search:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Search\n\nThe following settings are available for search:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the language of the search index, enabling [stemming]\nsupport for other languages than English. The default value is automatically\ncomputed from the [site language], but can be explicitly set to another language\nor even multiple languages with:\n\n=== \"Set language\"\n\n ``` yaml\n plugins:\n - search:\n lang: en\n ```\n\n=== \"Add further languages\"\n\n ``` yaml\n plugins:\n - search:\n lang: # (1)!\n - en\n - de\n ```\n\n 1. Be aware that including support for further languages increases the\n base JavaScript payload by around 20kb and by another 15-30kb per\n language, all before `gzip`.\n\n [stemming]: https://en.wikipedia.org/wiki/Stemming\n [site language]: ../setup/changing-the-language.md#site-language\n [lunr languages]: https://github.com/MihaiValentin/lunr-languages\n\nLanguage support is provided by [lunr languages], a collection of\nlanguage-specific stemmers and stop words for [lunr.js] maintained by the\nOpen Source community.\n\n---\n\nThe following languages are currently supported by [lunr languages]:\n\n\n\n- `ar` – Arabic\n- `da` – Danish\n- `de` – German\n- `du` – Dutch\n- `en` – English\n- `es` – Spanish\n- `fi` – Finnish\n- `fr` – French\n- `hi` – Hindi\n- `hu` – Hungarian\n- `hy` – Armenian\n- `it` – Italian\n- `ja` – Japanese\n- `kn` - Kannada\n- `ko` – Korean\n- `no` – Norwegian\n- `pt` – Portuguese\n- `ro` – Romanian\n- `ru` – Russian\n- `sa` – Sanskrit\n- `sv` – Swedish\n- `ta` – Tamil\n- `te` – Telugu\n- `th` – Thai\n- `tr` – Turkish\n- `vi` – Vietnamese\n- `zh` – Chinese\n\n
\n\nIf [lunr languages] doesn't provide support for the selected [site language],\nthe plugin falls back to another language that yields the best stemming results.\nIf you discover that the search results are not satisfactory, you can contribute\nto [lunr languages] by adding support for your language.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the separator used to split words when building the\nsearch index on the client side. The default value is automatically computed\nfrom the [site language], but can also be explicitly set to another value with:\n\n``` yaml\nplugins:\n - search:\n separator: '[\\s\\-,:!=\\[\\]()\"/]+|(?!\\b)(?=[A-Z][a-z])|\\.(?!\\d)|&[lg]t;'\n```\n\nSeparators support [positive and negative lookahead assertions], which allows\nfor rather complex expressions that yield precise control over how words are\nsplit when building the search index.\n\nBroken into its parts, this separator induces the following behavior:\n\n=== \"Special characters\"\n\n ```\n [\\s\\-,:!=\\[\\]()\"/]+\n ```\n\n The first part of the expression inserts token boundaries for each\n document before and after whitespace, hyphens, commas, brackets and\n other special characters. If several of those special characters are\n adjacent, they are treated as one.\n\n=== \"Case changes\"\n\n ```\n (?!\\b)(?=[A-Z][a-z])\n ```\n\n Many programming languages have naming conventions like `PascalCase` or\n `camelCase`. By adding this subexpression to the separator,\n [words are split at case changes], tokenizing the word `PascalCase`\n into `Pascal` and `Case`.\n\n=== \"Version strings\"\n\n ```\n \\.(?!\\d)\n ```\n\n When adding `.` to the separator, version strings like `1.2.3` are split\n into `1`, `2` and `3`, which makes them undiscoverable via search. When\n using this subexpression, a small lookahead is introduced which will\n [preserve version strings] and keep them discoverable.\n\n=== \"HTML/XML tags\"\n\n ```\n &[lg]t;\n ```\n\n If your documentation includes HTML/XML code examples, you may want to allow\n users to find [specific tag names]. Unfortunately, the `<` and `>` control\n characters are encoded in code blocks as `<` and `>`. Adding this\n subexpression to the separator allows for just that.\n\n [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html\n [words are split at case changes]: ?q=searchHighlight\n [preserve version strings]: ?q=9.0.0\n [specific tag names]: ?q=script\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify the [pipeline functions] that are used to filter and\nexpand tokens after tokenizing them with the [`separator`][config.separator] and\nbefore adding them to the search index. The default value is automatically\ncomputed from the [site language], but can also be explicitly set with:\n\n``` yaml\nplugins:\n - search:\n pipeline:\n - stemmer\n - stopWordFilter\n - trimmer\n```\n\nThe following pipeline functions can be used:\n\n- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`\n- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.\n- `trimmer` – Trim whitespace from tokens\n\n [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions\n\n### Segmentation\n\nThe plugin supports text segmentation of Chinese via [jieba], a popular\nChinese text segmentation library. Other languages like Japanese and Korean are\ncurrently segmented on the client side, but we're considering to move this\nfunctionality into the plugin in the future.\n\nThe following settings are available for segmentation:\n\n [jieba]: https://pypi.org/project/jieba/\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify a [custom dictionary] to be used by [jieba] for\nsegmenting text, replacing the default dictionary. [jieba] comes with\nseveral dictionaries, which can be used with:\n\n``` yaml\nplugins:\n - search:\n jieba_dict: dict.txt\n```\n\nThe following dictionaries are provided by [jieba]:\n\n- [dict.txt.small] – 占用内存较小的词典文件\n- [dict.txt.big] – 支持繁体分词更好的词典文件\n\nThe provided path is resolved from the root directory.\n\n [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8\n [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small\n [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify an additional [user dictionary] to be used by\n[jieba] for segmenting text, augmenting the default dictionary. User\ndictionaries are ideal for tuning the segmenter:\n\n``` yaml\nplugins:\n - search:\n jieba_dict_user: user_dict.txt\n```\n\nThe provided path is resolved from the root directory.\n\n [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to increase or decrease the relevance of a page in the search\nresults, giving more weight to them. Use values above `1` to rank up and values\nbelow `1` to rank down:\n\n=== \":material-arrow-up-circle: Rank up\"\n\n ``` yaml\n ---\n search:\n boost: 2 # (1)!\n ---\n\n # Page title\n ...\n ```\n\n 1. When boosting pages, always start with low values.\n\n=== \":material-arrow-down-circle: Rank down\"\n\n ``` yaml\n ---\n search:\n boost: 0.5\n ---\n\n # Page title\n ...\n ```\n\n---\n\n#### \n\n\n\n\n\nUse this property to exclude a page from the search results. Note that this will\nnot only remove the page, but also all subsections of the page from the search\nresults:\n\n``` yaml\n---\nsearch:\n exclude: true\n---\n\n# Page title\n...\n```\n","docs/plugins/privacy.md":"---\ntitle: Built-in privacy plugin\nicon: material/shield-account\n---\n\n\n# Built-in privacy plugin\n\nThe privacy plugin offers a streamlined solution for automatically self-hosting\nexternal assets. With just a single line of configuration, the plugin can\nautomatically identify and download external assets, making GDPR compliance\nas effortless as it can possibly be.\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML for external assets, i.e., scripts, style\nsheets, images, and web fonts, downloads them, stores them in the\n[`site` directory][mkdocs.site_dir] and replaces all references with links to\nthe downloaded copies for effortless self-hosting. For example:\n\n``` html\n\n```\n\nThis external script is downloaded, and the link is replaced with:\n\n``` html\n\n```\n\nOf course, scripts and style sheets can reference further external assets,\nwhich is why this process is repeated recursively until no further external\nassets are detected:\n\n- Scripts are scanned for further scripts, style sheets and JSON files\n- Style sheets are scanned for images and web fonts\n\nAdditionally, hints like [`preconnect`][preconnect], used to reduce latency when\nrequesting external assets, are removed from the output, as they're not\nnecessary when self-hosting. After the plugin has done its work, your project\nwill be free of requests to external services.\n\nThere are some [limitations].\n\n [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin was developed to make compliance with the 2018 European\n__General Data Protection Regulation__ (GDPR) as simple as possible, while\nretaining the flexibility and power that Material for MkDocs offers, like for\nexample its tight integration with [Google Fonts].\n\nBut, that's only the start. For example, if your project includes a lot of\nimages, enabling the plugin allows to move them outside of your repository, as\nthe plugin will automatically download and store them in the [`site` directory]\n[mkdocs.site_dir] when [building your project].\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin allows to optimize all downloaded external assets\n detected by the privacy plugin by using compression and conversion\n techniques.\n\n ---\n\n __External media files are automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [Google Fonts]: ../setup/changing-the-fonts.md\n [building your project]: ../creating-your-site.md#building-your-site\n [optimize]: optimize.md\n [offline]: offline.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the privacy plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\neffortlessly self-hosting external assets:\n\n``` yaml\nplugins:\n - privacy\n```\n\nThe privacy plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [privacy]: privacy.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - privacy:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete handling of external assets faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - privacy:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that external\nassets are only downloaded when they're not already contained in the cache.\nWhile the initial build might take some time, it's a good idea to use caching,\nas it will speed up consecutive builds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-schedule downloads for all external assets, even though the cache may not be\nstale. It's normally not necessary to specify this setting, except for when\ndebugging the plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - privacy:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where downloaded copies are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages when\nbuilding your site. While not being recommended, you can disable logging with:\n\n``` yaml\nplugins:\n - privacy:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot\n be created due to a lack of permissions on Windows systems (#6550).\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported, including which\n assets were successfully downloaded by the plugin.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: debug\n ```\n\n All messages are reported, including debug messages, if and only if MkDocs\n was started with the `--verbose` flag. Note that this will print a lot of\n messages and is only useful for debugging.\n\n### External assets\n\nThe following settings are available for external assets:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should download external\nassets. If you only want the plugin to process [external links], you can disable\nhandling of external assets with:\n\n``` yaml\nplugins:\n - privacy:\n assets: false\n```\n\n [external links]: #external-links\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should downloads or only report\nexternal assets when they're encountered. If you already self-host all external\nassets, this setting can be used as a safety net to detect links to external\nassets placed by the author in pages:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch: true\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nexternal assets are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch_dir: my/custom/dir\n```\n\nThis configuration stores the downloaded copies at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to enable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_include:\n - unsplash.com/*\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to disable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_exclude: # (1)!\n - unpkg.com/mathjax@3/*\n - giscus.app/*\n```\n\n1. [MathJax] loads web fonts for typesetting of mathematical content\n through relative URLs, and thus cannot be automatically bundled by the\n privacy plugin. [MathJax can be self-hosted].\n\n [Giscus], which we recommend to use as a [comment system], uses a technique\n called code-splitting to load only the code that is necessary, which\n is implemented via relative URLs. [Giscus can be self-hosted] as well.\n\n [MathJax]: ../reference/math.md\n [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html\n [Giscus]: https://giscus.app/\n [comment system]: ../setup/adding-a-comment-system.md\n [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md\n\n---\n\n### External links\n\nThe following settings are available for external links:\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to parse and process external links to\nannotate them for [improved security], or to automatically add additional\nattributes to external links. If you want to disable processing of external\nlinks, use:\n\n``` yaml\nplugins:\n - privacy:\n links: false\n```\n\n [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/\n\n---\n\n#### \n\n\n\n\nUse this setting to specify additional attributes that should be added to\nexternal links, for example, to add `target=\"_blank\"` to all external links\nso they open in a new tab:\n\n``` yaml\nplugins:\n - privacy:\n links_attr_map:\n target: _blank\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not recommended to change this setting, as it will automatically\nannotate external links that open in a new window with `rel=\"noopener\"` for\n[improved security]:\n\n``` yaml\nplugins:\n - privacy:\n links_noopener: true\n```\n\n## Limitations\n\n### Dynamic URLs\n\nDynamically created URLs as part of scripts are not detected, and thus cannot be\ndownloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:\n\n``` js\nconst host = \"https://example.com\"\nconst path = `${host}/script.js`\n```\n\nInstead, always use fully qualified URLs:\n\n``` js\nconst url =\"https://example.com/script.js\"\n```\n\n### Embedded HTML\n\nBy default, embedded HTML files (e.g. in iframes) are not scanned for external\nassets. This is a limitation of MkDocs, as it considers `.html` files to be\ntemplates, which must be explicitly listed under\n[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets\nof an embedded HTML file:\n\n``` yaml\nextra_templates:\n - iframe.html\n```\n\nNote that the path to `iframe.html` is relative to the\n[`docs_dir`][mkdocs.docs_dir] directory.\n","docs/plugins/projects.md":"---\ntitle: Built-in projects plugin\nicon: material/folder-open\nstatus: deprecated\n---\n\n# Built-in projects plugin\n\nThe projects plugin adds the ability to split your main project into multiple\ndistinct projects, build them concurrently and preview them together as one.\nThis is particularly useful when creating a multi-language project, but can also\nbe used to split very large projects into smaller parts.\n\n!!! bug \"The built-in projects plugin is deprecated\"\n\n [Material for MkDocs is in maintenance mode]. The projects plugin, which was\n formerly part of the [Insiders] edition, was released in , the last release that includes all features from the Insiders edition.\n Unfortunately, the projects plugin turned out impossible to maintain, and\n was one of the key motivators to create [Zensical].\n\n ---\n\n __If you're considering the projects plugin, please be aware that known issues will not be fixed.__\n\n [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523\n [Zensical]: ../blog/posts/zensical.md\n [Insiders]: ../blog/posts/insiders-now-free-for-everyone.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`projects` directory][config.projects_dir] for\n`mkdocs.yml` files, identifies all nested projects and builds them concurrently.\nIf not configured otherwise, the plugin expects that your project has\nthe following directory layout, e.g. for a multi-language project:\n\n``` { .sh .no-copy }\n.\n├─ docs/\n├─ projects/\n│ ├─ en/\n│ │ ├─ docs/\n│ │ └─ mkdocs.yml\n│ └─ de/\n│ ├─ docs/\n│ └─ mkdocs.yml\n└─ mkdocs.yml\n```\n\nOne of the most useful and interesting features of the plugin is that it allows\n[previewing your site] from the main project, while still being able to preview\nand build each project individually. This is especially useful for\nmulti-language projects.\n\nIf, when [previewing your site], you change a file in one of the projects, the\nplugin only rebuilds this project and makes sure that MkDocs will also reload\nthe associated files. This also creates the opportunity for splitting your\nmain project into several projects for a better editing experience.\n\nThere are some [limitations], but we're working hard to remove them.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin came into existence because we needed a convenient and scalable\nmethod to build our [examples] repository, which features many self-contained\nand runnable projects that users can download and use as a basis when\nbootstrapping a new project or [creating a reproduction].\n\nWhen you want to create a multi-language project, or have a very large existing\nproject, you might consider using the plugin, as it makes managing, editing\nand building more comfortable.\n\n [examples]: https://github.com/mkdocs-material/examples\n [creating a reproduction]: ../guides/creating-a-reproduction.md\n\n## Configuration\n\n\n\n\n\nIn order to get started with the projects plugin, just add the following lines\nto `mkdocs.yml`, and split your main project into several distinct projects that\ncan be built concurrently:\n\n``` yaml\nplugins:\n - projects\n```\n\nThe projects plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [projects]: projects.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\nbuild projects faster. If you want to disable concurrent processing completely,\nuse:\n\n``` yaml\nplugins:\n - projects:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a\nproject is only rebuilt when its contents change. While the initial build might\ntake some time, it's a good idea to use caching, as it will speed up consecutive\nbuilds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nrebuild all projects, even though the cache may not be stale. It's normally not\nnecessary to specify this setting, except for when debugging the plugin itself.\nCaching can be disabled with:\n\n``` yaml\nplugins:\n - projects:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where the metadata is cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - projects:\n cache_dir: my/custom/dir\n```\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages from\nprojects when building your site. While not being recommended, you can disable\nlogging with:\n\n``` yaml\nplugins:\n - projects:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: debug\n ```\n\n All messages are reported, including debug messages.\n\n### Projects\n\nThe following settings are available for projects:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable building of projects. Currently, the\nplugin's sole purpose is to build projects, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable building of projects, use:\n\n``` yaml\nplugins:\n - projects:\n projects: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your projects are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - projects:\n projects_dir: projects\n```\n\nNote that the [`projects` directory][config.projects_dir] is solely used for\nproject organization – it is not included in project URLs, since projects are\nautomatically hoisted by the plugin.\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the location or name of configuration files the\nplugin will look for when scanning the [`projects` directory]\n[config.projects_dir]. Adjusting this setting can be necessary when the\nconfiguration files are located in subdirectories of projects, e.g.\n`docs/mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n projects_config_files: \"**/mkdocs.yml\" # (1)!\n```\n\n1. If all projects share the same location for their configuration files, e.g.,\n `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster\n to resolve than a `**` glob pattern.\n\n ``` yaml\n plugins:\n - projects:\n projects_config_files: \"*/docs/mkdocs.yml\"\n ```\n\n This configuration fits the following directory structure, which is quite\n common for projects using git submodules:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n ├─ projects/\n │ ├─ git-submodule-a/\n │ │ └─ docs/\n │ │ └─ mkdocs.yml\n │ └─ git-submodule-b/\n │ └─ docs/\n │ └─ mkdocs.yml\n └─ mkdocs.yml\n ```\n\nThe provided path is resolved from the [`projects` directory]\n[config.projects_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to transform the configuration of each project as read from\n`mkdocs.yml` before it is built, which allows for adjusting the configuration\nof each project when building them together, but leave them untouched when\nbuilding them individually:\n\n``` yaml\nplugins:\n - projects:\n projects_config_transform: !!python/name:projects.transform\n```\n\nThe provided module and function name are looked up in Python's [module search\npath]. You need to add your root directory to the search path when building\nyour site, so Python can resolve it. The easiest way is to add the working\ndirectory to the [`PYTHONPATH`][PYTHONPATH] environment variable:\n\n``` .sh\nexport PYTHONPATH=.\n```\n\n!!! tip \"How to define a configuration transformation function\"\n\n The [`python/name`][python-name] tag is provided by [PyYAML] and must point\n to a valid module and function name within Python's [module search path].\n The plugin passes the `project` and top-level `config` objects to the\n function.\n\n As an example, we can inherit the [`use_directory_urls`]\n [mkdocs.use_directory_urls] setting for all projects from the top-level\n configuration:\n\n ``` py title=\"projects/__init__.py\"\n from mkdocs.config.defaults import MkDocsConfig\n\n # Transform project configuration\n def transform(project: MkDocsConfig, config: MkDocsConfig):\n project.use_directory_urls = config.use_directory_urls\n ```\n\n [module search path]: https://docs.python.org/3/library/sys_path_init.html\n [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH\n [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types\n [PyYAML]: https://pyyaml.org/\n\n### Hoisting\n\nThe following settings are available for hoisting:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable hoisting of themes files to the main\nproject. If you disable this setting, each project receives a copy of the\ntheme's files, which can be considered redundant:\n\n``` yaml\nplugins:\n - projects:\n hoisting: false\n```\n\nIt's generally advisable to enable hoisting, as it yields faster deployments\nand faster loading of your project's sites, because the files are the same for\nall projects and can be deduplicated.\n\n### Limitations\n\nThe plugin is one of the latest additions to Material for MkDocs, which means it\nis rather young and has some limitations. We're working hard to remove them, and\nwe're happy to receive feedback and learn about your requirements in ?5800.\nCurrent limitations are:\n\n- __Basic multi-language support only__: we'll be investigating how to provide\n better support for multi-language projects, allowing to easier interlink\n projects and switch between them.\n\n- __Separate search indexes and sitemaps__: currently, the projects are entirely\n separate, which means they will have separate search indexes and sitemaps.\n","docs/plugins/tags.md":"---\ntitle: Built-in tags plugin\nicon: material/tag-text\n---\n\n# Built-in tags plugin\n\nThe tags plugin adds first-class support for categorizing pages with the use\nof tags, adding the possibility to group related pages and make them\ndiscoverable via search and dedicated tags indexes. If your documentation is\nlarge, tags can help to discover relevant information faster.\n\n## Objective\n\n### How it works\n\nThe plugin scans all pages for the [`tags`][meta.tags] metadata property and\ngenerates a tags index, which is an inverted list of tags and the pages they\nappear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],\nallowing for maximum flexibility when adding tags to your project.\n\n### When to use it\n\nIf you want to add one or multiple tags indexes to your project, the tags\nplugin is a perfect choice as it makes this process ridiculously simple.\nAdditionally, it integrates perfectly with several of the other\n[built-in plugins] that Material for MkDocs offers:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags][meta.tags], so they can't be\n forgotten when adding pages.\n\n ---\n\n __Simpler organization and management of tags in different subsections__\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [blog]: blog.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the tags plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start using\n[tags][meta.tags] to categorize your pages:\n\n``` yaml\nplugins:\n - tags\n```\n\nThe tags plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [tags]: tags.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - tags:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Tags\n\nThe following settings are available for tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable rendering of tags. The plugin still\nextracts tags from all pages, e.g., for [exporting tags] without rendering them.\nRendering can be disabled with:\n\n``` yaml\nplugins:\n - tags:\n tags: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\n!!! warning \"This setting is deprecated\"\n\n As of version , this setting is deprecated, as this\n version ships a __ground up rewrite of the tags plugin__ which is much more\n powerful than the previous version. Tags [listings] can be used on any page\n now.\n\n\n\nUse this setting to specify the location of the tags index, which is the page\nused to render a list of all tags and their associated pages. If this setting is\nspecified, tags become clickable, pointing to the corresponding section in the\ntags index:\n\n``` yaml\nplugins:\n - tags:\n tags_file: tags.md\n```\n\nThe page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]\nsection of `mkdocs.yml`. This setting is not required – you should only use it\nif you want to have a tags index.\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n
\n\n [listings]: ../setup/setting-up-tags.md#adding-a-tags-index\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`tags_slugify`][config.tags_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating tag\nslugs. It is a good idea to prefix tag slugs with a string that makes them\nunique, the default being:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_format: \"tag:{slug}\"\n```\n\nThe following placeholders are available:\n\n- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]\n\n---\n\n#### \n\n\n\n\n\nUse this setting to enable support for tag hierarchies (nested tags, e.g.,\n`foo/bar`). If you intend to create hierarchical listings of tags, you can\nenable this setting in `mkdocs.yml` with:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy: true\n```\n\n---\n\n#### \n\n\n\n\n\nUse this setting to change the separator that is used when creating tag\nhierarchies. By default, tags are separated by a forward slash `/`, but you\ncan change this to any string, e.g., `.`:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy_separator: .\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags. By default,\ntag comparison is case-sensitive, but you can use `tag_name_casefold` for\ncase-insensitive comparison:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the front matter property that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_property: tags\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the template variable that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_variable: tags\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check tags against a predefined list, in order to catch\ntypos or make sure that tags are not arbitrarily added. Specify the tags you\nwant to allow with:\n\n``` yaml\nplugins:\n - tags:\n tags_allowed:\n - HTML5\n - JavaScript\n - CSS\n```\n\nThe plugin stops the build if a page references a tag that is not part of\nthis list. Pages can be assigned to tags by using the [`tags`][meta.tags]\nmetadata property.\n\n### Listings\n\nThe following settings are available for listings:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable listings. It is normally not necessary to\nchange this setting, as listings are created entirely by inline comments, but\nyou can disable them if necessary with:\n\n``` yaml\nplugins:\n - tags:\n listings: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\nUse this define listing configurations that you can then reference in listings\nwith a custom identifier. Sharing configurations is a good idea, especially\nwhen you have many tag listings:\n\n``` yaml\nplugins:\n - tags:\n listings_map:\n custom-id:\n scope: true\n exclude: Internal\n```\n\nThen, just reference the listing identifier:\n\n``` html\n\n```\n\nSee the [listings section] for a list of all available settings.\n\n [listings section]: #listing-configuration\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing listing items. By\ndefault, items are ordered by their titles, but you can change the sorting\ncriterion with the following configuration:\n\n=== \"Sort by item title\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_title\n ```\n\n=== \"Sort by item URL\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_url\n ```\n\nYou can also define your own comparison function, which must return a string\nor number representing the item, that is used for sorting, and reference it in\n[`listings_sort_by`][config.listings_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which items are sorted when comparing\nthem. By default, items are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n listings_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags in listings. By\ndefault, tag comparison is case-sensitive, but you can use `tag_name_casefold`\nfor case-insensitivity:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the directive the plugin will look for\nwhen processing pages. If you want to use a shorter directive than\n`material/tags`, you could use:\n\n``` yaml\nplugins:\n - tags:\n listings_directive: $tags\n```\n\nUsing this setting, listings must now be referenced as such:\n\n``` html\n\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable tags showing up in the table of contents.\nIf you don't want tags to show up in the table of contents, you can disable this\nbehavior with:\n\n``` yaml\nplugins:\n - tags:\n listings_toc: false\n```\n\n### Shadow tags\n\nThe following settings are available for shadow tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether the plugin should include shadow tags on\npages and in listings when [building your project], which might be useful for\ndeploy previews:\n\n=== \"Show shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: true\n ```\n\n=== \"Hide shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include shadow tags on\npages and in listings when [previewing your site]. If you don't wish to include\nthem when previewing, use:\n\n``` yaml\nplugins:\n - tags:\n shadow_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin allows to specify a predefined list of shadow tags which can be\nincluded and excluded from builds by using the [`shadow`][config.shadow]\nsetting. Shadow tags must be specified as a list:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags:\n - Draft\n - Internal\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a prefix for each tag.\nIf the tag starts with this string, the tag is marked as a shadow tag. A common\npractice is to use `_` as a prefix:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_prefix: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a suffix for each tag.\nIf the tag ends with this string, the tag is marked as a shadow tag. One option\ncan be to use `Internal` as a suffix:\n\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_suffix: Internal\n```\n\n### Export\n\nThe following settings are available for exporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin creates a `tags.json` file\ninside your [`site` directory][mkdocs.site_dir], which can then be consumed by\nother plugins and projects:\n\n``` yaml\nplugins:\n - tags:\n export: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the exported tags are\nstored. It's normally not necessary to change this setting, but if you need to,\nuse:\n\n``` yaml\nplugins:\n - tags:\n export_file: tags.json\n```\n\nThe provided path is resolved from the [`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nThis setting is solely provided for convenience to disable the rendering of tags\nand listings with a single setting (e.g. by using an environment variable),\nwhile keeping the export functionality:\n\n``` yaml\nplugins:\n - tags:\n export_only: true\n```\n\nThis will automatically disable the [`tags`][config.tags] and\n[`listings`][config.listings] settings.\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a page with one or more tags, making the page\nappear in the generated tags index. Tags are defined as a list of strings\n(whitespaces are allowed):\n\n``` yaml\n---\ntags:\n - HTML5\n - JavaScript\n - CSS\n---\n\n# Page title\n...\n```\n\nIf you want to prevent accidental typos when assigning tags to pages, you can\nset a predefined list of allowed tags in `mkdocs.yml` by using the\n[`tags_allowed`][config.tags_allowed] setting.\n\n### Listing configuration\n\nThe listings configuration controls which tags are included in or excluded from\na listing and whether a listing only includes pages in the current scope.\nFurthermore, listings can override some values from the global configuration.\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should only consider pages that are\nwithin the current subsection of the documentation of the page the listing is\nembedded in:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n scope: false\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should include shadow tags, which\nallows to override the global [`shadow`][config.shadow] setting on a per-listing\nbasis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n shadow: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should render tags inside the table\nof contents, allowing to override the global [`listings_toc`][config.listings_toc]\nsetting on a per-listing basis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n toc: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be included in the listing. Each\npage that features a tag that is part of this setting, is listed under the\nrespective tag:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n include:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, all tags and pages are included.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be excluded from the listing. Each\npage that features a tag that is part of this setting, is excluded from the\nlisting entirely:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n exclude:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, no tags or pages are excluded.\n\n## Limitations\n\nThe implementation of the tags plugin is tricky due to MkDocs architecture.\nNotably, tag listing markers cannot appear within code blocks. For technical\ndetails, refer to #8114.\n","docs/plugins/social.md":"---\ntitle: Built-in social plugin\nicon: material/share-circle\n---\n\n# Built-in social plugin\n\nThe social plugin automatically and intelligently generates beautiful and highly\ncustomizable social cards in different [layouts][default layouts] for each page\nof your project, rendering as preview images whenever you or somebody else share\na link to your project on social media.\n\n## Objective\n\n### How it works\n\nThe plugin automatically generates a customizable social card for each page\nof your project, which appears as a preview image when sharing a link to your\nproject on social media, without the use of external services and just\n[a single line of configuration][configuration].\n\nWith the use of an efficient [image processing] library, the plugin allows to\ndefine [custom layouts] for social cards, which can be adapted to match your\nproject's style and branding. While it would technically be much simpler to\ngenerate social cards by using a web browser and an automation framework like\n[Puppeteer][^1], it would add further liabilities to your toolchain, with the\npotential to make build pipelines more complex, much more resource intense,\nand significantly slower.\n\n [^1]:\n [GitHub wrote in their blog] that they use [Puppeteer] to generate social\n card images for repositories, issues, commits, discussions, and basically\n everything else that appear as preview images when shared on social media.\n\nThe generated social cards are [cached] and stored in the\n[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your\nproject doesn't depend on external services. In order to generate social cards\nimages, a few [dependencies] need to be available on your system.\n\n [configuration]: #configuration\n [image processing]: requirements/image-processing.md\n [custom layouts]: ../setup/setting-up-social-cards.md#customization\n [Puppeteer]: https://github.com/puppeteer/puppeteer\n [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/\n [cached]: #caching\n [dependencies]: #configuration\n\n### When to use it\n\nThere's one particular case when we don't recommend to use the plugin: when you\nbuild [offline-capable documentation] to offer it as a download. Otherwise, it\nalways makes sense to enable the plugin, as links to your documentation shared\non social media will appear much more appealing.\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social media__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin can be used to [change the layout][meta.social.cards_layout]\n for social cards or [change specific layout options]\n [meta.social.cards_layout_options] like [background][option.background_color]\n or [color][option.color] for a subset of pages.\n\n ---\n\n __Your documentation can use completely different social cards per section__\n\n
\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [blog]: blog.md\n [meta]: meta.md\n\n## Configuration\n\n\n\n\n\n\nIn order to get started with the social plugin, just add the following lines to\n`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social\ncards for you:\n\n``` yaml\nplugins:\n - social\n```\n\nThe social plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to generate social card images, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [social]: social.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - social:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete social card generation faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - social:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that social\ncards are only regenerated when their contents change or they're not already\ncontained in the cache. If any of the variables used in a layout changes, the\nplugin detects it and regenerates the social card.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-generate social cards for all pages, even though the cache may not be stale.\nIt's normally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - social:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where social card images are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should only log errors when\ngenerating social cards without terminating the build, e.g., invalid references\nto icons. To terminate the build, use:\n\n``` yaml\nplugins:\n - social:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: warn\n ```\n\n Errors are reported as warnings, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: info\n ```\n\n Errors are only reported as informational messages.\n\n=== \"`ignore`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: ignore\n ```\n\n Errors are only reported when using the `--verbose` flag.\n\n### Social cards\n\nThe following settings are available for social card generation:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable social card generation. Currently, the\nplugin's sole purpose is to generate social cards, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable social card generation, use:\n\n``` yaml\nplugins:\n - social:\n cards: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nsocial cards are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cards_dir: my/custom/dir\n```\n\nThis configuration stores the generated images at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nIf you want to build a [custom social card layout][custom layouts], use this\nsetting to change the folder where you store your custom layouts, the default\nbeing a folder called `layouts` in your root directory:\n\n``` yaml\nplugins:\n - social:\n cards_layout_dir: layouts\n```\n\nThe provided path is resolved from the root directory.\n\n!!! tip \"Where to store custom layouts\"\n\n Our recommendation is to locate the folder outside of the\n [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]\n are not copied to the [`site` directory][mkdocs.site_dir] when\n [building your project], e.g., by adhering to the following directory\n layout:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ *.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nThe plugin ships a growing list of [`default` layouts][default layouts] for\nsocial cards. If you've created a [custom social card layout][custom layouts],\nyou can instruct the plugin to use it exactly as one of the included layouts:\n\n``` yaml\nplugins:\n - social:\n cards_layout: my-custom-layout\n```\n\nThe provided path is resolved from the[\n`layouts` directory][config.cards_layout_dir].\n\n!!! tip \"How custom layouts are resolved\"\n\n By default, the plugin will load your [custom layouts] from a folder named\n `layouts` in your root directory. If your layout is called\n `my-custom-layout`, the directory layout must adhere to:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ my-custom-layout.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to set options for the layout specified via [`cards_layout`]\n[config.cards_layout] (if the layout supports it), which allows for making\nlayouts easily and entirely configurable:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n : \n```\n\nWhen creating a [custom layout][custom layouts], you are completely free in\ndefining which parts of your layout can be parametrized. The [`default` layouts]\n[default layouts] included with the plugin support the following options:\n\n\n\n- [`background_color`][option.background_color]\n- [`background_image`][option.background_image]\n- [`color`][option.color]\n- [`font_family`][option.font_family]\n- [`font_variant`][option.font_variant]\n- [`logo`][option.logo]\n- [`title`][option.title]\n- [`description`][option.description]\n\n
\n\n\n [default layouts]: #layouts\n\n---\n\n#### \n\n\n\n\nUse this setting to enable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_include:\n - blog/*\n```\n\nThis configuration enables social card generation for all pages that are\ncontained in the `blog` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_exclude:\n - changelog/*\n```\n\nThis configuration disables social card generation for all pages that are\ncontained in the `changelog` folder and its subfolders inside the\n[`docs` directory][mkdocs.docs_dir].\n\n### Debugging\n\nThe plugin includes a special mode for debugging layouts, which is very useful\nwhen creating [custom layouts], as it allows for quicker iteration and better\nunderstanding of composition.\n\nThe following settings are available for debugging:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable a special mode for debugging your layout, which\nrenders each layer with a colored outline and its `x` and `y` offsets, and\noverlays a dot grid for alignment, so it's easier to understand how the\ndistinct layers of your layout are composed together:\n\n``` yaml\nplugins:\n - social:\n debug: true\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin automatically disables [`debug`][config.debug] mode when\n[building your project], so you can be sure that debug overlays are never\ndeployed to production. If you want to change that, use:\n\n``` yaml\nplugins:\n - social:\n debug_on_build: true\n```\n\nIt's normally not necessary to change this setting, as it's just intended to\nbe a safety net.\n\n---\n\n#### \n\n\n\n\nWhen [`debug`][config.debug] mode is enabled, this setting specifies whether a\ndot grid is rendered on top of all layers, to allow for better alignment. If you\nwant to switch the grid off, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the step size of the dot grid in pixels, if enabled,\nwhich can be useful to create perfectly aligned layers for ideal composition.\nIt you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid_step: 64\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the color of the outlines that are added to each\nlayer and the dot grid that is rendered on top of all layers. If you need to\nchange it, use:\n\n``` yaml\nplugins:\n - social:\n debug_color: yellow\n```\n\nIn rare cases, it might be necessary to change this setting if the dot grid or\nthe outlines are hard to distinguish, as the plugin will automatically adjust\nthe color if not explicitly set.\n\n## Usage\n\n### Metadata\n\nThe plugin allows to override a subset of settings through metadata (front\nmatter) in order to customize social card generation, e.g., to set [options for\nthe included `default` layouts][default layouts] for a single page, or even\n[for an entire subsection] of your project by leveraging the [meta] plugin.\n\nThe following properties are available:\n\n [for an entire subsection]: meta.md#how-it-works\n [meta]: meta.md\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards`][config.cards] setting for the given\npage:\n\n``` yaml\n---\nsocial:\n cards: false\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to override the [`cards_layout`][config.cards_layout] setting\nfor the given page:\n\n``` yaml\n---\nsocial:\n cards_layout: my-custom-layout\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards_layout_options`]\n[config.cards_layout_options] setting for the given page:\n\n``` yaml\n---\nsocial:\n cards_layout_options:\n background_color: blue # Change background color\n background_image: null # Remove background image\n---\n\n# Page title\n...\n```\n\nSetting an option to `#!yaml null` resets the option.\n\n### Layouts\n\n\n\nWhile it is possible and simple to build [custom layouts], the plugin ships\nseveral predefined layouts, all of which are prefixed with `default`. The\nfollowing layouts are included:\n\n=== \"`default`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default\n ```\n\n \n\n ![Layout default]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/variant`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/variant\n ```\n\n \n\n ![Layout default variant]\n\n This layout includes the [page icon] and sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/accent`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/accent\n ```\n\n \n\n ![Layout default accent]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/invert`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/invert\n ```\n\n \n\n ![Layout default invert]\n\n This layout sets the following defaults:\n\n - [`color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/only/image`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/only/image\n cards_layout_options:\n background_image: layouts/background.png\n\n ```\n\n \n\n This layout only shows the given background image and scales it to cover.\n\n
\n\nThe [`default` layouts][default layouts] are very flexible and comfortable to\nuse, as they replicate the original behavior of the plugin, sourcing default\nvalues for all options from other `theme` settings.\n\nThe following options are available:\n\n [Layout default]: ../assets/screenshots/social-cards.png\n [Layout default variant]: ../assets/screenshots/social-cards-variant.png\n [Layout default accent]: ../assets/screenshots/social-cards-accent.png\n [Layout default invert]: ../assets/screenshots/social-cards-invert.png\n\n [primary color]: ../setup/changing-the-colors.md#primary-color\n [page icon]: ../reference/index.md#setting-the-page-icon\n [accent color]: ../setup/changing-the-colors.md#accent-color\n [font]: ../setup/changing-the-fonts.md#regular-font\n\n---\n\n#### \n\n\n\n\nUse this option to change the background color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: \"#ff1493\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: rgb(255, 20, 147) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: deeppink # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\nIf this options is used together with [`background_image`]\n[option.background_image], the color is rendered on top of the image which\nallows for tinting images. If you want to remove the background color, use:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n background_color: transparent\n```\n\n [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names\n [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color\n\n---\n\n#### \n\n\n\n\nUse this option to define a background image for the generated social card. Note\nthat the image is tinted with the [`background_color`][option.background_color],\nwhich can also be set to `transparent`:\n\n=== \"Image\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: transparent\n ```\n\n=== \"Image with tint\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: \"#ff149366\"\n ```\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this option to change the foreground color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: \"#ffffff\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: rgb(255, 255, 255) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: white # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\n---\n\n#### \n\n\n\n\nUse this option to change the font family of the generated social card. The\nplugin automatically downloads the font from [Google Fonts], so the font must\npoint to an existing Google Font:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_family: Ubuntu\n```\n\nWhen you've found a font that you like on [Google Fonts], you can just copy the\nname from the font's specimen page and use it as the value for this option –\nno further configuration needed.\n\n [Google Fonts]: https://fonts.google.com/\n\n---\n\n#### \n\n\n\n\nUse this option to change the font variant used to generate the social card.\nIf the downloaded font has variants like `Condensed` or `Expanded`, you can set\nthem with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_variant: Condensed\n```\n\nThe variant is combined with the style as used in the custom layout, so the\nplugin is instructed to use combinations like `Condensed Regular` or\n`Expanded Bold`.\n\n---\n\n#### \n\n\n\n\nUse this option to change the logo that is used in the generated social card.\nBy default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]\n[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n logo: layouts/logo.png\n```\n\nThe provided path is resolved from the root directory.\n\n [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image\n [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled\n\n---\n\n#### \n\n\n\n\nUse this option to change the title of the generated social card. This overrides\nthe computed page title as assigned by MkDocs, as well as the [`title`]\n[meta.title] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n title: My custom title\n```\n\n [meta.title]: ../reference/index.md#setting-the-page-title\n\n---\n\n#### \n\n\n\n\nUse this option to change the description of the generated social card. This\noverrides the set [`site_description`][mkdocs.site_description], if defined, as\nwell as the [`description`][meta.description] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n description: My custom description\n```\n\n [meta.description]: ../reference/index.md#setting-the-page-description\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up social cards, you might discover that you're missing\n specific functionality – we're happy to consider adding it to the plugin!\n You can [open a discussion] to ask a question, or create a [change request]\n on our [issue tracker], so we can find out if it might be a good fit for\n the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","docs/plugins/typeset.md":"# Plugins Skill\n\nPath: `docs/plugins/typeset.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/typeset.md)","docs/plugins/requirements/caching.md":"# Requirements Skill\n\nPath: `docs/plugins/requirements/caching.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/caching.md)","docs/plugins/requirements/image-processing.md":"# Requirements Skill\n\nPath: `docs/plugins/requirements/image-processing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/image-processing.md)","docs/schema/extensions/markdown.json":"# Extensions Skill\n\nPath: `docs/schema/extensions/markdown.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/markdown.json)","docs/schema/extensions/pymdownx.json":"# Extensions Skill\n\nPath: `docs/schema/extensions/pymdownx.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/pymdownx.json)","docs/schema/plugins/blog.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/blog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/blog.json)","docs/schema/plugins/group.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/group.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/group.json)","docs/schema/plugins/info.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/info.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/info.json)","docs/schema/plugins/meta.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/meta.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/meta.json)","docs/schema/plugins/offline.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/offline.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/offline.json)","docs/schema/plugins/optimize.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/optimize.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/optimize.json)","docs/schema/plugins/privacy.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/privacy.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/privacy.json)","docs/schema/plugins/projects.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/projects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/projects.json)","docs/schema/plugins/search.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/search.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/search.json)","docs/schema/plugins/social.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/social.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/social.json)","docs/schema/plugins/tags.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/tags.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/tags.json)","docs/schema/plugins/typeset.json":"# Plugins Skill\n\nPath: `docs/schema/plugins/typeset.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/typeset.json)","docs/setup/extensions/index.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/index.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/index.md)","docs/setup/extensions/python-markdown.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown.md)","docs/setup/extensions/python-markdown-extensions.md":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown-extensions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown-extensions.md)","docs/schema/plugins/external/awesome-nav.json":"# External Skill\n\nPath: `docs/schema/plugins/external/awesome-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/awesome-nav.json)","docs/schema/plugins/external/gen-files.json":"# External Skill\n\nPath: `docs/schema/plugins/external/gen-files.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/gen-files.json)","docs/schema/plugins/external/git-authors.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-authors.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-authors.json)","docs/schema/plugins/external/git-committers.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-committers.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-committers.json)","docs/schema/plugins/external/git-revision-date.json":"# External Skill\n\nPath: `docs/schema/plugins/external/git-revision-date.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-revision-date.json)","docs/schema/plugins/external/literate-nav.json":"# External Skill\n\nPath: `docs/schema/plugins/external/literate-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/literate-nav.json)","docs/schema/plugins/external/macros.json":"# External Skill\n\nPath: `docs/schema/plugins/external/macros.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/macros.json)","docs/schema/plugins/external/minify.json":"# External Skill\n\nPath: `docs/schema/plugins/external/minify.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/minify.json)","docs/schema/plugins/external/redirects.json":"# External Skill\n\nPath: `docs/schema/plugins/external/redirects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/redirects.json)","docs/schema/plugins/external/section-index.json":"# External Skill\n\nPath: `docs/schema/plugins/external/section-index.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/section-index.json)"},"items":[{"name":"blog.md","path":"docs/plugins/blog.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/blog.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in blog plugin\nicon: material/newspaper-variant-outline\n---\n\n# Built-in blog plugin\n\nThe blog plugin makes it very easy to build a blog, either as a sidecar to\nyour documentation or as the main thing. Focus on your content while the plugin\ndoes all the heavy lifting, generating a view of all latest posts, [archive] and\n[category] pages, configurable [pagination] and much more.\n\n [archive]: #archive\n [category]: #categories\n [pagination]: #pagination\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`posts` directory][config.post_dir] for\n`.md` files from which paginated views[^1] are automatically generated. If not\nconfigured otherwise, the plugin expects that your project has the following\ndirectory layout, and will create any missing directories or files for you:\n\n [^1]:\n Views are pages that are automatically generated, i.e., the entry point to\n your blog listing all latest posts, as well as [archive] and [category]\n pages that list all posts associated with them through [metadata] in\n chronological order.\n\n``` { .sh .no-copy }\n.\n├─ docs/\n│ └─ blog/\n│ ├─ posts/\n│ └─ index.md\n└─ mkdocs.yml\n```\n\nThe `index.md` file in the [`blog` directory][config.blog_dir] is the entry\npoint to your blog – a paginated view listing all posts in reverse chronological\norder. Besides that, the plugin supports automatically creating [archive] and\n[category] pages that list a subset of posts for a time interval or category.\n\n[Post URLs][config.post_url_format] are completely configurable, no matter if\nyou want your URLs to include the post's date or not. Rendered dates always\ndisplay in the locale of the [site language] of your project. Like in other\nstatic blog frameworks, posts can be annotated with a variety of [metadata],\nallowing for easy integration with other [built-in plugins], e.g., the\n[social] and [tags] plugin.\n\nPosts can be organized in nested folders with a directory layout that suits your\nspecific needs, and can make use of all components and syntax that Material for\nMkDocs offers, including [admonitions], [annotations], [code blocks],\n[content tabs], [diagrams], [icons], [math], and more.\n\n [metadata]: #metadata\n [admonitions]: ../reference/admonitions.md\n [annotations]: ../reference/annotations.md\n [code blocks]: ../reference/code-blocks.md\n [content tabs]: ../reference/content-tabs.md\n [diagrams]: ../reference/diagrams.md\n [icons]: ../reference/icons-emojis.md\n [math]: ../reference/math.md\n\n### When to use it\n\nIf you want to add a blog to your project, or migrate from another blog\nframework to Material for MkDocs because of its excellent technical writing\ncapabilities, this plugin is a great choice, as it integrates perfectly with\nmany other built-in plugins:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to apply [metadata] to a subset of posts,\n including authors, tags, categories, draft status, as well as social card\n layouts.\n\n ---\n\n __Simpler organization, categorization and management of post metadata__\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your blog loads faster as smaller images are served to your users__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [social]: social.md\n [optimize]: optimize.md\n [tags]: tags.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the blog plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and you can\nstart writing your first post:\n\n``` yaml\nplugins:\n - blog\n```\n\nThe blog plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [blog]: blog.md\n [built-in plugins]: index.md\n\n### Navigation\n\nIf you do not have site navigation configured in your `mkdocs.yml` then there is\nnothing more to do. The blog [archive] and [category] pages will automatically\nappear underneath the automatically generated navigation.\n\nIf you do have a navigation structure defined then you will need to specify\nwhere the blog should appear in this. Create a [navigation section with an index\npage] for the blog:\n\n```yaml\ntheme:\n name: material\n features:\n - navigation.indexes\nnav:\n - ...\n - Blog:\n - blog/index.md\n```\n\nThe [archive] and [category] pages will appear within that section as\nsubsections beneath pages in the blog section. In this case, they would appear\nafter `index.md`. The path to the `index.md` file must match\n[blog_dir][config.blog_dir]. This means that you can name the blog navigation\nentry anything you like: 'Blog' or 'News' or perhaps 'Tips'.\n\n[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - blog:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path where your blog is located in the\n[`docs` directory][mkdocs.docs_dir]. The path is included in the generated\nURLs as a prefix for all posts and views. You can change it with:\n\n=== \"Documentation + Blog\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: blog\n ```\n\n=== \"Blog only\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: .\n ```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles in\nviews. This might be useful, if your post excerpts are rather long. If you want\nto enable it, use:\n\n``` yaml\nplugins:\n - blog:\n blog_toc: true\n```\n\n### Posts\n\nThe following settings are available for posts:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your posts are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - blog:\n post_dir: \"{blog}/articles\"\n```\n\nNote that the [`posts` directory][config.post_dir] is solely used for post\norganization – it is not included in post URLs, since they are automatically\nand comfortably generated by this plugin.\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format of posts. This plugin uses [babel]\nto render dates in the configured [site language]. You can use [babel]'s\n[pattern syntax] or the following shortcodes:\n\n=== \"Monday, January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: full\n ```\n\n=== \"January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: long\n ```\n\n=== \"Jan 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: medium\n ```\n\n=== \"1/31/24\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: short\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n [babel]: https://pypi.org/project/Babel/\n [site language]: ../setup/changing-the-language.md#site-language\n [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used in post URLs. The format string\nmust adhere to [babel]'s [pattern syntax] and should not contain whitespace.\nSome popular choices:\n\n=== \":material-link: blog/2024/01/31/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM/dd\n ```\n\n=== \":material-link: blog/2024/01/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM\n ```\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy\n ```\n\nIf you want to remove the date from post URLs, e.g., when your blog features\nmostly evergreen content, you can remove the `date` placeholder from the\n[`post_url_format`][config.post_url_format] format string.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating post\nURLs. You can freely combine placeholders, and join them with slashes or other\ncharacters:\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{date}/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `categories` – Post categories, slugified with [`categories_slugify`][config.categories_slugify]\n- `date` – Post date, formatted with [`post_url_date_format`][config.post_url_date_format]\n- `slug` – Post title, slugified with [`post_slugify`][config.post_slugify], or explicitly set via [`slug`][meta.slug] metadata property\n- `file` – Post filename without `.md` file extension\n\nIf you remove the `date` placeholder, make sure that post URLs don't collide\nwith URLs of other pages hosted under the [`blog` directory][config.blog_dir],\nas this leads to undefined behavior.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories included in\npost URLs if the `categories` placeholder is part of [`post_url_format`]\n[config.post_url_format] and the post defines categories:\n\n``` yaml\nplugins:\n - blog:\n post_url_format: \"{categories}/{slug}\"\n post_url_max_categories: 2\n```\n\nIf more than one category is given, they are joined with `/` after slugifying.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n post_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`post_slugify`][config.post_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n post_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)\noptional. When a post doesn't define an excerpt, views include the entire post.\nThis setting can be used to make post excerpts required:\n\n=== \"Optional\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: optional\n ```\n\n=== \"Required\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: required\n ```\n\nWhen post excerpts are required, posts without excerpt separators raise an\nerror. Thus, this setting is useful when you want to make sure that all posts\nhave excerpts defined.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of authors rendered in\npost excerpts. While each post may be written by multiple authors, this setting\nallows to limit the display to just a few or even a single author, or disable\nauthors in post excerpts:\n\n=== \"Render up to 2 authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 2\n ```\n\n=== \"Disable authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all authors.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories rendered in\npost excerpts. While each post may be assigned to multiple categories, this\nsetting allows to limit the display to just a few or even a single category, or\ndisable categories in post excerpts:\n\n=== \"Render up to 2 categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 2\n ```\n\n=== \"Disable categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all categories.\n\n---\n\n#### \n\n\n\n\nUse this setting to set the separator the plugin will look for in a post's\ncontent when generating post excerpts. All content __before__ the separator is\nconsidered to be part of the excerpt:\n\n``` yaml\nplugins:\n - blog:\n post_excerpt_separator: \n```\n\nIt is common practice to use an HTML comment as a separator.\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should automatically compute the\nreading time of a post, which is then rendered in post excerpts, as well as in\nposts themselves:\n\n``` yaml\nplugins:\n - blog:\n post_readtime: false\n```\n\n!!! warning \"Chinese, Japanese and Korean characters\"\n\n Reading time computation currently does not take segmentation of Chinese,\n Japanese and Korean characters into account. This means that the reading\n time for posts in these languages may be inaccurate. We're planning on\n adding support in the future. In the meantime, please use the `readtime`\n front matter property to set the reading time.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of words that a reader is expected to read\nper minute when computing the reading time of a post. If you want to fine-tune\nit, use:\n\n``` yaml\nplugins:\n - blog:\n post_readtime_words_per_minute: 300\n```\n\nA reading time of 265 words per minute is considered to be the\n[average reading time of an adult].\n\n [average reading time of an adult]: https://help.medium.com/hc/en-us/articles/214991667-Read-time\n\n### Archive\n\nThe following settings are available for archive pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable archive pages. An archive page shows all\nposts for a specific interval (e.g. year, month, etc.) in reverse order. If you\nwant to disable archive pages, use:\n\n``` yaml\nplugins:\n - blog:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the archive section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_name: Archive\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page titles. The\nformat string must adhere to [babel]'s [pattern syntax]. Some popular choices:\n\n=== \"2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: yyyy\n ```\n\n=== \"January 2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: MMMM yyyy\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page URLs. The\nformat string must adhere to [babel]'s [pattern syntax] and should not contain\nwhitespace. Some popular choices:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy\n ```\n\n=== \":material-link: blog/archive/2024/01/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy/MM\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\narchive page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"archive/{date}\"\n ```\n\n=== \":material-link: blog/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"{date}\"\n ```\n\nThe following placeholders are available:\n\n- `date` – Archive date, formatted with [`archive_url_date_format`][config.archive_url_date_format]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for archive pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\narchive pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use\n\n``` yaml\nplugins:\n - blog:\n archive_toc: true\n```\n\n### Categories\n\nThe following settings are available for category pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable category pages. A category page shows all\nposts for a specific category in reverse chronological order. If you want to\ndisable category pages, use:\n\n``` yaml\nplugins:\n - blog:\n categories: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the category section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_name: Categories\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\ncategory page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/category/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"category/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Category, slugified with [`categories_slugify`][config.categories_slugify]\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom categories. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`categories_slugify`][config.categories_slugify]. While\nthe default is a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for sorting categories. For\nexample, if you want to sort categories by the number of posts they contain,\nuse the following configuration:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_by: !!python/name:material.plugins.blog.view_post_count\n```\n\nDon't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].\nYou can define your own comparison function, which must return something\nthat can be compared while sorting, i.e., a string or number.\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which categories are sorted. By\ndefault, categories are sorted in ascending order, but you can reverse ordering\nas follows:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check categories against a predefined list, in order to\ncatch typos or make sure that categories are not arbitrarily added. Specify the\ncategories you want to allow with:\n\n``` yaml\nplugins:\n - blog:\n categories_allowed:\n - Search\n - Performance\n```\n\nThe plugin stops the build if a post references a category that is not part of\nthis list. Posts can be assigned to categories by using the [`categories`]\n[meta.categories] metadata property.\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for category pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per category page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\ncategory pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_toc: true\n```\n\n### Authors\n\nThe following settings are available for authors:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable post authors. If this setting is enabled,\nthe plugin will look for a file named [`.authors.yml`][config.authors_file] and\nrender authors in posts and views. Disable this behavior with:\n\n``` yaml\nplugins:\n - blog:\n authors: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the author information for\nyour posts resides. It's normally not necessary to change this setting, but if\nyou need to, use:\n\n``` yaml\nplugins:\n - blog:\n authors_file: \"{blog}/.authors.yml\"\n```\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n!!! info \"Format of author information\"\n\n The `.authors.yml` file must adhere to the following format:\n\n ``` yaml title=\".authors.yml\"\n authors:\n :\n name: string # Author name\n description: string # Author description\n avatar: url # Author avatar\n slug: url # Author profile slug\n url: url # Author website URL\n ```\n\n Note that `` must be set to an identifier for associating authors\n with posts, e.g., a GitHub username like `squidfunk`. This identifier can\n then be used in the [`authors`][meta.authors] metadata property of\n a post. Multiple authors are supported. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable automatically generated author profiles.\nAn author profile shows all posts by an author in reverse chronological order.\nYou can enable author profiles with:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the authors section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_name: Authors\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\nauthor profile URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/author/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"author/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]\n- `name` – Author name from [`authors_file`][config.authors_file]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for author profiles. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\nauthor profiles. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_toc: true\n```\n\n### Pagination\n\nThe following settings are available for pagination:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination in views – generated pages\nthat show posts or subsets of posts in reverse chronological order. If you want\nto disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per page. If you have\nrather long post excerpts, it can be a good idea to reduce the number of posts\nper page:\n\n``` yaml\nplugins:\n - blog:\n pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\npaginated view URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/page/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"page/{page}\"\n ```\n\n=== \":material-link: blog/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"{page}\"\n ```\n\nThe following placeholders are available:\n\n- `page` – Page number\n\n---\n\n#### \n\n\n\n\nThe plugin uses the [paginate] module to generate the pagination markup using a\nspecial syntax. Use this setting to customize how pagination is constructed.\nSome popular choices:\n\n=== \"1 2 3 .. n\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"~2~\"\n ```\n\n=== \"1 2 3 .. n :material-chevron-right: :material-chevron-double-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_first $link_previous ~2~ $link_next $link_last\"\n ```\n\n=== \"1 :material-chevron-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_previous $page $link_next\"\n ```\n\nThe following placeholders are supported by [paginate]:\n\n- `#!css $first_page` – Number of first reachable page\n- `#!css $last_page` – Number of last reachable page\n- `#!css $page` – Number of currently selected page\n- `#!css $page_count` – Number of reachable pages\n- `#!css $items_per_page` – Maximal number of items per page\n- `#!css $first_item` – Index of first item on the current page\n- `#!css $last_item` – Index of last item on the current page\n- `#!css $item_count` – Total number of items\n- `#!css $link_first` – Link to first page (unless on first page)\n- `#!css $link_last` – Link to last page (unless on last page)\n- `#!css $link_previous` – Link to previous page (unless on first page)\n- `#!css $link_next` – Link to next page (unless on last page)\n\n [paginate]: https://pypi.org/project/paginate/\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether pagination should be automatically disabled\nwhen the view only consists of a single page. If you want to always render\npagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_if_single_page: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable persistence of content, i.e., if paginated\nviews should also display the content of their containing view. If you want to\nenable this behavior, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_keep_content: true\n```\n\n### Drafts\n\nThe following settings are available for drafts:\n\n---\n\n#### \n\n\n\n\nRendering [draft posts][meta.draft] can be useful in deploy previews. Use this\nsetting to specify whether the plugin should include posts marked as drafts when\n[building your project]:\n\n=== \"Render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: true\n ```\n\n=== \"Don't render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include posts marked as\ndrafts when [previewing your site]. If you don't wish to include draft posts\nwhen previewing, use:\n\n``` yaml\nplugins:\n - blog:\n draft_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin can automatically mark posts with future dates as drafts. When the\ndate is past today, the post is automatically included when\n[building your project], unless explicitly marked as draft:\n\n``` yaml\nplugins:\n - blog:\n draft_if_future_date: true\n```\n\n## Usage\n\n### Metadata\n\nPosts can define a handful of metadata properties that specify how the plugin\nrenders them, in which views they are integrated, and how they are linked to\neach other. The metadata of each post is validated against a schema to allow for\na quicker discovery of syntax errors.\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with [authors] by providing a list of\nidentifiers as defined in the [`authors_file`][config.authors_file]. If an\nauthor can't be resolved, the plugin will terminate with an error:\n\n``` yaml\n---\nauthors:\n - squidfunk # (1)!\n---\n\n# Post title\n...\n```\n\n1. Authors are linked by using their identifiers. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [authors]: #authors\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with one or more [categories][category],\nmaking the post a part of the generated category page. Categories are defined\nas a list of strings (whitespaces are allowed):\n\n``` yaml\n---\ncategories:\n - Search\n - Performance\n---\n\n# Post title\n...\n```\n\nIf you want to prevent accidental typos assigning categories to posts, you\ncan set a predefined list of allowed categories in `mkdocs.yml` by using\nthe [`categories_allowed`][config.categories_allowed] setting.\n\n---\n\n#### \n\n\n\n\n\nUse this property to specify a post's date. Note that this property is required,\nwhich means the build fails when it's not set. Additional dates can be set by\nusing a slightly different syntax:\n\n=== \"Date\"\n\n ``` yaml\n ---\n date: 2024-01-31\n ---\n\n # Post title\n ...\n ```\n\n=== \"Update date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31 # (1)!\n updated: 2024-02-01\n ---\n\n # Post title\n ...\n ```\n\n 1. Each post must have a creation date set.\n\n=== \"Custom date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31\n my_custom_date: 2024-02-01 # (1)!\n ---\n\n # Post title\n ...\n ```\n\n 1. The blog plugin validates all dates and allows to format them with\n [babel]'s [pattern syntax] in templates. When using theme extension,\n authors can add custom dates to templates.\n\n This was first requested in #5733.\n\nThe following date formats are supported:\n\n- `2024-01-31`\n- `2024-01-31T12:00:00`\n\n---\n\n#### \n\n\n\n\n\nUse this property to mark a post as draft. The plugin allows to include or\nexclude posts marked as drafts when [building your project] using the\n[`draft`][config.draft] setting. Mark a post as draft with:\n\n``` yaml\n---\ndraft: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to pin a post to the top of a view. In case multiple posts are\npinned, the pinned posts are sorted by descending order and appear before all\nother posts. Pin a post with:\n\n``` yaml\n---\npin: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to define a list of links that are rendered in the sidebar of\na post. The property follows the same syntax as [`nav`][mkdocs.nav] in\n`mkdocs.yml`, supporting sections and even anchors:\n\n=== \"Links\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - insiders/index.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with sections\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - Insiders:\n - insiders/index.md\n - insiders/getting-started.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with anchors\"\n\n ``` yaml\n ---\n links:\n - plugins/search.md # (1)!\n - Insiders:\n - insiders/how-to-sponsor.md\n - insiders/getting-started.md#requirements\n ---\n\n # Post title\n ...\n ```\n\n 1. If a link defines an anchor, the plugin resolves the anchor from the\n linked page and sets the anchor title as a [subtitle].\n\nAll relative links are resolved from the [`docs` directory][mkdocs.docs_dir].\n\n [subtitle]: ../reference/index.md#setting-the-page-subtitle\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the reading time of a post in minutes. When\n[`post_readtime`][config.post_readtime] is enabled, the plugin computes the\nreading time of a post, which can be overridden with:\n\n``` yaml\n---\nreadtime: 15\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the slug of a post. By default, the slug of\na post is automatically computed by the [`post_slugify`][config.post_slugify]\nfunction from the post's title, which can be overridden with:\n\n``` yaml\n---\nslug: help-im-trapped-in-a-universe-factory\n---\n\n# Post title\n...\n```\n\nSlugs are passed to [`post_url_format`][config.post_url_format].\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up your blog or migrating from another blog framework, you\n might discover that you're missing specific functionality – we're happy to\n consider adding it to the plugin! You can [open a discussion] to\n ask a question, or create a [change request] on our [issue tracker], so we\n can find out if it might be a good fit for the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","frontmatter":{"title":"Built-in blog plugin","icon":"material/newspaper-variant-outline"},"isInternal":false,"tokens":10072,"sizeBytes":41897},{"name":"group.md","path":"docs/plugins/group.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/group.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in group plugin\nicon: material/format-list-group\n---\n\n# Built-in group plugin\n\nThe group plugin allows to group plugins into logical units to conditionally\nenable or disable them for specific environments with the use of\n[environment variables][mkdocs.env], e.g., to only enable a subset of\nplugins when [building your project] during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin conditionally and lazily loads all plugins that are part of a group\nif and only if the group is enabled, which means that the plugin doesn't add any\noverhead when the group is disabled. It also means that the grouped plugins\nonly need to be installed when the group is enabled.\n\nThe plugins that are part of the group are executed in the same order as if\nthey were defined at the top-level in the list of [`plugins`][mkdocs.plugins].\nThus, order is preserved and deterministic.\n\n### When to use it\n\nWhenever you're using multiple plugins that are only required in specific\nenvironments, e.g., when building your project during continuous integration\n(CI), the plugin is the perfect utility for making configuration simpler, as it\nremoves the need for splitting configuration into multiple files.\n\nIt can be used with any built-in or third-party plugin.\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the group plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nsplitting plugins into logical units:\n\n``` yaml\nplugins:\n - group\n```\n\nThe group plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [group]: group.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nThe plugin behaves differently than all other built-in plugins – __it is\ndisabled by default__. To enable a group, use:\n\n``` yaml\nplugins:\n - group:\n enabled: !ENV CI # (1)!\n```\n\n1. If you only want to use the group plugin for better organization and\n always want to enable the plugins that are part of it, use:\n\n ``` yaml\n plugins:\n - group:\n enabled: true\n ```\n\nThe decision to disable the plugin by default was made to simplify the usage\nof environment variables, as it removes the need to provide a default value for\nan environment variable.\n\nNow, when [building your project], you can enable a group by setting the\n[environment variable][mkdocs.env]:\n\n``` sh\nCI=true mkdocs build\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to list the plugins that are part of the group. The syntax is\nexactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can\nsimply copy the list of plugins that you want to group, e.g:\n\n``` yaml\nplugins:\n - group:\n plugins:\n - optimize\n - minify\n```\n\nThe plugins mentioned here are just used for illustration purposes.\n","frontmatter":{"title":"Built-in group plugin","icon":"material/format-list-group"},"isInternal":false,"tokens":758,"sizeBytes":3345},{"name":"index.md","path":"docs/plugins/index.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/index.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"# Built-in plugins\n\nMaterial for MkDocs started out as a theme for [MkDocs][mkdocs], but has since\nevolved into a full-fledged framework for building and maintaining documentation.\nThe theme is still the core of the project, but it's now accompanied by a\ngrowing number of complementary built-in plugins.\n\nWe strive to make those plugins as modular and generic as possible, so that they\ncan be used in a wide variety of projects and use cases. By providing useful\ndefault settings, we also try to make them as easy to use as possible, so that\nyou can get started quickly, tweaking their settings later on. When\ndeveloping built-in plugins, we always adhere to the following design principles:\n\n- **Modularity:** Built-in plugins are designed to be modular, so that they can\n be easily combined to implement sophisticated pipelines. For example, the\n [offline], [optimize] and [privacy] plugins can be used together to build\n truly [offline-capable documentation].\n\n- **Interoperability:** Built-in plugins are designed to be as compatible as\n possible, so they can be used in combination with other plugins, including\n third-party plugins. We strive to make it simple to integrate with the vast\n ecosystem that has evolved around [MkDocs][mkdocs].\n\n- **Performance:** Built-in plugins are designed to be as fast and\n memory-efficient as possible, so that they don't unnecessarily slow down\n builds. This is particularly important for large documentation projects with\n thousands of pages.\n\n [mkdocs]: https://www.mkdocs.org/\n [design principles]: ../design-principles.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Categories\n\n### Management\n\nThe following plugins greatly improve the authoring experience when working on\ndocumentation projects by providing better management capabilities, from the\nmanagement of plugins, multiple projects, and metadata, to the creation of\nminimal reproductions for bug reports:\n\n\n\n- :material-format-list-group: __[Built-in group plugin][group]__\n\n ---\n\n The group plugin allows to group plugins into logical units to conditionally\n enable or disable them for specific environments with the use of\n [environment variables][mkdocs.env].\n\n ---\n\n __Optimal management of plugins when building in different environments__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to manage metadata (front matter) for all\n pages in a folder, so a certain subset of pages uses specific tags or a\n custom template.\n\n ---\n\n __Simpler organization, categorization and management of metadata__\n\n- :material-folder-open: __[Built-in projects plugin][projects]__\n\n ---\n\n The projects plugin allows to split your main project into multiple distinct\n projects, build them concurrently and preview them together as one.\n\n ---\n\n __Connect multiple projects together, and build them separately or as one__\n\n- :material-information: __[Built-in info plugin][info]__\n\n ---\n\n The info plugin is a small and useful utility that helps to create\n self-contained minimal reproductions, so we maintainers can fix reported\n bugs more quickly.\n\n ---\n\n __Your bug reports are of the highest quality, so we can fix them as fast as\n possible__\n\n\n
\n\n [group]: group.md\n [info]: info.md\n [meta]: meta.md\n [projects]: projects.md\n\n### Optimization\n\nThe following plugins are designed to help you build optimized documentation,\nmaking it more accessible to your users through faster loading times, better\nsearch engine rankings, beautiful preview images on social media, and GDPR\ncompliance with a few lines of configuration:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each page of your documentation, showing as previews on\n social media.\n\n ---\n\n __Links to your site render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your site loads faster as smaller images are served to your users__\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin downloads external assets automatically for easy\n self-hosting, allowing for GDPR compliance with a single line of\n configuration.\n\n ---\n\n __Your documentation can be made GDPR compliant with minimal effort__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [offline]: offline.md\n [optimize]: optimize.md\n [privacy]: privacy.md\n [social]: social.md\n\n### Content\n\nThe following plugins are designed to help you set up a blog, provide search\nfunctionality to your users, add tags to pages and posts, and use the same\ntypesetting capabilities in specific parts of the documentation exactly as in\nthe main content:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The blog plugin adds first-class support for blogging to Material for\n MkDocs, either as a sidecar to your documentation or as a standalone\n installation.\n\n ---\n\n __Your blog is built with the same powerful engine as your documentation__\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The search plugin adds a search bar to the header, allowing users to search\n the entire documentation, so it's easier for them to find what they're\n looking for.\n\n ---\n\n __Your documentation is searchable without any external services, even\n offline__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin adds first-class support for categorizing pages with tags,\n adding the ability to group related pages to improve the discovery of\n related content.\n\n ---\n\n __Your pages are categorized with tags, yielding additional context__\n\n- :material-format-title: __[Built-in typeset plugin][typeset]__\n\n ---\n\n The typeset plugin allows to preserve the enriched presentation of titles\n and headlines within the navigation and table of contents.\n\n ---\n\n __Sidebars preserve the same formatting as section titles in pages__\n\n
\n\n [blog]: blog.md\n [search]: search.md\n [tags]: tags.md\n [typeset]: typeset.md\n\n## Architecture\n\n### Multiple instances\n\nSeveral built-in plugins have support for multiple instances, which means that\nthey can be used multiple times in the same configuration file, allowing to\nfine-tune behavior for separate sections of your project. Currently, the\nfollowing plugins have support for multiple instances:\n\n\n\n- [Built-in blog plugin][blog]\n- [Built-in group plugin][group]\n- [Built-in optimize plugin][optimize]\n- [Built-in privacy plugin][privacy]\n- [Built-in social plugin][social]\n\n
\n","isInternal":false,"tokens":1656,"sizeBytes":7545},{"name":"info.md","path":"docs/plugins/info.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/info.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in info plugin\nicon: material/information\n---\n\n# Built-in info plugin\n\nThe info plugin is a utility that is solely intended to create self-contained\n[minimal reproductions] as `.zip` files when [reporting bugs] or proposing\n[change requests], making communication between us maintainers and you much\neasier, as we have a common ground to work on.\n\n [minimal reproductions]: ../guides/creating-a-reproduction.md\n [reporting bugs]: ../contributing/reporting-a-bug.md\n [change requests]: ../contributing/requesting-a-change.md\n\n## Objective\n\n### How it works\n\nThe plugin helps you to prepare a minimal reproduction by collecting the\nnecessary information about the environment and configuration of your project.\nThis makes it easier for us to fix bugs, as it requires that you\n[upgrade to the latest version] and [remove your customizations].\n\nWhen following these principles, you can be confident that you don't report a\nbug that has already been fixed in a subsequent release, or which is caused by\none of your customizations. Even more importantly, you actively help\nus to fix the bug as quickly as possible.\n\nThe output of the plugin is a `.zip` file that you can share with us maintainers.\n\n [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version\n [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations\n\n\n### When to use it\n\nWhenever you're [reporting a bug][reporting bugs] or have something to discuss,\nlike a question or [change request][change requests], you should attach\na small, self-contained minimal reproduction. Runnable examples help to make\ncommunication much more efficient, giving us maintainers more time to benefit\nmore users by pushing the project forward. Minimal reproductions are mandatory\nfor bug reports.\n\n## Configuration\n\n\n\n\nIn order to get started with the built-in info plugin, just add the following\nlines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share\nwith us maintainers:\n\n``` yaml\nplugins:\n - info\n```\n\nThe info plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [info]: info.md\n [create a minimal reproduction]: ../guides/creating-a-reproduction.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - info:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should be enabled when\n[previewing your site]. It's normally not necessary to specify this setting,\nbut if you want to change this behavior, use:\n\n``` yaml\nplugins:\n - info:\n enabled_on_serve: true\n```\n\nThis setting streamlines the process of creating and inspecting minimal\nreproductions, as it allows to quickly iterate on the reproduction without\nhaving to disable the plugin first.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n### Archive\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should create a `.zip` file\nfrom the project or exit after the version check. This setting is solely\nintended for debugging the plugin itself:\n\n``` yaml\nplugins:\n - info:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should stop creating the `.zip`\nfile when one of the [requirements] is not satisfied. This setting must only be\nused when [reporting a bug][reporting bugs] that is related to a customization\n[explicitly mentioned in our documentation]. You can change it with:\n\n``` yaml\nplugins:\n - info:\n archive_stop_on_violation: false\n```\n\nIf you're using this setting when [reporting a bug][reporting bugs], please\nexplain why you think it is necessary to include customizations. If you're\nunsure, please ask us first by [creating a discussion].\n\n [requirements]: #how-it-works\n [explicitly mentioned in our documentation]: ?q=%22extends+base%22\n [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n","frontmatter":{"title":"Built-in info plugin","icon":"material/information"},"isInternal":false,"tokens":1071,"sizeBytes":4622},{"name":"meta.md","path":"docs/plugins/meta.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/meta.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in meta plugin\nicon: material/file-tree\n---\n\n# Built-in meta plugin\n\nThe meta plugin solves the problem of setting metadata (front matter) for all\npages in a folder, i.e., a subsection of your project, which is particularly\nuseful to ensure that a certain subset of pages features specific tags, uses a\ncustom template, or is attributed to an author.\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,\nand recursively merges the contents of those files with the metadata (front\nmatter) of all pages that are contained in the same folder and all subfolders.\nFor example, if you want to add the tag Example to\nmultiple pages, use:\n\n``` yaml title=\".meta.yml\"\ntags:\n - Example\n```\n\nNow, given the following directory layout, if you store the file in the folder\nnamed `example`, all pages in that folder receive the tag, while all pages\noutside of the folder remain unaffected:\n\n``` { .sh .no-copy hl_lines=\"4-8\" }\n.\n├─ docs/\n│ ├─ ...\n│ ├─ example/\n│ │ ├─ .meta.yml\n│ │ ├─ a.md\n│ │ ├─ ...\n│ │ └─ z.md\n│ └─ ...\n└─ mkdocs.yml\n```\n\nWhen combining metadata, lists and dictionaries are recursively merged, which\nmeans you can append values to a list and add or set specific properties in a\ndictionary on arbitrary levels.\n\n### When to use it\n\nWhile the plugin itself doesn't offer much functionality beyond adding and\nmerging metadata, it is a perfect companion for many of the other built-in\nplugins that Material for MkDocs offers. Some of the most powerful combinations\nof the meta plugin and other built-in plugins are:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The meta plugin can be used to [change the layout] for social cards or\n [change specific layout options] like [background] or [color]\n for a subset of pages.\n\n ``` yaml title=\".meta.yml\"\n social:\n cards_layout: default/variant\n ```\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The meta plugin allows to automatically associate blog posts with specific\n [authors] and [categories], ensuring that blog posts are always correctly\n annotated.\n\n ``` yaml title=\".meta.yml\"\n authors:\n - squidfunk\n ```\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags], so they can't be forgotten when\n adding pages.\n\n ``` yaml title=\".meta.yml\"\n tags:\n - Example\n ```\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The meta plugin makes it easy to [boost] specific sections in search results\n or to [exclude] them entirely from being indexed, giving more granular\n control over search.\n\n ``` yaml title=\".meta.yml\"\n search:\n exclude: true\n ```\n\n
\n\n [social]: social.md\n [change the layout]: social.md#meta.social.cards_layout\n [change specific layout options]: social.md#meta.social.cards_layout_options\n [background]: social.md#option.background_color\n [color]: social.md#option.color\n [blog]: blog.md\n [authors]: blog.md#meta.authors\n [categories]: blog.md#meta.categories\n [tags]: tags.md\n [specific tags]: tags.md#meta.tags\n [search]: search.md\n [exclude]: search.md#meta.search.exclude\n [boost]: search.md#meta.search.boost\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the meta plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\napplying metadata for multiple pages at once:\n\n``` yaml\nplugins:\n - meta\n```\n\nThe meta plugin is included with Material for MkDocs and doesn't need to be\ninstalled.\n\n [meta]: meta.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - meta:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Meta file\n\nThe following settings are available for meta files:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the meta file name the plugin will look for when\nscanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to\nchange this setting, but if you want to change it, use:\n\n``` yaml\nplugins:\n - meta:\n meta_file: .meta.yml\n```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir]\nrecursively.\n","frontmatter":{"title":"Built-in meta plugin","icon":"material/file-tree"},"isInternal":false,"tokens":1230,"sizeBytes":5017},{"name":"offline.md","path":"docs/plugins/offline.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/offline.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in offline plugin\nicon: material/connection\n---\n\n\n# Built-in offline plugin\n\n[MkDocs][mkdocs] is one of the few frameworks that supports building\noffline-capable documentation that can be directly viewed by the user – no\nserver needed. With the offline plugin, you can distribute the\n[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while\nretaining most interactive functionality.\n\n## Objective\n\n### How it works\n\nAfter [building your project], switch to the [`site` directory][mkdocs.site_dir]\nand open `index.html` in your browser – you're now viewing your documentation\nfrom your local file system! Most browsers will denote this by showing `file://`\nin the address bar. However, you'll realize that the site search is gone.\n\nMaterial for MkDocs offers many interactive features, some of which will not\nwork from the local file system due to the restrictions of modern browsers. More\nspecifically and technically, all calls to the [Fetch API] will error with a\nmessage like:\n\n```\nCross origin requests are only supported for protocol schemes: http, [...]\n```\n\nWhile browsers impose those restriction for security reasons, it reduces the\ninteractivity of your project. The offline plugin makes sure that site search\nkeeps working by moving the search index to a JavaScript file, and leveraging\n@squidfunk's [iframe-worker] shim.\n\nAdditionally, the plugin automatically disables the [`use_directory_urls`]\n[mkdocs.use_directory_urls] setting, ensuring that users can open your\ndocumentation directly from the local file system.\n\nThere are some [limitations].\n\n [building your project]: ../creating-your-site.md#building-your-site\n [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API\n [iframe-worker]: https://github.com/squidfunk/iframe-worker\n [limitations]: #limitations\n\n### When to use it\n\nAs the name already indicates, the plugin should only be used when you're\n[building your project] for offline distribution. It's also good to know, that\nthe offline plugin plays nicely with the following other plugins, helping to\ncreate even better offline-capable documentation:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use external assets when building for\n offline usage, as it automatically downloads them for distribution with\n your documentation.\n\n ---\n\n __Your documentation can work without connectivity to the internet[^1]__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [^1]:\n You might wonder why the [privacy plugin][privacy] is necessary to build\n truly offline-capable documentation with the offline plugin. While it's\n certainly possible to also add support for downloading external assets to\n the offline plugin, this functionality is already fully implemented in the\n privacy plugin and is its very raison d'être.\n\n Material for MkDocs follows a modular approach for its plugin system – many\n of the plugins work perfectly together and enhance each others\n functionalities, allowing to solve complex problems with a few lines\n of configuration.\n\n [privacy]: privacy.md\n [optimize]: optimize.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the offline plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nbuilding offline-capable documentation:\n\n``` yaml\nplugins:\n - offline\n```\n\nThe offline plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [offline]: offline.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to build online- as well as offline-capable documentation, it's a\ngood idea to use an [environment variable][mkdocs.env]:\n\n``` yaml\nplugins:\n - offline:\n enabled: !ENV [OFFLINE, false]\n```\n\n## Limitations\n\nWhen enabling the offline plugin, make sure to disable the following settings,\nas they make use of the [Fetch API] which will error when invoked from the local\nfile system:\n\n- [Instant loading]\n- [Site analytics]\n- [Versioning]\n- [Comment systems]\n\n [Instant loading]: ../setup/setting-up-navigation.md#instant-loading\n [Site analytics]: ../setup/setting-up-site-analytics.md\n [Versioning]: ../setup/setting-up-versioning.md\n [Comment systems]: ../setup/adding-a-comment-system.md\n","frontmatter":{"title":"Built-in offline plugin","icon":"material/connection"},"isInternal":false,"tokens":1081,"sizeBytes":4930},{"name":"optimize.md","path":"docs/plugins/optimize.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/optimize.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in optimize plugin\nicon: material/rabbit\n---\n\n# Built-in optimize plugin\n\nThe optimize plugin automatically identifies and optimizes all media files when\n[building your project] by using common compression and conversion techniques.\nAs a result, your site loads significantly faster and yields better rankings in\nsearch engines.\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and\nassets, optimizing them automatically in order to reduce the final size of the\n[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you\nship less bytes to your users, as well as a smaller download for\n[offline-capable documentation].\n\nOptimized images are [intelligently cached][intelligent caching], which is why\nthe plugin will only optimize media files that changed since the last build.\nThis makes it possible to swap out or update images, without having to worry\nabout optimizing them, or even worse, forgetting to do so.\n\nIn order to optimize media files, a few [dependencies] need to be available on\nyour system.\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [dependencies]: #configuration\n\n### When to use it\n\nIt's generally recommended to use the plugin, as media files are optimized\nautomatically without the need for intervention, ensuring that your site loads\nas fast as possible. Optimized media files are one of the key components for a\nhigh and consistent ranking in search engines.\n\nAdditionally, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated\nbuild pipelines tailored to your project:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use unoptimized external assets, passing\n them to the optimize plugin before copying them to the [`site` directory]\n [mkdocs.site_dir].\n\n ---\n\n __External media files can be automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [privacy]: privacy.md\n [offline]: offline.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the optimize plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and observe how\nmedia files are optimized automatically:\n\n``` yaml\nplugins:\n - optimize\n```\n\nThe optimize plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to optimize all media files, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [optimize]: optimize.md\n [built-in plugins]: index.md\n [image processing]: requirements/image-processing.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - optimize:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete media file optimization faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - optimize:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a media\nfile or asset is only passed through the optimization pipeline when its contents\nchange. If you swap out or update an image, the plugin detects it and updates\nthe optimized version of the media file.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-optimize all media files, even though the cache may not be stale. It's\nnormally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - optimize:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where media files are cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - optimize:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Optimization\n\nDocumentation often makes use of screenshots or diagrams for better\nvisualization of things, both of which are prime candidates for optimization.\nThe plugin automatically optimizes images using [pngquant] for `.png` files,\nand [Pillow] for `.jpg` files.\n\nThe following settings are available for optimization:\n\n [pngquant]: https://pngquant.org/\n [Pillow]: https://pillow.readthedocs.io/\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable media file optimization. Currently,\nthe plugin's sole purpose is to optimize media files, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the near future, other features\nmight be added. If you want to disable optimization, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.png` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.png` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the speed/quality tradeoff that [pngquant] applies\nwhen optimizing `.png` files. The lower the number, the more aggressively\n[pngquant] will try to optimize:\n\n=== \"Slower smaller \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 1\n ```\n\n=== \"Faster larger \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 10\n ```\n\nA factor of `10` has 5% lower quality, but is 8x faster than the default `3`.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [pngquant] should strip optional metadata\nfrom `.png` files that are not required to display the image, e.g., [EXIF].\nIf you want to preserve metadata, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png_strip: false\n```\n\n [EXIF]: https://en.wikipedia.org/wiki/Exif\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.jpg` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.jpg` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the image quality that [Pillow] applies when\noptimizing `.jpg` files. If the images look blurry, it's a good idea to\nfine-tune and change this setting:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_quality: 75\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [Pillow] should use progressive encoding\nwhen optimizing `.jpg` files, rendering faster on slow connections. If you want\nto disable progressive encoding, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_progressive: false\n```\n\n [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339\n\n---\n\n#### \n\n\n\n\nUse this setting to enable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - optimize:\n optimize_include:\n - screenshots/*\n```\n\nThis configuration enables optimization for all media files that are contained\nin the `screenshots` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - social:\n optimize_exclude:\n - vendor/*\n```\n\nThis configuration disables optimization for all media files that are contained\nin the `vendor` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n### Reporting\n\nThe following settings are available for reporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the number of bytes\ngained after optimizing each file. If you want to disable this behavior, use:\n\n``` yaml\nplugins:\n - optimize:\n print_gain: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the total number of\nbytes gained after optimizing all files. If you want to disable this behavior,\nuse:\n\n``` yaml\nplugins:\n - optimize:\n print_gain_summary: false\n```\n","frontmatter":{"title":"Built-in optimize plugin","icon":"material/rabbit"},"isInternal":false,"tokens":2557,"sizeBytes":11092},{"name":"privacy.md","path":"docs/plugins/privacy.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/privacy.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in privacy plugin\nicon: material/shield-account\n---\n\n\n# Built-in privacy plugin\n\nThe privacy plugin offers a streamlined solution for automatically self-hosting\nexternal assets. With just a single line of configuration, the plugin can\nautomatically identify and download external assets, making GDPR compliance\nas effortless as it can possibly be.\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML for external assets, i.e., scripts, style\nsheets, images, and web fonts, downloads them, stores them in the\n[`site` directory][mkdocs.site_dir] and replaces all references with links to\nthe downloaded copies for effortless self-hosting. For example:\n\n``` html\n\n```\n\nThis external script is downloaded, and the link is replaced with:\n\n``` html\n\n```\n\nOf course, scripts and style sheets can reference further external assets,\nwhich is why this process is repeated recursively until no further external\nassets are detected:\n\n- Scripts are scanned for further scripts, style sheets and JSON files\n- Style sheets are scanned for images and web fonts\n\nAdditionally, hints like [`preconnect`][preconnect], used to reduce latency when\nrequesting external assets, are removed from the output, as they're not\nnecessary when self-hosting. After the plugin has done its work, your project\nwill be free of requests to external services.\n\nThere are some [limitations].\n\n [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin was developed to make compliance with the 2018 European\n__General Data Protection Regulation__ (GDPR) as simple as possible, while\nretaining the flexibility and power that Material for MkDocs offers, like for\nexample its tight integration with [Google Fonts].\n\nBut, that's only the start. For example, if your project includes a lot of\nimages, enabling the plugin allows to move them outside of your repository, as\nthe plugin will automatically download and store them in the [`site` directory]\n[mkdocs.site_dir] when [building your project].\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin allows to optimize all downloaded external assets\n detected by the privacy plugin by using compression and conversion\n techniques.\n\n ---\n\n __External media files are automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [Google Fonts]: ../setup/changing-the-fonts.md\n [building your project]: ../creating-your-site.md#building-your-site\n [optimize]: optimize.md\n [offline]: offline.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the privacy plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\neffortlessly self-hosting external assets:\n\n``` yaml\nplugins:\n - privacy\n```\n\nThe privacy plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [privacy]: privacy.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - privacy:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete handling of external assets faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - privacy:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that external\nassets are only downloaded when they're not already contained in the cache.\nWhile the initial build might take some time, it's a good idea to use caching,\nas it will speed up consecutive builds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-schedule downloads for all external assets, even though the cache may not be\nstale. It's normally not necessary to specify this setting, except for when\ndebugging the plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - privacy:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where downloaded copies are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages when\nbuilding your site. While not being recommended, you can disable logging with:\n\n``` yaml\nplugins:\n - privacy:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot\n be created due to a lack of permissions on Windows systems (#6550).\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported, including which\n assets were successfully downloaded by the plugin.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: debug\n ```\n\n All messages are reported, including debug messages, if and only if MkDocs\n was started with the `--verbose` flag. Note that this will print a lot of\n messages and is only useful for debugging.\n\n### External assets\n\nThe following settings are available for external assets:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should download external\nassets. If you only want the plugin to process [external links], you can disable\nhandling of external assets with:\n\n``` yaml\nplugins:\n - privacy:\n assets: false\n```\n\n [external links]: #external-links\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should downloads or only report\nexternal assets when they're encountered. If you already self-host all external\nassets, this setting can be used as a safety net to detect links to external\nassets placed by the author in pages:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch: true\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nexternal assets are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch_dir: my/custom/dir\n```\n\nThis configuration stores the downloaded copies at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to enable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_include:\n - unsplash.com/*\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to disable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_exclude: # (1)!\n - unpkg.com/mathjax@3/*\n - giscus.app/*\n```\n\n1. [MathJax] loads web fonts for typesetting of mathematical content\n through relative URLs, and thus cannot be automatically bundled by the\n privacy plugin. [MathJax can be self-hosted].\n\n [Giscus], which we recommend to use as a [comment system], uses a technique\n called code-splitting to load only the code that is necessary, which\n is implemented via relative URLs. [Giscus can be self-hosted] as well.\n\n [MathJax]: ../reference/math.md\n [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html\n [Giscus]: https://giscus.app/\n [comment system]: ../setup/adding-a-comment-system.md\n [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md\n\n---\n\n### External links\n\nThe following settings are available for external links:\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to parse and process external links to\nannotate them for [improved security], or to automatically add additional\nattributes to external links. If you want to disable processing of external\nlinks, use:\n\n``` yaml\nplugins:\n - privacy:\n links: false\n```\n\n [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/\n\n---\n\n#### \n\n\n\n\nUse this setting to specify additional attributes that should be added to\nexternal links, for example, to add `target=\"_blank\"` to all external links\nso they open in a new tab:\n\n``` yaml\nplugins:\n - privacy:\n links_attr_map:\n target: _blank\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not recommended to change this setting, as it will automatically\nannotate external links that open in a new window with `rel=\"noopener\"` for\n[improved security]:\n\n``` yaml\nplugins:\n - privacy:\n links_noopener: true\n```\n\n## Limitations\n\n### Dynamic URLs\n\nDynamically created URLs as part of scripts are not detected, and thus cannot be\ndownloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:\n\n``` js\nconst host = \"https://example.com\"\nconst path = `${host}/script.js`\n```\n\nInstead, always use fully qualified URLs:\n\n``` js\nconst url =\"https://example.com/script.js\"\n```\n\n### Embedded HTML\n\nBy default, embedded HTML files (e.g. in iframes) are not scanned for external\nassets. This is a limitation of MkDocs, as it considers `.html` files to be\ntemplates, which must be explicitly listed under\n[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets\nof an embedded HTML file:\n\n``` yaml\nextra_templates:\n - iframe.html\n```\n\nNote that the path to `iframe.html` is relative to the\n[`docs_dir`][mkdocs.docs_dir] directory.\n","frontmatter":{"title":"Built-in privacy plugin","icon":"material/shield-account"},"isInternal":false,"tokens":3010,"sizeBytes":13084},{"name":"projects.md","path":"docs/plugins/projects.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/projects.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in projects plugin\nicon: material/folder-open\nstatus: deprecated\n---\n\n# Built-in projects plugin\n\nThe projects plugin adds the ability to split your main project into multiple\ndistinct projects, build them concurrently and preview them together as one.\nThis is particularly useful when creating a multi-language project, but can also\nbe used to split very large projects into smaller parts.\n\n!!! bug \"The built-in projects plugin is deprecated\"\n\n [Material for MkDocs is in maintenance mode]. The projects plugin, which was\n formerly part of the [Insiders] edition, was released in , the last release that includes all features from the Insiders edition.\n Unfortunately, the projects plugin turned out impossible to maintain, and\n was one of the key motivators to create [Zensical].\n\n ---\n\n __If you're considering the projects plugin, please be aware that known issues will not be fixed.__\n\n [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523\n [Zensical]: ../blog/posts/zensical.md\n [Insiders]: ../blog/posts/insiders-now-free-for-everyone.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`projects` directory][config.projects_dir] for\n`mkdocs.yml` files, identifies all nested projects and builds them concurrently.\nIf not configured otherwise, the plugin expects that your project has\nthe following directory layout, e.g. for a multi-language project:\n\n``` { .sh .no-copy }\n.\n├─ docs/\n├─ projects/\n│ ├─ en/\n│ │ ├─ docs/\n│ │ └─ mkdocs.yml\n│ └─ de/\n│ ├─ docs/\n│ └─ mkdocs.yml\n└─ mkdocs.yml\n```\n\nOne of the most useful and interesting features of the plugin is that it allows\n[previewing your site] from the main project, while still being able to preview\nand build each project individually. This is especially useful for\nmulti-language projects.\n\nIf, when [previewing your site], you change a file in one of the projects, the\nplugin only rebuilds this project and makes sure that MkDocs will also reload\nthe associated files. This also creates the opportunity for splitting your\nmain project into several projects for a better editing experience.\n\nThere are some [limitations], but we're working hard to remove them.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin came into existence because we needed a convenient and scalable\nmethod to build our [examples] repository, which features many self-contained\nand runnable projects that users can download and use as a basis when\nbootstrapping a new project or [creating a reproduction].\n\nWhen you want to create a multi-language project, or have a very large existing\nproject, you might consider using the plugin, as it makes managing, editing\nand building more comfortable.\n\n [examples]: https://github.com/mkdocs-material/examples\n [creating a reproduction]: ../guides/creating-a-reproduction.md\n\n## Configuration\n\n\n\n\n\nIn order to get started with the projects plugin, just add the following lines\nto `mkdocs.yml`, and split your main project into several distinct projects that\ncan be built concurrently:\n\n``` yaml\nplugins:\n - projects\n```\n\nThe projects plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [projects]: projects.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\nbuild projects faster. If you want to disable concurrent processing completely,\nuse:\n\n``` yaml\nplugins:\n - projects:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a\nproject is only rebuilt when its contents change. While the initial build might\ntake some time, it's a good idea to use caching, as it will speed up consecutive\nbuilds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nrebuild all projects, even though the cache may not be stale. It's normally not\nnecessary to specify this setting, except for when debugging the plugin itself.\nCaching can be disabled with:\n\n``` yaml\nplugins:\n - projects:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where the metadata is cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - projects:\n cache_dir: my/custom/dir\n```\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages from\nprojects when building your site. While not being recommended, you can disable\nlogging with:\n\n``` yaml\nplugins:\n - projects:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: debug\n ```\n\n All messages are reported, including debug messages.\n\n### Projects\n\nThe following settings are available for projects:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable building of projects. Currently, the\nplugin's sole purpose is to build projects, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable building of projects, use:\n\n``` yaml\nplugins:\n - projects:\n projects: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your projects are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - projects:\n projects_dir: projects\n```\n\nNote that the [`projects` directory][config.projects_dir] is solely used for\nproject organization – it is not included in project URLs, since projects are\nautomatically hoisted by the plugin.\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the location or name of configuration files the\nplugin will look for when scanning the [`projects` directory]\n[config.projects_dir]. Adjusting this setting can be necessary when the\nconfiguration files are located in subdirectories of projects, e.g.\n`docs/mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n projects_config_files: \"**/mkdocs.yml\" # (1)!\n```\n\n1. If all projects share the same location for their configuration files, e.g.,\n `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster\n to resolve than a `**` glob pattern.\n\n ``` yaml\n plugins:\n - projects:\n projects_config_files: \"*/docs/mkdocs.yml\"\n ```\n\n This configuration fits the following directory structure, which is quite\n common for projects using git submodules:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n ├─ projects/\n │ ├─ git-submodule-a/\n │ │ └─ docs/\n │ │ └─ mkdocs.yml\n │ └─ git-submodule-b/\n │ └─ docs/\n │ └─ mkdocs.yml\n └─ mkdocs.yml\n ```\n\nThe provided path is resolved from the [`projects` directory]\n[config.projects_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to transform the configuration of each project as read from\n`mkdocs.yml` before it is built, which allows for adjusting the configuration\nof each project when building them together, but leave them untouched when\nbuilding them individually:\n\n``` yaml\nplugins:\n - projects:\n projects_config_transform: !!python/name:projects.transform\n```\n\nThe provided module and function name are looked up in Python's [module search\npath]. You need to add your root directory to the search path when building\nyour site, so Python can resolve it. The easiest way is to add the working\ndirectory to the [`PYTHONPATH`][PYTHONPATH] environment variable:\n\n``` .sh\nexport PYTHONPATH=.\n```\n\n!!! tip \"How to define a configuration transformation function\"\n\n The [`python/name`][python-name] tag is provided by [PyYAML] and must point\n to a valid module and function name within Python's [module search path].\n The plugin passes the `project` and top-level `config` objects to the\n function.\n\n As an example, we can inherit the [`use_directory_urls`]\n [mkdocs.use_directory_urls] setting for all projects from the top-level\n configuration:\n\n ``` py title=\"projects/__init__.py\"\n from mkdocs.config.defaults import MkDocsConfig\n\n # Transform project configuration\n def transform(project: MkDocsConfig, config: MkDocsConfig):\n project.use_directory_urls = config.use_directory_urls\n ```\n\n [module search path]: https://docs.python.org/3/library/sys_path_init.html\n [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH\n [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types\n [PyYAML]: https://pyyaml.org/\n\n### Hoisting\n\nThe following settings are available for hoisting:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable hoisting of themes files to the main\nproject. If you disable this setting, each project receives a copy of the\ntheme's files, which can be considered redundant:\n\n``` yaml\nplugins:\n - projects:\n hoisting: false\n```\n\nIt's generally advisable to enable hoisting, as it yields faster deployments\nand faster loading of your project's sites, because the files are the same for\nall projects and can be deduplicated.\n\n### Limitations\n\nThe plugin is one of the latest additions to Material for MkDocs, which means it\nis rather young and has some limitations. We're working hard to remove them, and\nwe're happy to receive feedback and learn about your requirements in ?5800.\nCurrent limitations are:\n\n- __Basic multi-language support only__: we'll be investigating how to provide\n better support for multi-language projects, allowing to easier interlink\n projects and switch between them.\n\n- __Separate search indexes and sitemaps__: currently, the projects are entirely\n separate, which means they will have separate search indexes and sitemaps.\n","frontmatter":{"title":"Built-in projects plugin","icon":"material/folder-open","status":"deprecated"},"isInternal":false,"tokens":2881,"sizeBytes":12490},{"name":"caching.md","path":"docs/plugins/requirements/caching.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/caching.md","title":"Requirements Skill","category":"anthropic-skill","format":"markdown","content":"# Requirements Skill\n\nPath: `docs/plugins/requirements/caching.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/caching.md)","tokens":300,"sizeBytes":199},{"name":"image-processing.md","path":"docs/plugins/requirements/image-processing.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/image-processing.md","title":"Requirements Skill","category":"anthropic-skill","format":"markdown","content":"# Requirements Skill\n\nPath: `docs/plugins/requirements/image-processing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/image-processing.md)","tokens":300,"sizeBytes":217},{"name":"search.md","path":"docs/plugins/search.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/search.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in search plugin\nicon: material/magnify\n---\n\n# Built-in search plugin\n\nThe search plugin adds a search bar to the header, allowing users to search your\ndocumentation. It's powered by [lunr.js], a lightweight full-text search engine\nfor the browser, elimininating the need for external services, and even works\nwhen building [offline-capable documentation].\n\n [lunr.js]: https://lunrjs.com/\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML and builds a search index from all pages and\nsections by extracting the section titles and contents. It preserves some inline\nformatting like code blocks and lists, but removes all other formatting, so the\nsearch index is as small as possible.\n\nWhen a user visits your site, the search index is shipped to the browser,\nindexed with [lunr.js] and made available for fast and simple querying – no\nserver needed. This ensures that the search index is always up to date with\nyour documentation, yielding accurate results.\n\n### When to use it\n\nIt's generally recommended to use the plugin, as interactive search functionality\nis a vital part of every good documentation. Additionally, the plugin integrates\nperfectly with several of the other [built-in plugins] that Material for MkDocs\noffers:\n\n\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to [boost][meta.search.boost] specific\n sections in search results or to [exclude][meta.search.exclude] them\n entirely from being indexed, giving more granular control over search.\n\n ---\n\n __Simpler organization and management of search in different subsections__\n\n
\n\n [offline]: offline.md\n [meta]: meta.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the search plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and your users\nwill be able to search your documentation:\n\n``` yaml\nplugins:\n - search\n```\n\nThe search plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [search]: search.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - search:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Search\n\nThe following settings are available for search:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the language of the search index, enabling [stemming]\nsupport for other languages than English. The default value is automatically\ncomputed from the [site language], but can be explicitly set to another language\nor even multiple languages with:\n\n=== \"Set language\"\n\n ``` yaml\n plugins:\n - search:\n lang: en\n ```\n\n=== \"Add further languages\"\n\n ``` yaml\n plugins:\n - search:\n lang: # (1)!\n - en\n - de\n ```\n\n 1. Be aware that including support for further languages increases the\n base JavaScript payload by around 20kb and by another 15-30kb per\n language, all before `gzip`.\n\n [stemming]: https://en.wikipedia.org/wiki/Stemming\n [site language]: ../setup/changing-the-language.md#site-language\n [lunr languages]: https://github.com/MihaiValentin/lunr-languages\n\nLanguage support is provided by [lunr languages], a collection of\nlanguage-specific stemmers and stop words for [lunr.js] maintained by the\nOpen Source community.\n\n---\n\nThe following languages are currently supported by [lunr languages]:\n\n\n\n- `ar` – Arabic\n- `da` – Danish\n- `de` – German\n- `du` – Dutch\n- `en` – English\n- `es` – Spanish\n- `fi` – Finnish\n- `fr` – French\n- `hi` – Hindi\n- `hu` – Hungarian\n- `hy` – Armenian\n- `it` – Italian\n- `ja` – Japanese\n- `kn` - Kannada\n- `ko` – Korean\n- `no` – Norwegian\n- `pt` – Portuguese\n- `ro` – Romanian\n- `ru` – Russian\n- `sa` – Sanskrit\n- `sv` – Swedish\n- `ta` – Tamil\n- `te` – Telugu\n- `th` – Thai\n- `tr` – Turkish\n- `vi` – Vietnamese\n- `zh` – Chinese\n\n
\n\nIf [lunr languages] doesn't provide support for the selected [site language],\nthe plugin falls back to another language that yields the best stemming results.\nIf you discover that the search results are not satisfactory, you can contribute\nto [lunr languages] by adding support for your language.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the separator used to split words when building the\nsearch index on the client side. The default value is automatically computed\nfrom the [site language], but can also be explicitly set to another value with:\n\n``` yaml\nplugins:\n - search:\n separator: '[\\s\\-,:!=\\[\\]()\"/]+|(?!\\b)(?=[A-Z][a-z])|\\.(?!\\d)|&[lg]t;'\n```\n\nSeparators support [positive and negative lookahead assertions], which allows\nfor rather complex expressions that yield precise control over how words are\nsplit when building the search index.\n\nBroken into its parts, this separator induces the following behavior:\n\n=== \"Special characters\"\n\n ```\n [\\s\\-,:!=\\[\\]()\"/]+\n ```\n\n The first part of the expression inserts token boundaries for each\n document before and after whitespace, hyphens, commas, brackets and\n other special characters. If several of those special characters are\n adjacent, they are treated as one.\n\n=== \"Case changes\"\n\n ```\n (?!\\b)(?=[A-Z][a-z])\n ```\n\n Many programming languages have naming conventions like `PascalCase` or\n `camelCase`. By adding this subexpression to the separator,\n [words are split at case changes], tokenizing the word `PascalCase`\n into `Pascal` and `Case`.\n\n=== \"Version strings\"\n\n ```\n \\.(?!\\d)\n ```\n\n When adding `.` to the separator, version strings like `1.2.3` are split\n into `1`, `2` and `3`, which makes them undiscoverable via search. When\n using this subexpression, a small lookahead is introduced which will\n [preserve version strings] and keep them discoverable.\n\n=== \"HTML/XML tags\"\n\n ```\n &[lg]t;\n ```\n\n If your documentation includes HTML/XML code examples, you may want to allow\n users to find [specific tag names]. Unfortunately, the `<` and `>` control\n characters are encoded in code blocks as `<` and `>`. Adding this\n subexpression to the separator allows for just that.\n\n [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html\n [words are split at case changes]: ?q=searchHighlight\n [preserve version strings]: ?q=9.0.0\n [specific tag names]: ?q=script\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify the [pipeline functions] that are used to filter and\nexpand tokens after tokenizing them with the [`separator`][config.separator] and\nbefore adding them to the search index. The default value is automatically\ncomputed from the [site language], but can also be explicitly set with:\n\n``` yaml\nplugins:\n - search:\n pipeline:\n - stemmer\n - stopWordFilter\n - trimmer\n```\n\nThe following pipeline functions can be used:\n\n- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`\n- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.\n- `trimmer` – Trim whitespace from tokens\n\n [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions\n\n### Segmentation\n\nThe plugin supports text segmentation of Chinese via [jieba], a popular\nChinese text segmentation library. Other languages like Japanese and Korean are\ncurrently segmented on the client side, but we're considering to move this\nfunctionality into the plugin in the future.\n\nThe following settings are available for segmentation:\n\n [jieba]: https://pypi.org/project/jieba/\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify a [custom dictionary] to be used by [jieba] for\nsegmenting text, replacing the default dictionary. [jieba] comes with\nseveral dictionaries, which can be used with:\n\n``` yaml\nplugins:\n - search:\n jieba_dict: dict.txt\n```\n\nThe following dictionaries are provided by [jieba]:\n\n- [dict.txt.small] – 占用内存较小的词典文件\n- [dict.txt.big] – 支持繁体分词更好的词典文件\n\nThe provided path is resolved from the root directory.\n\n [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8\n [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small\n [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify an additional [user dictionary] to be used by\n[jieba] for segmenting text, augmenting the default dictionary. User\ndictionaries are ideal for tuning the segmenter:\n\n``` yaml\nplugins:\n - search:\n jieba_dict_user: user_dict.txt\n```\n\nThe provided path is resolved from the root directory.\n\n [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to increase or decrease the relevance of a page in the search\nresults, giving more weight to them. Use values above `1` to rank up and values\nbelow `1` to rank down:\n\n=== \":material-arrow-up-circle: Rank up\"\n\n ``` yaml\n ---\n search:\n boost: 2 # (1)!\n ---\n\n # Page title\n ...\n ```\n\n 1. When boosting pages, always start with low values.\n\n=== \":material-arrow-down-circle: Rank down\"\n\n ``` yaml\n ---\n search:\n boost: 0.5\n ---\n\n # Page title\n ...\n ```\n\n---\n\n#### \n\n\n\n\n\nUse this property to exclude a page from the search results. Note that this will\nnot only remove the page, but also all subsections of the page from the search\nresults:\n\n``` yaml\n---\nsearch:\n exclude: true\n---\n\n# Page title\n...\n```\n","frontmatter":{"title":"Built-in search plugin","icon":"material/magnify"},"isInternal":false,"tokens":2812,"sizeBytes":11286},{"name":"social.md","path":"docs/plugins/social.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/social.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in social plugin\nicon: material/share-circle\n---\n\n# Built-in social plugin\n\nThe social plugin automatically and intelligently generates beautiful and highly\ncustomizable social cards in different [layouts][default layouts] for each page\nof your project, rendering as preview images whenever you or somebody else share\na link to your project on social media.\n\n## Objective\n\n### How it works\n\nThe plugin automatically generates a customizable social card for each page\nof your project, which appears as a preview image when sharing a link to your\nproject on social media, without the use of external services and just\n[a single line of configuration][configuration].\n\nWith the use of an efficient [image processing] library, the plugin allows to\ndefine [custom layouts] for social cards, which can be adapted to match your\nproject's style and branding. While it would technically be much simpler to\ngenerate social cards by using a web browser and an automation framework like\n[Puppeteer][^1], it would add further liabilities to your toolchain, with the\npotential to make build pipelines more complex, much more resource intense,\nand significantly slower.\n\n [^1]:\n [GitHub wrote in their blog] that they use [Puppeteer] to generate social\n card images for repositories, issues, commits, discussions, and basically\n everything else that appear as preview images when shared on social media.\n\nThe generated social cards are [cached] and stored in the\n[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your\nproject doesn't depend on external services. In order to generate social cards\nimages, a few [dependencies] need to be available on your system.\n\n [configuration]: #configuration\n [image processing]: requirements/image-processing.md\n [custom layouts]: ../setup/setting-up-social-cards.md#customization\n [Puppeteer]: https://github.com/puppeteer/puppeteer\n [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/\n [cached]: #caching\n [dependencies]: #configuration\n\n### When to use it\n\nThere's one particular case when we don't recommend to use the plugin: when you\nbuild [offline-capable documentation] to offer it as a download. Otherwise, it\nalways makes sense to enable the plugin, as links to your documentation shared\non social media will appear much more appealing.\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social media__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin can be used to [change the layout][meta.social.cards_layout]\n for social cards or [change specific layout options]\n [meta.social.cards_layout_options] like [background][option.background_color]\n or [color][option.color] for a subset of pages.\n\n ---\n\n __Your documentation can use completely different social cards per section__\n\n
\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [blog]: blog.md\n [meta]: meta.md\n\n## Configuration\n\n\n\n\n\n\nIn order to get started with the social plugin, just add the following lines to\n`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social\ncards for you:\n\n``` yaml\nplugins:\n - social\n```\n\nThe social plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to generate social card images, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [social]: social.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - social:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete social card generation faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - social:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that social\ncards are only regenerated when their contents change or they're not already\ncontained in the cache. If any of the variables used in a layout changes, the\nplugin detects it and regenerates the social card.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-generate social cards for all pages, even though the cache may not be stale.\nIt's normally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - social:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where social card images are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should only log errors when\ngenerating social cards without terminating the build, e.g., invalid references\nto icons. To terminate the build, use:\n\n``` yaml\nplugins:\n - social:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: warn\n ```\n\n Errors are reported as warnings, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: info\n ```\n\n Errors are only reported as informational messages.\n\n=== \"`ignore`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: ignore\n ```\n\n Errors are only reported when using the `--verbose` flag.\n\n### Social cards\n\nThe following settings are available for social card generation:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable social card generation. Currently, the\nplugin's sole purpose is to generate social cards, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable social card generation, use:\n\n``` yaml\nplugins:\n - social:\n cards: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nsocial cards are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cards_dir: my/custom/dir\n```\n\nThis configuration stores the generated images at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nIf you want to build a [custom social card layout][custom layouts], use this\nsetting to change the folder where you store your custom layouts, the default\nbeing a folder called `layouts` in your root directory:\n\n``` yaml\nplugins:\n - social:\n cards_layout_dir: layouts\n```\n\nThe provided path is resolved from the root directory.\n\n!!! tip \"Where to store custom layouts\"\n\n Our recommendation is to locate the folder outside of the\n [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]\n are not copied to the [`site` directory][mkdocs.site_dir] when\n [building your project], e.g., by adhering to the following directory\n layout:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ *.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nThe plugin ships a growing list of [`default` layouts][default layouts] for\nsocial cards. If you've created a [custom social card layout][custom layouts],\nyou can instruct the plugin to use it exactly as one of the included layouts:\n\n``` yaml\nplugins:\n - social:\n cards_layout: my-custom-layout\n```\n\nThe provided path is resolved from the[\n`layouts` directory][config.cards_layout_dir].\n\n!!! tip \"How custom layouts are resolved\"\n\n By default, the plugin will load your [custom layouts] from a folder named\n `layouts` in your root directory. If your layout is called\n `my-custom-layout`, the directory layout must adhere to:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ my-custom-layout.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to set options for the layout specified via [`cards_layout`]\n[config.cards_layout] (if the layout supports it), which allows for making\nlayouts easily and entirely configurable:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n : \n```\n\nWhen creating a [custom layout][custom layouts], you are completely free in\ndefining which parts of your layout can be parametrized. The [`default` layouts]\n[default layouts] included with the plugin support the following options:\n\n\n\n- [`background_color`][option.background_color]\n- [`background_image`][option.background_image]\n- [`color`][option.color]\n- [`font_family`][option.font_family]\n- [`font_variant`][option.font_variant]\n- [`logo`][option.logo]\n- [`title`][option.title]\n- [`description`][option.description]\n\n
\n\n\n [default layouts]: #layouts\n\n---\n\n#### \n\n\n\n\nUse this setting to enable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_include:\n - blog/*\n```\n\nThis configuration enables social card generation for all pages that are\ncontained in the `blog` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_exclude:\n - changelog/*\n```\n\nThis configuration disables social card generation for all pages that are\ncontained in the `changelog` folder and its subfolders inside the\n[`docs` directory][mkdocs.docs_dir].\n\n### Debugging\n\nThe plugin includes a special mode for debugging layouts, which is very useful\nwhen creating [custom layouts], as it allows for quicker iteration and better\nunderstanding of composition.\n\nThe following settings are available for debugging:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable a special mode for debugging your layout, which\nrenders each layer with a colored outline and its `x` and `y` offsets, and\noverlays a dot grid for alignment, so it's easier to understand how the\ndistinct layers of your layout are composed together:\n\n``` yaml\nplugins:\n - social:\n debug: true\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin automatically disables [`debug`][config.debug] mode when\n[building your project], so you can be sure that debug overlays are never\ndeployed to production. If you want to change that, use:\n\n``` yaml\nplugins:\n - social:\n debug_on_build: true\n```\n\nIt's normally not necessary to change this setting, as it's just intended to\nbe a safety net.\n\n---\n\n#### \n\n\n\n\nWhen [`debug`][config.debug] mode is enabled, this setting specifies whether a\ndot grid is rendered on top of all layers, to allow for better alignment. If you\nwant to switch the grid off, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the step size of the dot grid in pixels, if enabled,\nwhich can be useful to create perfectly aligned layers for ideal composition.\nIt you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid_step: 64\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the color of the outlines that are added to each\nlayer and the dot grid that is rendered on top of all layers. If you need to\nchange it, use:\n\n``` yaml\nplugins:\n - social:\n debug_color: yellow\n```\n\nIn rare cases, it might be necessary to change this setting if the dot grid or\nthe outlines are hard to distinguish, as the plugin will automatically adjust\nthe color if not explicitly set.\n\n## Usage\n\n### Metadata\n\nThe plugin allows to override a subset of settings through metadata (front\nmatter) in order to customize social card generation, e.g., to set [options for\nthe included `default` layouts][default layouts] for a single page, or even\n[for an entire subsection] of your project by leveraging the [meta] plugin.\n\nThe following properties are available:\n\n [for an entire subsection]: meta.md#how-it-works\n [meta]: meta.md\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards`][config.cards] setting for the given\npage:\n\n``` yaml\n---\nsocial:\n cards: false\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to override the [`cards_layout`][config.cards_layout] setting\nfor the given page:\n\n``` yaml\n---\nsocial:\n cards_layout: my-custom-layout\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards_layout_options`]\n[config.cards_layout_options] setting for the given page:\n\n``` yaml\n---\nsocial:\n cards_layout_options:\n background_color: blue # Change background color\n background_image: null # Remove background image\n---\n\n# Page title\n...\n```\n\nSetting an option to `#!yaml null` resets the option.\n\n### Layouts\n\n\n\nWhile it is possible and simple to build [custom layouts], the plugin ships\nseveral predefined layouts, all of which are prefixed with `default`. The\nfollowing layouts are included:\n\n=== \"`default`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default\n ```\n\n \n\n ![Layout default]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/variant`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/variant\n ```\n\n \n\n ![Layout default variant]\n\n This layout includes the [page icon] and sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/accent`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/accent\n ```\n\n \n\n ![Layout default accent]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/invert`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/invert\n ```\n\n \n\n ![Layout default invert]\n\n This layout sets the following defaults:\n\n - [`color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/only/image`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/only/image\n cards_layout_options:\n background_image: layouts/background.png\n\n ```\n\n \n\n This layout only shows the given background image and scales it to cover.\n\n
\n\nThe [`default` layouts][default layouts] are very flexible and comfortable to\nuse, as they replicate the original behavior of the plugin, sourcing default\nvalues for all options from other `theme` settings.\n\nThe following options are available:\n\n [Layout default]: ../assets/screenshots/social-cards.png\n [Layout default variant]: ../assets/screenshots/social-cards-variant.png\n [Layout default accent]: ../assets/screenshots/social-cards-accent.png\n [Layout default invert]: ../assets/screenshots/social-cards-invert.png\n\n [primary color]: ../setup/changing-the-colors.md#primary-color\n [page icon]: ../reference/index.md#setting-the-page-icon\n [accent color]: ../setup/changing-the-colors.md#accent-color\n [font]: ../setup/changing-the-fonts.md#regular-font\n\n---\n\n#### \n\n\n\n\nUse this option to change the background color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: \"#ff1493\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: rgb(255, 20, 147) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: deeppink # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\nIf this options is used together with [`background_image`]\n[option.background_image], the color is rendered on top of the image which\nallows for tinting images. If you want to remove the background color, use:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n background_color: transparent\n```\n\n [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names\n [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color\n\n---\n\n#### \n\n\n\n\nUse this option to define a background image for the generated social card. Note\nthat the image is tinted with the [`background_color`][option.background_color],\nwhich can also be set to `transparent`:\n\n=== \"Image\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: transparent\n ```\n\n=== \"Image with tint\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: \"#ff149366\"\n ```\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this option to change the foreground color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: \"#ffffff\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: rgb(255, 255, 255) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: white # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\n---\n\n#### \n\n\n\n\nUse this option to change the font family of the generated social card. The\nplugin automatically downloads the font from [Google Fonts], so the font must\npoint to an existing Google Font:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_family: Ubuntu\n```\n\nWhen you've found a font that you like on [Google Fonts], you can just copy the\nname from the font's specimen page and use it as the value for this option –\nno further configuration needed.\n\n [Google Fonts]: https://fonts.google.com/\n\n---\n\n#### \n\n\n\n\nUse this option to change the font variant used to generate the social card.\nIf the downloaded font has variants like `Condensed` or `Expanded`, you can set\nthem with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_variant: Condensed\n```\n\nThe variant is combined with the style as used in the custom layout, so the\nplugin is instructed to use combinations like `Condensed Regular` or\n`Expanded Bold`.\n\n---\n\n#### \n\n\n\n\nUse this option to change the logo that is used in the generated social card.\nBy default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]\n[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n logo: layouts/logo.png\n```\n\nThe provided path is resolved from the root directory.\n\n [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image\n [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled\n\n---\n\n#### \n\n\n\n\nUse this option to change the title of the generated social card. This overrides\nthe computed page title as assigned by MkDocs, as well as the [`title`]\n[meta.title] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n title: My custom title\n```\n\n [meta.title]: ../reference/index.md#setting-the-page-title\n\n---\n\n#### \n\n\n\n\nUse this option to change the description of the generated social card. This\noverrides the set [`site_description`][mkdocs.site_description], if defined, as\nwell as the [`description`][meta.description] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n description: My custom description\n```\n\n [meta.description]: ../reference/index.md#setting-the-page-description\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up social cards, you might discover that you're missing\n specific functionality – we're happy to consider adding it to the plugin!\n You can [open a discussion] to ask a question, or create a [change request]\n on our [issue tracker], so we can find out if it might be a good fit for\n the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n","frontmatter":{"title":"Built-in social plugin","icon":"material/share-circle"},"isInternal":false,"tokens":6505,"sizeBytes":27678},{"name":"tags.md","path":"docs/plugins/tags.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/tags.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Built-in tags plugin\nicon: material/tag-text\n---\n\n# Built-in tags plugin\n\nThe tags plugin adds first-class support for categorizing pages with the use\nof tags, adding the possibility to group related pages and make them\ndiscoverable via search and dedicated tags indexes. If your documentation is\nlarge, tags can help to discover relevant information faster.\n\n## Objective\n\n### How it works\n\nThe plugin scans all pages for the [`tags`][meta.tags] metadata property and\ngenerates a tags index, which is an inverted list of tags and the pages they\nappear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],\nallowing for maximum flexibility when adding tags to your project.\n\n### When to use it\n\nIf you want to add one or multiple tags indexes to your project, the tags\nplugin is a perfect choice as it makes this process ridiculously simple.\nAdditionally, it integrates perfectly with several of the other\n[built-in plugins] that Material for MkDocs offers:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags][meta.tags], so they can't be\n forgotten when adding pages.\n\n ---\n\n __Simpler organization and management of tags in different subsections__\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [blog]: blog.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the tags plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start using\n[tags][meta.tags] to categorize your pages:\n\n``` yaml\nplugins:\n - tags\n```\n\nThe tags plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [tags]: tags.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - tags:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Tags\n\nThe following settings are available for tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable rendering of tags. The plugin still\nextracts tags from all pages, e.g., for [exporting tags] without rendering them.\nRendering can be disabled with:\n\n``` yaml\nplugins:\n - tags:\n tags: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\n!!! warning \"This setting is deprecated\"\n\n As of version , this setting is deprecated, as this\n version ships a __ground up rewrite of the tags plugin__ which is much more\n powerful than the previous version. Tags [listings] can be used on any page\n now.\n\n\n\nUse this setting to specify the location of the tags index, which is the page\nused to render a list of all tags and their associated pages. If this setting is\nspecified, tags become clickable, pointing to the corresponding section in the\ntags index:\n\n``` yaml\nplugins:\n - tags:\n tags_file: tags.md\n```\n\nThe page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]\nsection of `mkdocs.yml`. This setting is not required – you should only use it\nif you want to have a tags index.\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n
\n\n [listings]: ../setup/setting-up-tags.md#adding-a-tags-index\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`tags_slugify`][config.tags_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating tag\nslugs. It is a good idea to prefix tag slugs with a string that makes them\nunique, the default being:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_format: \"tag:{slug}\"\n```\n\nThe following placeholders are available:\n\n- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]\n\n---\n\n#### \n\n\n\n\n\nUse this setting to enable support for tag hierarchies (nested tags, e.g.,\n`foo/bar`). If you intend to create hierarchical listings of tags, you can\nenable this setting in `mkdocs.yml` with:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy: true\n```\n\n---\n\n#### \n\n\n\n\n\nUse this setting to change the separator that is used when creating tag\nhierarchies. By default, tags are separated by a forward slash `/`, but you\ncan change this to any string, e.g., `.`:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy_separator: .\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags. By default,\ntag comparison is case-sensitive, but you can use `tag_name_casefold` for\ncase-insensitive comparison:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the front matter property that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_property: tags\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the template variable that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_variable: tags\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check tags against a predefined list, in order to catch\ntypos or make sure that tags are not arbitrarily added. Specify the tags you\nwant to allow with:\n\n``` yaml\nplugins:\n - tags:\n tags_allowed:\n - HTML5\n - JavaScript\n - CSS\n```\n\nThe plugin stops the build if a page references a tag that is not part of\nthis list. Pages can be assigned to tags by using the [`tags`][meta.tags]\nmetadata property.\n\n### Listings\n\nThe following settings are available for listings:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable listings. It is normally not necessary to\nchange this setting, as listings are created entirely by inline comments, but\nyou can disable them if necessary with:\n\n``` yaml\nplugins:\n - tags:\n listings: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\nUse this define listing configurations that you can then reference in listings\nwith a custom identifier. Sharing configurations is a good idea, especially\nwhen you have many tag listings:\n\n``` yaml\nplugins:\n - tags:\n listings_map:\n custom-id:\n scope: true\n exclude: Internal\n```\n\nThen, just reference the listing identifier:\n\n``` html\n\n```\n\nSee the [listings section] for a list of all available settings.\n\n [listings section]: #listing-configuration\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing listing items. By\ndefault, items are ordered by their titles, but you can change the sorting\ncriterion with the following configuration:\n\n=== \"Sort by item title\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_title\n ```\n\n=== \"Sort by item URL\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_url\n ```\n\nYou can also define your own comparison function, which must return a string\nor number representing the item, that is used for sorting, and reference it in\n[`listings_sort_by`][config.listings_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which items are sorted when comparing\nthem. By default, items are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n listings_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags in listings. By\ndefault, tag comparison is case-sensitive, but you can use `tag_name_casefold`\nfor case-insensitivity:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the directive the plugin will look for\nwhen processing pages. If you want to use a shorter directive than\n`material/tags`, you could use:\n\n``` yaml\nplugins:\n - tags:\n listings_directive: $tags\n```\n\nUsing this setting, listings must now be referenced as such:\n\n``` html\n\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable tags showing up in the table of contents.\nIf you don't want tags to show up in the table of contents, you can disable this\nbehavior with:\n\n``` yaml\nplugins:\n - tags:\n listings_toc: false\n```\n\n### Shadow tags\n\nThe following settings are available for shadow tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether the plugin should include shadow tags on\npages and in listings when [building your project], which might be useful for\ndeploy previews:\n\n=== \"Show shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: true\n ```\n\n=== \"Hide shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include shadow tags on\npages and in listings when [previewing your site]. If you don't wish to include\nthem when previewing, use:\n\n``` yaml\nplugins:\n - tags:\n shadow_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin allows to specify a predefined list of shadow tags which can be\nincluded and excluded from builds by using the [`shadow`][config.shadow]\nsetting. Shadow tags must be specified as a list:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags:\n - Draft\n - Internal\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a prefix for each tag.\nIf the tag starts with this string, the tag is marked as a shadow tag. A common\npractice is to use `_` as a prefix:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_prefix: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a suffix for each tag.\nIf the tag ends with this string, the tag is marked as a shadow tag. One option\ncan be to use `Internal` as a suffix:\n\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_suffix: Internal\n```\n\n### Export\n\nThe following settings are available for exporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin creates a `tags.json` file\ninside your [`site` directory][mkdocs.site_dir], which can then be consumed by\nother plugins and projects:\n\n``` yaml\nplugins:\n - tags:\n export: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the exported tags are\nstored. It's normally not necessary to change this setting, but if you need to,\nuse:\n\n``` yaml\nplugins:\n - tags:\n export_file: tags.json\n```\n\nThe provided path is resolved from the [`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nThis setting is solely provided for convenience to disable the rendering of tags\nand listings with a single setting (e.g. by using an environment variable),\nwhile keeping the export functionality:\n\n``` yaml\nplugins:\n - tags:\n export_only: true\n```\n\nThis will automatically disable the [`tags`][config.tags] and\n[`listings`][config.listings] settings.\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a page with one or more tags, making the page\nappear in the generated tags index. Tags are defined as a list of strings\n(whitespaces are allowed):\n\n``` yaml\n---\ntags:\n - HTML5\n - JavaScript\n - CSS\n---\n\n# Page title\n...\n```\n\nIf you want to prevent accidental typos when assigning tags to pages, you can\nset a predefined list of allowed tags in `mkdocs.yml` by using the\n[`tags_allowed`][config.tags_allowed] setting.\n\n### Listing configuration\n\nThe listings configuration controls which tags are included in or excluded from\na listing and whether a listing only includes pages in the current scope.\nFurthermore, listings can override some values from the global configuration.\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should only consider pages that are\nwithin the current subsection of the documentation of the page the listing is\nembedded in:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n scope: false\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should include shadow tags, which\nallows to override the global [`shadow`][config.shadow] setting on a per-listing\nbasis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n shadow: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should render tags inside the table\nof contents, allowing to override the global [`listings_toc`][config.listings_toc]\nsetting on a per-listing basis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n toc: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be included in the listing. Each\npage that features a tag that is part of this setting, is listed under the\nrespective tag:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n include:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, all tags and pages are included.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be excluded from the listing. Each\npage that features a tag that is part of this setting, is excluded from the\nlisting entirely:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n exclude:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, no tags or pages are excluded.\n\n## Limitations\n\nThe implementation of the tags plugin is tricky due to MkDocs architecture.\nNotably, tag listing markers cannot appear within code blocks. For technical\ndetails, refer to #8114.\n","frontmatter":{"title":"Built-in tags plugin","icon":"material/tag-text"},"isInternal":false,"tokens":5045,"sizeBytes":21136},{"name":"typeset.md","path":"docs/plugins/typeset.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/typeset.md","title":"Plugins Skill","category":"anthropic-skill","format":"markdown","content":"# Plugins Skill\n\nPath: `docs/plugins/typeset.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/typeset.md)","tokens":300,"sizeBytes":168},{"name":"markdown.json","path":"docs/schema/extensions/markdown.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/markdown.json","title":"Extensions Skill","category":"anthropic-skill","format":"json","content":"# Extensions Skill\n\nPath: `docs/schema/extensions/markdown.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/markdown.json)","tokens":300,"sizeBytes":197},{"name":"pymdownx.json","path":"docs/schema/extensions/pymdownx.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/pymdownx.json","title":"Extensions Skill","category":"anthropic-skill","format":"json","content":"# Extensions Skill\n\nPath: `docs/schema/extensions/pymdownx.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/pymdownx.json)","tokens":300,"sizeBytes":197},{"name":"blog.json","path":"docs/schema/plugins/blog.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/blog.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/blog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/blog.json)","tokens":300,"sizeBytes":180},{"name":"awesome-nav.json","path":"docs/schema/plugins/external/awesome-nav.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/awesome-nav.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/awesome-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/awesome-nav.json)","tokens":300,"sizeBytes":213},{"name":"gen-files.json","path":"docs/schema/plugins/external/gen-files.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/gen-files.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/gen-files.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/gen-files.json)","tokens":300,"sizeBytes":209},{"name":"git-authors.json","path":"docs/schema/plugins/external/git-authors.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-authors.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/git-authors.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-authors.json)","tokens":300,"sizeBytes":213},{"name":"git-committers.json","path":"docs/schema/plugins/external/git-committers.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-committers.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/git-committers.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-committers.json)","tokens":300,"sizeBytes":219},{"name":"git-revision-date.json","path":"docs/schema/plugins/external/git-revision-date.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-revision-date.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/git-revision-date.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-revision-date.json)","tokens":300,"sizeBytes":225},{"name":"literate-nav.json","path":"docs/schema/plugins/external/literate-nav.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/literate-nav.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/literate-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/literate-nav.json)","tokens":300,"sizeBytes":215},{"name":"macros.json","path":"docs/schema/plugins/external/macros.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/macros.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/macros.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/macros.json)","tokens":300,"sizeBytes":203},{"name":"minify.json","path":"docs/schema/plugins/external/minify.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/minify.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/minify.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/minify.json)","tokens":300,"sizeBytes":203},{"name":"redirects.json","path":"docs/schema/plugins/external/redirects.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/redirects.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/redirects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/redirects.json)","tokens":300,"sizeBytes":209},{"name":"section-index.json","path":"docs/schema/plugins/external/section-index.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/section-index.json","title":"External Skill","category":"anthropic-skill","format":"json","content":"# External Skill\n\nPath: `docs/schema/plugins/external/section-index.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/section-index.json)","tokens":300,"sizeBytes":217},{"name":"group.json","path":"docs/schema/plugins/group.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/group.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/group.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/group.json)","tokens":300,"sizeBytes":182},{"name":"info.json","path":"docs/schema/plugins/info.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/info.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/info.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/info.json)","tokens":300,"sizeBytes":180},{"name":"meta.json","path":"docs/schema/plugins/meta.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/meta.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/meta.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/meta.json)","tokens":300,"sizeBytes":180},{"name":"offline.json","path":"docs/schema/plugins/offline.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/offline.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/offline.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/offline.json)","tokens":300,"sizeBytes":186},{"name":"optimize.json","path":"docs/schema/plugins/optimize.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/optimize.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/optimize.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/optimize.json)","tokens":300,"sizeBytes":188},{"name":"privacy.json","path":"docs/schema/plugins/privacy.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/privacy.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/privacy.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/privacy.json)","tokens":300,"sizeBytes":186},{"name":"projects.json","path":"docs/schema/plugins/projects.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/projects.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/projects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/projects.json)","tokens":300,"sizeBytes":188},{"name":"search.json","path":"docs/schema/plugins/search.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/search.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/search.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/search.json)","tokens":300,"sizeBytes":184},{"name":"social.json","path":"docs/schema/plugins/social.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/social.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/social.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/social.json)","tokens":300,"sizeBytes":184},{"name":"tags.json","path":"docs/schema/plugins/tags.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/tags.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/tags.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/tags.json)","tokens":300,"sizeBytes":180},{"name":"typeset.json","path":"docs/schema/plugins/typeset.json","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/typeset.json","title":"Plugins Skill","category":"anthropic-skill","format":"json","content":"# Plugins Skill\n\nPath: `docs/schema/plugins/typeset.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/typeset.json)","tokens":300,"sizeBytes":186},{"name":"index.md","path":"docs/setup/extensions/index.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/index.md","title":"Extensions Skill","category":"anthropic-skill","format":"markdown","content":"# Extensions Skill\n\nPath: `docs/setup/extensions/index.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/index.md)","tokens":300,"sizeBytes":185},{"name":"python-markdown-extensions.md","path":"docs/setup/extensions/python-markdown-extensions.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown-extensions.md","title":"Extensions Skill","category":"anthropic-skill","format":"markdown","content":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown-extensions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown-extensions.md)","tokens":300,"sizeBytes":227},{"name":"python-markdown.md","path":"docs/setup/extensions/python-markdown.md","rawUrl":"https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown.md","title":"Extensions Skill","category":"anthropic-skill","format":"markdown","content":"# Extensions Skill\n\nPath: `docs/setup/extensions/python-markdown.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/setup/extensions/python-markdown.md)","tokens":300,"sizeBytes":205}],"systemPromptSnippet":"\n\n---\ntitle: Built-in blog plugin\nicon: material/newspaper-variant-outline\n---\n\n# Built-in blog plugin\n\nThe blog plugin makes it very easy to build a blog, either as a sidecar to\nyour documentation or as the main thing. Focus on your content while the plugin\ndoes all the heavy lifting, generating a view of all latest posts, [archive] and\n[category] pages, configurable [pagination] and much more.\n\n [archive]: #archive\n [category]: #categories\n [pagination]: #pagination\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`posts` directory][config.post_dir] for\n`.md` files from which paginated views[^1] are automatically generated. If not\nconfigured otherwise, the plugin expects that your project has the following\ndirectory layout, and will create any missing directories or files for you:\n\n [^1]:\n Views are pages that are automatically generated, i.e., the entry point to\n your blog listing all latest posts, as well as [archive] and [category]\n pages that list all posts associated with them through [metadata] in\n chronological order.\n\n``` { .sh .no-copy }\n.\n├─ docs/\n│ └─ blog/\n│ ├─ posts/\n│ └─ index.md\n└─ mkdocs.yml\n```\n\nThe `index.md` file in the [`blog` directory][config.blog_dir] is the entry\npoint to your blog – a paginated view listing all posts in reverse chronological\norder. Besides that, the plugin supports automatically creating [archive] and\n[category] pages that list a subset of posts for a time interval or category.\n\n[Post URLs][config.post_url_format] are completely configurable, no matter if\nyou want your URLs to include the post's date or not. Rendered dates always\ndisplay in the locale of the [site language] of your project. Like in other\nstatic blog frameworks, posts can be annotated with a variety of [metadata],\nallowing for easy integration with other [built-in plugins], e.g., the\n[social] and [tags] plugin.\n\nPosts can be organized in nested folders with a directory layout that suits your\nspecific needs, and can make use of all components and syntax that Material for\nMkDocs offers, including [admonitions], [annotations], [code blocks],\n[content tabs], [diagrams], [icons], [math], and more.\n\n [metadata]: #metadata\n [admonitions]: ../reference/admonitions.md\n [annotations]: ../reference/annotations.md\n [code blocks]: ../reference/code-blocks.md\n [content tabs]: ../reference/content-tabs.md\n [diagrams]: ../reference/diagrams.md\n [icons]: ../reference/icons-emojis.md\n [math]: ../reference/math.md\n\n### When to use it\n\nIf you want to add a blog to your project, or migrate from another blog\nframework to Material for MkDocs because of its excellent technical writing\ncapabilities, this plugin is a great choice, as it integrates perfectly with\nmany other built-in plugins:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to apply [metadata] to a subset of posts,\n including authors, tags, categories, draft status, as well as social card\n layouts.\n\n ---\n\n __Simpler organization, categorization and management of post metadata__\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your blog loads faster as smaller images are served to your users__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [social]: social.md\n [optimize]: optimize.md\n [tags]: tags.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the blog plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and you can\nstart writing your first post:\n\n``` yaml\nplugins:\n - blog\n```\n\nThe blog plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [blog]: blog.md\n [built-in plugins]: index.md\n\n### Navigation\n\nIf you do not have site navigation configured in your `mkdocs.yml` then there is\nnothing more to do. The blog [archive] and [category] pages will automatically\nappear underneath the automatically generated navigation.\n\nIf you do have a navigation structure defined then you will need to specify\nwhere the blog should appear in this. Create a [navigation section with an index\npage] for the blog:\n\n```yaml\ntheme:\n name: material\n features:\n - navigation.indexes\nnav:\n - ...\n - Blog:\n - blog/index.md\n```\n\nThe [archive] and [category] pages will appear within that section as\nsubsections beneath pages in the blog section. In this case, they would appear\nafter `index.md`. The path to the `index.md` file must match\n[blog_dir][config.blog_dir]. This means that you can name the blog navigation\nentry anything you like: 'Blog' or 'News' or perhaps 'Tips'.\n\n[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - blog:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path where your blog is located in the\n[`docs` directory][mkdocs.docs_dir]. The path is included in the generated\nURLs as a prefix for all posts and views. You can change it with:\n\n=== \"Documentation + Blog\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: blog\n ```\n\n=== \"Blog only\"\n\n ``` yaml\n plugins:\n - blog:\n blog_dir: .\n ```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles in\nviews. This might be useful, if your post excerpts are rather long. If you want\nto enable it, use:\n\n``` yaml\nplugins:\n - blog:\n blog_toc: true\n```\n\n### Posts\n\nThe following settings are available for posts:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your posts are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - blog:\n post_dir: \"{blog}/articles\"\n```\n\nNote that the [`posts` directory][config.post_dir] is solely used for post\norganization – it is not included in post URLs, since they are automatically\nand comfortably generated by this plugin.\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format of posts. This plugin uses [babel]\nto render dates in the configured [site language]. You can use [babel]'s\n[pattern syntax] or the following shortcodes:\n\n=== \"Monday, January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: full\n ```\n\n=== \"January 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: long\n ```\n\n=== \"Jan 31, 2024\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: medium\n ```\n\n=== \"1/31/24\"\n\n ``` yaml\n plugins:\n - blog:\n post_date_format: short\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n [babel]: https://pypi.org/project/Babel/\n [site language]: ../setup/changing-the-language.md#site-language\n [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used in post URLs. The format string\nmust adhere to [babel]'s [pattern syntax] and should not contain whitespace.\nSome popular choices:\n\n=== \":material-link: blog/2024/01/31/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM/dd\n ```\n\n=== \":material-link: blog/2024/01/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy/MM\n ```\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_date_format: yyyy\n ```\n\nIf you want to remove the date from post URLs, e.g., when your blog features\nmostly evergreen content, you can remove the `date` placeholder from the\n[`post_url_format`][config.post_url_format] format string.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating post\nURLs. You can freely combine placeholders, and join them with slashes or other\ncharacters:\n\n=== \":material-link: blog/2024/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{date}/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n post_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `categories` – Post categories, slugified with [`categories_slugify`][config.categories_slugify]\n- `date` – Post date, formatted with [`post_url_date_format`][config.post_url_date_format]\n- `slug` – Post title, slugified with [`post_slugify`][config.post_slugify], or explicitly set via [`slug`][meta.slug] metadata property\n- `file` – Post filename without `.md` file extension\n\nIf you remove the `date` placeholder, make sure that post URLs don't collide\nwith URLs of other pages hosted under the [`blog` directory][config.blog_dir],\nas this leads to undefined behavior.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories included in\npost URLs if the `categories` placeholder is part of [`post_url_format`]\n[config.post_url_format] and the post defines categories:\n\n``` yaml\nplugins:\n - blog:\n post_url_format: \"{categories}/{slug}\"\n post_url_max_categories: 2\n```\n\nIf more than one category is given, they are joined with `/` after slugifying.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n post_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`post_slugify`][config.post_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n post_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)\noptional. When a post doesn't define an excerpt, views include the entire post.\nThis setting can be used to make post excerpts required:\n\n=== \"Optional\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: optional\n ```\n\n=== \"Required\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt: required\n ```\n\nWhen post excerpts are required, posts without excerpt separators raise an\nerror. Thus, this setting is useful when you want to make sure that all posts\nhave excerpts defined.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of authors rendered in\npost excerpts. While each post may be written by multiple authors, this setting\nallows to limit the display to just a few or even a single author, or disable\nauthors in post excerpts:\n\n=== \"Render up to 2 authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 2\n ```\n\n=== \"Disable authors\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_authors: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all authors.\n\n---\n\n#### \n\n\n\n\nUse this setting to set an upper bound for the number of categories rendered in\npost excerpts. While each post may be assigned to multiple categories, this\nsetting allows to limit the display to just a few or even a single category, or\ndisable categories in post excerpts:\n\n=== \"Render up to 2 categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 2\n ```\n\n=== \"Disable categories\"\n\n ``` yaml\n plugins:\n - blog:\n post_excerpt_max_categories: 0\n ```\n\nThis only applies to post excerpts in views. Posts always render all categories.\n\n---\n\n#### \n\n\n\n\nUse this setting to set the separator the plugin will look for in a post's\ncontent when generating post excerpts. All content __before__ the separator is\nconsidered to be part of the excerpt:\n\n``` yaml\nplugins:\n - blog:\n post_excerpt_separator: \n```\n\nIt is common practice to use an HTML comment as a separator.\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should automatically compute the\nreading time of a post, which is then rendered in post excerpts, as well as in\nposts themselves:\n\n``` yaml\nplugins:\n - blog:\n post_readtime: false\n```\n\n!!! warning \"Chinese, Japanese and Korean characters\"\n\n Reading time computation currently does not take segmentation of Chinese,\n Japanese and Korean characters into account. This means that the reading\n time for posts in these languages may be inaccurate. We're planning on\n adding support in the future. In the meantime, please use the `readtime`\n front matter property to set the reading time.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of words that a reader is expected to read\nper minute when computing the reading time of a post. If you want to fine-tune\nit, use:\n\n``` yaml\nplugins:\n - blog:\n post_readtime_words_per_minute: 300\n```\n\nA reading time of 265 words per minute is considered to be the\n[average reading time of an adult].\n\n [average reading time of an adult]: https://help.medium.com/hc/en-us/articles/214991667-Read-time\n\n### Archive\n\nThe following settings are available for archive pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable archive pages. An archive page shows all\nposts for a specific interval (e.g. year, month, etc.) in reverse order. If you\nwant to disable archive pages, use:\n\n``` yaml\nplugins:\n - blog:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the archive section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_name: Archive\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page titles. The\nformat string must adhere to [babel]'s [pattern syntax]. Some popular choices:\n\n=== \"2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: yyyy\n ```\n\n=== \"January 2024\"\n\n ``` yaml\n plugins:\n - blog:\n archive_date_format: MMMM yyyy\n ```\n\nNote that depending on the [site language], results might look different for\nother languages.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the date format used for archive page URLs. The\nformat string must adhere to [babel]'s [pattern syntax] and should not contain\nwhitespace. Some popular choices:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy\n ```\n\n=== \":material-link: blog/archive/2024/01/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_date_format: yyyy/MM\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\narchive page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/archive/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"archive/{date}\"\n ```\n\n=== \":material-link: blog/2024/\"\n\n ``` yaml\n plugins:\n - blog:\n archive_url_format: \"{date}\"\n ```\n\nThe following placeholders are available:\n\n- `date` – Archive date, formatted with [`archive_url_date_format`][config.archive_url_date_format]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for archive pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n archive_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\narchive pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use\n\n``` yaml\nplugins:\n - blog:\n archive_toc: true\n```\n\n### Categories\n\nThe following settings are available for category pages:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable category pages. A category page shows all\nposts for a specific category in reverse chronological order. If you want to\ndisable category pages, use:\n\n``` yaml\nplugins:\n - blog:\n categories: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the category section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_name: Categories\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\ncategory page URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/category/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"category/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n categories_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Category, slugified with [`categories_slugify`][config.categories_slugify]\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom categories. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`categories_slugify`][config.categories_slugify]. While\nthe default is a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - blog:\n categories_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for sorting categories. For\nexample, if you want to sort categories by the number of posts they contain,\nuse the following configuration:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_by: !!python/name:material.plugins.blog.view_post_count\n```\n\nDon't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].\nYou can define your own comparison function, which must return something\nthat can be compared while sorting, i.e., a string or number.\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which categories are sorted. By\ndefault, categories are sorted in ascending order, but you can reverse ordering\nas follows:\n\n``` yaml\nplugins:\n - blog:\n categories_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check categories against a predefined list, in order to\ncatch typos or make sure that categories are not arbitrarily added. Specify the\ncategories you want to allow with:\n\n``` yaml\nplugins:\n - blog:\n categories_allowed:\n - Search\n - Performance\n```\n\nThe plugin stops the build if a post references a category that is not part of\nthis list. Posts can be assigned to categories by using the [`categories`]\n[meta.categories] metadata property.\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for category pages. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per category page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\ncategory pages. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n categories_toc: true\n```\n\n### Authors\n\nThe following settings are available for authors:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable post authors. If this setting is enabled,\nthe plugin will look for a file named [`.authors.yml`][config.authors_file] and\nrender authors in posts and views. Disable this behavior with:\n\n``` yaml\nplugins:\n - blog:\n authors: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the author information for\nyour posts resides. It's normally not necessary to change this setting, but if\nyou need to, use:\n\n``` yaml\nplugins:\n - blog:\n authors_file: \"{blog}/.authors.yml\"\n```\n\nThe following placeholders are available:\n\n- `blog` – [`blog` directory][config.blog_dir]\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n!!! info \"Format of author information\"\n\n The `.authors.yml` file must adhere to the following format:\n\n ``` yaml title=\".authors.yml\"\n authors:\n :\n name: string # Author name\n description: string # Author description\n avatar: url # Author avatar\n slug: url # Author profile slug\n url: url # Author website URL\n ```\n\n Note that `` must be set to an identifier for associating authors\n with posts, e.g., a GitHub username like `squidfunk`. This identifier can\n then be used in the [`authors`][meta.authors] metadata property of\n a post. Multiple authors are supported. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable automatically generated author profiles.\nAn author profile shows all posts by an author in reverse chronological order.\nYou can enable author profiles with:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the title of the authors section the plugin adds to\nthe navigation. If this setting is omitted, it's sourced from the translations.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_name: Authors\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\nauthor profile URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/author/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"author/{slug}\"\n ```\n\n=== \":material-link: blog/:material-dots-horizontal:/\"\n\n ``` yaml\n plugins:\n - blog:\n authors_profiles_url_format: \"{slug}\"\n ```\n\nThe following placeholders are available:\n\n- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]\n- `name` – Author name from [`authors_file`][config.authors_file]\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination for author profiles. The value\nof this setting is inherited from [`pagination`][config.pagination], unless it's\nexplicitly set. To disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per archive page. The\nvalue of this setting is inherited from [`pagination_per_page`]\n[config.pagination_per_page], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to leverage the table of contents to display post titles on all\nauthor profiles. The value of this setting is inherited from [`blog_toc`]\n[config.blog_toc], unless it's explicitly set. To change it, use:\n\n``` yaml\nplugins:\n - blog:\n authors_profiles_toc: true\n```\n\n### Pagination\n\nThe following settings are available for pagination:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable pagination in views – generated pages\nthat show posts or subsets of posts in reverse chronological order. If you want\nto disable pagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the number of posts rendered per page. If you have\nrather long post excerpts, it can be a good idea to reduce the number of posts\nper page:\n\n``` yaml\nplugins:\n - blog:\n pagination_per_page: 5\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating\npaginated view URLs. You can freely combine placeholders, and join them with\nslashes or other characters:\n\n=== \":material-link: blog/page/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"page/{page}\"\n ```\n\n=== \":material-link: blog/n/\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_url_format: \"{page}\"\n ```\n\nThe following placeholders are available:\n\n- `page` – Page number\n\n---\n\n#### \n\n\n\n\nThe plugin uses the [paginate] module to generate the pagination markup using a\nspecial syntax. Use this setting to customize how pagination is constructed.\nSome popular choices:\n\n=== \"1 2 3 .. n\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"~2~\"\n ```\n\n=== \"1 2 3 .. n :material-chevron-right: :material-chevron-double-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_first $link_previous ~2~ $link_next $link_last\"\n ```\n\n=== \"1 :material-chevron-right:\"\n\n ``` yaml\n plugins:\n - blog:\n pagination_format: \"$link_previous $page $link_next\"\n ```\n\nThe following placeholders are supported by [paginate]:\n\n- `#!css $first_page` – Number of first reachable page\n- `#!css $last_page` – Number of last reachable page\n- `#!css $page` – Number of currently selected page\n- `#!css $page_count` – Number of reachable pages\n- `#!css $items_per_page` – Maximal number of items per page\n- `#!css $first_item` – Index of first item on the current page\n- `#!css $last_item` – Index of last item on the current page\n- `#!css $item_count` – Total number of items\n- `#!css $link_first` – Link to first page (unless on first page)\n- `#!css $link_last` – Link to last page (unless on last page)\n- `#!css $link_previous` – Link to previous page (unless on first page)\n- `#!css $link_next` – Link to next page (unless on last page)\n\n [paginate]: https://pypi.org/project/paginate/\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether pagination should be automatically disabled\nwhen the view only consists of a single page. If you want to always render\npagination, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_if_single_page: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable persistence of content, i.e., if paginated\nviews should also display the content of their containing view. If you want to\nenable this behavior, use:\n\n``` yaml\nplugins:\n - blog:\n pagination_keep_content: true\n```\n\n### Drafts\n\nThe following settings are available for drafts:\n\n---\n\n#### \n\n\n\n\nRendering [draft posts][meta.draft] can be useful in deploy previews. Use this\nsetting to specify whether the plugin should include posts marked as drafts when\n[building your project]:\n\n=== \"Render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: true\n ```\n\n=== \"Don't render drafts\"\n\n ``` yaml\n plugins:\n - blog:\n draft: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include posts marked as\ndrafts when [previewing your site]. If you don't wish to include draft posts\nwhen previewing, use:\n\n``` yaml\nplugins:\n - blog:\n draft_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin can automatically mark posts with future dates as drafts. When the\ndate is past today, the post is automatically included when\n[building your project], unless explicitly marked as draft:\n\n``` yaml\nplugins:\n - blog:\n draft_if_future_date: true\n```\n\n## Usage\n\n### Metadata\n\nPosts can define a handful of metadata properties that specify how the plugin\nrenders them, in which views they are integrated, and how they are linked to\neach other. The metadata of each post is validated against a schema to allow for\na quicker discovery of syntax errors.\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with [authors] by providing a list of\nidentifiers as defined in the [`authors_file`][config.authors_file]. If an\nauthor can't be resolved, the plugin will terminate with an error:\n\n``` yaml\n---\nauthors:\n - squidfunk # (1)!\n---\n\n# Post title\n...\n```\n\n1. Authors are linked by using their identifiers. As an example, see\n [the `.authors.yml` file][.authors.yml] we're using for our blog.\n\n [authors]: #authors\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a post with one or more [categories][category],\nmaking the post a part of the generated category page. Categories are defined\nas a list of strings (whitespaces are allowed):\n\n``` yaml\n---\ncategories:\n - Search\n - Performance\n---\n\n# Post title\n...\n```\n\nIf you want to prevent accidental typos assigning categories to posts, you\ncan set a predefined list of allowed categories in `mkdocs.yml` by using\nthe [`categories_allowed`][config.categories_allowed] setting.\n\n---\n\n#### \n\n\n\n\n\nUse this property to specify a post's date. Note that this property is required,\nwhich means the build fails when it's not set. Additional dates can be set by\nusing a slightly different syntax:\n\n=== \"Date\"\n\n ``` yaml\n ---\n date: 2024-01-31\n ---\n\n # Post title\n ...\n ```\n\n=== \"Update date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31 # (1)!\n updated: 2024-02-01\n ---\n\n # Post title\n ...\n ```\n\n 1. Each post must have a creation date set.\n\n=== \"Custom date\"\n\n ``` yaml\n ---\n date:\n created: 2024-01-31\n my_custom_date: 2024-02-01 # (1)!\n ---\n\n # Post title\n ...\n ```\n\n 1. The blog plugin validates all dates and allows to format them with\n [babel]'s [pattern syntax] in templates. When using theme extension,\n authors can add custom dates to templates.\n\n This was first requested in #5733.\n\nThe following date formats are supported:\n\n- `2024-01-31`\n- `2024-01-31T12:00:00`\n\n---\n\n#### \n\n\n\n\n\nUse this property to mark a post as draft. The plugin allows to include or\nexclude posts marked as drafts when [building your project] using the\n[`draft`][config.draft] setting. Mark a post as draft with:\n\n``` yaml\n---\ndraft: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to pin a post to the top of a view. In case multiple posts are\npinned, the pinned posts are sorted by descending order and appear before all\nother posts. Pin a post with:\n\n``` yaml\n---\npin: true\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to define a list of links that are rendered in the sidebar of\na post. The property follows the same syntax as [`nav`][mkdocs.nav] in\n`mkdocs.yml`, supporting sections and even anchors:\n\n=== \"Links\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - insiders/index.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with sections\"\n\n ``` yaml\n ---\n links:\n - setup/setting-up-site-search.md\n - Insiders:\n - insiders/index.md\n - insiders/getting-started.md\n ---\n\n # Post title\n ...\n ```\n\n=== \"Links with anchors\"\n\n ``` yaml\n ---\n links:\n - plugins/search.md # (1)!\n - Insiders:\n - insiders/how-to-sponsor.md\n - insiders/getting-started.md#requirements\n ---\n\n # Post title\n ...\n ```\n\n 1. If a link defines an anchor, the plugin resolves the anchor from the\n linked page and sets the anchor title as a [subtitle].\n\nAll relative links are resolved from the [`docs` directory][mkdocs.docs_dir].\n\n [subtitle]: ../reference/index.md#setting-the-page-subtitle\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the reading time of a post in minutes. When\n[`post_readtime`][config.post_readtime] is enabled, the plugin computes the\nreading time of a post, which can be overridden with:\n\n``` yaml\n---\nreadtime: 15\n---\n\n# Post title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to explicitly set the slug of a post. By default, the slug of\na post is automatically computed by the [`post_slugify`][config.post_slugify]\nfunction from the post's title, which can be overridden with:\n\n``` yaml\n---\nslug: help-im-trapped-in-a-universe-factory\n---\n\n# Post title\n...\n```\n\nSlugs are passed to [`post_url_format`][config.post_url_format].\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up your blog or migrating from another blog framework, you\n might discover that you're missing specific functionality – we're happy to\n consider adding it to the plugin! You can [open a discussion] to\n ask a question, or create a [change request] on our [issue tracker], so we\n can find out if it might be a good fit for the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n\n\n---\ntitle: Built-in group plugin\nicon: material/format-list-group\n---\n\n# Built-in group plugin\n\nThe group plugin allows to group plugins into logical units to conditionally\nenable or disable them for specific environments with the use of\n[environment variables][mkdocs.env], e.g., to only enable a subset of\nplugins when [building your project] during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin conditionally and lazily loads all plugins that are part of a group\nif and only if the group is enabled, which means that the plugin doesn't add any\noverhead when the group is disabled. It also means that the grouped plugins\nonly need to be installed when the group is enabled.\n\nThe plugins that are part of the group are executed in the same order as if\nthey were defined at the top-level in the list of [`plugins`][mkdocs.plugins].\nThus, order is preserved and deterministic.\n\n### When to use it\n\nWhenever you're using multiple plugins that are only required in specific\nenvironments, e.g., when building your project during continuous integration\n(CI), the plugin is the perfect utility for making configuration simpler, as it\nremoves the need for splitting configuration into multiple files.\n\nIt can be used with any built-in or third-party plugin.\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the group plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nsplitting plugins into logical units:\n\n``` yaml\nplugins:\n - group\n```\n\nThe group plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [group]: group.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nThe plugin behaves differently than all other built-in plugins – __it is\ndisabled by default__. To enable a group, use:\n\n``` yaml\nplugins:\n - group:\n enabled: !ENV CI # (1)!\n```\n\n1. If you only want to use the group plugin for better organization and\n always want to enable the plugins that are part of it, use:\n\n ``` yaml\n plugins:\n - group:\n enabled: true\n ```\n\nThe decision to disable the plugin by default was made to simplify the usage\nof environment variables, as it removes the need to provide a default value for\nan environment variable.\n\nNow, when [building your project], you can enable a group by setting the\n[environment variable][mkdocs.env]:\n\n``` sh\nCI=true mkdocs build\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to list the plugins that are part of the group. The syntax is\nexactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can\nsimply copy the list of plugins that you want to group, e.g:\n\n``` yaml\nplugins:\n - group:\n plugins:\n - optimize\n - minify\n```\n\nThe plugins mentioned here are just used for illustration purposes.\n\n\n# Built-in plugins\n\nMaterial for MkDocs started out as a theme for [MkDocs][mkdocs], but has since\nevolved into a full-fledged framework for building and maintaining documentation.\nThe theme is still the core of the project, but it's now accompanied by a\ngrowing number of complementary built-in plugins.\n\nWe strive to make those plugins as modular and generic as possible, so that they\ncan be used in a wide variety of projects and use cases. By providing useful\ndefault settings, we also try to make them as easy to use as possible, so that\nyou can get started quickly, tweaking their settings later on. When\ndeveloping built-in plugins, we always adhere to the following design principles:\n\n- **Modularity:** Built-in plugins are designed to be modular, so that they can\n be easily combined to implement sophisticated pipelines. For example, the\n [offline], [optimize] and [privacy] plugins can be used together to build\n truly [offline-capable documentation].\n\n- **Interoperability:** Built-in plugins are designed to be as compatible as\n possible, so they can be used in combination with other plugins, including\n third-party plugins. We strive to make it simple to integrate with the vast\n ecosystem that has evolved around [MkDocs][mkdocs].\n\n- **Performance:** Built-in plugins are designed to be as fast and\n memory-efficient as possible, so that they don't unnecessarily slow down\n builds. This is particularly important for large documentation projects with\n thousands of pages.\n\n [mkdocs]: https://www.mkdocs.org/\n [design principles]: ../design-principles.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Categories\n\n### Management\n\nThe following plugins greatly improve the authoring experience when working on\ndocumentation projects by providing better management capabilities, from the\nmanagement of plugins, multiple projects, and metadata, to the creation of\nminimal reproductions for bug reports:\n\n\n\n- :material-format-list-group: __[Built-in group plugin][group]__\n\n ---\n\n The group plugin allows to group plugins into logical units to conditionally\n enable or disable them for specific environments with the use of\n [environment variables][mkdocs.env].\n\n ---\n\n __Optimal management of plugins when building in different environments__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to manage metadata (front matter) for all\n pages in a folder, so a certain subset of pages uses specific tags or a\n custom template.\n\n ---\n\n __Simpler organization, categorization and management of metadata__\n\n- :material-folder-open: __[Built-in projects plugin][projects]__\n\n ---\n\n The projects plugin allows to split your main project into multiple distinct\n projects, build them concurrently and preview them together as one.\n\n ---\n\n __Connect multiple projects together, and build them separately or as one__\n\n- :material-information: __[Built-in info plugin][info]__\n\n ---\n\n The info plugin is a small and useful utility that helps to create\n self-contained minimal reproductions, so we maintainers can fix reported\n bugs more quickly.\n\n ---\n\n __Your bug reports are of the highest quality, so we can fix them as fast as\n possible__\n\n\n
\n\n [group]: group.md\n [info]: info.md\n [meta]: meta.md\n [projects]: projects.md\n\n### Optimization\n\nThe following plugins are designed to help you build optimized documentation,\nmaking it more accessible to your users through faster loading times, better\nsearch engine rankings, beautiful preview images on social media, and GDPR\ncompliance with a few lines of configuration:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each page of your documentation, showing as previews on\n social media.\n\n ---\n\n __Links to your site render beautiful social cards when shared on social\n media__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your site loads faster as smaller images are served to your users__\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin downloads external assets automatically for easy\n self-hosting, allowing for GDPR compliance with a single line of\n configuration.\n\n ---\n\n __Your documentation can be made GDPR compliant with minimal effort__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [offline]: offline.md\n [optimize]: optimize.md\n [privacy]: privacy.md\n [social]: social.md\n\n### Content\n\nThe following plugins are designed to help you set up a blog, provide search\nfunctionality to your users, add tags to pages and posts, and use the same\ntypesetting capabilities in specific parts of the documentation exactly as in\nthe main content:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The blog plugin adds first-class support for blogging to Material for\n MkDocs, either as a sidecar to your documentation or as a standalone\n installation.\n\n ---\n\n __Your blog is built with the same powerful engine as your documentation__\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The search plugin adds a search bar to the header, allowing users to search\n the entire documentation, so it's easier for them to find what they're\n looking for.\n\n ---\n\n __Your documentation is searchable without any external services, even\n offline__\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The tags plugin adds first-class support for categorizing pages with tags,\n adding the ability to group related pages to improve the discovery of\n related content.\n\n ---\n\n __Your pages are categorized with tags, yielding additional context__\n\n- :material-format-title: __[Built-in typeset plugin][typeset]__\n\n ---\n\n The typeset plugin allows to preserve the enriched presentation of titles\n and headlines within the navigation and table of contents.\n\n ---\n\n __Sidebars preserve the same formatting as section titles in pages__\n\n
\n\n [blog]: blog.md\n [search]: search.md\n [tags]: tags.md\n [typeset]: typeset.md\n\n## Architecture\n\n### Multiple instances\n\nSeveral built-in plugins have support for multiple instances, which means that\nthey can be used multiple times in the same configuration file, allowing to\nfine-tune behavior for separate sections of your project. Currently, the\nfollowing plugins have support for multiple instances:\n\n\n\n- [Built-in blog plugin][blog]\n- [Built-in group plugin][group]\n- [Built-in optimize plugin][optimize]\n- [Built-in privacy plugin][privacy]\n- [Built-in social plugin][social]\n\n
\n\n\n---\ntitle: Built-in info plugin\nicon: material/information\n---\n\n# Built-in info plugin\n\nThe info plugin is a utility that is solely intended to create self-contained\n[minimal reproductions] as `.zip` files when [reporting bugs] or proposing\n[change requests], making communication between us maintainers and you much\neasier, as we have a common ground to work on.\n\n [minimal reproductions]: ../guides/creating-a-reproduction.md\n [reporting bugs]: ../contributing/reporting-a-bug.md\n [change requests]: ../contributing/requesting-a-change.md\n\n## Objective\n\n### How it works\n\nThe plugin helps you to prepare a minimal reproduction by collecting the\nnecessary information about the environment and configuration of your project.\nThis makes it easier for us to fix bugs, as it requires that you\n[upgrade to the latest version] and [remove your customizations].\n\nWhen following these principles, you can be confident that you don't report a\nbug that has already been fixed in a subsequent release, or which is caused by\none of your customizations. Even more importantly, you actively help\nus to fix the bug as quickly as possible.\n\nThe output of the plugin is a `.zip` file that you can share with us maintainers.\n\n [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version\n [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations\n\n\n### When to use it\n\nWhenever you're [reporting a bug][reporting bugs] or have something to discuss,\nlike a question or [change request][change requests], you should attach\na small, self-contained minimal reproduction. Runnable examples help to make\ncommunication much more efficient, giving us maintainers more time to benefit\nmore users by pushing the project forward. Minimal reproductions are mandatory\nfor bug reports.\n\n## Configuration\n\n\n\n\nIn order to get started with the built-in info plugin, just add the following\nlines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share\nwith us maintainers:\n\n``` yaml\nplugins:\n - info\n```\n\nThe info plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [info]: info.md\n [create a minimal reproduction]: ../guides/creating-a-reproduction.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - info:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should be enabled when\n[previewing your site]. It's normally not necessary to specify this setting,\nbut if you want to change this behavior, use:\n\n``` yaml\nplugins:\n - info:\n enabled_on_serve: true\n```\n\nThis setting streamlines the process of creating and inspecting minimal\nreproductions, as it allows to quickly iterate on the reproduction without\nhaving to disable the plugin first.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n### Archive\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should create a `.zip` file\nfrom the project or exit after the version check. This setting is solely\nintended for debugging the plugin itself:\n\n``` yaml\nplugins:\n - info:\n archive: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should stop creating the `.zip`\nfile when one of the [requirements] is not satisfied. This setting must only be\nused when [reporting a bug][reporting bugs] that is related to a customization\n[explicitly mentioned in our documentation]. You can change it with:\n\n``` yaml\nplugins:\n - info:\n archive_stop_on_violation: false\n```\n\nIf you're using this setting when [reporting a bug][reporting bugs], please\nexplain why you think it is necessary to include customizations. If you're\nunsure, please ask us first by [creating a discussion].\n\n [requirements]: #how-it-works\n [explicitly mentioned in our documentation]: ?q=%22extends+base%22\n [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n\n\n---\ntitle: Built-in meta plugin\nicon: material/file-tree\n---\n\n# Built-in meta plugin\n\nThe meta plugin solves the problem of setting metadata (front matter) for all\npages in a folder, i.e., a subsection of your project, which is particularly\nuseful to ensure that a certain subset of pages features specific tags, uses a\ncustom template, or is attributed to an author.\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,\nand recursively merges the contents of those files with the metadata (front\nmatter) of all pages that are contained in the same folder and all subfolders.\nFor example, if you want to add the tag Example to\nmultiple pages, use:\n\n``` yaml title=\".meta.yml\"\ntags:\n - Example\n```\n\nNow, given the following directory layout, if you store the file in the folder\nnamed `example`, all pages in that folder receive the tag, while all pages\noutside of the folder remain unaffected:\n\n``` { .sh .no-copy hl_lines=\"4-8\" }\n.\n├─ docs/\n│ ├─ ...\n│ ├─ example/\n│ │ ├─ .meta.yml\n│ │ ├─ a.md\n│ │ ├─ ...\n│ │ └─ z.md\n│ └─ ...\n└─ mkdocs.yml\n```\n\nWhen combining metadata, lists and dictionaries are recursively merged, which\nmeans you can append values to a list and add or set specific properties in a\ndictionary on arbitrary levels.\n\n### When to use it\n\nWhile the plugin itself doesn't offer much functionality beyond adding and\nmerging metadata, it is a perfect companion for many of the other built-in\nplugins that Material for MkDocs offers. Some of the most powerful combinations\nof the meta plugin and other built-in plugins are:\n\n\n\n- :material-share-circle: __[Built-in social plugin][social]__\n\n ---\n\n The meta plugin can be used to [change the layout] for social cards or\n [change specific layout options] like [background] or [color]\n for a subset of pages.\n\n ``` yaml title=\".meta.yml\"\n social:\n cards_layout: default/variant\n ```\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The meta plugin allows to automatically associate blog posts with specific\n [authors] and [categories], ensuring that blog posts are always correctly\n annotated.\n\n ``` yaml title=\".meta.yml\"\n authors:\n - squidfunk\n ```\n\n- :material-tag-text: __[Built-in tags plugin][tags]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags], so they can't be forgotten when\n adding pages.\n\n ``` yaml title=\".meta.yml\"\n tags:\n - Example\n ```\n\n- :material-magnify: __[Built-in search plugin][search]__\n\n ---\n\n The meta plugin makes it easy to [boost] specific sections in search results\n or to [exclude] them entirely from being indexed, giving more granular\n control over search.\n\n ``` yaml title=\".meta.yml\"\n search:\n exclude: true\n ```\n\n
\n\n [social]: social.md\n [change the layout]: social.md#meta.social.cards_layout\n [change specific layout options]: social.md#meta.social.cards_layout_options\n [background]: social.md#option.background_color\n [color]: social.md#option.color\n [blog]: blog.md\n [authors]: blog.md#meta.authors\n [categories]: blog.md#meta.categories\n [tags]: tags.md\n [specific tags]: tags.md#meta.tags\n [search]: search.md\n [exclude]: search.md#meta.search.exclude\n [boost]: search.md#meta.search.boost\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the meta plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\napplying metadata for multiple pages at once:\n\n``` yaml\nplugins:\n - meta\n```\n\nThe meta plugin is included with Material for MkDocs and doesn't need to be\ninstalled.\n\n [meta]: meta.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - meta:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Meta file\n\nThe following settings are available for meta files:\n\n---\n\n#### \n\n\n\n\nUse this setting to change the meta file name the plugin will look for when\nscanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to\nchange this setting, but if you want to change it, use:\n\n``` yaml\nplugins:\n - meta:\n meta_file: .meta.yml\n```\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir]\nrecursively.\n\n\n---\ntitle: Built-in offline plugin\nicon: material/connection\n---\n\n\n# Built-in offline plugin\n\n[MkDocs][mkdocs] is one of the few frameworks that supports building\noffline-capable documentation that can be directly viewed by the user – no\nserver needed. With the offline plugin, you can distribute the\n[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while\nretaining most interactive functionality.\n\n## Objective\n\n### How it works\n\nAfter [building your project], switch to the [`site` directory][mkdocs.site_dir]\nand open `index.html` in your browser – you're now viewing your documentation\nfrom your local file system! Most browsers will denote this by showing `file://`\nin the address bar. However, you'll realize that the site search is gone.\n\nMaterial for MkDocs offers many interactive features, some of which will not\nwork from the local file system due to the restrictions of modern browsers. More\nspecifically and technically, all calls to the [Fetch API] will error with a\nmessage like:\n\n```\nCross origin requests are only supported for protocol schemes: http, [...]\n```\n\nWhile browsers impose those restriction for security reasons, it reduces the\ninteractivity of your project. The offline plugin makes sure that site search\nkeeps working by moving the search index to a JavaScript file, and leveraging\n@squidfunk's [iframe-worker] shim.\n\nAdditionally, the plugin automatically disables the [`use_directory_urls`]\n[mkdocs.use_directory_urls] setting, ensuring that users can open your\ndocumentation directly from the local file system.\n\nThere are some [limitations].\n\n [building your project]: ../creating-your-site.md#building-your-site\n [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API\n [iframe-worker]: https://github.com/squidfunk/iframe-worker\n [limitations]: #limitations\n\n### When to use it\n\nAs the name already indicates, the plugin should only be used when you're\n[building your project] for offline distribution. It's also good to know, that\nthe offline plugin plays nicely with the following other plugins, helping to\ncreate even better offline-capable documentation:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use external assets when building for\n offline usage, as it automatically downloads them for distribution with\n your documentation.\n\n ---\n\n __Your documentation can work without connectivity to the internet[^1]__\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin automatically identifies and optimizes all media files\n that you reference in your project by using compression and conversion\n techniques.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [^1]:\n You might wonder why the [privacy plugin][privacy] is necessary to build\n truly offline-capable documentation with the offline plugin. While it's\n certainly possible to also add support for downloading external assets to\n the offline plugin, this functionality is already fully implemented in the\n privacy plugin and is its very raison d'être.\n\n Material for MkDocs follows a modular approach for its plugin system – many\n of the plugins work perfectly together and enhance each others\n functionalities, allowing to solve complex problems with a few lines\n of configuration.\n\n [privacy]: privacy.md\n [optimize]: optimize.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the offline plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\nbuilding offline-capable documentation:\n\n``` yaml\nplugins:\n - offline\n```\n\nThe offline plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [offline]: offline.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to build online- as well as offline-capable documentation, it's a\ngood idea to use an [environment variable][mkdocs.env]:\n\n``` yaml\nplugins:\n - offline:\n enabled: !ENV [OFFLINE, false]\n```\n\n## Limitations\n\nWhen enabling the offline plugin, make sure to disable the following settings,\nas they make use of the [Fetch API] which will error when invoked from the local\nfile system:\n\n- [Instant loading]\n- [Site analytics]\n- [Versioning]\n- [Comment systems]\n\n [Instant loading]: ../setup/setting-up-navigation.md#instant-loading\n [Site analytics]: ../setup/setting-up-site-analytics.md\n [Versioning]: ../setup/setting-up-versioning.md\n [Comment systems]: ../setup/adding-a-comment-system.md\n\n\n---\ntitle: Built-in optimize plugin\nicon: material/rabbit\n---\n\n# Built-in optimize plugin\n\nThe optimize plugin automatically identifies and optimizes all media files when\n[building your project] by using common compression and conversion techniques.\nAs a result, your site loads significantly faster and yields better rankings in\nsearch engines.\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n## Objective\n\n### How it works\n\nThe plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and\nassets, optimizing them automatically in order to reduce the final size of the\n[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you\nship less bytes to your users, as well as a smaller download for\n[offline-capable documentation].\n\nOptimized images are [intelligently cached][intelligent caching], which is why\nthe plugin will only optimize media files that changed since the last build.\nThis makes it possible to swap out or update images, without having to worry\nabout optimizing them, or even worse, forgetting to do so.\n\nIn order to optimize media files, a few [dependencies] need to be available on\nyour system.\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [dependencies]: #configuration\n\n### When to use it\n\nIt's generally recommended to use the plugin, as media files are optimized\nautomatically without the need for intervention, ensuring that your site loads\nas fast as possible. Optimized media files are one of the key components for a\nhigh and consistent ranking in search engines.\n\nAdditionally, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated\nbuild pipelines tailored to your project:\n\n\n\n- :material-shield-account: __[Built-in privacy plugin][privacy]__\n\n ---\n\n The privacy plugin makes it easy to use unoptimized external assets, passing\n them to the optimize plugin before copying them to the [`site` directory]\n [mkdocs.site_dir].\n\n ---\n\n __External media files can be automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can be distributed as a smaller `.zip` download__\n\n
\n\n [privacy]: privacy.md\n [offline]: offline.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the optimize plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and observe how\nmedia files are optimized automatically:\n\n``` yaml\nplugins:\n - optimize\n```\n\nThe optimize plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to optimize all media files, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [optimize]: optimize.md\n [built-in plugins]: index.md\n [image processing]: requirements/image-processing.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - optimize:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete media file optimization faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - optimize:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a media\nfile or asset is only passed through the optimization pipeline when its contents\nchange. If you swap out or update an image, the plugin detects it and updates\nthe optimized version of the media file.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-optimize all media files, even though the cache may not be stale. It's\nnormally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - optimize:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where media files are cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - optimize:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Optimization\n\nDocumentation often makes use of screenshots or diagrams for better\nvisualization of things, both of which are prime candidates for optimization.\nThe plugin automatically optimizes images using [pngquant] for `.png` files,\nand [Pillow] for `.jpg` files.\n\nThe following settings are available for optimization:\n\n [pngquant]: https://pngquant.org/\n [Pillow]: https://pillow.readthedocs.io/\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable media file optimization. Currently,\nthe plugin's sole purpose is to optimize media files, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the near future, other features\nmight be added. If you want to disable optimization, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.png` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.png` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the speed/quality tradeoff that [pngquant] applies\nwhen optimizing `.png` files. The lower the number, the more aggressively\n[pngquant] will try to optimize:\n\n=== \"Slower smaller \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 1\n ```\n\n=== \"Faster larger \"\n\n ``` yaml\n plugins:\n - optimize:\n optimize_png_speed: 10\n ```\n\nA factor of `10` has 5% lower quality, but is 8x faster than the default `3`.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [pngquant] should strip optional metadata\nfrom `.png` files that are not required to display the image, e.g., [EXIF].\nIf you want to preserve metadata, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_png_strip: false\n```\n\n [EXIF]: https://en.wikipedia.org/wiki/Exif\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the optimization of `.jpg` files. It's\nnormally not necessary to specify this setting, but if you want to disable\nthe optimization of `.jpg` files, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the image quality that [Pillow] applies when\noptimizing `.jpg` files. If the images look blurry, it's a good idea to\nfine-tune and change this setting:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_quality: 75\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether [Pillow] should use progressive encoding\nwhen optimizing `.jpg` files, rendering faster on slow connections. If you want\nto disable progressive encoding, use:\n\n``` yaml\nplugins:\n - optimize:\n optimize_jpg_progressive: false\n```\n\n [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339\n\n---\n\n#### \n\n\n\n\nUse this setting to enable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - optimize:\n optimize_include:\n - screenshots/*\n```\n\nThis configuration enables optimization for all media files that are contained\nin the `screenshots` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable media file optimization for specific directories\nof your project, e.g., when using [multiple instances] of the plugin to optimize\nmedia files differently:\n\n``` yaml\nplugins:\n - social:\n optimize_exclude:\n - vendor/*\n```\n\nThis configuration disables optimization for all media files that are contained\nin the `vendor` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n### Reporting\n\nThe following settings are available for reporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the number of bytes\ngained after optimizing each file. If you want to disable this behavior, use:\n\n``` yaml\nplugins:\n - optimize:\n print_gain: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should print the total number of\nbytes gained after optimizing all files. If you want to disable this behavior,\nuse:\n\n``` yaml\nplugins:\n - optimize:\n print_gain_summary: false\n```\n\n\n---\ntitle: Built-in privacy plugin\nicon: material/shield-account\n---\n\n\n# Built-in privacy plugin\n\nThe privacy plugin offers a streamlined solution for automatically self-hosting\nexternal assets. With just a single line of configuration, the plugin can\nautomatically identify and download external assets, making GDPR compliance\nas effortless as it can possibly be.\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML for external assets, i.e., scripts, style\nsheets, images, and web fonts, downloads them, stores them in the\n[`site` directory][mkdocs.site_dir] and replaces all references with links to\nthe downloaded copies for effortless self-hosting. For example:\n\n``` html\n\n```\n\nThis external script is downloaded, and the link is replaced with:\n\n``` html\n\n```\n\nOf course, scripts and style sheets can reference further external assets,\nwhich is why this process is repeated recursively until no further external\nassets are detected:\n\n- Scripts are scanned for further scripts, style sheets and JSON files\n- Style sheets are scanned for images and web fonts\n\nAdditionally, hints like [`preconnect`][preconnect], used to reduce latency when\nrequesting external assets, are removed from the output, as they're not\nnecessary when self-hosting. After the plugin has done its work, your project\nwill be free of requests to external services.\n\nThere are some [limitations].\n\n [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin was developed to make compliance with the 2018 European\n__General Data Protection Regulation__ (GDPR) as simple as possible, while\nretaining the flexibility and power that Material for MkDocs offers, like for\nexample its tight integration with [Google Fonts].\n\nBut, that's only the start. For example, if your project includes a lot of\nimages, enabling the plugin allows to move them outside of your repository, as\nthe plugin will automatically download and store them in the [`site` directory]\n[mkdocs.site_dir] when [building your project].\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-rabbit: __[Built-in optimize plugin][optimize]__\n\n ---\n\n The optimize plugin allows to optimize all downloaded external assets\n detected by the privacy plugin by using compression and conversion\n techniques.\n\n ---\n\n __External media files are automatically downloaded and optimized__\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building [offline-capable documentation],\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n
\n\n [Google Fonts]: ../setup/changing-the-fonts.md\n [building your project]: ../creating-your-site.md#building-your-site\n [optimize]: optimize.md\n [offline]: offline.md\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Configuration\n\n\n\n\n\n\nAs with all [built-in plugins], getting started with the privacy plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start\neffortlessly self-hosting external assets:\n\n``` yaml\nplugins:\n - privacy\n```\n\nThe privacy plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [privacy]: privacy.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - privacy:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete handling of external assets faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - privacy:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that external\nassets are only downloaded when they're not already contained in the cache.\nWhile the initial build might take some time, it's a good idea to use caching,\nas it will speed up consecutive builds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-schedule downloads for all external assets, even though the cache may not be\nstale. It's normally not necessary to specify this setting, except for when\ndebugging the plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - privacy:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where downloaded copies are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages when\nbuilding your site. While not being recommended, you can disable logging with:\n\n``` yaml\nplugins:\n - privacy:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot\n be created due to a lack of permissions on Windows systems (#6550).\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported, including which\n assets were successfully downloaded by the plugin.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - privacy:\n log_level: debug\n ```\n\n All messages are reported, including debug messages, if and only if MkDocs\n was started with the `--verbose` flag. Note that this will print a lot of\n messages and is only useful for debugging.\n\n### External assets\n\nThe following settings are available for external assets:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should download external\nassets. If you only want the plugin to process [external links], you can disable\nhandling of external assets with:\n\n``` yaml\nplugins:\n - privacy:\n assets: false\n```\n\n [external links]: #external-links\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should downloads or only report\nexternal assets when they're encountered. If you already self-host all external\nassets, this setting can be used as a safety net to detect links to external\nassets placed by the author in pages:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch: true\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nexternal assets are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - privacy:\n assets_fetch_dir: my/custom/dir\n```\n\nThis configuration stores the downloaded copies at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to enable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_include:\n - unsplash.com/*\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to disable downloading of external assets for specific origins,\ne.g., when using [multiple instances] of the plugin to fine-tune processing of\nexternal assets for different origins:\n\n``` yaml\nplugins:\n - privacy:\n assets_exclude: # (1)!\n - unpkg.com/mathjax@3/*\n - giscus.app/*\n```\n\n1. [MathJax] loads web fonts for typesetting of mathematical content\n through relative URLs, and thus cannot be automatically bundled by the\n privacy plugin. [MathJax can be self-hosted].\n\n [Giscus], which we recommend to use as a [comment system], uses a technique\n called code-splitting to load only the code that is necessary, which\n is implemented via relative URLs. [Giscus can be self-hosted] as well.\n\n [MathJax]: ../reference/math.md\n [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html\n [Giscus]: https://giscus.app/\n [comment system]: ../setup/adding-a-comment-system.md\n [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md\n\n---\n\n### External links\n\nThe following settings are available for external links:\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to parse and process external links to\nannotate them for [improved security], or to automatically add additional\nattributes to external links. If you want to disable processing of external\nlinks, use:\n\n``` yaml\nplugins:\n - privacy:\n links: false\n```\n\n [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/\n\n---\n\n#### \n\n\n\n\nUse this setting to specify additional attributes that should be added to\nexternal links, for example, to add `target=\"_blank\"` to all external links\nso they open in a new tab:\n\n``` yaml\nplugins:\n - privacy:\n links_attr_map:\n target: _blank\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not recommended to change this setting, as it will automatically\nannotate external links that open in a new window with `rel=\"noopener\"` for\n[improved security]:\n\n``` yaml\nplugins:\n - privacy:\n links_noopener: true\n```\n\n## Limitations\n\n### Dynamic URLs\n\nDynamically created URLs as part of scripts are not detected, and thus cannot be\ndownloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:\n\n``` js\nconst host = \"https://example.com\"\nconst path = `${host}/script.js`\n```\n\nInstead, always use fully qualified URLs:\n\n``` js\nconst url =\"https://example.com/script.js\"\n```\n\n### Embedded HTML\n\nBy default, embedded HTML files (e.g. in iframes) are not scanned for external\nassets. This is a limitation of MkDocs, as it considers `.html` files to be\ntemplates, which must be explicitly listed under\n[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets\nof an embedded HTML file:\n\n``` yaml\nextra_templates:\n - iframe.html\n```\n\nNote that the path to `iframe.html` is relative to the\n[`docs_dir`][mkdocs.docs_dir] directory.\n\n\n---\ntitle: Built-in projects plugin\nicon: material/folder-open\nstatus: deprecated\n---\n\n# Built-in projects plugin\n\nThe projects plugin adds the ability to split your main project into multiple\ndistinct projects, build them concurrently and preview them together as one.\nThis is particularly useful when creating a multi-language project, but can also\nbe used to split very large projects into smaller parts.\n\n!!! bug \"The built-in projects plugin is deprecated\"\n\n [Material for MkDocs is in maintenance mode]. The projects plugin, which was\n formerly part of the [Insiders] edition, was released in , the last release that includes all features from the Insiders edition.\n Unfortunately, the projects plugin turned out impossible to maintain, and\n was one of the key motivators to create [Zensical].\n\n ---\n\n __If you're considering the projects plugin, please be aware that known issues will not be fixed.__\n\n [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523\n [Zensical]: ../blog/posts/zensical.md\n [Insiders]: ../blog/posts/insiders-now-free-for-everyone.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the configured [`projects` directory][config.projects_dir] for\n`mkdocs.yml` files, identifies all nested projects and builds them concurrently.\nIf not configured otherwise, the plugin expects that your project has\nthe following directory layout, e.g. for a multi-language project:\n\n``` { .sh .no-copy }\n.\n├─ docs/\n├─ projects/\n│ ├─ en/\n│ │ ├─ docs/\n│ │ └─ mkdocs.yml\n│ └─ de/\n│ ├─ docs/\n│ └─ mkdocs.yml\n└─ mkdocs.yml\n```\n\nOne of the most useful and interesting features of the plugin is that it allows\n[previewing your site] from the main project, while still being able to preview\nand build each project individually. This is especially useful for\nmulti-language projects.\n\nIf, when [previewing your site], you change a file in one of the projects, the\nplugin only rebuilds this project and makes sure that MkDocs will also reload\nthe associated files. This also creates the opportunity for splitting your\nmain project into several projects for a better editing experience.\n\nThere are some [limitations], but we're working hard to remove them.\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n [limitations]: #limitations\n\n### When to use it\n\nThe plugin came into existence because we needed a convenient and scalable\nmethod to build our [examples] repository, which features many self-contained\nand runnable projects that users can download and use as a basis when\nbootstrapping a new project or [creating a reproduction].\n\nWhen you want to create a multi-language project, or have a very large existing\nproject, you might consider using the plugin, as it makes managing, editing\nand building more comfortable.\n\n [examples]: https://github.com/mkdocs-material/examples\n [creating a reproduction]: ../guides/creating-a-reproduction.md\n\n## Configuration\n\n\n\n\n\nIn order to get started with the projects plugin, just add the following lines\nto `mkdocs.yml`, and split your main project into several distinct projects that\ncan be built concurrently:\n\n``` yaml\nplugins:\n - projects\n```\n\nThe projects plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [projects]: projects.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\nbuild projects faster. If you want to disable concurrent processing completely,\nuse:\n\n``` yaml\nplugins:\n - projects:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that a\nproject is only rebuilt when its contents change. While the initial build might\ntake some time, it's a good idea to use caching, as it will speed up consecutive\nbuilds.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nrebuild all projects, even though the cache may not be stale. It's normally not\nnecessary to specify this setting, except for when debugging the plugin itself.\nCaching can be disabled with:\n\n``` yaml\nplugins:\n - projects:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where the metadata is cached.\nIf you want to change it, use:\n\n``` yaml\nplugins:\n - projects:\n cache_dir: my/custom/dir\n```\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should display log messages from\nprojects when building your site. While not being recommended, you can disable\nlogging with:\n\n``` yaml\nplugins:\n - projects:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`error`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: error\n ```\n\n Only errors are reported.\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: warn\n ```\n\n Errors and warnings are reported, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: info\n ```\n\n Errors, warnings and informational messages are reported.\n\n=== \"`debug`\"\n\n ``` yaml\n plugins:\n - projects:\n log_level: debug\n ```\n\n All messages are reported, including debug messages.\n\n### Projects\n\nThe following settings are available for projects:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable building of projects. Currently, the\nplugin's sole purpose is to build projects, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable building of projects, use:\n\n``` yaml\nplugins:\n - projects:\n projects: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the folder where your projects are located. It's\nnormally not necessary to change this setting, but if you want to rename the\nfolder or change its file system location, use:\n\n``` yaml\nplugins:\n - projects:\n projects_dir: projects\n```\n\nNote that the [`projects` directory][config.projects_dir] is solely used for\nproject organization – it is not included in project URLs, since projects are\nautomatically hoisted by the plugin.\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this setting to change the location or name of configuration files the\nplugin will look for when scanning the [`projects` directory]\n[config.projects_dir]. Adjusting this setting can be necessary when the\nconfiguration files are located in subdirectories of projects, e.g.\n`docs/mkdocs.yml`:\n\n``` yaml\nplugins:\n - projects:\n projects_config_files: \"**/mkdocs.yml\" # (1)!\n```\n\n1. If all projects share the same location for their configuration files, e.g.,\n `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster\n to resolve than a `**` glob pattern.\n\n ``` yaml\n plugins:\n - projects:\n projects_config_files: \"*/docs/mkdocs.yml\"\n ```\n\n This configuration fits the following directory structure, which is quite\n common for projects using git submodules:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n ├─ projects/\n │ ├─ git-submodule-a/\n │ │ └─ docs/\n │ │ └─ mkdocs.yml\n │ └─ git-submodule-b/\n │ └─ docs/\n │ └─ mkdocs.yml\n └─ mkdocs.yml\n ```\n\nThe provided path is resolved from the [`projects` directory]\n[config.projects_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to transform the configuration of each project as read from\n`mkdocs.yml` before it is built, which allows for adjusting the configuration\nof each project when building them together, but leave them untouched when\nbuilding them individually:\n\n``` yaml\nplugins:\n - projects:\n projects_config_transform: !!python/name:projects.transform\n```\n\nThe provided module and function name are looked up in Python's [module search\npath]. You need to add your root directory to the search path when building\nyour site, so Python can resolve it. The easiest way is to add the working\ndirectory to the [`PYTHONPATH`][PYTHONPATH] environment variable:\n\n``` .sh\nexport PYTHONPATH=.\n```\n\n!!! tip \"How to define a configuration transformation function\"\n\n The [`python/name`][python-name] tag is provided by [PyYAML] and must point\n to a valid module and function name within Python's [module search path].\n The plugin passes the `project` and top-level `config` objects to the\n function.\n\n As an example, we can inherit the [`use_directory_urls`]\n [mkdocs.use_directory_urls] setting for all projects from the top-level\n configuration:\n\n ``` py title=\"projects/__init__.py\"\n from mkdocs.config.defaults import MkDocsConfig\n\n # Transform project configuration\n def transform(project: MkDocsConfig, config: MkDocsConfig):\n project.use_directory_urls = config.use_directory_urls\n ```\n\n [module search path]: https://docs.python.org/3/library/sys_path_init.html\n [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH\n [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types\n [PyYAML]: https://pyyaml.org/\n\n### Hoisting\n\nThe following settings are available for hoisting:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable hoisting of themes files to the main\nproject. If you disable this setting, each project receives a copy of the\ntheme's files, which can be considered redundant:\n\n``` yaml\nplugins:\n - projects:\n hoisting: false\n```\n\nIt's generally advisable to enable hoisting, as it yields faster deployments\nand faster loading of your project's sites, because the files are the same for\nall projects and can be deduplicated.\n\n### Limitations\n\nThe plugin is one of the latest additions to Material for MkDocs, which means it\nis rather young and has some limitations. We're working hard to remove them, and\nwe're happy to receive feedback and learn about your requirements in ?5800.\nCurrent limitations are:\n\n- __Basic multi-language support only__: we'll be investigating how to provide\n better support for multi-language projects, allowing to easier interlink\n projects and switch between them.\n\n- __Separate search indexes and sitemaps__: currently, the projects are entirely\n separate, which means they will have separate search indexes and sitemaps.\n\n\n# Requirements Skill\n\nPath: `docs/plugins/requirements/caching.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/caching.md)\n\n\n# Requirements Skill\n\nPath: `docs/plugins/requirements/image-processing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/requirements/image-processing.md)\n\n\n---\ntitle: Built-in search plugin\nicon: material/magnify\n---\n\n# Built-in search plugin\n\nThe search plugin adds a search bar to the header, allowing users to search your\ndocumentation. It's powered by [lunr.js], a lightweight full-text search engine\nfor the browser, elimininating the need for external services, and even works\nwhen building [offline-capable documentation].\n\n [lunr.js]: https://lunrjs.com/\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n\n## Objective\n\n### How it works\n\nThe plugin scans the generated HTML and builds a search index from all pages and\nsections by extracting the section titles and contents. It preserves some inline\nformatting like code blocks and lists, but removes all other formatting, so the\nsearch index is as small as possible.\n\nWhen a user visits your site, the search index is shipped to the browser,\nindexed with [lunr.js] and made available for fast and simple querying – no\nserver needed. This ensures that the search index is always up to date with\nyour documentation, yielding accurate results.\n\n### When to use it\n\nIt's generally recommended to use the plugin, as interactive search functionality\nis a vital part of every good documentation. Additionally, the plugin integrates\nperfectly with several of the other [built-in plugins] that Material for MkDocs\noffers:\n\n\n\n- :material-connection: __[Built-in offline plugin][offline]__\n\n ---\n\n The offline plugin adds support for building offline-capable documentation,\n so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`\n file that can be downloaded.\n\n ---\n\n __Your documentation can work without connectivity to the internet__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it easy to [boost][meta.search.boost] specific\n sections in search results or to [exclude][meta.search.exclude] them\n entirely from being indexed, giving more granular control over search.\n\n ---\n\n __Simpler organization and management of search in different subsections__\n\n
\n\n [offline]: offline.md\n [meta]: meta.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\nAs with all [built-in plugins], getting started with the search plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and your users\nwill be able to search your documentation:\n\n``` yaml\nplugins:\n - search\n```\n\nThe search plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [search]: search.md\n [built-in plugins]: index.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - search:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Search\n\nThe following settings are available for search:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the language of the search index, enabling [stemming]\nsupport for other languages than English. The default value is automatically\ncomputed from the [site language], but can be explicitly set to another language\nor even multiple languages with:\n\n=== \"Set language\"\n\n ``` yaml\n plugins:\n - search:\n lang: en\n ```\n\n=== \"Add further languages\"\n\n ``` yaml\n plugins:\n - search:\n lang: # (1)!\n - en\n - de\n ```\n\n 1. Be aware that including support for further languages increases the\n base JavaScript payload by around 20kb and by another 15-30kb per\n language, all before `gzip`.\n\n [stemming]: https://en.wikipedia.org/wiki/Stemming\n [site language]: ../setup/changing-the-language.md#site-language\n [lunr languages]: https://github.com/MihaiValentin/lunr-languages\n\nLanguage support is provided by [lunr languages], a collection of\nlanguage-specific stemmers and stop words for [lunr.js] maintained by the\nOpen Source community.\n\n---\n\nThe following languages are currently supported by [lunr languages]:\n\n\n\n- `ar` – Arabic\n- `da` – Danish\n- `de` – German\n- `du` – Dutch\n- `en` – English\n- `es` – Spanish\n- `fi` – Finnish\n- `fr` – French\n- `hi` – Hindi\n- `hu` – Hungarian\n- `hy` – Armenian\n- `it` – Italian\n- `ja` – Japanese\n- `kn` - Kannada\n- `ko` – Korean\n- `no` – Norwegian\n- `pt` – Portuguese\n- `ro` – Romanian\n- `ru` – Russian\n- `sa` – Sanskrit\n- `sv` – Swedish\n- `ta` – Tamil\n- `te` – Telugu\n- `th` – Thai\n- `tr` – Turkish\n- `vi` – Vietnamese\n- `zh` – Chinese\n\n
\n\nIf [lunr languages] doesn't provide support for the selected [site language],\nthe plugin falls back to another language that yields the best stemming results.\nIf you discover that the search results are not satisfactory, you can contribute\nto [lunr languages] by adding support for your language.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the separator used to split words when building the\nsearch index on the client side. The default value is automatically computed\nfrom the [site language], but can also be explicitly set to another value with:\n\n``` yaml\nplugins:\n - search:\n separator: '[\\s\\-,:!=\\[\\]()\"/]+|(?!\\b)(?=[A-Z][a-z])|\\.(?!\\d)|&[lg]t;'\n```\n\nSeparators support [positive and negative lookahead assertions], which allows\nfor rather complex expressions that yield precise control over how words are\nsplit when building the search index.\n\nBroken into its parts, this separator induces the following behavior:\n\n=== \"Special characters\"\n\n ```\n [\\s\\-,:!=\\[\\]()\"/]+\n ```\n\n The first part of the expression inserts token boundaries for each\n document before and after whitespace, hyphens, commas, brackets and\n other special characters. If several of those special characters are\n adjacent, they are treated as one.\n\n=== \"Case changes\"\n\n ```\n (?!\\b)(?=[A-Z][a-z])\n ```\n\n Many programming languages have naming conventions like `PascalCase` or\n `camelCase`. By adding this subexpression to the separator,\n [words are split at case changes], tokenizing the word `PascalCase`\n into `Pascal` and `Case`.\n\n=== \"Version strings\"\n\n ```\n \\.(?!\\d)\n ```\n\n When adding `.` to the separator, version strings like `1.2.3` are split\n into `1`, `2` and `3`, which makes them undiscoverable via search. When\n using this subexpression, a small lookahead is introduced which will\n [preserve version strings] and keep them discoverable.\n\n=== \"HTML/XML tags\"\n\n ```\n &[lg]t;\n ```\n\n If your documentation includes HTML/XML code examples, you may want to allow\n users to find [specific tag names]. Unfortunately, the `<` and `>` control\n characters are encoded in code blocks as `<` and `>`. Adding this\n subexpression to the separator allows for just that.\n\n [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html\n [words are split at case changes]: ?q=searchHighlight\n [preserve version strings]: ?q=9.0.0\n [specific tag names]: ?q=script\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify the [pipeline functions] that are used to filter and\nexpand tokens after tokenizing them with the [`separator`][config.separator] and\nbefore adding them to the search index. The default value is automatically\ncomputed from the [site language], but can also be explicitly set with:\n\n``` yaml\nplugins:\n - search:\n pipeline:\n - stemmer\n - stopWordFilter\n - trimmer\n```\n\nThe following pipeline functions can be used:\n\n- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`\n- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.\n- `trimmer` – Trim whitespace from tokens\n\n [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions\n\n### Segmentation\n\nThe plugin supports text segmentation of Chinese via [jieba], a popular\nChinese text segmentation library. Other languages like Japanese and Korean are\ncurrently segmented on the client side, but we're considering to move this\nfunctionality into the plugin in the future.\n\nThe following settings are available for segmentation:\n\n [jieba]: https://pypi.org/project/jieba/\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify a [custom dictionary] to be used by [jieba] for\nsegmenting text, replacing the default dictionary. [jieba] comes with\nseveral dictionaries, which can be used with:\n\n``` yaml\nplugins:\n - search:\n jieba_dict: dict.txt\n```\n\nThe following dictionaries are provided by [jieba]:\n\n- [dict.txt.small] – 占用内存较小的词典文件\n- [dict.txt.big] – 支持繁体分词更好的词典文件\n\nThe provided path is resolved from the root directory.\n\n [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8\n [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small\n [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big\n\n---\n\n#### \n\n\n\n\n\nUse this setting to specify an additional [user dictionary] to be used by\n[jieba] for segmenting text, augmenting the default dictionary. User\ndictionaries are ideal for tuning the segmenter:\n\n``` yaml\nplugins:\n - search:\n jieba_dict_user: user_dict.txt\n```\n\nThe provided path is resolved from the root directory.\n\n [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to increase or decrease the relevance of a page in the search\nresults, giving more weight to them. Use values above `1` to rank up and values\nbelow `1` to rank down:\n\n=== \":material-arrow-up-circle: Rank up\"\n\n ``` yaml\n ---\n search:\n boost: 2 # (1)!\n ---\n\n # Page title\n ...\n ```\n\n 1. When boosting pages, always start with low values.\n\n=== \":material-arrow-down-circle: Rank down\"\n\n ``` yaml\n ---\n search:\n boost: 0.5\n ---\n\n # Page title\n ...\n ```\n\n---\n\n#### \n\n\n\n\n\nUse this property to exclude a page from the search results. Note that this will\nnot only remove the page, but also all subsections of the page from the search\nresults:\n\n``` yaml\n---\nsearch:\n exclude: true\n---\n\n# Page title\n...\n```\n\n\n---\ntitle: Built-in social plugin\nicon: material/share-circle\n---\n\n# Built-in social plugin\n\nThe social plugin automatically and intelligently generates beautiful and highly\ncustomizable social cards in different [layouts][default layouts] for each page\nof your project, rendering as preview images whenever you or somebody else share\na link to your project on social media.\n\n## Objective\n\n### How it works\n\nThe plugin automatically generates a customizable social card for each page\nof your project, which appears as a preview image when sharing a link to your\nproject on social media, without the use of external services and just\n[a single line of configuration][configuration].\n\nWith the use of an efficient [image processing] library, the plugin allows to\ndefine [custom layouts] for social cards, which can be adapted to match your\nproject's style and branding. While it would technically be much simpler to\ngenerate social cards by using a web browser and an automation framework like\n[Puppeteer][^1], it would add further liabilities to your toolchain, with the\npotential to make build pipelines more complex, much more resource intense,\nand significantly slower.\n\n [^1]:\n [GitHub wrote in their blog] that they use [Puppeteer] to generate social\n card images for repositories, issues, commits, discussions, and basically\n everything else that appear as preview images when shared on social media.\n\nThe generated social cards are [cached] and stored in the\n[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your\nproject doesn't depend on external services. In order to generate social cards\nimages, a few [dependencies] need to be available on your system.\n\n [configuration]: #configuration\n [image processing]: requirements/image-processing.md\n [custom layouts]: ../setup/setting-up-social-cards.md#customization\n [Puppeteer]: https://github.com/puppeteer/puppeteer\n [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/\n [cached]: #caching\n [dependencies]: #configuration\n\n### When to use it\n\nThere's one particular case when we don't recommend to use the plugin: when you\nbuild [offline-capable documentation] to offer it as a download. Otherwise, it\nalways makes sense to enable the plugin, as links to your documentation shared\non social media will appear much more appealing.\n\nEven more interestingly, the plugin can be combined with other built-in plugins\nthat Material for MkDocs offers, in order to create sophisticated build\npipelines tailored to your project:\n\n\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The social plugin automatically generates beautiful and customizable\n social cards for each post and page, showing as previews on social media.\n\n ---\n\n __Links to your blog render beautiful social cards when shared on social media__\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin can be used to [change the layout][meta.social.cards_layout]\n for social cards or [change specific layout options]\n [meta.social.cards_layout_options] like [background][option.background_color]\n or [color][option.color] for a subset of pages.\n\n ---\n\n __Your documentation can use completely different social cards per section__\n\n
\n\n [offline-capable documentation]: ../setup/building-for-offline-usage.md\n [blog]: blog.md\n [meta]: meta.md\n\n## Configuration\n\n\n\n\n\n\nIn order to get started with the social plugin, just add the following lines to\n`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social\ncards for you:\n\n``` yaml\nplugins:\n - social\n```\n\nThe social plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\nHowever, in order to generate social card images, it's necessary to install the\ndependencies for [image processing], if they're not already available on your\nsystem. The linked guide includes instructions for several operating systems\nand mentions some alternative environments.\n\n [social]: social.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIf you want to disable the plugin, e.g., for local builds, you can use an\n[environment variable][mkdocs.env] in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - social:\n enabled: !ENV [CI, false]\n```\n\nThis configuration enables the plugin only during continuous integration (CI).\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n---\n\n#### \n\n\n\n\nWith more CPUs available, the plugin can do more work in parallel, and thus\ncomplete social card generation faster. If you want to disable concurrent\nprocessing completely, use:\n\n``` yaml\nplugins:\n - social:\n concurrency: 1\n```\n\nBy default, the plugin uses all available CPUs - 1 with a minimum of 1.\n\n### Caching\n\nThe plugin implements an [intelligent caching] mechanism, ensuring that social\ncards are only regenerated when their contents change or they're not already\ncontained in the cache. If any of the variables used in a layout changes, the\nplugin detects it and regenerates the social card.\n\nThe following settings are available for caching:\n\n [intelligent caching]: requirements/caching.md\n\n---\n\n#### \n\n\n\n\nUse this setting to instruct the plugin to bypass the cache, in order to\nre-generate social cards for all pages, even though the cache may not be stale.\nIt's normally not necessary to specify this setting, except for when debugging\nthe plugin itself. Caching can be disabled with:\n\n``` yaml\nplugins:\n - social:\n cache: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within your root directory where social card images are\ncached. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cache_dir: my/custom/dir\n```\n\nIf you're using [multiple instances] of the plugin, it can be a good idea to\nset different cache directories for both instances, so that they don't interfere\nwith each other.\n\n [multiple instances]: index.md#multiple-instances\n\n### Logging\n\nThe following settings are available for logging:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should only log errors when\ngenerating social cards without terminating the build, e.g., invalid references\nto icons. To terminate the build, use:\n\n``` yaml\nplugins:\n - social:\n log: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to control the log level that the plugin should employ when\nencountering errors, which requires that the [`log`][config.log] setting is\nenabled. The following log levels are available:\n\n=== \"`warn`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: warn\n ```\n\n Errors are reported as warnings, terminating the build in\n [`strict`][mkdocs.strict] mode.\n\n=== \"`info`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: info\n ```\n\n Errors are only reported as informational messages.\n\n=== \"`ignore`\"\n\n ``` yaml\n plugins:\n - social:\n log_level: ignore\n ```\n\n Errors are only reported when using the `--verbose` flag.\n\n### Social cards\n\nThe following settings are available for social card generation:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable social card generation. Currently, the\nplugin's sole purpose is to generate social cards, so it's equivalent to the\n[`enabled`][config.enabled] setting, but in the future, other features might be\nadded. If you want to disable social card generation, use:\n\n``` yaml\nplugins:\n - social:\n cards: false\n```\n\n---\n\n#### \n\n\n\n\nIt is normally not necessary to specify this setting, except for when you want\nto change the path within the [`site` directory][mkdocs.site_dir] where\nsocial cards are stored. If you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n cards_dir: my/custom/dir\n```\n\nThis configuration stores the generated images at `my/custom/dir` in the\n[`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nIf you want to build a [custom social card layout][custom layouts], use this\nsetting to change the folder where you store your custom layouts, the default\nbeing a folder called `layouts` in your root directory:\n\n``` yaml\nplugins:\n - social:\n cards_layout_dir: layouts\n```\n\nThe provided path is resolved from the root directory.\n\n!!! tip \"Where to store custom layouts\"\n\n Our recommendation is to locate the folder outside of the\n [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]\n are not copied to the [`site` directory][mkdocs.site_dir] when\n [building your project], e.g., by adhering to the following directory\n layout:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ *.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nThe plugin ships a growing list of [`default` layouts][default layouts] for\nsocial cards. If you've created a [custom social card layout][custom layouts],\nyou can instruct the plugin to use it exactly as one of the included layouts:\n\n``` yaml\nplugins:\n - social:\n cards_layout: my-custom-layout\n```\n\nThe provided path is resolved from the[\n`layouts` directory][config.cards_layout_dir].\n\n!!! tip \"How custom layouts are resolved\"\n\n By default, the plugin will load your [custom layouts] from a folder named\n `layouts` in your root directory. If your layout is called\n `my-custom-layout`, the directory layout must adhere to:\n\n ``` { .sh .no-copy }\n .\n ├─ docs/\n │ └─ *.md\n ├─ layouts/\n │ └─ my-custom-layout.yml\n └─ mkdocs.yml\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to set options for the layout specified via [`cards_layout`]\n[config.cards_layout] (if the layout supports it), which allows for making\nlayouts easily and entirely configurable:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n : \n```\n\nWhen creating a [custom layout][custom layouts], you are completely free in\ndefining which parts of your layout can be parametrized. The [`default` layouts]\n[default layouts] included with the plugin support the following options:\n\n\n\n- [`background_color`][option.background_color]\n- [`background_image`][option.background_image]\n- [`color`][option.color]\n- [`font_family`][option.font_family]\n- [`font_variant`][option.font_variant]\n- [`logo`][option.logo]\n- [`title`][option.title]\n- [`description`][option.description]\n\n
\n\n\n [default layouts]: #layouts\n\n---\n\n#### \n\n\n\n\nUse this setting to enable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_include:\n - blog/*\n```\n\nThis configuration enables social card generation for all pages that are\ncontained in the `blog` folder and its subfolders inside the [`docs` directory]\n[mkdocs.docs_dir].\n\n---\n\n#### \n\n\n\n\nUse this setting to disable social card generation for subsections of your\nproject, e.g., when using [multiple instances] of the plugin to generate\ndifferent social cards for different subsections:\n\n``` yaml\nplugins:\n - social:\n cards_exclude:\n - changelog/*\n```\n\nThis configuration disables social card generation for all pages that are\ncontained in the `changelog` folder and its subfolders inside the\n[`docs` directory][mkdocs.docs_dir].\n\n### Debugging\n\nThe plugin includes a special mode for debugging layouts, which is very useful\nwhen creating [custom layouts], as it allows for quicker iteration and better\nunderstanding of composition.\n\nThe following settings are available for debugging:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable a special mode for debugging your layout, which\nrenders each layer with a colored outline and its `x` and `y` offsets, and\noverlays a dot grid for alignment, so it's easier to understand how the\ndistinct layers of your layout are composed together:\n\n``` yaml\nplugins:\n - social:\n debug: true\n```\n\n---\n\n#### \n\n\n\n\nBy default, the plugin automatically disables [`debug`][config.debug] mode when\n[building your project], so you can be sure that debug overlays are never\ndeployed to production. If you want to change that, use:\n\n``` yaml\nplugins:\n - social:\n debug_on_build: true\n```\n\nIt's normally not necessary to change this setting, as it's just intended to\nbe a safety net.\n\n---\n\n#### \n\n\n\n\nWhen [`debug`][config.debug] mode is enabled, this setting specifies whether a\ndot grid is rendered on top of all layers, to allow for better alignment. If you\nwant to switch the grid off, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid: false\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the step size of the dot grid in pixels, if enabled,\nwhich can be useful to create perfectly aligned layers for ideal composition.\nIt you want to change it, use:\n\n``` yaml\nplugins:\n - social:\n debug_grid_step: 64\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify the color of the outlines that are added to each\nlayer and the dot grid that is rendered on top of all layers. If you need to\nchange it, use:\n\n``` yaml\nplugins:\n - social:\n debug_color: yellow\n```\n\nIn rare cases, it might be necessary to change this setting if the dot grid or\nthe outlines are hard to distinguish, as the plugin will automatically adjust\nthe color if not explicitly set.\n\n## Usage\n\n### Metadata\n\nThe plugin allows to override a subset of settings through metadata (front\nmatter) in order to customize social card generation, e.g., to set [options for\nthe included `default` layouts][default layouts] for a single page, or even\n[for an entire subsection] of your project by leveraging the [meta] plugin.\n\nThe following properties are available:\n\n [for an entire subsection]: meta.md#how-it-works\n [meta]: meta.md\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards`][config.cards] setting for the given\npage:\n\n``` yaml\n---\nsocial:\n cards: false\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\n\nUse this property to override the [`cards_layout`][config.cards_layout] setting\nfor the given page:\n\n``` yaml\n---\nsocial:\n cards_layout: my-custom-layout\n---\n\n# Page title\n...\n```\n\n---\n\n#### \n\n\n\n\n\nUse this property to override the [`cards_layout_options`]\n[config.cards_layout_options] setting for the given page:\n\n``` yaml\n---\nsocial:\n cards_layout_options:\n background_color: blue # Change background color\n background_image: null # Remove background image\n---\n\n# Page title\n...\n```\n\nSetting an option to `#!yaml null` resets the option.\n\n### Layouts\n\n\n\nWhile it is possible and simple to build [custom layouts], the plugin ships\nseveral predefined layouts, all of which are prefixed with `default`. The\nfollowing layouts are included:\n\n=== \"`default`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default\n ```\n\n \n\n ![Layout default]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/variant`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/variant\n ```\n\n \n\n ![Layout default variant]\n\n This layout includes the [page icon] and sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/accent`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/accent\n ```\n\n \n\n ![Layout default accent]\n\n This layout sets the following defaults:\n\n - [`background_color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/invert`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/invert\n ```\n\n \n\n ![Layout default invert]\n\n This layout sets the following defaults:\n\n - [`color`][option.background_color]\n – \n\n - [`font_family`][option.font_family]\n – \n\n
\n\n=== \"`default/only/image`\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout: default/only/image\n cards_layout_options:\n background_image: layouts/background.png\n\n ```\n\n \n\n This layout only shows the given background image and scales it to cover.\n\n
\n\nThe [`default` layouts][default layouts] are very flexible and comfortable to\nuse, as they replicate the original behavior of the plugin, sourcing default\nvalues for all options from other `theme` settings.\n\nThe following options are available:\n\n [Layout default]: ../assets/screenshots/social-cards.png\n [Layout default variant]: ../assets/screenshots/social-cards-variant.png\n [Layout default accent]: ../assets/screenshots/social-cards-accent.png\n [Layout default invert]: ../assets/screenshots/social-cards-invert.png\n\n [primary color]: ../setup/changing-the-colors.md#primary-color\n [page icon]: ../reference/index.md#setting-the-page-icon\n [accent color]: ../setup/changing-the-colors.md#accent-color\n [font]: ../setup/changing-the-fonts.md#regular-font\n\n---\n\n#### \n\n\n\n\nUse this option to change the background color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: \"#ff1493\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: rgb(255, 20, 147) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_color: deeppink # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\nIf this options is used together with [`background_image`]\n[option.background_image], the color is rendered on top of the image which\nallows for tinting images. If you want to remove the background color, use:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n background_color: transparent\n```\n\n [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names\n [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color\n\n---\n\n#### \n\n\n\n\nUse this option to define a background image for the generated social card. Note\nthat the image is tinted with the [`background_color`][option.background_color],\nwhich can also be set to `transparent`:\n\n=== \"Image\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: transparent\n ```\n\n=== \"Image with tint\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n background_image: layouts/background.png\n background_color: \"#ff149366\"\n ```\n\nThe provided path is resolved from the root directory.\n\n---\n\n#### \n\n\n\n\nUse this option to change the foreground color of the generated social card.\nThe value can be set to a valid color value [supported by pillow], the imaging\nlibrary used for card generation:\n\n=== \"Hexadecimal\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: \"#ffffff\" # (1)!\n ```\n\n 1. The following notations are supported, whereas each character after the\n `#` must be a valid hexadecimal in the range `#!css 0-F`:\n\n - `#!css #rgb` – Color (short)\n - `#!css #rgba` – Color + alpha (short)\n - `#!css #rrggbb` – Color\n - `#!css #rrggbbaa` – Color + alpha\n\n=== \"Color function\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: rgb(255, 255, 255) # (1)!\n ```\n\n 1. The following functions are supported, listing the allowed maximum\n values with the minimum values all being `#!css 0` or `#!css 0%`:\n\n - `#!css rgb(255, 255, 255)` – Red, green and blue\n - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness\n - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value\n\n=== \"Color name\"\n\n ``` yaml\n plugins:\n - social:\n cards_layout_options:\n color: white # (1)!\n ```\n\n 1. See the [``][named-color] CSS data type for a list of\n supported color names. Note that some might not be available.\n\n---\n\n#### \n\n\n\n\nUse this option to change the font family of the generated social card. The\nplugin automatically downloads the font from [Google Fonts], so the font must\npoint to an existing Google Font:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_family: Ubuntu\n```\n\nWhen you've found a font that you like on [Google Fonts], you can just copy the\nname from the font's specimen page and use it as the value for this option –\nno further configuration needed.\n\n [Google Fonts]: https://fonts.google.com/\n\n---\n\n#### \n\n\n\n\nUse this option to change the font variant used to generate the social card.\nIf the downloaded font has variants like `Condensed` or `Expanded`, you can set\nthem with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n font_variant: Condensed\n```\n\nThe variant is combined with the style as used in the custom layout, so the\nplugin is instructed to use combinations like `Condensed Regular` or\n`Expanded Bold`.\n\n---\n\n#### \n\n\n\n\nUse this option to change the logo that is used in the generated social card.\nBy default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]\n[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n logo: layouts/logo.png\n```\n\nThe provided path is resolved from the root directory.\n\n [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image\n [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled\n\n---\n\n#### \n\n\n\n\nUse this option to change the title of the generated social card. This overrides\nthe computed page title as assigned by MkDocs, as well as the [`title`]\n[meta.title] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n title: My custom title\n```\n\n [meta.title]: ../reference/index.md#setting-the-page-title\n\n---\n\n#### \n\n\n\n\nUse this option to change the description of the generated social card. This\noverrides the set [`site_description`][mkdocs.site_description], if defined, as\nwell as the [`description`][meta.description] metadata property:\n\n``` yaml\nplugins:\n - social:\n cards_layout_options:\n description: My custom description\n```\n\n [meta.description]: ../reference/index.md#setting-the-page-description\n\n---\n\n!!! question \"Missing something?\"\n\n When setting up social cards, you might discover that you're missing\n specific functionality – we're happy to consider adding it to the plugin!\n You can [open a discussion] to ask a question, or create a [change request]\n on our [issue tracker], so we can find out if it might be a good fit for\n the plugin.\n\n [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions\n [change request]: ../contributing/requesting-a-change.md\n [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues\n\n\n---\ntitle: Built-in tags plugin\nicon: material/tag-text\n---\n\n# Built-in tags plugin\n\nThe tags plugin adds first-class support for categorizing pages with the use\nof tags, adding the possibility to group related pages and make them\ndiscoverable via search and dedicated tags indexes. If your documentation is\nlarge, tags can help to discover relevant information faster.\n\n## Objective\n\n### How it works\n\nThe plugin scans all pages for the [`tags`][meta.tags] metadata property and\ngenerates a tags index, which is an inverted list of tags and the pages they\nappear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],\nallowing for maximum flexibility when adding tags to your project.\n\n### When to use it\n\nIf you want to add one or multiple tags indexes to your project, the tags\nplugin is a perfect choice as it makes this process ridiculously simple.\nAdditionally, it integrates perfectly with several of the other\n[built-in plugins] that Material for MkDocs offers:\n\n\n\n- :material-file-tree: __[Built-in meta plugin][meta]__\n\n ---\n\n The meta plugin makes it possible to ensure that subsections of your\n project are annotated with [specific tags][meta.tags], so they can't be\n forgotten when adding pages.\n\n ---\n\n __Simpler organization and management of tags in different subsections__\n\n- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__\n\n ---\n\n The tags plugin allows to categorize posts alongside with pages in your\n project, to improve their discoverability and connect posts to your\n documentation.\n\n ---\n\n __Your documentation's tag system integrates with your blog__\n\n
\n\n [meta]: meta.md\n [blog]: blog.md\n [built-in plugins]: index.md\n\n## Configuration\n\n\n\n\n\nAs with all [built-in plugins], getting started with the tags plugin is\nstraightforward. Just add the following lines to `mkdocs.yml`, and start using\n[tags][meta.tags] to categorize your pages:\n\n``` yaml\nplugins:\n - tags\n```\n\nThe tags plugin is built into Material for MkDocs and doesn't need to be\ninstalled.\n\n [tags]: tags.md\n\n### General\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable the plugin when [building your project].\nIt's normally not necessary to specify this setting, but if you want to disable\nthe plugin, use:\n\n``` yaml\nplugins:\n - tags:\n enabled: false\n```\n\n [building your project]: ../creating-your-site.md#building-your-site\n\n### Tags\n\nThe following settings are available for tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable rendering of tags. The plugin still\nextracts tags from all pages, e.g., for [exporting tags] without rendering them.\nRendering can be disabled with:\n\n``` yaml\nplugins:\n - tags:\n tags: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\n!!! warning \"This setting is deprecated\"\n\n As of version , this setting is deprecated, as this\n version ships a __ground up rewrite of the tags plugin__ which is much more\n powerful than the previous version. Tags [listings] can be used on any page\n now.\n\n\n\nUse this setting to specify the location of the tags index, which is the page\nused to render a list of all tags and their associated pages. If this setting is\nspecified, tags become clickable, pointing to the corresponding section in the\ntags index:\n\n``` yaml\nplugins:\n - tags:\n tags_file: tags.md\n```\n\nThe page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]\nsection of `mkdocs.yml`. This setting is not required – you should only use it\nif you want to have a tags index.\n\nThe provided path is resolved from the [`docs` directory][mkdocs.docs_dir].\n\n
\n\n [listings]: ../setup/setting-up-tags.md#adding-a-tags-index\n\n---\n\n#### \n\n\n\n\nUse this setting to change the function for generating URL-compatible slugs\nfrom post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function\nfrom [Python Markdown Extensions] is used as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify: !!python/object/apply:pymdownx.slugs.slugify\n kwds:\n case: lower\n```\n\nThe default configuration is Unicode-aware and should produce good slugs for all\nlanguages. Of course, you can also provide a custom slugification function for\nmore granular control.\n\n [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65\n [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/\n\n---\n\n#### \n\n\n\n\nUse this setting to change the separator that is passed to the slugification\nfunction set as part of [`tags_slugify`][config.tags_slugify]. While the default\nis a hyphen, it can be set to any string, e.g., `_`:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_separator: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the format string that is used when generating tag\nslugs. It is a good idea to prefix tag slugs with a string that makes them\nunique, the default being:\n\n``` yaml\nplugins:\n - tags:\n tags_slugify_format: \"tag:{slug}\"\n```\n\nThe following placeholders are available:\n\n- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]\n\n---\n\n#### \n\n\n\n\n\nUse this setting to enable support for tag hierarchies (nested tags, e.g.,\n`foo/bar`). If you intend to create hierarchical listings of tags, you can\nenable this setting in `mkdocs.yml` with:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy: true\n```\n\n---\n\n#### \n\n\n\n\n\nUse this setting to change the separator that is used when creating tag\nhierarchies. By default, tags are separated by a forward slash `/`, but you\ncan change this to any string, e.g., `.`:\n\n``` yaml\nplugins:\n - tags:\n tags_hierarchy_separator: .\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags. By default,\ntag comparison is case-sensitive, but you can use `tag_name_casefold` for\ncase-insensitive comparison:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the front matter property that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_property: tags\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the template variable that is used by\nthe plugin. It is normally not necessary to change this setting, but if you want\nto change it, you can use:\n\n``` yaml\nplugins:\n - tags:\n tags_name_variable: tags\n```\n\n---\n\n#### \n\n\n\n\nThe plugin allows to check tags against a predefined list, in order to catch\ntypos or make sure that tags are not arbitrarily added. Specify the tags you\nwant to allow with:\n\n``` yaml\nplugins:\n - tags:\n tags_allowed:\n - HTML5\n - JavaScript\n - CSS\n```\n\nThe plugin stops the build if a page references a tag that is not part of\nthis list. Pages can be assigned to tags by using the [`tags`][meta.tags]\nmetadata property.\n\n### Listings\n\nThe following settings are available for listings:\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable listings. It is normally not necessary to\nchange this setting, as listings are created entirely by inline comments, but\nyou can disable them if necessary with:\n\n``` yaml\nplugins:\n - tags:\n listings: false\n```\n\nThis setting is automatically disabled if [`export_only`][config.export_only]\nis enabled.\n\n [exporting tags]: #export\n\n---\n\n#### \n\n\n\n\nUse this define listing configurations that you can then reference in listings\nwith a custom identifier. Sharing configurations is a good idea, especially\nwhen you have many tag listings:\n\n``` yaml\nplugins:\n - tags:\n listings_map:\n custom-id:\n scope: true\n exclude: Internal\n```\n\nThen, just reference the listing identifier:\n\n``` html\n\n```\n\nSee the [listings section] for a list of all available settings.\n\n [listings section]: #listing-configuration\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing listing items. By\ndefault, items are ordered by their titles, but you can change the sorting\ncriterion with the following configuration:\n\n=== \"Sort by item title\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_title\n ```\n\n=== \"Sort by item URL\"\n\n ``` yaml\n plugins:\n - tags:\n listings_sort_by: !!python/name:material.plugins.tags.item_url\n ```\n\nYou can also define your own comparison function, which must return a string\nor number representing the item, that is used for sorting, and reference it in\n[`listings_sort_by`][config.listings_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which items are sorted when comparing\nthem. By default, items are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n listings_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a custom function for comparing tags in listings. By\ndefault, tag comparison is case-sensitive, but you can use `tag_name_casefold`\nfor case-insensitivity:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold\n```\n\nYou can also define your own comparison function, which must return a string\nor number representing the tag, that is used for sorting, and reference it in\n[`tags_sort_by`][config.tags_sort_by].\n\n---\n\n#### \n\n\n\n\nUse this setting to reverse the order in which tags are sorted when comparing\nthem. By default, tags are sorted in ascending order, but you can reverse\nordering as follows:\n\n``` yaml\nplugins:\n - tags:\n tags_sort_reverse: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the name of the directive the plugin will look for\nwhen processing pages. If you want to use a shorter directive than\n`material/tags`, you could use:\n\n``` yaml\nplugins:\n - tags:\n listings_directive: $tags\n```\n\nUsing this setting, listings must now be referenced as such:\n\n``` html\n\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to enable or disable tags showing up in the table of contents.\nIf you don't want tags to show up in the table of contents, you can disable this\nbehavior with:\n\n``` yaml\nplugins:\n - tags:\n listings_toc: false\n```\n\n### Shadow tags\n\nThe following settings are available for shadow tags:\n\n---\n\n#### \n\n\n\n\nUse this setting to specify whether the plugin should include shadow tags on\npages and in listings when [building your project], which might be useful for\ndeploy previews:\n\n=== \"Show shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: true\n ```\n\n=== \"Hide shadow tags\"\n\n ``` yaml\n plugins:\n - tags:\n shadow: false\n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin should include shadow tags on\npages and in listings when [previewing your site]. If you don't wish to include\nthem when previewing, use:\n\n``` yaml\nplugins:\n - tags:\n shadow_on_serve: false\n```\n\n [previewing your site]: ../creating-your-site.md#previewing-as-you-write\n\n---\n\n#### \n\n\n\n\nThe plugin allows to specify a predefined list of shadow tags which can be\nincluded and excluded from builds by using the [`shadow`][config.shadow]\nsetting. Shadow tags must be specified as a list:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags:\n - Draft\n - Internal\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a prefix for each tag.\nIf the tag starts with this string, the tag is marked as a shadow tag. A common\npractice is to use `_` as a prefix:\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_prefix: _\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify a string that is checked as a suffix for each tag.\nIf the tag ends with this string, the tag is marked as a shadow tag. One option\ncan be to use `Internal` as a suffix:\n\n\n``` yaml\nplugins:\n - tags:\n shadow_tags_suffix: Internal\n```\n\n### Export\n\nThe following settings are available for exporting:\n\n---\n\n#### \n\n\n\n\nUse this setting to control whether the plugin creates a `tags.json` file\ninside your [`site` directory][mkdocs.site_dir], which can then be consumed by\nother plugins and projects:\n\n``` yaml\nplugins:\n - tags:\n export: true\n```\n\n---\n\n#### \n\n\n\n\nUse this setting to change the path of the file where the exported tags are\nstored. It's normally not necessary to change this setting, but if you need to,\nuse:\n\n``` yaml\nplugins:\n - tags:\n export_file: tags.json\n```\n\nThe provided path is resolved from the [`site` directory][mkdocs.site_dir].\n\n---\n\n#### \n\n\n\n\nThis setting is solely provided for convenience to disable the rendering of tags\nand listings with a single setting (e.g. by using an environment variable),\nwhile keeping the export functionality:\n\n``` yaml\nplugins:\n - tags:\n export_only: true\n```\n\nThis will automatically disable the [`tags`][config.tags] and\n[`listings`][config.listings] settings.\n\n## Usage\n\n### Metadata\n\nThe following properties are available:\n\n---\n\n#### \n\n\n\n\n\nUse this property to associate a page with one or more tags, making the page\nappear in the generated tags index. Tags are defined as a list of strings\n(whitespaces are allowed):\n\n``` yaml\n---\ntags:\n - HTML5\n - JavaScript\n - CSS\n---\n\n# Page title\n...\n```\n\nIf you want to prevent accidental typos when assigning tags to pages, you can\nset a predefined list of allowed tags in `mkdocs.yml` by using the\n[`tags_allowed`][config.tags_allowed] setting.\n\n### Listing configuration\n\nThe listings configuration controls which tags are included in or excluded from\na listing and whether a listing only includes pages in the current scope.\nFurthermore, listings can override some values from the global configuration.\n\nThe following settings are available:\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should only consider pages that are\nwithin the current subsection of the documentation of the page the listing is\nembedded in:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n scope: false\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should include shadow tags, which\nallows to override the global [`shadow`][config.shadow] setting on a per-listing\nbasis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n shadow: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nThis setting specifies whether the listing should render tags inside the table\nof contents, allowing to override the global [`listings_toc`][config.listings_toc]\nsetting on a per-listing basis:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n toc: true\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be included in the listing. Each\npage that features a tag that is part of this setting, is listed under the\nrespective tag:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n include:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, all tags and pages are included.\n\n---\n\n#### \n\n\n\n\nUse this setting to specify which tags should be excluded from the listing. Each\npage that features a tag that is part of this setting, is excluded from the\nlisting entirely:\n\n=== \"Inline usage\"\n\n ``` html\n \n ```\n\n=== \"Usage in `mkdocs.yml`\"\n\n ``` yaml\n plugins:\n - tags:\n listings_map:\n custom-id:\n exclude:\n - foo\n - bar\n ```\n\n Then, just reference the listing identifier:\n\n ``` html\n \n ```\n\nIf this setting is left empty, no tags or pages are excluded.\n\n## Limitations\n\nThe implementation of the tags plugin is tricky due to MkDocs architecture.\nNotably, tag listing markers cannot appear within code blocks. For technical\ndetails, refer to #8114.\n\n\n# Plugins Skill\n\nPath: `docs/plugins/typeset.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/plugins/typeset.md)\n\n\n# Extensions Skill\n\nPath: `docs/schema/extensions/markdown.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/markdown.json)\n\n\n# Extensions Skill\n\nPath: `docs/schema/extensions/pymdownx.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/extensions/pymdownx.json)\n\n\n# Plugins Skill\n\nPath: `docs/schema/plugins/blog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/blog.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/awesome-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/awesome-nav.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/gen-files.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/gen-files.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/git-authors.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-authors.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/git-committers.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-committers.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/git-revision-date.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/git-revision-date.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/literate-nav.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/literate-nav.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/macros.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/macros.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/minify.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/minify.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/redirects.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/redirects.json)\n\n\n# External Skill\n\nPath: `docs/schema/plugins/external/section-index.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/external/section-index.json)\n\n\n# Plugins Skill\n\nPath: `docs/schema/plugins/group.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/group.json)\n\n\n# Plugins Skill\n\nPath: `docs/schema/plugins/info.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/squidfunk/mkdocs-material/HEAD/docs/schema/plugins/info.json)\n\n\n "}