commit eb8e790d38acb1afc2d15be9b831dbdee05ac201
Author: sairate
Date: Tue Apr 22 17:56:04 2025 +0800
Signed-off-by: sairate
diff --git a/.idea/.gitignore b/.idea/.gitignore
new file mode 100644
index 0000000..359bb53
--- /dev/null
+++ b/.idea/.gitignore
@@ -0,0 +1,3 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
new file mode 100644
index 0000000..25bde2c
--- /dev/null
+++ b/.idea/inspectionProfiles/Project_Default.xml
@@ -0,0 +1,14 @@
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml
new file mode 100644
index 0000000..105ce2d
--- /dev/null
+++ b/.idea/inspectionProfiles/profiles_settings.xml
@@ -0,0 +1,6 @@
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/material_theme_project_new.xml b/.idea/material_theme_project_new.xml
new file mode 100644
index 0000000..1a19c2f
--- /dev/null
+++ b/.idea/material_theme_project_new.xml
@@ -0,0 +1,10 @@
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/misc.xml b/.idea/misc.xml
new file mode 100644
index 0000000..b4d4b27
--- /dev/null
+++ b/.idea/misc.xml
@@ -0,0 +1,7 @@
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/modules.xml b/.idea/modules.xml
new file mode 100644
index 0000000..b5a8876
--- /dev/null
+++ b/.idea/modules.xml
@@ -0,0 +1,8 @@
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/.idea/yao.iml b/.idea/yao.iml
new file mode 100644
index 0000000..dad81f6
--- /dev/null
+++ b/.idea/yao.iml
@@ -0,0 +1,10 @@
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..083a176
--- /dev/null
+++ b/README.md
@@ -0,0 +1,13 @@
+# Mkdocs 编程知识总结项目
+
+这个项目是一个基于 Mkdocs 的编程知识总结,旨在为开发者提供一个集成、易于访问的学习资源。
+
+## 安装
+
+如果你希望在本地运行项目,请按以下步骤操作:
+
+- 环境安装
+ ``` python
+ pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+ ```
+- 运行start.py
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..53830bf
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+# 紫菱的中药总结
diff --git a/docs/郁金生品/1.复肝丸.md b/docs/郁金生品/1.复肝丸.md
new file mode 100644
index 0000000..6309bb3
--- /dev/null
+++ b/docs/郁金生品/1.复肝丸.md
@@ -0,0 +1,40 @@
+# 复肝丸说明书
+
+## 药品名称
+复肝丸
+
+## 出处
+《上海中医药杂志》1980年第6期
+
+## 药物组成
+- 紫河车
+- 红参须
+- 炙地鳖虫
+- 炮山甲
+- 参三七
+- 片姜黄
+- 广郁金
+- 鸡内金
+(各60克)
+
+## 功能与主治
+益气活血,化瘀消症。
+
+## 适应症
+适用于早期肝硬化患者的辅助治疗。
+
+## 用法用量
+请按照医师或中医师指导合理用药,切勿擅自增减剂量。
+
+## 注意事项
+- 使用期间应配合合理饮食
+- 避免辛辣刺激食物摄入
+- 建议定期复查肝功能
+- 孕妇慎用,或在医师指导下使用
+
+## 贮藏方法
+密封保存,置于阴凉干燥处,防止潮湿变质。
+
+## 附注说明
+本品来源于传统中医药理论与临床经验,具体效果因个体体质差异可能有所不同,务必在专业医生指导下使用。
+
diff --git a/mkdocs-material/.browserslistrc b/mkdocs-material/.browserslistrc
new file mode 100644
index 0000000..5fbcf99
--- /dev/null
+++ b/mkdocs-material/.browserslistrc
@@ -0,0 +1 @@
+last 4 years
diff --git a/mkdocs-material/.devcontainer/devcontainer.json b/mkdocs-material/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..aa357f2
--- /dev/null
+++ b/mkdocs-material/.devcontainer/devcontainer.json
@@ -0,0 +1,11 @@
+{
+ "name": "Material for MkDocs - VS Code dev container",
+ "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18",
+ "features": {
+ "ghcr.io/devcontainers/features/python:1": {
+ "installTools": true,
+ "version": "3.11"
+ }
+ },
+ "postCreateCommand": "pip install -e . && pip install mkdocs-minify-plugin mkdocs-redirects && npm install && npm run build"
+}
diff --git a/mkdocs-material/.dockerignore b/mkdocs-material/.dockerignore
new file mode 100644
index 0000000..bdaff1a
--- /dev/null
+++ b/mkdocs-material/.dockerignore
@@ -0,0 +1,27 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+.cache
+.git
+.github
+docs
+material/overrides
+node_modules
+src
diff --git a/mkdocs-material/.editorconfig b/mkdocs-material/.editorconfig
new file mode 100644
index 0000000..84c3600
--- /dev/null
+++ b/mkdocs-material/.editorconfig
@@ -0,0 +1,36 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# Top-level config
+root = true
+
+# All files
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Python
+[*.py]
+indent_style = space
+indent_size = 4
diff --git a/mkdocs-material/.eslintignore b/mkdocs-material/.eslintignore
new file mode 100644
index 0000000..2a886f9
--- /dev/null
+++ b/mkdocs-material/.eslintignore
@@ -0,0 +1,55 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Node, TypeScript, Python
+# -----------------------------------------------------------------------------
+
+# Dependencies
+node_modules
+__pycache__
+venv
+
+# Build files
+build
+MANIFEST
+manifest.json
+site
+
+# Configuration
+typings
+webpack.config.ts
+
+# Distribution files
+dist
+mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.eslintcache
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Temporary files
+tmp
diff --git a/mkdocs-material/.eslintrc b/mkdocs-material/.eslintrc
new file mode 100644
index 0000000..ade9302
--- /dev/null
+++ b/mkdocs-material/.eslintrc
@@ -0,0 +1,355 @@
+{
+ "root": true,
+ "parser": "@typescript-eslint/parser",
+ "parserOptions": {
+ "project": "tsconfig.json"
+ },
+ "plugins": [
+ "@typescript-eslint",
+ "@stylistic/ts",
+ "eslint-plugin-eslint-comments",
+ "eslint-plugin-import",
+ "eslint-plugin-jsdoc",
+ "eslint-plugin-no-null"
+ ],
+ "extends": [
+ "eslint:recommended",
+ "plugin:@typescript-eslint/eslint-recommended",
+ "plugin:@typescript-eslint/recommended"
+ ],
+ "settings": {
+ "import/extensions": [
+ ".ts",
+ ".tsx",
+ ".js",
+ ".jsx",
+ ".json"
+ ],
+ "import/parsers": {
+ "@typescript-eslint/parser": [
+ ".ts",
+ ".tsx"
+ ]
+ }
+ },
+ "rules": {
+ "array-bracket-spacing": "warn",
+ "arrow-parens": [
+ "warn",
+ "as-needed"
+ ],
+ "block-spacing": "warn",
+ "brace-style": [
+ "warn",
+ "1tbs",
+ {
+ "allowSingleLine": true
+ }
+ ],
+ "comma-dangle": [
+ "error",
+ "never"
+ ],
+ "comma-spacing": "warn",
+ "comma-style": "error",
+ "computed-property-spacing": "warn",
+ "curly": "off",
+ "eqeqeq": [
+ "error",
+ "smart"
+ ],
+ "func-call-spacing": "warn",
+ "keyword-spacing": "warn",
+ "lines-around-comment": [
+ "error",
+ {
+ "allowBlockStart": true,
+ "allowBlockEnd": true,
+ "beforeBlockComment": true,
+ "ignorePattern": "@ts-ignore"
+ }
+ ],
+ "lines-between-class-members": "warn",
+ "max-classes-per-file": "error",
+ "new-parens": "error",
+ "no-caller": "error",
+ "no-case-declarations": "off",
+ "no-console": "error",
+ "no-duplicate-imports": "error",
+ "no-eval": "error",
+ "no-extra-bind": "error",
+ "no-multiple-empty-lines": [
+ "error",
+ {
+ "max": 1
+ }
+ ],
+ "no-new-func": "error",
+ "no-new-wrappers": "error",
+ "no-restricted-globals": [
+ "error",
+ {
+ "name": "fdescribe",
+ "message": "Did you mean 'describe'?"
+ },
+ {
+ "name": "xdescribe",
+ "message": "Did you mean 'describe'?"
+ },
+ {
+ "name": "fit",
+ "message": "Did you mean 'it'?"
+ },
+ {
+ "name": "xit",
+ "message": "Did you mean 'xit'?"
+ }
+ ],
+ "no-return-await": "error",
+ "no-sequences": "error",
+ "no-shadow": "off",
+ "no-tabs": "error",
+ "no-template-curly-in-string": "error",
+ "no-throw-literal": "off",
+ "no-trailing-spaces": "warn",
+ "no-undef-init": "error",
+ "no-underscore-dangle": "error",
+ "no-var": "error",
+ "no-whitespace-before-property": "warn",
+ "object-shorthand": "error",
+ "one-var": [
+ "error",
+ "never"
+ ],
+ "prefer-exponentiation-operator": "error",
+ "prefer-object-spread": "error",
+ "prefer-template": "error",
+ "quote-props": [
+ "error",
+ "consistent-as-needed"
+ ],
+ "quotes": [
+ "error",
+ "double",
+ {
+ "avoidEscape": true
+ }
+ ],
+ "radix": "error",
+ "semi": "off",
+ "sort-imports": [
+ "error",
+ {
+ "ignoreDeclarationSort": true
+ }
+ ],
+ "space-before-blocks": "warn",
+ "space-before-function-paren": [
+ "warn",
+ {
+ "anonymous": "always",
+ "named": "never",
+ "asyncArrow": "always"
+ }
+ ],
+ "space-in-parens": "warn",
+ "space-infix-ops": "warn",
+ "space-unary-ops": "warn",
+ "spaced-comment": "warn",
+ "switch-colon-spacing": "warn",
+ "template-tag-spacing": "warn",
+
+ /* Plugin: @typescript-eslint */
+ "@typescript-eslint/array-type": "off",
+ "@typescript-eslint/await-thenable": "error",
+ "@typescript-eslint/ban-ts-comment": "off",
+ "@typescript-eslint/ban-types": "off",
+ "@typescript-eslint/consistent-type-assertions": "error",
+ "@typescript-eslint/dot-notation": "error",
+ "@typescript-eslint/explicit-member-accessibility": "error",
+ "@typescript-eslint/naming-convention": [
+ "error",
+ {
+ "selector": "enumMember",
+ "format": [
+ "UPPER_CASE"
+ ]
+ }
+ ],
+ "@typescript-eslint/no-empty-interface": "off",
+ "@typescript-eslint/no-empty-object-type": "off",
+ "@typescript-eslint/no-extraneous-class": "error",
+ "@typescript-eslint/no-misused-promises": "off",
+ "@typescript-eslint/no-non-null-assertion": "off",
+ "@typescript-eslint/no-parameter-properties": "off",
+ "@typescript-eslint/no-floating-promises": "error",
+ "@typescript-eslint/no-shadow": [
+ "error",
+ {
+ "hoist": "never"
+ }
+ ],
+ "@typescript-eslint/no-unnecessary-type-assertion": "error",
+ "@typescript-eslint/no-unused-expressions": "error",
+ "@typescript-eslint/no-unused-vars": "off",
+ "@typescript-eslint/no-var-requires": "off",
+ "@typescript-eslint/only-throw-error": "error",
+ "@typescript-eslint/prefer-for-of": "off",
+ "@typescript-eslint/prefer-function-type": "error",
+ "@typescript-eslint/triple-slash-reference": "off",
+ "@typescript-eslint/unbound-method": "error",
+ "@typescript-eslint/unified-signatures": "error",
+
+ /* Plugin: @stylistic/ts */
+ "@stylistic/ts/indent": [
+ "warn",
+ 2,
+ {
+ "FunctionDeclaration": {
+ "parameters": 1,
+ "body": 1
+ },
+ "FunctionExpression": {
+ "parameters": 1,
+ "body": 1
+ },
+ "MemberExpression": "off",
+ "ObjectExpression": 1,
+ "SwitchCase": 1,
+ "ignoreComments": true,
+ "ignoredNodes": [
+ "ArrowFunctionExpression > *",
+ "CallExpression > ObjectExpression",
+ "ConditionalExpression > ConditionalExpression",
+ "TSTypeReference > *"
+ ],
+ "offsetTernaryExpressions": true
+ }
+ ],
+ "@stylistic/ts/member-delimiter-style": [
+ "error",
+ {
+ "multiline": {
+ "delimiter": "none"
+ },
+ "singleline": {
+ "delimiter": "comma",
+ "requireLast": false
+ }
+ }
+ ],
+ "@stylistic/ts/semi": [
+ "error",
+ "never"
+ ],
+ "@stylistic/ts/type-annotation-spacing": "error",
+
+ /* Plugin: eslint-plugin-eslint-comments */
+ "eslint-comments/no-unused-disable": "error",
+ "eslint-comments/no-unused-enable": "error",
+ "eslint-comments/no-use": [
+ "warn",
+ {
+ "allow": [
+ "eslint-disable-line",
+ "eslint-disable-next-line"
+ ]
+ }
+ ],
+
+ /* Plugin: eslint-plugin-import */
+ "import/first": "error",
+ "import/newline-after-import": "error",
+ "import/no-default-export": "error",
+ "import/no-duplicates": "error",
+ "import/no-mutable-exports": "error",
+ "import/no-self-import": "error",
+ "import/order": [
+ "error",
+ {
+ "alphabetize": {
+ "order": "asc"
+ },
+ "newlines-between": "always",
+ "groups": [
+ [
+ "builtin",
+ "external"
+ ],
+ [
+ "internal"
+ ],
+ [
+ "index"
+ ],
+ [
+ "parent"
+ ],
+ [
+ "sibling"
+ ]
+ ],
+ "pathGroups": [
+ {
+ "pattern": "~/**",
+ "group": "index",
+ "position": "before"
+ },
+ {
+ "pattern": "_/**",
+ "group": "index",
+ "position": "after"
+ }
+ ],
+ "pathGroupsExcludedImportTypes": [
+ "builtin"
+ ]
+ }
+ ],
+
+ /* Plugin: eslint-plugin-jsdoc */
+ "jsdoc/check-alignment": "warn",
+ "jsdoc/check-param-names": [
+ "warn",
+ {
+ "checkDestructured": false
+ }
+ ],
+ "jsdoc/check-syntax": "warn",
+ "jsdoc/check-tag-names": [
+ "warn",
+ {
+ "definedTags": [
+ "internal"
+ ]
+ }
+ ],
+ "jsdoc/empty-tags": "warn",
+ "jsdoc/no-bad-blocks": "warn",
+ "jsdoc/no-defaults": "warn",
+ "jsdoc/no-types": "warn",
+ "jsdoc/require-hyphen-before-param-description": "warn",
+ "jsdoc/require-jsdoc": "warn",
+ "jsdoc/require-param-description": "warn",
+ "jsdoc/require-param-name": "warn",
+ "jsdoc/require-param": [
+ "warn",
+ {
+ "checkDestructured": false,
+ "checkDestructuredRoots": true
+ }
+ ],
+ "jsdoc/require-returns-check": "warn",
+ "jsdoc/require-returns-description": "warn",
+ "jsdoc/require-returns": [
+ "warn",
+ {
+ "checkGetters": false,
+ "forceReturnsWithAsync": true
+ }
+ ],
+
+ /* Plugin: eslint-plugin-no-null */
+ "no-null/no-null": "error"
+ }
+}
diff --git a/mkdocs-material/.gitattributes b/mkdocs-material/.gitattributes
new file mode 100644
index 0000000..205021e
--- /dev/null
+++ b/mkdocs-material/.gitattributes
@@ -0,0 +1,2 @@
+# Enforce Unix newlines
+* text=auto eol=lf
diff --git a/mkdocs-material/.github/ISSUE_TEMPLATE/01-report-a-bug.yml b/mkdocs-material/.github/ISSUE_TEMPLATE/01-report-a-bug.yml
new file mode 100644
index 0000000..f1985d3
--- /dev/null
+++ b/mkdocs-material/.github/ISSUE_TEMPLATE/01-report-a-bug.yml
@@ -0,0 +1,124 @@
+name: Report a bug
+description: Something is not working? Report a bug
+body:
+
+ - type: textarea
+ id: context
+ attributes:
+ label: Context
+ description: >-
+ This field is optional. You may provide additional context for the bug
+ you want to report, helping us to understand what you are working on and
+ what you are trying to achieve. If the context is not relevant, you can
+ leave this field empty.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#context)
+
+ - type: textarea
+ id: description
+ attributes:
+ label: Bug description
+ description: >-
+ Please give a detailed description of the bug. Explain where Material
+ for MkDocs does not behave as you would expect it to. Be as specific as
+ possible. If you have found a workaround or a fix for the problem,
+ please let us maintainers (and all other users) know.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#bug-description)
+ validations:
+ required: true
+
+ - type: textarea
+ id: related-links
+ attributes:
+ label: Related links
+ description: >-
+ Please list all links to the sections of
+ [our documentation](https://squidfunk.github.io/mkdocs-material/) that
+ are relevant to the bug in order to show that you have consulted and
+ thoroughly read it. Additionally, list links to possibly related open
+ and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
+ and [discussions](https://github.com/squidfunk/mkdocs-material/discussions)
+ you encountered when searching our issue tracker.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#related-links)
+ value: |-
+ - [Reporting a bug](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/)
+ -
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: >-
+ Please create a __.zip file__ with a __minimal reproduction__ for the
+ bug. First, read our [reproduction guide](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/)
+ that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/plugins/info/) (mandatory) to create a self-contained
+ .zip file with the reproduction. We reserve the right to close issues
+ without .zip files.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
+ placeholder: |-
+ Drag and drop the .zip file with the minimal reproduction here.
+ validations:
+ required: true
+
+ - type: textarea
+ id: steps-to-reproduce
+ attributes:
+ label: Steps to reproduce
+ description: >-
+ Please provide a detailed list of instructions, guiding us maintainers
+ through the required steps, helping us to recreate the problem using the
+ minimal reproduction you provided. Be as specific as possible and as
+ verbose as necessary – try not to leave anything out.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#steps-to-reproduce)
+ placeholder: |-
+ 1. ...
+ 2. ...
+ 3. ...
+ validations:
+ required: true
+
+ - type: dropdown
+ id: browser
+ attributes:
+ label: Browser
+ description: >-
+ This field is optional. If the bug only happens in __specific browsers__,
+ please select them from the dropdown below. If your browser is not
+ listed or the version is relevant, you may select _Other_ and provide
+ more details in the field above.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#browser)
+ multiple: true
+ options:
+ - Chrome
+ - Safari
+ - Edge
+ - Firefox
+ - Opera
+ - Other
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Before submitting
+ description: >-
+ Please ensure your bug report fulfills all of the following requirements.
+ If you are not sure what a specific requirement means, follow the link
+ to learn about it and understand why it is necessary before ticking the
+ box. This will save the maintainers and you valuable time.
+ options:
+ - label: >-
+ I have read and followed the [bug reporting guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/).
+ required: true
+ - label: >-
+ I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material/),
+ and possibly related [issues](https://github.com/squidfunk/mkdocs-material/issues)
+ and [discussions](https://github.com/squidfunk/mkdocs-material/discussions).
+ required: true
+ - label: >-
+ I assure that I have [removed all customizations](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#remove-customizations)
+ before submitting this bug report.
+ required: true
+ - label: >-
+ I have attached a __.zip file__ with a [minimal reproduction](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/) using the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/plugins/info/).
+ required: true
diff --git a/mkdocs-material/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml b/mkdocs-material/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml
new file mode 100644
index 0000000..3ea1c79
--- /dev/null
+++ b/mkdocs-material/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml
@@ -0,0 +1,65 @@
+name: Report a documentation issue
+description: Missing information in our docs? Report a documentation issue
+labels:
+ - documentation
+body:
+
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: >-
+ Please describe the inconsistency or issue you have found in
+ [our documentation](https://squidfunk.github.io/mkdocs-material/)
+ or indicate where you feel there is a need for improvement. Furthermore,
+ explain the severity of the issue, i.e., its impact on you and potentially
+ other users.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#description)
+ validations:
+ required: true
+
+ - type: textarea
+ id: related-links
+ attributes:
+ label: Related links
+ description: >-
+ Please list all links to the sections of [our documentation](https://squidfunk.github.io/mkdocs-material/)
+ that are impacted by the issue you described above. If applicable,
+ add screenshots. Additionally, list links to possibly related open
+ and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
+ and [discussions](https://github.com/squidfunk/mkdocs-material/discussions)
+ you encountered when searching our issue tracker.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+ value: |-
+ - [Reporting a docs issue](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/)
+ -
+ validations:
+ required: true
+
+ - type: textarea
+ id: proposed-change
+ attributes:
+ label: Proposed change
+ description: >-
+ This field is optional. You may provide an improvement proposal for our
+ documentation by describing your suggestion in the text field below or
+ creating a pull request after reporting this issue referencing the issue.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#proposed-change)
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Before submitting
+ description: >-
+ Please ensure your documentation issue report fulfills all of the
+ following requirements. If you need clarification on a specific
+ requirement, follow the link to learn about it and understand why it is
+ necessary before ticking the box. This will save the maintainers and you
+ valuable time.
+ options:
+ - label: >-
+ I have read and followed the [documentation issue guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
+ required: true
+ - label: >-
+ I have attached the links to the affected sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+ required: true
diff --git a/mkdocs-material/.github/ISSUE_TEMPLATE/03-request-a-change.yml b/mkdocs-material/.github/ISSUE_TEMPLATE/03-request-a-change.yml
new file mode 100644
index 0000000..a2c4dfb
--- /dev/null
+++ b/mkdocs-material/.github/ISSUE_TEMPLATE/03-request-a-change.yml
@@ -0,0 +1,95 @@
+name: Request a change
+description: Want to submit an idea? Propose a change or feature request
+body:
+
+ - type: textarea
+ id: context
+ attributes:
+ label: Context
+ description: >-
+ This field is optional. You may provide additional context for the idea
+ you want to propose, helping us to understand what you are working on
+ and what you are trying to achieve. If the context is not relevant, you
+ can leave this field empty.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#context)
+
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: >-
+ Please provide a detailed description of your idea in 2-3 sentences so
+ that we maintainers can fully understand what change, feature, or the
+ improvement you are proposing. Don't yet explain the benefits of your
+ idea, we'll come to that. Focus on functionality.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#description)
+ validations:
+ required: true
+
+ - type: textarea
+ id: related-links
+ attributes:
+ label: Related links
+ description: >-
+ Please list all links to open and closed [issues](https://github.com/squidfunk/mkdocs-material/issues),
+ [discussions](https://github.com/squidfunk/mkdocs-material/discussions),
+ or to [documentation sections](https://squidfunk.github.io/mkdocs-material/)
+ that are relevant to your idea. If you discussed your idea with the
+ community on our [discussion board](https://github.com/squidfunk/mkdocs-material/discussions)
+ prior to creating this change request, please link the discussion here as well.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#related-links)
+ value: |-
+ - [Requesting a change](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/)
+ -
+ validations:
+ required: true
+
+ - type: textarea
+ id: use-cases
+ attributes:
+ label: Use Cases
+ description: >-
+ Please explain how your idea will work from an author's and user's
+ perspective. Elaborate on how the change would positively impact not only
+ you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+ of the project.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
+ validations:
+ required: true
+
+ - type: textarea
+ id: visuals
+ attributes:
+ label: Visuals
+ description: >-
+ This field is optional. You may provide sketches, screenshots, mockups,
+ or external assets to illustrate your idea. If you have seen this change,
+ feature, or improvement used in other static site generators or themes,
+ please describe how it is implemented and advertised.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#visuals)
+ placeholder: |-
+ Drag and drop images here or link external assets.
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Before submitting
+ description:
+ Please ensure your idea fulfills all of the following requirements. If
+ you need clarification on a specific requirement, follow the link to
+ learn about it and understand why it is necessary before ticking the box.
+ This will save the maintainers and you valuable time.
+ options:
+ - label: >-
+ I have read and followed the [change request guidelines](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/).
+ required: true
+ - label: >-
+ I have verified that [my idea is a change request and not a bug report](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#its-not-a-bug-its-a-feature).
+ required: true
+ - label: >-
+ I have ensured that, to the best of my knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
+ required: true
+ - label: >-
+ I have included relevant links to [the documentation](https://squidfunk.github.io/mkdocs-material/), related [issues](https://github.com/squidfunk/mkdocs-material/issues),
+ and [discussions](https://github.com/squidfunk/mkdocs-material/discussions) to underline the need for my idea.
+ required: true
diff --git a/mkdocs-material/.github/ISSUE_TEMPLATE/04-add-translations.yml b/mkdocs-material/.github/ISSUE_TEMPLATE/04-add-translations.yml
new file mode 100644
index 0000000..42c10f2
--- /dev/null
+++ b/mkdocs-material/.github/ISSUE_TEMPLATE/04-add-translations.yml
@@ -0,0 +1,111 @@
+name: Add a translation
+description: Missing support for your language? Add a translation
+title: Add translations for ...
+labels:
+ - change request
+body:
+
+ - type: markdown
+ attributes:
+ value: >-
+ **Important**: Before creating a new translation, please check if
+ Material for MkDocs already supports your language. Review the list of
+ [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
+ pick your language to add new or improve existing translations.
+
+ - type: textarea
+ id: translations
+ attributes:
+ label: Translations
+ description: >-
+ Please translate the labels on the right. For new languages, translate
+ each line. For existing languages, only translate lines containing the
+ :arrow_left: icon and remove the icon before submitting.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#translations_1)
+ value: |-
+ {% macro t(key) %}{{ {
+ "language": "en ⬅️",
+ "direction": "ltr ⬅️",
+ "action.edit": "Edit this page ⬅️",
+ "action.skip": "Skip to content ⬅️",
+ "action.view": "View source of this page ⬅️",
+ "announce.dismiss": "Don't show this again ⬅️",
+ "blog.archive": "Archive ⬅️",
+ "blog.categories": "Categories ⬅️",
+ "blog.categories.in": "in ⬅️",
+ "blog.continue": "Continue reading ⬅️",
+ "blog.draft": "Draft ⬅️",
+ "blog.index": "Back to index ⬅️",
+ "blog.meta": "Metadata ⬅️",
+ "blog.references": "Related links ⬅️",
+ "clipboard.copy": "Copy to clipboard ⬅️",
+ "clipboard.copied": "Copied to clipboard ⬅️",
+ "consent.accept": "Accept ⬅️",
+ "consent.manage": "Manage settings ⬅️",
+ "consent.reject": "Reject ⬅️",
+ "footer": "Footer ⬅️",
+ "footer.next": "Next ⬅️",
+ "footer.previous": "Previous ⬅️",
+ "header": "Header ⬅️",
+ "meta.comments": "Comments ⬅️",
+ "meta.source": "Source ⬅️",
+ "nav": "Navigation ⬅️",
+ "readtime.one": "1 min read ⬅️",
+ "readtime.other": "# min read ⬅️",
+ "rss.created": "RSS feed ⬅️",
+ "rss.updated": "RSS feed of updated content ⬅️",
+ "search": "Search ⬅️",
+ "search.placeholder": "Search ⬅️",
+ "search.share": "Share ⬅️",
+ "search.reset": "Clear ⬅️",
+ "search.result.initializer": "Initializing search ⬅️",
+ "search.result.placeholder": "Type to start searching ⬅️",
+ "search.result.none": "No matching documents ⬅️",
+ "search.result.one": "1 matching document ⬅️",
+ "search.result.other": "# matching documents ⬅️",
+ "search.result.more.one": "1 more on this page ⬅️",
+ "search.result.more.other": "# more on this page ⬅️",
+ "search.result.term.missing": "Missing ⬅️",
+ "select.language": "Select language ⬅️",
+ "select.version": "Select version ⬅️",
+ "source": "Go to repository ⬅️",
+ "source.file.contributors": "Contributors ⬅️",
+ "source.file.date.created": "Created ⬅️",
+ "source.file.date.updated": "Last update ⬅️",
+ "tabs": "Tabs ⬅️",
+ "toc": "Table of contents ⬅️",
+ "top": "Back to top ⬅️"
+ }[key] }}{% endmacro %}
+ render: Jinja
+ validations:
+ required: true
+
+ - type: input
+ id: country-flag
+ attributes:
+ label: Country flag
+ description: >-
+ This field is optional. Please add the flag of the country when adding a
+ new language. Go to our [emoji search](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
+ and enter `flag` to find all available shortcodes. If your flag is not
+ included, please choose the most appropriate available flag.
+ [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#country-flag)
+ placeholder: |-
+ Country flag shortcode, e.g. :flag_en:
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Before submitting
+ description: >-
+ Please ensure that your translation fulfills the following requirements.
+ options:
+ - label: >-
+ I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
+ required: true
+ - label: >-
+ I assure that the translations are accurate to the best of my knowledge.
+ required: true
+ - label: >-
+ __Optional__: I want to integrate this translation myself and create a
+ pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
diff --git a/mkdocs-material/.github/ISSUE_TEMPLATE/config.yml b/mkdocs-material/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..c2819d3
--- /dev/null
+++ b/mkdocs-material/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,27 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+blank_issues_enabled: false
+contact_links:
+ - name: Ask a question
+ url: https://github.com/squidfunk/mkdocs-material/discussions
+ about: >
+ Have a question or need help? Connect with our community on the
+ discussion board
diff --git a/mkdocs-material/.github/assets/logo.svg b/mkdocs-material/.github/assets/logo.svg
new file mode 100644
index 0000000..d7a3684
--- /dev/null
+++ b/mkdocs-material/.github/assets/logo.svg
@@ -0,0 +1,236 @@
+
diff --git a/mkdocs-material/.github/assets/screenshot.png b/mkdocs-material/.github/assets/screenshot.png
new file mode 100644
index 0000000..7aec41f
Binary files /dev/null and b/mkdocs-material/.github/assets/screenshot.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-3dr.png b/mkdocs-material/.github/assets/sponsors/sponsor-3dr.png
new file mode 100644
index 0000000..80ca01e
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-3dr.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-apex-ai.png b/mkdocs-material/.github/assets/sponsors/sponsor-apex-ai.png
new file mode 100644
index 0000000..74ee858
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-apex-ai.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-astral.png b/mkdocs-material/.github/assets/sponsors/sponsor-astral.png
new file mode 100644
index 0000000..dda0e60
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-astral.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-basler.png b/mkdocs-material/.github/assets/sponsors/sponsor-basler.png
new file mode 100644
index 0000000..679da9c
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-basler.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-bitcrowd.png b/mkdocs-material/.github/assets/sponsors/sponsor-bitcrowd.png
new file mode 100644
index 0000000..17053c3
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-bitcrowd.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-botcity.png b/mkdocs-material/.github/assets/sponsors/sponsor-botcity.png
new file mode 100644
index 0000000..bf22945
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-botcity.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-buhler.png b/mkdocs-material/.github/assets/sponsors/sponsor-buhler.png
new file mode 100644
index 0000000..d58a2c5
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-buhler.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-cashapp.png b/mkdocs-material/.github/assets/sponsors/sponsor-cashapp.png
new file mode 100644
index 0000000..91bc9eb
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-cashapp.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-cirrus-ci.png b/mkdocs-material/.github/assets/sponsors/sponsor-cirrus-ci.png
new file mode 100644
index 0000000..7146f8c
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-cirrus-ci.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-civic-actions.png b/mkdocs-material/.github/assets/sponsors/sponsor-civic-actions.png
new file mode 100644
index 0000000..8da7b9e
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-civic-actions.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-coda.png b/mkdocs-material/.github/assets/sponsors/sponsor-coda.png
new file mode 100644
index 0000000..014934f
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-coda.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-dogado.png b/mkdocs-material/.github/assets/sponsors/sponsor-dogado.png
new file mode 100644
index 0000000..c926c03
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-dogado.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-eccenca.png b/mkdocs-material/.github/assets/sponsors/sponsor-eccenca.png
new file mode 100644
index 0000000..f3c2153
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-eccenca.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-elastic.png b/mkdocs-material/.github/assets/sponsors/sponsor-elastic.png
new file mode 100644
index 0000000..080d9a0
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-elastic.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-equipmentshare.png b/mkdocs-material/.github/assets/sponsors/sponsor-equipmentshare.png
new file mode 100644
index 0000000..ab7e400
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-equipmentshare.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-evergiving.png b/mkdocs-material/.github/assets/sponsors/sponsor-evergiving.png
new file mode 100644
index 0000000..31950c7
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-evergiving.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-fastapi.png b/mkdocs-material/.github/assets/sponsors/sponsor-fastapi.png
new file mode 100644
index 0000000..b0c84c5
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-fastapi.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-future.svg b/mkdocs-material/.github/assets/sponsors/sponsor-future.svg
new file mode 100644
index 0000000..a1a3600
--- /dev/null
+++ b/mkdocs-material/.github/assets/sponsors/sponsor-future.svg
@@ -0,0 +1,21 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-getscreenme.png b/mkdocs-material/.github/assets/sponsors/sponsor-getscreenme.png
new file mode 100644
index 0000000..fc3c974
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-getscreenme.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-hummingbot.png b/mkdocs-material/.github/assets/sponsors/sponsor-hummingbot.png
new file mode 100644
index 0000000..2d172e7
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-hummingbot.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-invers.png b/mkdocs-material/.github/assets/sponsors/sponsor-invers.png
new file mode 100644
index 0000000..1db8872
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-invers.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-ip-fabric.png b/mkdocs-material/.github/assets/sponsors/sponsor-ip-fabric.png
new file mode 100644
index 0000000..c86ec46
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-ip-fabric.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-jitterbit.png b/mkdocs-material/.github/assets/sponsors/sponsor-jitterbit.png
new file mode 100644
index 0000000..aeade4d
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-jitterbit.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-kolena.png b/mkdocs-material/.github/assets/sponsors/sponsor-kolena.png
new file mode 100644
index 0000000..a0a65d3
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-kolena.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-koor.png b/mkdocs-material/.github/assets/sponsors/sponsor-koor.png
new file mode 100644
index 0000000..dfa2c5f
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-koor.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-kx.png b/mkdocs-material/.github/assets/sponsors/sponsor-kx.png
new file mode 100644
index 0000000..fb2b8ad
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-kx.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-lechler.png b/mkdocs-material/.github/assets/sponsors/sponsor-lechler.png
new file mode 100644
index 0000000..b4200d3
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-lechler.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-maxar.png b/mkdocs-material/.github/assets/sponsors/sponsor-maxar.png
new file mode 100644
index 0000000..56bc8b1
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-maxar.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-milford.png b/mkdocs-material/.github/assets/sponsors/sponsor-milford.png
new file mode 100644
index 0000000..21bd4f8
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-milford.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-n8n.png b/mkdocs-material/.github/assets/sponsors/sponsor-n8n.png
new file mode 100644
index 0000000..57fc969
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-n8n.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-neptune-ai.png b/mkdocs-material/.github/assets/sponsors/sponsor-neptune-ai.png
new file mode 100644
index 0000000..0158c8e
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-neptune-ai.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-oikolab.png b/mkdocs-material/.github/assets/sponsors/sponsor-oikolab.png
new file mode 100644
index 0000000..8fd593f
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-oikolab.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-posit.png b/mkdocs-material/.github/assets/sponsors/sponsor-posit.png
new file mode 100644
index 0000000..a599ece
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-posit.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-prefect.png b/mkdocs-material/.github/assets/sponsors/sponsor-prefect.png
new file mode 100644
index 0000000..c30ec9e
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-prefect.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-rackn.png b/mkdocs-material/.github/assets/sponsors/sponsor-rackn.png
new file mode 100644
index 0000000..77bf33d
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-rackn.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-sailpoint.png b/mkdocs-material/.github/assets/sponsors/sponsor-sailpoint.png
new file mode 100644
index 0000000..042b030
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-sailpoint.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-siemens.png b/mkdocs-material/.github/assets/sponsors/sponsor-siemens.png
new file mode 100644
index 0000000..5a42914
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-siemens.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-sn-technology.png b/mkdocs-material/.github/assets/sponsors/sponsor-sn-technology.png
new file mode 100644
index 0000000..9d72964
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-sn-technology.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-sparkfun.png b/mkdocs-material/.github/assets/sponsors/sponsor-sparkfun.png
new file mode 100644
index 0000000..e155d95
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-sparkfun.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-spotware.png b/mkdocs-material/.github/assets/sponsors/sponsor-spotware.png
new file mode 100644
index 0000000..3afab60
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-spotware.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-trendpop.png b/mkdocs-material/.github/assets/sponsors/sponsor-trendpop.png
new file mode 100644
index 0000000..4c2cd8a
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-trendpop.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-wwt.png b/mkdocs-material/.github/assets/sponsors/sponsor-wwt.png
new file mode 100644
index 0000000..6bc5148
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-wwt.png differ
diff --git a/mkdocs-material/.github/assets/sponsors/sponsor-zenoss.png b/mkdocs-material/.github/assets/sponsors/sponsor-zenoss.png
new file mode 100644
index 0000000..fae4549
Binary files /dev/null and b/mkdocs-material/.github/assets/sponsors/sponsor-zenoss.png differ
diff --git a/mkdocs-material/.github/dependabot.yml b/mkdocs-material/.github/dependabot.yml
new file mode 100644
index 0000000..fe7664b
--- /dev/null
+++ b/mkdocs-material/.github/dependabot.yml
@@ -0,0 +1,45 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+version: 2
+updates:
+- package-ecosystem: npm
+ open-pull-requests-limit: 10
+ directory: "/"
+ labels: []
+ schedule:
+ interval: weekly
+ time: "04:00"
+- package-ecosystem: pip
+ # We only want to bump versions of packages in case of security updates, as
+ # we want to keep maximum compatibility - see https://t.ly/INSR_
+ open-pull-requests-limit: 0
+ directory: "/"
+ labels: []
+ schedule:
+ interval: weekly
+ time: "04:00"
+- package-ecosystem: github-actions
+ open-pull-requests-limit: 10
+ directory: "/"
+ labels: []
+ schedule:
+ interval: weekly
+ time: "04:00"
diff --git a/mkdocs-material/.github/workflows/build.yml b/mkdocs-material/.github/workflows/build.yml
new file mode 100644
index 0000000..4838816
--- /dev/null
+++ b/mkdocs-material/.github/workflows/build.yml
@@ -0,0 +1,205 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+name: build
+on:
+ push:
+ branches:
+ - master
+ pull_request:
+ release:
+ types:
+ - published
+
+env:
+ NODE_VERSION: 18.x
+ PYTHON_VERSION: 3.x
+
+permissions:
+ contents: read
+
+jobs:
+ npm-build:
+ runs-on: ubuntu-latest
+ steps:
+
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Node.js runtime
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+
+ - name: Set up Node.js dependency cache
+ uses: actions/cache@v4
+ id: cache
+ with:
+ key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+ path: node_modules
+
+ - name: Set up Node.js dependencies
+ if: steps.cache.outputs.cache-hit != 'true'
+ run: npm install
+
+ - name: Build project
+ run: |
+ npm run build
+ git diff --name-only
+
+ npm-check:
+ runs-on: ubuntu-latest
+ steps:
+
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Node.js runtime
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+
+ - name: Set up Node.js dependency cache
+ uses: actions/cache@v4
+ id: cache
+ with:
+ key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+ path: node_modules
+
+ - name: Set up Node.js dependencies
+ if: steps.cache.outputs.cache-hit != 'true'
+ run: npm install
+
+ - name: Check project
+ run: npm run check
+
+ python:
+ runs-on: ubuntu-latest
+ steps:
+
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Python runtime
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ cache: pip
+ cache-dependency-path: |
+ pyproject.toml
+ requirements.txt
+
+ - name: Set up Python dependencies
+ run: pip install --upgrade build twine
+
+ - name: Build Python package
+ run: python -m build
+
+ - name: Publish Python package
+ if: github.event_name == 'release'
+ env:
+ PYPI_USERNAME: ${{ secrets.PYPI_USERNAME }}
+ PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+ run: twine upload --disable-progress-bar -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} dist/*
+
+ docker:
+ runs-on: ubuntu-latest
+ steps:
+
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@v3
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Login to DockerHub
+ if: github.event_name == 'release'
+ uses: docker/login-action@v3
+ with:
+ username: ${{ secrets.DOCKER_USERNAME }}
+ password: ${{ secrets.DOCKER_PASSWORD }}
+
+ - name: Login to GitHub Container Registry
+ if: github.event_name == 'release'
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.repository_owner }}
+ password: ${{ secrets.GHCR_TOKEN }}
+
+ - name: Generate Docker tags and labels
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: |
+ ${{ github.event.repository.full_name }}
+ ghcr.io/${{ github.event.repository.full_name }}
+ tags: |
+ type=semver,pattern={{version}}
+ type=semver,pattern={{major}}.{{minor}}
+ type=semver,pattern={{major}}
+ type=ref,event=branch
+ type=ref,event=pr
+ flavor: |
+ latest=${{ github.event.release.prerelease == false }}
+
+ - name: Build Docker image
+ uses: docker/build-push-action@v6
+ with:
+ context: .
+ load: true
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+
+ - name: Check Docker image
+ working-directory: /tmp
+ env:
+ REPO_FULL_NAME: '${{ github.event.repository.full_name }}'
+ run: |
+ docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} new .
+ docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} build
+
+ - name: Set platforms
+ if: github.event_name == 'release'
+ run: |
+ echo "PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7" >> $GITHUB_ENV
+
+ - name: Publish Docker image
+ uses: docker/build-push-action@v6
+ with:
+ context: .
+ platforms: ${{ env.PLATFORMS }}
+ push: ${{ github.event_name == 'release' }}
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+
+ - name: Check manifest
+ if: github.event_name == 'release'
+ run: |
+ docker buildx imagetools inspect ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+
+ - name: Inspect image
+ if: github.event_name == 'release'
+ run: |
+ docker pull ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+ docker image inspect ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
diff --git a/mkdocs-material/.github/workflows/documentation.yml b/mkdocs-material/.github/workflows/documentation.yml
new file mode 100644
index 0000000..bd712aa
--- /dev/null
+++ b/mkdocs-material/.github/workflows/documentation.yml
@@ -0,0 +1,118 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+name: documentation
+on:
+ push:
+ branches:
+ - master
+
+env:
+ PYTHON_VERSION: 3.x
+
+permissions:
+ contents: write
+ id-token: write
+ pages: write
+
+jobs:
+ documentation:
+ name: Build documentation
+ runs-on: ubuntu-latest
+ steps:
+
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+ material/overrides
+ src/templates/partials/languages
+
+ - name: Set up Python runtime
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ cache: pip
+ cache-dependency-path: |
+ pyproject.toml
+ requirements.txt
+
+ - name: Set up build cache
+ uses: actions/cache/restore@v4
+ with:
+ key: mkdocs-material-${{ hashfiles('.cache/**') }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+
+ - name: Install dependencies
+ run: sudo apt-get install pngquant
+
+ - name: Install Python dependencies
+ run: |
+ pip install mkdocs-material
+ pip install .[recommended,git,imaging]
+
+ - name: Install Insiders build
+ if: github.event.repository.fork == false
+ env:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
+ run: |
+ # Warning: please don't use this method when installing Insiders from
+ # CI! We have to do it this way in order to allow for overrides on our
+ # own documentation, but you should stick to the method we recommend
+ # in the publishing guide – see https://bit.ly/3zjdJtw
+ git clone --depth 1 https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ pip install -e mkdocs-material-insiders
+ cp mkdocs-material-insiders/mkdocs.yml mkdocs.yml
+ # echo 'extra_javascript: [${{ vars.CHAT_CLIENT_URL }}]' >> mkdocs.yml
+ rm -rf material
+ cp -r mkdocs-material-insiders/material material
+
+ - name: Build documentation
+ env:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
+ GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
+ run: |
+ mkdocs build --clean
+ mkdocs --version
+
+ - name: Adjust permissions
+ run: |
+ chmod -c -R +rX site/ | while read line; do
+ echo "::warning title=Invalid file permissions automatically fixed::$line"
+ done
+
+ - name: Upload to GitHub Pages
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: site
+
+ - name: Deploy to GitHub Pages
+ uses: actions/deploy-pages@v4
+
+ - name: Save build cache
+ uses: actions/cache/save@v4
+ with:
+ key: mkdocs-material-${{ hashfiles('.cache/**') }}
+ path: .cache
diff --git a/mkdocs-material/.gitignore b/mkdocs-material/.gitignore
new file mode 100644
index 0000000..04f3c0e
--- /dev/null
+++ b/mkdocs-material/.gitignore
@@ -0,0 +1,71 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Node, TypeScript, Python
+# -----------------------------------------------------------------------------
+
+# Dependencies
+node_modules
+__pycache__
+venv
+.venv
+
+# Build files
+build
+site
+
+# Distribution files
+dist
+mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.cache
+.eslintcache
+__pycache__
+
+# Examples
+example
+example.zip
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Never ignore .gitkeep files
+!**/.gitkeep
+
+# macOS internals
+.DS_Store
+
+# Temporary files
+TODO
+tmp
+
+# IDEs
+.vscode
+.idea
+*~
+
+# Vendor resources
+/material/assets/vendor
diff --git a/mkdocs-material/.stylelintignore b/mkdocs-material/.stylelintignore
new file mode 100644
index 0000000..2ddc9da
--- /dev/null
+++ b/mkdocs-material/.stylelintignore
@@ -0,0 +1,28 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# Distribution files
+docs
+material
+src/**/*.html
+
+# Prevent stylelint from constantly complaining
+*.css
+*.ts
diff --git a/mkdocs-material/.stylelintrc b/mkdocs-material/.stylelintrc
new file mode 100644
index 0000000..390a629
--- /dev/null
+++ b/mkdocs-material/.stylelintrc
@@ -0,0 +1,166 @@
+{
+ "extends": [
+ "@stylistic/stylelint-config",
+ "stylelint-config-recess-order",
+ "stylelint-config-recommended",
+ "stylelint-config-standard-scss"
+ ],
+ "plugins": [
+ "@stylistic/stylelint-plugin",
+ "stylelint-scss"
+ ],
+ "rules": {
+ "alpha-value-notation": "number",
+ "annotation-no-unknown": null,
+ "at-rule-empty-line-before": [
+ "always",
+ {
+ "except": [
+ "blockless-after-same-name-blockless",
+ "first-nested"
+ ],
+ "ignore": [
+ "after-comment"
+ ],
+ "ignoreAtRules": [
+ "if",
+ "each",
+ "else",
+ "elseif",
+ "for",
+ "import",
+ "return"
+ ]
+ }
+ ],
+ "at-rule-no-unknown": null,
+ "color-function-notation": null,
+ "color-hex-length": "long",
+ "color-named": "never",
+ "comment-empty-line-before": [
+ "always",
+ {
+ "ignore": [
+ "stylelint-commands"
+ ]
+ }
+ ],
+ "custom-property-empty-line-before": null,
+ "custom-property-pattern": null,
+ "declaration-no-important": true,
+ "declaration-block-single-line-max-declarations": 0,
+ "font-family-name-quotes": "always-where-recommended",
+ "font-weight-notation": "numeric",
+ "function-calc-no-unspaced-operator": null,
+ "function-no-unknown": null,
+ "function-url-no-scheme-relative": true,
+ "function-url-quotes": "always",
+ "hue-degree-notation": "number",
+ "length-zero-no-unit": [
+ true,
+ {
+ "ignore": ["custom-properties"]
+ }
+ ],
+ "media-feature-name-no-unknown": null,
+ "media-feature-range-notation": null,
+ "media-query-no-invalid": null,
+ "no-descending-specificity": null,
+ "no-unknown-animations": true,
+ "property-no-unknown": null,
+ "property-no-vendor-prefix": [
+ true,
+ {
+ "ignoreProperties": [
+ "line-clamp",
+ "box-orient"
+ ]
+ }
+ ],
+ "selector-class-pattern": null,
+ "selector-id-pattern": null,
+ "selector-max-id": 0,
+ "selector-no-qualifying-type": null,
+ "selector-pseudo-class-no-unknown": null,
+ "selector-pseudo-element-no-unknown": null,
+ "unit-allowed-list": [
+ "%",
+ "ch",
+ "dppx",
+ "deg",
+ "em",
+ "fr",
+ "mm",
+ "ms",
+ "px",
+ "vh",
+ "vw"
+ ],
+ "value-keyword-case": [
+ "lower",
+ {
+ "ignoreProperties": [
+ "/^--/"
+ ]
+ }
+ ],
+ "value-no-vendor-prefix": [
+ true,
+ {
+ "ignoreValues": [
+ "box"
+ ]
+ }
+ ],
+ "scss/at-each-key-value-single-line": true,
+ "scss/at-else-closing-brace-newline-after": "always-last-in-chain",
+ "scss/at-function-parentheses-space-before": "never",
+ "scss/at-function-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+ "scss/at-if-closing-brace-newline-after": "always-last-in-chain",
+ "scss/at-if-no-null": true,
+ "scss/at-mixin-argumentless-call-parentheses": "always",
+ "scss/at-mixin-parentheses-space-before": "never",
+ "scss/at-mixin-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+ "scss/at-rule-conditional-no-parentheses": true,
+ "scss/comment-no-empty": null,
+ "scss/comment-no-loud": true,
+ "scss/declaration-nested-properties": "never",
+ "scss/dimension-no-non-numeric-values": true,
+ "scss/dollar-variable-colon-newline-after": "always-multi-line",
+ "scss/dollar-variable-colon-space-after": "always-single-line",
+ "scss/dollar-variable-colon-space-before": "never",
+ "scss/dollar-variable-first-in-block": null,
+ "scss/dollar-variable-no-missing-interpolation": true,
+ "scss/dollar-variable-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+ "scss/double-slash-comment-empty-line-before": null,
+ "scss/double-slash-comment-whitespace-inside": "always",
+ "scss/at-extend-no-missing-placeholder": null,
+ "scss/load-partial-extension": "never",
+ "scss/no-duplicate-mixins": true,
+ "scss/no-global-function-names": null,
+ "scss/operator-no-newline-after": null,
+ "scss/operator-no-unspaced": true,
+ "scss/partial-no-import": true,
+ "scss/percent-placeholder-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+ "scss/selector-no-redundant-nesting-selector": true,
+ "@stylistic/block-closing-brace-newline-after": [
+ "always",
+ {
+ "ignoreAtRules": [
+ "if",
+ "else",
+ "elseif"
+ ]
+ }
+ ],
+ "@stylistic/declaration-colon-space-after": null,
+ "@stylistic/no-empty-first-line": true,
+ "@stylistic/linebreaks": "unix",
+ "@stylistic/selector-combinator-space-before": null,
+ "@stylistic/selector-descendant-combinator-no-non-space": null,
+ "@stylistic/selector-max-empty-lines": 0,
+ "@stylistic/string-quotes": "double",
+ "@stylistic/unicode-bom": "never",
+ "@stylistic/value-list-comma-newline-after": null
+ }
+}
diff --git a/mkdocs-material/CHANGELOG b/mkdocs-material/CHANGELOG
new file mode 100644
index 0000000..3d9cfcc
--- /dev/null
+++ b/mkdocs-material/CHANGELOG
@@ -0,0 +1,3516 @@
+mkdocs-material-9.5.43 (2024-10-31)
+
+ * Added support for external images in SVGs in privacy plugin
+ * Fixed #7651: Privacy plugin doesn't handle quoted URLs in CSS
+
+mkdocs-material-9.5.42 (2024-10-20)
+
+ * Fixed #7625: Invalid encoding of boolean attributes in privacy plugin
+ * Fixed #7624: Crash when disabling privacy plugin (9.5.41 regression)
+
+mkdocs-material-9.5.41 (2024-10-15)
+
+ * Fixed #7619: Improved tooltip on logo disappears after instant navigation
+ * Fixed #7616: Race condition in built-in privacy plugin when inlining assets
+ * Fixed #7615: Comments and "Was this page helpful?" visible when printing
+
+mkdocs-material-9.5.40 (2024-10-10)
+
+ * Updated Latvian translations
+ * Fixed #7597: Social cards not using site name on home page
+
+mkdocs-material-9.5.39+insiders-4.53.14 (2024-09-29)
+
+ * Fixed #7567: Empty headlines when using typeset plugin with anchorlinks
+
+mkdocs-material-9.5.39 (2024-09-29)
+
+ * Fixed #7226: not staying on page when using mike's canonical versioning
+
+mkdocs-material-9.5.38 (2024-09-26)
+
+ * Added Albanian translations
+
+mkdocs-material-9.5.37 (2024-09-25)
+
+ * Added 4th and 5th level ordered list styles
+ * Fixed #7548: Tags have no spacing in search
+
+mkdocs-material-9.5.36 (2024-09-21)
+
+ * Fixed #7544: Social cards incorrectly rendering HTML entities
+ * Fixed #7542: Improved support for setting custom list styles
+
+mkdocs-material-9.5.35 (2024-09-18)
+
+ * Fixed #7498: Search not showing for Vietnamese language
+
+mkdocs-material-9.5.34+insiders-4.53.13 (2024-09-14)
+
+ * Fixed #7520: Social plugin errors for generated files (MkDocs 1.6+)
+
+mkdocs-material-9.5.34 (2024-08-31)
+
+ * Updated Mermaid.js to version 11 (latest)
+
+mkdocs-material-9.5.33 (2024-08-23)
+
+ * Fixed #7453: Incorrect position of tooltip when sorting table
+
+mkdocs-material-9.5.32 (2024-08-19)
+
+ * Fixed RXSS vulnerability via deep link in search results
+ * Added support for fetching latest release from GitLab
+
+mkdocs-material-9.5.31+insiders-4.53.12 (2024-08-02)
+
+ * Fixed #7410: Instant previews jump on content tabs with anchor links
+ * Fixed #7408: Instant previews jump on content tabs
+
+mkdocs-material-9.5.31 (2024-08-02)
+
+ * Fixed #7405: DockerHub missing images > 9.5.27 due to change in Alpine/APK
+
+mkdocs-material-9.5.30 (2024-07-23)
+
+ * Fixed #7380: Navigation icons disappearing on hover in Safari
+ * Fixed #7367: Blog readtime computation includes SVG text content
+
+mkdocs-material-9.5.29 (2024-07-14)
+
+ * Updated Galician translations
+ * Fixed #7362: Annotations in figure captions rendering incorrectly
+
+mkdocs-material-9.5.28 (2024-07-02)
+
+ * Fixed #7313: Improved tooltips mounted in sidebar when feature is disabled
+
+mkdocs-material-9.5.27 (2024-06-16)
+
+ * Updated Estonian translations
+
+mkdocs-material-9.5.26 (2024-06-06)
+
+ * Fixed #7232: Tab switches on scroll when linking tabs (9.5.19 regression)
+ * Fixed #7230: Blog author avatar broken when referring to local file
+
+mkdocs-material-9.5.25+insiders-4.53.11 (2024-05-27)
+
+ * Fixed projects plugin crashing when serving before building subprojects
+
+mkdocs-material-9.5.25 (2024-05-27)
+
+ * Fixed #7209: Tags plugin crashing on numeric tags
+
+mkdocs-material-9.5.24+insiders-4.53.10 (2024-05-20)
+
+ * Fixed projects plugin crashing in serve mode when disabled
+ * Fixed projects plugin crashing when building nested projects
+
+mkdocs-material-9.5.24+insiders-4.53.9 (2024-05-20)
+
+ * Fixed #7191: Tags listings not rendering when toc_depth is changed
+
+mkdocs-material-9.5.24 (2024-05-20)
+
+ * Fixed #7187: Version selector title rendering issue
+
+mkdocs-material-9.5.23 (2024-05-15)
+
+ * Fixed #7183: Edge case in anchor navigation when using instant navigation
+ * Fixed #6436: Version selector not showing version alias
+
+mkdocs-material-9.5.22 (2024-05-12)
+
+ * Fixed #7170: Copy button adds empty lines for line spans (9.5.18 regression)
+ * Fixed #7160: Version switching doesn't stay on page (9.5.5 regression)
+ * Fixed #5619: Links in Mermaid.js diagrams not discernible
+
+mkdocs-material-9.5.21 (2024-05-03)
+
+ * Fixed #7133: Ensure latest version of Mermaid.js is used
+ * Fixed #7125: Added warning for dotfiles in info plugin
+
+mkdocs-material-9.5.20 (2024-04-29)
+
+ * Fixed deprecation warning in privacy plugin (9.5.19 regression)
+ * Fixed #7119: Tags plugin emits deprecation warning (9.5.19 regression)
+ * Fixed #7118: Social plugin crashes if fonts are disabled (9.5.19 regression)
+ * Fixed #7085: Social plugin crashes on Windows when downloading fonts
+
+mkdocs-material-9.5.19+insiders-4.53.8 (2024-04-26)
+
+ * Fixed #7052: Preview extension automatically including all pages
+ * Fixed #7051: Instant previews mounting on footnote references
+ * Fixed #5165: Improved tooltips not mounting in sidebar for typeset plugin
+
+mkdocs-material-9.5.19+insiders-4.53.7 (2024-04-25)
+
+ * Fixed #7060: Incorrect resolution of translation when using static-i18n
+
+mkdocs-material-9.5.19 (2024-04-25)
+
+ * Updated MkDocs to 1.6 and limited version to < 2
+ * Updated Docker image to latest Alpine Linux
+ * Removed setup.py, now that GitHub fully understands pyproject.toml
+ * Improved interop of social plugin with third-party MkDocs themes
+ * Fixed #7099: Blog reading time not rendered correctly for Japanese
+ * Fixed #7097: Improved resilience of tags plugin when no tags are given
+ * Fixed #7090: Active tab indicator in nested content tabs rendering bug
+
+mkdocs-material-9.5.18 (2024-04-16)
+
+ * Refactored tooltips implementation to fix positioning issues
+ * Fixed #7044: Rendering glitch when hovering contributor avatar in Chrome
+ * Fixed #7043: Highlighted lines in code blocks cutoff on mobile
+ * Fixed #6910: Incorrect position of tooltip for page status in sidebar
+ * Fixed #6760: Incorrect position and overly long tooltip in tables
+ * Fixed #6488: Incorrect position and cutoff tooltip in content tabs
+
+mkdocs-material-9.5.17+insiders-4.53.6 (2024-04-05)
+
+ * Ensure working directory is set for projects when using projects plugin
+ * Fixed #6970: Incorrect relative paths in git submodules with projects plugin
+
+mkdocs-material-9.5.17+insiders-4.53.5 (2024-04-02)
+
+ * Fixed social plugin crashing when no colors are specified in palettes
+
+mkdocs-material-9.5.17 (2024-04-02)
+
+ * Updated Serbian translations
+ * Fixed #7003: Confusing keyboard interaction for palette toggle
+ * Fixed #7001: Blog posts now show time by default (9.5.16 regression)
+ * Fixed edge case in backport of social plugin font loading logic
+
+mkdocs-material-9.5.16+insiders-4.53.4 (2024-03-31)
+
+ * Fixed #6973: Escaping issue in tags extra files deprecation helper
+
+mkdocs-material-9.5.16 (2024-03-31)
+
+ * Updated Russian translations
+ * Improved error handling and reporting in social plugin
+ * Improved error handling and reporting in privacy plugin
+ * Fixed blog plugin not allowing to use time in format strings
+ * Fixed #6983: Social plugin crashes because of Google Fonts API change
+
+mkdocs-material-9.5.15+insiders-4.53.3 (2024-03-23)
+
+ * Added support for font variants in social plugin
+ * Improved resilience of font resolution in social plugin
+ * Fixed tag listing sometimes not being auto-populated
+ * Fixed tag listing scope not being correctly resolved
+ * Fixed #6941: Meta plugin adding duplicate entries
+ * Fixed #6928: Social plugin crashes for some fonts
+
+mkdocs-material-9.5.15 (2024-03-23)
+
+ * Reverted fix for transparent iframes (9.5.14)
+ * Fixed #6929: Interference of social plugin and auto dark mode
+ * Fixed #6938: Giscus shows dark background in light mode (9.5.14 regression)
+
+mkdocs-material-9.5.14+insiders-4.53.2 (2024-03-18)
+
+ * Fixed abort on first non-matching configuration in preview extension
+ * Fixed #6914: Meta files take precedence over front matter
+
+mkdocs-material-9.5.14 (2024-03-18)
+
+ * Added support for hiding versions from selector when using mike
+ * Added init system to improve signal handling in Docker image
+ * Fixed edge cases in exclusion logic of info plugin
+ * Fixed inability to reset pipeline in search plugin
+ * Fixed syntax error in Finnish translations
+ * Fixed #6917: UTF-8 encoding problems in blog plugin on Windows
+ * Fixed #6889: Transparent iframes get background color
+
+mkdocs-material-9.5.13+insiders-4.53.1 (2024-03-06)
+
+ * Fixed #6877: Projects plugin computes incorrect path to assets
+ * Fixed #6869: Blog plugin should emit warning on invalid related link
+
+mkdocs-material-9.5.13 (2024-03-06)
+
+ * Updated Slovak translations
+ * Improved info plugin interop with projects plugin
+ * Improved info plugin inclusion/exclusion logic
+ * Fixed info plugin not gathering files recursively
+ * Fixed #6750: Ensure info plugin packs up all necessary files
+
+mkdocs-material-9.5.12 (2024-02-29)
+
+ * Fixed #6846: Some meta tags removed on instant navigation (9.4.2 regression)
+ * Fixed #6823: KaTex not rendering on instant navigation (9.5.5 regression)
+ * Fixed #6821: Privacy plugin doesn't handle URLs with encoded characters
+
+mkdocs-material-9.5.11+insiders-4.53.0 (2024-02-24)
+
+ * Added support for automatic instant previews
+ * Added support for pinned blog posts
+
+mkdocs-material-9.5.11 (2024-02-19)
+
+ * Updated Finnish translation
+
+mkdocs-material-9.5.10+insiders-4.52.3 (2024-02-21)
+
+ * Fixed resolution of URLs in instant previews
+ * Fixed instant previews not mounting for same-page links
+
+mkdocs-material-9.5.10 (2024-02-19)
+
+ * Updated Bahasa Malaysia translations
+ * Fixed #6783: Hide continue reading link for blog posts without separators
+ * Fixed #6779: Incorrect positioning of integrated table of contents
+
+mkdocs-material-9.5.9 (2024-02-10)
+
+ * Fixed navigation pruning with tabs and sections enabled
+
+mkdocs-material-9.5.8+insiders-4.52.2 (2024-02-07)
+
+ * Fixed #6735: Instant previews misplaced when below tabs
+
+mkdocs-material-9.5.8 (2024-02-07)
+
+ * Added Tamil translations
+ * Updated Esperanto translations
+ * Fixed relative images not being resolved for instant navigation
+
+mkdocs-material-9.5.7 (2024-02-03)
+
+ * Fixed #6731: Small images in figures are not centered
+ * Fixed #6719: Instant navigation breaks table of contents (9.5.5 regression)
+
+mkdocs-material-9.5.6+insiders-4.52.1 (2024-01-30)
+
+ * Fixed #6705: Navigation path not being hidden when specified
+ * Fixed #6703: New tags plugin crashes on Windows (2nd attempt)
+
+mkdocs-material-9.5.6+insiders-4.52.0 (2024-01-28)
+
+ * Added support for instant previews
+ * Fixed footnote tooltips positioning edge cases
+ * Fixed #6703: New tags plugin crashes on Windows
+
+mkdocs-material-9.5.6 (2024-01-28)
+
+ * Fixed #6700: Missing styles for Mermaid.js labels with Markdown
+
+mkdocs-material-9.5.5+insiders-4.51.0 (2024-01-24)
+
+ * Added support for footnote tooltips
+
+mkdocs-material-9.5.5 (2024-01-24)
+
+ * Updated Tagalog translations
+ * Updated Pillow to 10.2 to mitigate security vulnerabilities
+ * Improved resilience of instant navigation
+ * Fixed #6687: Updated Mermaid.js to version 10.7.0 (latest)
+ * Fixed #6652: Keyboard events in custom elements captured
+ * Fixed #6582: Instant navigation doesn't correctly handle alternate URLs
+ * Fixed #6565: Instant navigation doesn't allow for onclick handlers
+ * Fixed #6345: Instant navigation sometimes breaks browser back button
+ * Fixed #6334: Instant navigation doesn't correctly position anchors (Safari)
+ * Fixed #6275: Instant navigation doesn't correctly resolve after 404
+ * Fixed #6102: Instant navigation reloads page on same link navigation
+
+mkdocs-material-9.5.4+insiders-4.50.0 (2024-01-19)
+
+ * Added configurable logging capabilities to privacy plugin
+
+mkdocs-material-9.5.4 (2024-01-15)
+
+ * Fixed #6645: Local storage with invalid value can break site
+ * Fixed #6635: Tags icons before default ignored if default is set
+
+mkdocs-material-9.5.3+insiders-4.49.2 (2024-01-09)
+
+ * Fixed missing attribute lists extension for tags plugin
+ * Fixed #6627: New tags plugin crashes on Python 3.8
+
+mkdocs-material-9.5.3+insiders-4.49.1 (2024-01-07)
+
+ * Improved interop of new tags plugin with other plugins
+ * Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
+ * Fixed #6569: Social plugin crashes if in different file system location
+
+mkdocs-material-9.5.3+insiders-4.49.0 (2023-12-29)
+
+ * Added support for exporting tags and mappings
+ * Added support for disabling tags and/or listings or both
+ * Fixed tag links from pages to listings on homepage
+
+mkdocs-material-9.5.3+insiders-4.48.0 (2023-12-23)
+
+ * Rewrite of tags plugin, now much more powerful
+ * Added support for nested tags (tag hierarchies, e.g. foo/bar)
+ * Added support for shadow tags (by list, prefix or suffix)
+ * Added support for custom tag layouts and templates
+ * Added support for hiding tags in table of contents
+ * Added support for configurable inline tag listings
+ * Added support for automatically linking to closest tag listing
+ * Added support for scoped listings (limit to subsection of site)
+ * Added support for multiple instances of tags plugin
+ * Added support for changing front matter property and template variable
+ * Added support for tag slugification format strings
+ * Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
+ * Fixed projects plugin not notifying plugins about serve mode
+ * Fixed projects plugin skipping projects on prefix match
+ * Deprecated tags_file and tags_extra_files settings
+ * Modernized tags plugin code base
+
+mkdocs-material-9.5.3 (2023-12-23)
+
+ * Limited version range of MkDocs to < 1.6
+ * Updated Macedonian translations
+ * Fixed #6520: Group plugin crashes when using mike
+ * Fixed #6494: Hide author's email address if disabled in git-authors plugin
+
+mkdocs-material-9.5.2+insiders-4.47.1 (2023-12-11)
+
+ * Improved editing experience for projects plugin
+ * Improved resilience of optimize and social plugin
+ * Fixed race condition when writing manifest in optimize and social plugin
+ * Fixed #6475: Logo not taking precedence over icon in social card
+ * Fixed #6399: Projects plugin doesn't pick up added/removed projects
+ * Fixed #6306: Projects plugin cache not correctly updated
+
+mkdocs-material-9.5.2 (2023-12-11)
+
+ * Fixed types for slugify settings in blog plugin config
+ * Fixed #6469: Horizontal scrollbars on MathJax containers
+
+mkdocs-material-9.5.1+insiders-4.47.0 (2023-12-08)
+
+ * Added support for staying on page when switching languages
+ * Added configurable logging capabilities to projects plugin
+ * Removed temporary warning on blog plugin authors file format change
+ * Fixed projects plugin logging messages twice on Linux systems
+ * Fixed projects plugin trying to hoist theme assets of divergent themes
+ * Fixed compatibility of optimize plugin and projects plugin
+ * Fixed compatibility of social plugin and projects plugin
+ * Fixed #6448: Code line selection broken for code blocks with custom ids
+ * Fixed #6437: Projects plugin crashing for certain site URL configurations
+ * Fixed #6414: Projects plugin doesn't prefix messages coming from projects
+
+mkdocs-material-9.5.1 (2023-12-08)
+
+ * Updated Greek translations
+ * Fixed #6464: Privacy plugin cannot be enabled
+ * Fixed #6461: Sorting blog posts ignores time component in date
+
+mkdocs-material-9.5.0 (2023-12-07)
+
+ Merged Insiders features of 'Goat's Horn' funding goal
+
+ * Added privacy plugin: automatic downloading of external assets
+ * Added support for card grids and grid layouts
+ * Added support for improved tooltips
+ * Added support for content tabs anchor links (deep linking)
+ * Added support for automatic dark/light mode
+ * Added support for document contributors
+
+mkdocs-material-9.4.14+insiders-4.46.0 (2023-11-26)
+
+ * Added support for author profiles in blog plugin
+ * Fixed custom index pages yielding two navigation items (4.45.0 regression)
+
+mkdocs-material-9.4.14 (2023-11-26)
+
+ * Added support for linking authors in blog posts
+
+mkdocs-material-9.4.13 (2023-11-26)
+
+ * Fixed #6365: Blog plugin pagination links to previous pages broken
+ * Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
+
+mkdocs-material-9.4.12+insiders-4.45.0 (2023-11-24)
+
+ * Added support for sorting blog categories by post count or custom function
+ * Improved tags plugin to generate Unicode-aware slugs by default
+ * Fixed non-deterministic order of multiple authors in blog plugin
+
+mkdocs-material-9.4.12 (2023-11-24)
+
+ * Improved blog plugin to generate Unicode-aware slugs by default
+ * Fixed non-deterministic order of categories in blog plugin
+
+mkdocs-material-9.4.11+insiders-4.44.0 (2023-11-23)
+
+ * Added pagination settings for archive pages in blog plugin
+ * Added pagination settings for category pages in blog plugin
+
+mkdocs-material-9.4.11 (2023-11-23)
+
+ * Fixed #6364: Search plugin crashing when enabling theme while serving
+ * Fixed blog plugin crashing when disabling pagination
+
+mkdocs-material-9.4.10+insiders-4.43.1 (2023-11-19)
+
+ * Added third-party theme support in projects plugin, improving editing
+ * Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
+ * Fixed #6306: Projects plugin not reloading nested project configuration
+
+mkdocs-material-9.4.10 (2023-11-19)
+
+ * Fixed #6356: Version selector can't be disabled via mike's configuration
+ * Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
+ * Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
+
+mkdocs-material-9.4.9 (2023-11-17)
+
+ * Fixed #6344: Long entries cutoff in table of contents
+ * Fixed #6336: Custom template for glob archive not working with pagination
+ * Fixed #6328: Blog plugin crashes for locales with dashes, e.g. pt-BR
+ * Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
+ * Fixed #6302: Version strings not matched when using mike, only aliases
+ * Fixed instant navigation progress indicator for gzipped content in Chrome
+ * Fixed rendering bug on details marker rotation in Firefox
+
+mkdocs-material-9.4.8+insiders-4.43.0 (2023-11-05)
+
+ * Added support for GitLab committers (document contributors)
+ * Fixed #6264: Fixed compatibility with Python < 3.10
+ * Fixed #6254: Meta plugin not applying meta files to blog posts
+
+mkdocs-material-9.4.8 (2023-11-05)
+
+ * Fixed invalid local address replacement when using instant loading
+ * Fixed #6275: Crash after navigation caused 404 when using instant loading
+
+mkdocs-material-9.4.7+insiders-4.42.3 (2023-10-27)
+
+ * Fixed #6251: Cards in grids cut off on very small screens
+ * Fixed #6241: Using social plugin + static-i18n plugin errors
+
+mkdocs-material-9.4.7 (2023-10-27)
+
+ * Added Azerbaijani translations
+
+mkdocs-material-9.4.6+insiders-4.42.2 (2023-10-14)
+
+ * Fixed #6186: Privacy plugin ignores hash fragments on images
+ * Fixed #6180: Projects plugin crashing when adding or removing files
+
+mkdocs-material-9.4.6 (2023-10-14)
+
+ * Updated Danish and Norwegian (Nynorsk) translations
+ * Fixed #6169: Blog post metadata layout overflows on small screens
+
+mkdocs-material-9.4.5 (2023-10-10)
+
+ * Fixed sidebar auto-positioning (9.4.2 regression)
+ * Fixed #6166: Improve group plugin compatibility with Python < 3.10
+ * Fixed #6157: Hiding tags does not work (9.4.3 regression)
+
+mkdocs-material-9.4.4+insiders-4.42.1 (2023-10-05)
+
+ * Fixed spacing of related links in blog posts on small screens
+
+mkdocs-material-9.4.4 (2023-10-05)
+
+ * Added support for overriding text to be copied for code blocks
+ * Fixed broken layout in some browsers at breakpoints when using zoom
+ * Fixed #6132: Incomplete search highlighting for code blocks in titles
+
+mkdocs-material-9.4.3 (2023-10-02)
+
+ * Added support for instant navigation progress indicator
+ * Improved spacing and alignment of tags
+ * Moved back-to-top button into separate partial
+ * Fixed #6104: Indentation for some code blocks lost in search
+ * Fixed #6094: Blog post metadata overlaps with footer on small screens
+ * Fixed #6069: Blog plugin crashes for categories with non-ASCII names
+
+ Updated templates
+
+ - base.html
+
+mkdocs-material-9.4.2 (2023-09-25)
+
+ * Updated Slovenian translations
+ * Added animation to sidebar navigation expansion and collapse
+ * Added support for auto-replacement of document head for instant navigation
+ * Improved compatibility of new emoji extension with Python < 3.10
+ * Switched regex dependency to use minimal version
+ * Refactored alignment and spacing of sidebar navigation
+ * Fixed expansion button not focusable via keyboard in sidebar navigation
+ * Fixed viewport offset restoration on first load when using instant navigation
+ * Fixed accidental highlight of non-clickable elements in blog plugin sidebar
+ * Fixed #6041: Blog plugin crashes when nav is defined and blog not included
+ * Fixed #5972: Blog plugin ignores section index pages in paginated views
+ * Fixed #5954: Repeated click on anchor ignored when using instant navigation
+ * Fixed #5742: Keyboard navigation broken when using instant navigation
+
+ Updated templates
+
+ * partials/nav-item.html
+ * blog-post.html
+
+mkdocs-material-9.4.1 (2023-09-22)
+
+ * Improved colors and contrast in dark mode
+ * Improved admonition borders to match font weight
+ * Switched content tabs to neutral color
+
+mkdocs-material-9.4.0 (2023-09-21)
+
+ * Added Belarusian translations
+ * Added version info to entrypoint of package
+ * Added emoji extension as a replacement for materialx
+ * Improved slate color scheme (dark mode) - now even darker
+ * Restructured project to improve development experience
+ * Updated MkDocs to 1.5.3
+ * Fixed #3890: Development mode crashes on Linux
+
+mkdocs-material-9.3.2+insiders-4.42.0 (2023-09-19)
+
+ * Added support for using git submodules in projects plugin
+ * Added support for transforming project configurations
+ * Improved resilience of optimize and blog plugin
+ * Fixed optimize plugin crashing on .jpeg extension
+ * Fixed project URLs not using site URLs in projects plugin
+
+mkdocs-material-9.3.2 (2023-09-19)
+
+ * Updated Slovenian translations
+ * Updated Python dependencies in requirements to use minimum versions
+ * Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
+ * Fixed #6001: Contributor avatars display incorrectly in Firefox
+ * Fixed #6000: Blog post drafts are included in navigation
+
+mkdocs-material-9.3.1+insiders-4.41.0 (2023-09-11)
+
+ * Improved multi-instance support for optimize plugin
+ * Added inclusion and exclusion patterns for optimize plugin
+ * Added transparent keyword for color handling in social plugin
+ * Changed default quality of PNGs to 3 in optimize plugin
+ * Fixed #5979: meta file not detected in root of docs directory
+
+mkdocs-material-9.3.1 (2023-09-11)
+
+ * Fixed crash of group plugin when used together with hooks
+
+mkdocs-material-9.3.0 (2023-09-11)
+
+ * Improved configuration sharing between Community and Insiders edition
+ * Added experimental built-in group plugin for enabling plugins conditionally
+ * Added new settings in tags plugin for enabling/disabling
+ * Dropped support for Python 3.7 (EOL)
+
+mkdocs-material-9.2.8+insiders-4.40.4 (2023-09-04)
+
+ * Fixed privacy plugin choking on boolean HTML5 attributes
+ * Fixed wrapping of inline code blocks in typeset table of contents
+ * Fixed blog plugin error when running under dirty reload
+
+mkdocs-material-9.2.8 (2023-09-04)
+
+ * Updated Italian and Russian translations
+ * Fixed #5952: Combining blog and tags plugin leads to wrong links
+ * Fixed #5951: Blog plugin ignores post title in metadata
+ * Fixed #5949: Blog plugin ignores post linked in nav
+
+mkdocs-material-9-2.7+insiders-4.40.3 (2023-09-02)
+
+ * Fixed #5946: Docker image missing pngquant for optimize plugin
+
+mkdocs-material-9.2.7 (2023-09-02)
+
+ * Switched dependencies to compatible release clauses
+ * Removed readtime and lxml dependencies for blog plugin
+ * Reduced size of Docker image to improve CI build performance
+ * Fixed #5945: Incorrect footer navigation for sibling pages of blog
+ * Fixed #5939: Page jumps when changing color palette (Firefox 117)
+ * Fixed #5901: Announcement bar reappears when using instant loading
+ * Fixed #5824: Allow to customize styles of sequence diagrams
+
+mkdocs-material-9-2.6+insiders-4.40.2 (2023-08-31)
+
+ * Added configurable error handling capabilities for social plugin
+ * Fixed #5922: Blog plugin shows no posts when building a standalone blog
+ * Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
+ * Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
+
+mkdocs-material-9-2.6 (2023-08-31)
+
+ * Added Basque translations
+ * Added template for simple redirects
+ * Improved blog plugin interop by moving view generation to on_files
+ * Fixed #5924: Social plugin still checks dependencies when disabled
+ * Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
+
+mkdocs-material-9-2.5+insiders-4.40.1 (2023-08-27)
+
+ * Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
+ * Fixed empty category pages in blog plugin (4.40.0 regression)
+
+mkdocs-material-9-2.5 (2023-08-27)
+
+ * Fixed error in dirty serve mode when using blog plugin
+ * Fixed page title not being consistent in blog plugin pagination
+ * Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
+
+mkdocs-material-9.2.4+insiders-4.40.0 (2023-08-26)
+
+ * Added logo, title and description options to social plugin default layouts
+ * Fixed privacy plugin compatibility issue with Python < 3.10
+ * Fixed #5896: Blog plugin errors when using custom index pages
+
+mkdocs-material-9.2.4 (2023-08-26)
+
+ * Added version to bug report name in info plugin
+ * Updated Afrikaans translations
+
+mkdocs-material-9.2.3+insiders-4.39.3 (2023-08-24)
+
+ * Fixed lxml dependency missing in Docker image (4.39.2 regression)
+
+mkdocs-material-9.2.3+insiders-4.39.2 (2023-08-23)
+
+ * Fixed color palette toggle being reversed (9.2.0 regression)
+
+mkdocs-material-9.2.3 (2023-08-22)
+
+ * Fixed blog plugin rendering wrongly with markdown.extensions.toc
+ * Fixed blog plugin entrypoint generation
+
+mkdocs-material-9.2.2 (2023-08-22)
+
+ * Fixed #5880: Blog plugin failing when building a standalone blog
+ * Fixed #5881: Blog plugin not compatible with Python < 3.10
+
+mkdocs-material-9.2.1 (2023-08-21)
+
+ * Fixed #5879: Blog plugin failing when building a standalone blog
+ * Fixed error in blog plugin when using draft tagging on future date
+ * Fixed error in blog plugin when toc extension is not enabled
+
+mkdocs-material-9.2.0+insiders-4.39.1 (2023-08-21)
+
+ * Fixed git diff in tags plugin after merging back 9.2.0 changes
+
+mkdocs-material-9.2.0 (2023-08-21)
+
+ Additions and improvements
+
+ * Added blogging support via built-in blog plugin
+ * Added support for Chinese language segmentaiton in search plugin
+ * Added support for adding custom dates to blog posts
+ * Added support for paginating archive and category pages
+ * Added support for annotations (outside of code blocks)
+ * Added support for navigation icons
+ * Added support for navigation pruning
+ * Added support for navigation status
+ * Added support for customizing site icons
+ * Added support for customizing (code) annotation icons
+ * Added focus outline to admonitions and details
+ * Added prompt for bug report name to info plugin
+ * Added Luxembourgish translations
+ * Improved rendering of (code) annotation markers
+ * Improved print styles for (code) annotations
+ * Improved customizability of navigation tabs
+ * Improved interop of plugins with external tools like mike
+ * Improved interop of blog plugin with awesome pages plugin
+ * Improved header partial by moving buttons into separate partials
+ * Improved clarity of site_url warning in social plugin
+ * Improved blog plugin to automatically setup directory structure
+ * Switched info plugin to importlib to mitigate deprecations
+ * Automatically download ResizeObserver polyfill when necessary
+ * Automatically add iframe-worker polyfill when necessary in offline plugin
+ * Automatically focus and bring up keyboard on touch devices
+ * Updated Serbo-Croatian translations
+ * Updated MkDocs to 1.5.2
+
+ Removals
+
+ * Removed Universal Analytics integration
+ * Removed ancient polyfills to reduce size of bundled JavaScript by 20%
+ * Removed necessity for Array.flat and Array.flatMap polyfill
+ * Removed announcement bar button when JavaScript is not available
+
+ Fixes
+
+ * Fixed rendering of tags when announcement bar is present
+ * Fixed tags plugin rendering pages excluded by other plugins
+ * Fixed #5132: Blog plugin requires nav entry in mkdocs.yml
+ * Fixed #5599: Insufficient contrast for default link color
+ * Fixed #5715: Blog plugin missing integrated table of contents in pagination
+ * Fixed #5806: Version selector not hoverable on some Android devices
+ * Fixed #5826: Blog post drafts with tags show up in tags index
+
+mkdocs-material-9.1.21+insiders-4.39.0 (2023-08-01)
+
+ * Added support for hoisting theme media files when building projects
+ * Added support for sorting pages on tags index for tags plugin
+ * Added support for adding date of last update to blog posts
+ * Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
+mkdocs-material-9.1.21+insiders-4.38.1 (2023-08-01)
+
+ * Improved nested serve mode for projects plugin
+ * Improved compat in privacy plugin with third-party plugins
+ * Fixed #5790: Typeset plugin ignores data-toc-label attribute
+ * Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+ * Fixed #5773: Info plugin erroring when community edition is in beta
+
+mkdocs-material-9.1.21+insiders-4.38.0 (2023-07-29)
+
+ * Added projects plugin for building nested projects
+ * Updated privacy plugin to new MkDocs API
+
+mkdocs-material-9.1.21+insiders-4.37.1 (2023-07-28)
+
+ * Updated MkDocs to 1.5.1
+ * Fixed deprecation warning in social plugin due to MkDocs upgrade
+ * Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+mkdocs-material-9.1.21 (2023-07-27)
+
+ * Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
+mkdocs-material-9.1.20 (2023-07-27)
+
+ * Fixed deprecation warnings for social plugin
+
+mkdocs-material-9.1.19 (2023-07-18)
+
+ * Added support for MkDocs 1.5+
+ * Fixed #5699: Improve error reporting in social plugin
+
+mkdocs-material-9.1.18+insiders-4.37.0 (2023-07-07)
+
+ * Added support for overriding social cards settings per page
+ * Added new social card default/only/image layout
+ * Improved resilience of optimize and social plugin
+ * Fixed rendering bugs for pruned navigation items
+ * Fixed jumping of content tabs anchor links when instant loading is enabled
+ * Fixed #5676: Optimize plugin doesn't check for pngquant
+
+mkdocs-material-9.1.18 (2023-07-03)
+
+ * Updated Danish translations
+ * Added support for installing user requirements in Docker image
+ * Fixed #5655: Search separator with lookbehind breaks highlighting
+
+mkdocs-material-9.1.17+insiders-4.36.1 (2023-06-23)
+
+ * Fixed #5618: Date comparison breaking for drafts in blog plugin
+
+mkdocs-material-9.1.17 (2023-06-23)
+
+ * Fixed #5633: Code annotations with nested lists incorrectly mounted
+ * Fixed #5628: Regression in new social plugin configuration scheme
+
+mkdocs-material-9.1.16+insiders-4.36.0 (2023-06-15)
+
+ * Added support for instant prefetching to speed up slow connections
+ * Improved stability of anchor link removal in built-in typeset plugin
+ * Improved performance of regular expressions in typeset plugin
+ * Removed unnecessary import test for cairosvg in optimize plugin
+ * Fixed #5590: regular expression for anchor link removal too greedy
+
+mkdocs-material-9.1.16 (2023-06-15)
+
+ * Updated Indonesian translations
+ * Ensure scroll bar follows color scheme of operating system
+
+mkdocs-material-9.1.15+insiders-4.35.3 (2023-06-01)
+
+ * Fixed #5579: Abbreviations in headlines filtered by typeset plugin
+
+mkdocs-material-9.1.15+insiders-4.35.2 (2023-05-29)
+
+ * Fixed #5555: Blog plugin crashes when computing readtime for emojis
+
+mkdocs-material-9.1.15 (2023-05-29)
+
+ * Fixed #5566: Indicate color scheme to operating system
+ * Fixed #5565: Update Dockerfile to latest version of base image
+ * Fixed #5554: Add additional version tags (9, 9.1) to Docker image
+ * Fixed #5536: Strip tags of ARIA labels in table of contents
+
+mkdocs-material-9.1.14+insiders-4.35.1 (2023-05-20)
+
+ * Fixed internal handling of errors in social plugin
+
+mkdocs-material-9.1.14+insiders-4.35.0 (2023-05-20)
+
+ * Improve editing experience and stability of social plugin
+ * Added support for custom layout syntax validation in social plugin
+ * Added support for layer origin for easier placement in social plugin
+ * Added support for in- and exclusion patterns in social plugin
+ * Catch and print syntax errors in custom layouts
+
+mkdocs-material-9.1.14 (2023-05-20)
+
+ * Updated Armenian and Greek translations
+
+mkdocs-material-9.1.13+insiders-4.34.1 (2023-05-16)
+
+ * Disable social plugin debug mode by default on mkdocs build
+ * Added warning in social plugin debug mode when font style couldn't be found
+ * Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+ * Fixed #5521: Social plugin triggers race condition when downloading fonts
+ * Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+mkdocs-material-9.1.13 (2023-05-16)
+
+ * Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+mkdocs-material-9.1.12+insiders-4.34.0 (2023-05-14)
+
+ * Added support for new overflow mode to auto-fit text in social plugin
+ * Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+ * Improved print styles for (code) annotation lists
+ * Improved performance of social plugin, now 3x as fast
+ * Improved interop of typeset plugin with MkDocstrings
+ * Fixed logo location for variants of default template in social plugin
+ * Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+mkdocs-material-9.1.12+insiders-4.33.2 (2023-05-12)
+
+ * Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+ * Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+ * Fixed #5505: Social plugin trying to resolve logo in wrong location
+ * Fixed #5496: Annotations with nested lists incorrectly mounted
+ * Fixed #5493: Social plugin crashes on Python 3.8
+
+mkdocs-material-9.1.12 (2023-05-12)
+
+ * Updated Bengali (Bangla) translations
+ * Fixed #5503: Docker image publish errors on uppercase characters
+ * Fixed #5407: Auto-pause media when in hidden content tabs
+
+mkdocs-material-9.1.11+insiders-4.33.1 (2023-05-09)
+
+ * Added support for SVG background images in social plugin
+
+mkdocs-material-9.1.11 (2023-05-08)
+
+ * Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+mkdocs-material-9.1.10+insiders-4.33.0 (2023-05-08)
+
+ * Added support for custom layouts for social plugin
+ * Added support for background images for social cards
+
+mkdocs-material-9.1.10 (2023-05-08)
+
+ * Added cards_layout_options setting for social cards
+ * Deprecated cards_color and cards_font setting for social cards
+
+mkdocs-material-9.1.9 (2023-05-02)
+
+ * Added Telugu, Kannada and Sanskrit translations
+ * Fixed #5428: Fixed margins for light/dark mode images in figures
+ * Fixed #5420: Social plugin crashing for some specific Google Fonts
+ * Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+ * Fixed #4920: Social plugin not loading logo from custom icon set
+ * Fixed social plugin crashing when only code font is specified
+
+mkdocs-material-9.1.8 (2023-04-24)
+
+ * Fixed #5417: Theme breaks when palette is not defined (9.1.7 regression)
+
+mkdocs-material-9.1.7+insiders-4.32.6 (2023-04-22)
+
+ * Fixed #5336: Interplay of blog plugin with git-revision-date-localized
+
+mkdocs-material-9.1.7 (2023-04-22)
+
+ * Updated Persian (Farsi) and Turkish translations
+ * Fixed #5401: Added missing flag to disable built-in tags plugin
+ * Fixed #5206: Ensure defaults are set for primary and accent colors
+ * Fixed unnecessary inclusion of palette CSS when unused
+
+mkdocs-material-9.1.6+insiders-4.32.5 (2023-04-07)
+
+ * Fixed #5322: Navigation tabs hoist nested page icons
+
+mkdocs-material-9.1.6 (2023-04-07)
+
+ * Updated Persian (Farsi) translations
+ * Fixed #5300: Boxes in Mermaid sequence diagrams not color-abiding
+
+mkdocs-material-9.1.5 (2023-03-31)
+
+ * Updated Lithuanian and Japanese translations
+ * Updated Mermaid.js to version 9.4.3
+ * Fixed #5290: Footer previous/next labels cut-off for short page titles
+
+mkdocs-material-9.1.4+insiders-4.32.4 (2023-03-24)
+
+ * Fixed #5241: Built-in typeset plugin jams navigation for anchors in headings
+
+mkdocs-material-9.1.4 (2023-03-24)
+
+ * Fixed #5239: Instant loading breaks anchors in details (9.1.1 regression)
+ * Fixed #5211: Anchor following not working for Chinese (9.1.2 regression)
+
+mkdocs-material-9.1.3 (2023-03-14)
+
+ * Added Kurdish (Soranî) translations
+ * Updated Norwegian (Bokmål), Portuguese and Romanian translations
+ * Improved compatibility with mkdocs-jupyter plugin
+ * Fixed #5198: Built-in search plugin not filtering script and style tags
+ * Fixed #5176: Back-to-top + instant loading not working (9.1.1 regression)
+
+mkdocs-material-9.1.2+insiders-4.32.3 (2023-03-09)
+
+ * Fixed Docker image release workflow (9.1.0 regression)
+ * Fixed #5159: Missing underline for abbreviations (9.1.0 regression)
+
+mkdocs-material-9.1.2 (2023-03-09)
+
+ * Updated Icelandic, Korean and Swedish translations
+ * Fixed #5168: Mermaid text boxes overflow (9.0.13 regression)
+ * Fixed #5155: Table of contents not highlighting percent-encoded URLs
+
+mkdocs-material-9.1.1 (2023-03-05)
+
+ * Updated Czech and Thai translations
+ * Improved instant loading (scroll restoration, slow connections)
+ * Fixed #5023: Instant loading not allowing to go back to initial page
+ * Fixed #3797: Instant loading does not work with section anchors in Safari
+
+mkdocs-material-9.1.0+insiders-4.32.2 (2023-03-02)
+
+ * Fixed #5127: Privacy plugin not handling large number of occurrences
+ * Fixed #5126: Privacy plugin breaks when replacing specific emojis
+
+mkdocs-material-9.1.0 (2023-03-02)
+
+ * Docker image now available for amd64, arm64 and arm/v7
+ * Updated Chinese (Taiwanese) translations
+ * Generalized tag identifier implementation
+ * Fixed flickering of header shadow on load
+ * Fixed occasional flickering of announcement bar
+
+mkdocs-material-9.0.15 (2023-02-26)
+
+ * Updated Chinese (Traditional) translations
+ * Updated Hebrew translations
+
+mkdocs-material-9.0.14+insiders-4.32.1 (2023-02-23)
+
+ * Fixed code block spans interfering with copying
+ * Fixed #5077: Privacy plugin breaks image alt text encoding
+ * Fixed #5079: Privacy plugin removing rel=me on external links
+
+mkdocs-material-9.0.14 (2023-02-23)
+
+ * Fixed #5072: Rendering bug on navigation expand button in Firefox
+
+mkdocs-material-9.0.13+insiders-4.32.0 (2023-02-19)
+
+ * Added support for custom selectors for code annotations
+ * Added support for code line range selection for better sharing
+
+mkdocs-material-9.0.13+insiders-4.31.0 (2023-02-18)
+
+ * Added support for table of contents on blog index and archive pages
+ * Fixed #4512: Allow custom search field boosts (experimental)
+
+mkdocs-material-9.0.13 (2023-02-18)
+
+ * Updated Uzbek translations
+ * Switched back to pre-9.0.0 headline detection in content partial
+ * Fixed #5062: Version warning not readable when using slate scheme
+ * Fixed #5061: Improved discernibility of table row hover color
+ * Fixed #5034: Sequence actors in Mermaid diagrams not color-abiding
+ * Fixed #4919: Allow to hide version warning in multiple versions
+
+mkdocs-material-9.0.12+insiders-4.30.2 (2023-02-13)
+
+ * Fixed privacy plugin excludes not working (4.30.0 regression)
+
+mkdocs-material-9.0.12+insiders-4.30.1 (2023-02-12)
+
+ * Fixed privacy plugin not handling static templates e.g. 404.html
+
+mkdocs-material-9.0.12 (2023-02-09)
+
+ * Updated Catalan translations
+ * Fixed #4975: Mermaid entity relationship rendering diagrams bug
+ * Fixed #4924: Header title not reset when using instant loading
+
+mkdocs-material-9.0.11+insiders-4.30.0 (2023-02-06)
+
+ * Rewrite of privacy plugin for concurrency, now twice as fast
+ * Added support for explicit inclusion for privacy plugin
+ * Added optimization support for privacy plugin (+ optimize plugin)
+
+mkdocs-material-9.0.11 (2023-02-03)
+
+ * Added Mastodon verification for social links (rel=me)
+ * Updated Italian translations
+
+mkdocs-material-9.0.10 (2023-02-02)
+
+ * Updated Arabic translations
+ * Updated Korean translations
+ * Updated Hungarian translations
+ * Updated Russian translations
+ * Fixed #4977: Improved accessibility for content tabs
+ * Fixed #4960: Sometimes anchor following doesn't bring last item into view
+
+mkdocs-material-9.0.9 (2023-01-30)
+
+ * Updated Bulgarian translations
+ * Updated Chinese (Simplified) translations
+ * Updated Dutch translations
+ * Updated Hindi translations
+ * Updated Japanese translations
+ * Updated Polish translations
+
+mkdocs-material-9.0.8 (2023-01-29)
+
+ * Updated Croatian translations
+ * Updated French translations
+ * Updated Hungarian translations
+ * Updated Portuguese (Brasilian) translations
+ * Updated Spanish translations
+ * Updated Ukrainian translations
+ * Updated Urdu translations
+ * Updated Vietnamese translations
+
+mkdocs-material-9.0.7 (2023-01-28)
+
+ * Improved accessibility of sidebar navigation
+ * Moved all translations into Community edition
+ * Updated Polish and Portuguese (Brasilian) translations
+ * Fixed info plugin terminating on subsequent reload when serving
+ * Fixed #4910: Sidebar navigation labels have invalid ARIA roles
+ * Fixed #4884: Search query terms can't be separated by colons
+
+mkdocs-material-9.0.6+insiders-4.29.0 (2023-01-21)
+
+ * Added built-in optimize plugin for automatically compressing images
+ * Switched reporting in built-in privacy plugin to info level
+
+mkdocs-material-9.0.6 (2023-01-19)
+
+ * Fixed #4883: Automatically disable info plugin when serving
+ * Fixed #4885: Search plugin crashes in some exotic cases (9.0.3 regression)
+
+mkdocs-material-9.0.5+insiders-4.28.1 (2023-01-17)
+
+ * Fixed built-in info plugin erroring for Insiders on version check
+ * Fixed #4865: Navigation paths render bug when there's no top-level section
+ * Fixed #4875: Added support for hiding navigation paths
+ * Improved navigation path to not render for a single item
+
+mkdocs-material-9.0.5+insiders-4.28.0 (2023-01-14)
+
+ * Added support for navigation path (breadcrumbs)
+
+mkdocs-material-9.0.5 (2023-01-14)
+
+ * Fixed #4842: Improved accessibility of search result list
+
+mkdocs-material-9.0.4 (2023-01-12)
+
+ * Fixed #4823: Improved contrast ratio in footer (9.0.2 regression)
+ * Fixed #4832: Set navigation items back to black (9.0.3 regression)
+ * Fixed #4843: Emojis broken due to maxcdn.com shutting down
+ * Upgraded Python Markdown Extensions to 9.9.1
+
+mkdocs-material-9.0.3+insiders-4.27.1 (2023-01-08)
+
+ * Fixed rendering of succeeding navigation items in typeset plugin
+ * Fixed #4795: Built-in typeset plugin changes MkDocs' title precedence
+ * Fixed #4724: Blog plugin not rendering integrate table of contents
+
+mkdocs-material-9.0.3 (2023-01-08)
+
+ * Improved discernibility of section index pages in navigation
+ * Improved collapsing of adjacent whitespace in search plugin
+ * Updated Indonesian translations
+ * Fixed view source of this page button when edit URL points to blob
+ * Fixed #4829: Search overlay does not close for active anchor result
+ * Fixed #4824: Search plugin crashes for h1-6 contained in other elements
+ * Fixed #4804: Nested navigation items not expandable with keyboard
+ * Fixed #4689: anchor tracking not working for anchors in tables
+ * Upgraded to Mermaid 9.3.0
+
+mkdocs-material-9.0.2 (2023-01-04)
+
+ * Fixed #4823: Improved contrast ratio in footer to meet WCAG guidelines
+ * Fixed #4819: Social plugin crashes when card generation is disabled
+ * Fixed #4817: Search plugin crashes on numeric page titles in nav
+
+mkdocs-material-9.0.1 (2023-01-03)
+
+ * Removed pipdeptree dependency for built-in info plugin
+ * Fixed appearance of linked tags when hovered (9.0.0 regression)
+ * Fixed #4810: Abbreviations run out of screen on touch devices
+ * Fixed #4813: View source and edit button links are the same
+
+mkdocs-material-9.0.0 (2023-01-02)
+
+ Additions and improvements
+
+ * Added support for rich search previews
+ * Added support for tokenizer lookahead
+ * Added support for better search highlighting
+ * Added support for excluding content from search
+ * Added support for configurable search pipeline
+ * Added support for offline search via offline plugin
+ * Added support for multiple instances of built-in tags plugin
+ * Added support for removing copy-to-clipboard button
+ * Added support for removing footer navigation
+ * Added support for button to view the source of a page
+ * Improved readability of query string for search sharing
+ * Improved stability of search plugin when using --dirtyreload
+ * Improved search result group button, now sticky and stable
+ * Updated Norwegian translations
+ * Updated MkDocs to 1.4.2
+
+ Removals
+
+ * Removed deprecated alternative admonition qualifiers
+ * Removed :is() selectors (in output) for easier overriding
+ * Removed .title suffix on translations
+ * Removed legacy method for providing page title in feedback URL
+ * Removed support for indexing only titles in search
+ * Removed support for custom search transforms
+ * Removed support for custom search workers
+ * Removed temporary snow feature (easter egg)
+
+ Fixes
+
+ * Fixed Norwegian and Korean language code
+ * Fixed detection of composition events in search interface
+ * Fixed search plugin not using title set via front matter
+ * Fixed search highlighting of tags
+ * Fixed search sharing URL using post transformed string
+ * Fixed theme-color meta tag getting out-of-sync with palette toggle
+ * Fixed prev/next page keyboard navigation when footer is not present
+ * Fixed overflowing navigation tabs not being scrollable
+ * Fixed inclusion of code block line numbers from search
+
+mkdocs-material-8.5.11+insiders-4.27.0 (2022-12-20)
+
+ * Added built-in typeset plugin to preserve formatting in sidebars
+ * Added URL and table of contents support for blog categories
+
+mkdocs-material-8.5.11 (2022-11-30)
+
+ * Let it snow, see https://x.com/squidfunk/status/1597939243090788352
+
+mkdocs-material-8.5.10+insiders-4.26.6 (2022-11-28)
+
+ * Fixed #4683: Tags plugin crashes when a tag is empty
+
+mkdocs-material-8.5.10+insiders-4.26.5 (2022-11-27)
+
+ * Fixed #4632: Post excerpt title link doesn't point to top of the page
+
+mkdocs-material-8.5.10+insiders-4.26.4 (2022-11-27)
+
+ * Fixed redundant file extension when using privacy plugin
+
+mkdocs-material-8.5.10+insiders-4.26.3 (2022-11-15)
+
+ * Fixed #4637: Attachments w/o titles in related links error in blog plugin
+ * Fixed #4631: Remote favicons not downloaded and inlined by privacy plugin
+
+mkdocs-material-8.5.10 (2022-11-11)
+
+ * Adjusted CSS to better allow for custom primary and accent colors
+ * Fixed #4620: Primary color is not applied (8.5.9 regression)
+
+mkdocs-material-8.5.9 (2022-11-08)
+
+ * Fixed #4600: Illegible link colors for black and white primary colors
+ * Fixed #4594: Need to set schema to change link color
+
+mkdocs-material-8.5.8+insiders-4.26.2 (2022-11-03)
+
+ * Updated MkDocs to 1.4.2
+ * Added support for tag compare functions when sorting on index pages
+ * Fixed footnotes being rendered in post excerpts without separators
+ * Fixed error in blog plugin when toc extension is not enabled
+ * Fixed issues with invalid asset paths and linked post titles
+ * Fixed #4572: Privacy plugin fails when symlinks cannot be created
+ * Fixed #4545: Blog plugin doesn't automatically link headline to post
+ * Fixed #4542: Blog plugin doesn't allow for multiple instances
+ * Fixed #4532: Blog plugin doesn't allow for mixed use of date and datetime
+
+mkdocs-material-8.5.8 (2022-11-03)
+
+ * Added support for always showing settings in cookie consent
+ * Fixed #4571: Buttons invisible if primary color is white or black
+ * Fixed #4517: Illegible note in sequence diagram when using slate scheme
+
+mkdocs-material-8.5.7+insiders-4.26.1 (2022-10-22)
+
+ * Improved reporting of configuration errors in tags plugin
+ * Fixed #4515: Privacy plugin fails when site URL is not defined
+ * Fixed #4514: Privacy plugin doesn't fetch Google fonts (4.26.0 regression)
+
+mkdocs-material-8.5.7 (2022-10-22)
+
+ * Deprecated additional admonition qualifiers to reduce size of CSS
+ * Fixed #4511: Search boost does not apply to sections
+
+mkdocs-material-8.5.6+insiders-4.26.0 (2022-10-18)
+
+ * Refactored privacy plugin to prepare for new features
+ * Added support for rel=noopener links in privacy plugin
+ * Resolve encoding issues with blog and privacy plugin
+
+mkdocs-material-8.5.6+insiders-4.25.5 (2022-10-16)
+
+ * Updated MkDocs to 1.4.1
+ * Added namespace prefix to built-in plugins
+ * Updated content and header partial
+
+mkdocs-material-8.5.6+insiders-4.25.4 (2022-10-09)
+
+ * Fixed other path issues for standalone blogs (4.24.2 regression)
+
+mkdocs-material-8.5.6+insiders-4.25.3 (2022-10-09)
+
+ * Fixed #4457: Posts not collected for standalone blog (4.24.2 regression)
+
+mkdocs-material-8.5.6+insiders-4.25.2 (2022-10-04)
+
+ * Fixed #4452: Blog and tags plugin crash when specifying slugify function
+
+mkdocs-material-8.5.6+insiders-4.25.1 (2022-10-03)
+
+ * Updated mkdocs-rss-plugin in Dockerfile to fix MkDocs compat errors
+
+mkdocs-material-8.5.6+insiders-4.25.0 (2022-10-02)
+
+ * Added support for navigation subtitles
+ * Added support for defining an allow list for built-in tags plugin
+ * Added support for custom slugify functions for built-in tags plugin
+ * Improved stability of search plugin when using --dirtyreload
+
+mkdocs-material-8.5.6 (2022-10-02)
+
+ * Modernized appearance of admonitions (with fallback, see docs)
+ * Improved appearance of inline code blocks in admonition titles
+
+mkdocs-material-8.5.5+insiders-4.24.2 (2022-10-01)
+
+ * Updated MkDocs to 1.4
+ * Fixed compatibility issues with MkDocs 1.4
+ * Fixed incorrectly generated paths in privacy plugin
+ * Fixed blog index page not showing navigation when using meta plugin
+
+mkdocs-material-8.5.5 (2022-10-01)
+
+ * Updated MkDocs to 1.4
+ * Fixed compatibility issues with MkDocs 1.4
+ * Fixed #4430: build error when enabling consent without repository URL
+
+mkdocs-material-8.5.4+insiders-4.24.1 (2022-09-30)
+
+ * Fixed #4430: build error when enabling consent without repository URL
+
+mkdocs-material-8.5.4 (2022-09-30)
+
+ * Fixed expand icons shift on sidebar overflow (using scrollbar-gutter)
+ * Fixed #4429: Text in sequence diagrams overflows in Firefox
+
+mkdocs-material-8.5.3+insiders-4.24.0 (2022-09-27)
+
+ * Added support for custom content on index pages (blog)
+ * Added support for keeping content on paginated index pages (blog)
+ * Added support for limiting categories in post excerpts (blog)
+ * Added support for simple override of templates via front matter (blog)
+ * Added icon in navigation for pages with encrypted content
+ * Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+ * Improved performance by building post excerpts once (blog)
+
+mkdocs-material-8.5.3+insiders-4.23.6 (2022-09-22)
+
+ * Fixed #4389: Blog posts in first week of year in wrong archive
+ * Fixed (= switched) footer previous and next links for blog posts
+
+mkdocs-material-8.5.3 (2022-09-20)
+
+ * Fixed build error when enabling cookie consent without analytics
+ * Fixed #4381: Code blocks render ligatures for some fonts
+
+mkdocs-material-8.5.2+insiders-4.23.5 (2022-09-18)
+
+ * Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+ * Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+mkdocs-material-8.5.2 (2022-09-18)
+
+ * Updated Mermaid.js to version 9.1.7
+ * Fixed overly large headlines in search results (8.5.0 regression)
+ * Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+ * Fixed #4356: GitHub repository statistics fetched before cookie consent
+
+mkdocs-material-8.5.1 (2022-09-15)
+
+ * Fixed #4366: Removed dependencies with native extensions
+
+mkdocs-material-8.5.0+insiders-4.23.4 (2022-09-14)
+
+ * Fixed #4365: Recursion error in blog plugin due to deepcopy
+ * Fixed path errors for blog plugin on Windows
+ * Fixed publishing workflow in forked repositories
+
+mkdocs-material-8.5.0+insiders-4.23.3 (2022-09-13)
+
+ * Fixed previous and next page links for drafts of blog posts
+
+mkdocs-material-8.5.0 (2022-09-13)
+
+ * Added support for social cards
+ * Added support for code annotation anchor links (deep linking)
+ * Added support for code annotation comment stripping (syntax modifier)
+ * Added support for sidebars scrolling automatically to active item
+ * Added support for anchor following table of contents (= auto scroll)
+ * Added support for tag icons
+
+mkdocs-material-8.4.4+insiders-4.23.2 (2022-09-13)
+
+ * Fixed #4348: Blog plugin crashes on custom nav title
+ * Fixed blog plugin crashing when category contained only drafts
+ * Fixed rendering of content from blog index file
+
+mkdocs-material-8.4.4+insiders-4.23.1 (2022-09-12)
+
+ * Fixed #4345: Blog plugin errors with default settings
+
+mkdocs-material-8.4.4+insiders-4.23.0 (2022-09-12)
+
+ * Added blogging support via built-in blog plugin
+
+mkdocs-material-8.4.4 (2022-09-12)
+
+ * Moved comments integration to separate partial (comments.html)
+
+mkdocs-material-8.4.3+insiders-4.22.1 (2022-09-07)
+
+ * Fixed #4217: Tooltips in data tables render in wrong position
+
+mkdocs-material-8.4.3 (2022-09-07)
+
+ * Added Simple Icons to bundled icons (+2,300 icons)
+ * Added support for changing edit icon
+ * Moved page actions to separate partial (actions.html)
+ * Fixed #4291: Version switching doesn't stay on page when anchors are used
+ * Fixed #4327: Links in data tables do not receive link styling
+
+mkdocs-material-8.4.2 (2022-08-27)
+
+ * Updated Slovenian translations
+ * Fixed #4277: Feedback widget hidden after navigation with instant loading
+ * Fixed numeric tags in front matter breaking search functionality
+
+mkdocs-material-8.4.1+insiders-4.22.0 (2022-08-21)
+
+ * Added support for navigation status
+
+mkdocs-material-8.4.1 (2022-08-21)
+
+ * Updated Croatian and Hebrew translations
+
+mkdocs-material-8.4.0+insiders-4.21.1 (2022-08-13)
+
+ * Fixed #4176: Broken image when avatar is served by Gravatar
+ * Fixed #4212: Deferred search initialization for file:// locations
+
+mkdocs-material-8.4.0 (2022-08-13)
+
+ * Added support for cookie consent
+ * Added support for feedback widget (Was this page helpful?)
+ * Added support for dismissible announcement bar
+ * Added Armenian, Lithuanian, Tagalog, and Urdu translations
+
+mkdocs-material-8.3.9+insiders-4.21.0 (2022-07-17)
+
+ * Added meta plugin: set front matter for all pages in a folder
+ * Fixed #4114: Tags plugin fails if only tags_extra_files is set
+
+mkdocs-material-8.3.9+insiders-4.20.1 (2022-07-11)
+
+ * Fixed #4105: Tags plugin fails if tags_file is not set (4.20.0 regression)
+
+mkdocs-material-8.3.9+insiders-4.20.0 (2022-07-07)
+
+ * Added support for additional tags indexes
+ * Fixed #4100: Tag icons not shown in tags index
+
+mkdocs-material-8.3.9+insiders-4.19.2 (2022-07-04)
+
+ * Fixed #4051: Privacy plugin fails if symlinking isn't allowed on Windows
+
+mkdocs-material-8.3.9 (2022-07-04)
+
+ * Updated Taiwanese translations for search
+ * Allow ids for content tabs with special characters (for mkdocstrings)
+ * Fixed #4083: home not clickable when using versioning (8.3.5 regression)
+
+mkdocs-material-8.3.8+insiders-4.19.1 (2022-06-25)
+
+ * Added mkdocs-git-committers-plugin to Dockerfile
+ * Added mkdocs-git-revision-date-localized-plugin to Dockerfile
+
+mkdocs-material-8.3.8+insiders-4.19.0 (2022-06-24)
+
+ * Added support for document contributors
+ * Updated French translations for cookie consent
+
+mkdocs-material-8.3.8 (2022-06-24)
+
+ * Fixed #4053: Limit width of videos to content area
+ * Fixed empty tags in front matter breaking search
+
+mkdocs-material-8.3.7 (2022-06-22)
+
+ * Fixed search being stuck initializing when using tags (8.3.4 regression)
+
+mkdocs-material-8.3.6+insiders-4.18.2 (2022-06-16)
+
+ * Fixed #4026: Fixed tooltips not mounted for nested navigation links
+
+mkdocs-material-8.3.6 (2022-06-16)
+
+ * Fixed #4028: Links not clickable when using versioning (8.3.5 regression)
+
+mkdocs-material-8.3.5+insiders-4.18.1 (2022-06-14)
+
+ * Fixed #3990: Chinese search highlighting not working on non-boundaries
+
+mkdocs-material-8.3.5 (2022-06-14)
+
+ * Fixed #4012: Stay on page not working for alias of active version
+
+mkdocs-material-8.3.4+insiders-4.18.0 (2022-06-11)
+
+ * Added support for automatic dark/light mode
+ * Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows
+
+mkdocs-material-8.3.4 (2022-06-11)
+
+ * Fixed #4004: Tags with multiple words not searchable
+
+mkdocs-material-8.3.3 (2022-06-07)
+
+ * Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression)
+
+mkdocs-material-8.3.2+insiders-4.17.2 (2022-06-05)
+
+ * Added support for custom jieba dictionaries (Chinese search)
+
+mkdocs-material-8.3.2+insiders-4.17.1 (2022-06-05)
+
+ * Added support for cookie consent reject button
+ * Added support for cookie consent custom button ordering
+ * Fixed #3988: Content tab not focused after alternating anchor links
+
+mkdocs-material-8.3.2 (2022-06-05)
+
+ * Fixed #3987: Custom admonition icons don't work when defining color palette
+
+mkdocs-material-8.3.1+insiders-4.17.0 (2022-06-04)
+
+ * Added support for content tabs anchor links (deep linking)
+ * Fixed #3975: Detect composition events in search interface (Chinese)
+ * Fixed #3980: Search plugin doesn't use title set via front matter
+
+mkdocs-material-8.3.1 (2022-06-04)
+
+ * Bump required Jinja version to 3.0.2
+ * Removed unnecessary conditions in templates
+ * Fixed scroll offset when content tabs are brought into view
+ * Fixed #3977: Content tabs snapping oddly in Firefox
+ * Fixed #3983: Missing condition in footer partial (8.3.0 regression)
+
+mkdocs-material-8.3.0 (2022-06-02)
+
+ * Added support for custom admonition icons
+ * Added support for linking of content tabs
+ * Added support for boosting pages in search
+ * Added support for hiding footer navigation
+ * Added previous/next indicators to content tabs
+ * Improved typeset link colors in light and dark modes
+
+mkdocs-material-8.2.16+insiders-4.16.2 (2022-05-28)
+
+ * Fixed #3961: Nested sections triggered build error for navigation tabs
+
+mkdocs-material-8.2.16+insiders-4.16.1 (2022-05-28)
+
+ * Switched feedback widget rating titles to tooltips
+ * Improved contrast of link colors for light/dark color schemes
+ * Fixed #3950: Sticky navigation tabs rendering broken (4.15.2 regression)
+ * Fixed #3958: Links invisible when using white primary color
+
+mkdocs-material-8.2.16 (2022-05-28)
+
+ * Fixed #3957: Only animate code annotations when visible (save CPU cycles)
+
+mkdocs-material-8.2.15+insiders-4.16.0 (2022-05-25)
+
+ * Added support for navigation pruning
+ * Fixed search results for non-segmented characters (4.15.2 regression)
+
+mkdocs-material-8.2.15+insiders-4.15.2 (2022-05-22)
+
+ * Removed workaround for abbr on touch devices (superseded by tooltips)
+ * Fixed #3915: Improved Chinese search query segmentation
+ * Fixed #3938: Fixed tooltips position for navigation titles with ellipsis
+
+mkdocs-material-8.2.15+insiders-4.15.1 (2022-05-14)
+
+ * Improved performance of element focus observables
+ * Fixed #3531: Added prev/next buttons to content tabs
+ * Fixed tooltip positioning when host element is hidden
+
+mkdocs-material-8.2.15 (2022-05-14)
+
+ * Added Uzbek translations
+ * Fixed spacing for code block results in content tabs
+
+mkdocs-material-8.2.14+insiders-4.15.0 (2022-05-08)
+
+ * Added support for improved tooltips
+ * Fixed #3785: Show tooltip on hover for overflowing navigation link
+
+mkdocs-material-8.2.14 (2022-05-08)
+
+ * Fixed missing top right rounded border on admonition
+ * Fixed #3886: 4xx status codes not handled when using instant loading
+
+mkdocs-material-8.2.13+insiders-4.14.0 (2022-05-05)
+
+ * Added Chinese language support to built-in search plugin
+ * Fixed all-numeric page titles raising error in social plugin
+
+mkdocs-material-8.2.13 (2022-05-02)
+
+ * Fixed #3865: Tags index links to tagged pages 404 on Windows
+ * Fixed #3866: Bump required Python version from 3.6+ to 3.7+
+
+mkdocs-material-8.2.12+insiders-4.13.2 (2022-04-30)
+
+ * Improved caching of downloaded resources in privacy plugin
+ * Fixed #3851: External images not downloaded by privacy plugin
+
+mkdocs-material-8.2.12 (2022-04-30)
+
+ * Added support for GitHub-style hash fragments for dark/light images
+ * Improved rendering of nested code blocks in content tabs and annotations
+ * Fixed #3862: Upgraded to latest Pygments and Python Markdown Extensions
+
+mkdocs-material-8.2.11+insiders-4.13.1 (2022-04-25)
+
+ * Fixed #3839: Tags plugin breaks without icons (4.13.0 regression)
+
+mkdocs-material-8.2.11 (2022-04-25)
+
+ * Temporarily pinned Pygments to <2.12
+ * Temporarily pinned Python Markdown Extensions to <9.4
+ * Improved rendering of code annotation markers
+
+mkdocs-material-8.2.10+insiders-4.13.0 (2022-04-24)
+
+ * Added support for tag icons
+
+mkdocs-material-8.2.10 (2022-04-24)
+
+ * Added Macedonian translations
+ * Updated Mermaid.js to version 9.0.1
+ * Switched sidebar title in mobile navigation to bold font
+ * Fixed color of arrows in class and state diagrams for dark mode
+ * Fixed #3836: Inline admonitions overlayed by code block titles
+
+mkdocs-material-8.2.9 (2022-04-08)
+
+ * Mitigate flicker on color palette switch by disabling all transitions
+ * Fixed search suggestions not triggered when following deep link
+ * Fixed incorrectly computed header height when using instant loading
+ * Fixed #3782: Admonition titles have extra pixels on wide screens in Firefox
+ * Fixed #3802: Always render table of contents container (except when hidden)
+
+mkdocs-material-8.2.8+insiders-4.12.0 (2022-03-27)
+
+ * Added support for card grids and grid layouts
+ * Fixed #3685: Annotations sometimes broken when using instant loading
+ * Fixed #3742: Automatically add Mermaid.js when building for offline usage
+
+mkdocs-material-8.2.8 (2022-03-27)
+
+ * Bumped MkDocs version to 1.3.0 to mitigate breaking changes in Jinja
+ * Reverted Jinja version range limitation (added in 8.2.7)
+ * Improved styling of annotations and fixed borders of code blocks in tabs
+ * Added background color to code blocks in focused/hovered links
+ * Added check in tags plugin whether tags overview page exists
+ * Fixed #3744: Content tab indicator on wrong position when using back button
+
+mkdocs-material-8.2.7 (2022-03-24)
+
+ * Temporarily limit Jinja version range to < 3.1 due to breaking changes
+
+mkdocs-material-8.2.6 (2022-03-23)
+
+ * Fixed #3695: Deprecation warning for unescaped backslashes in templates
+ * Fixed #3696: Annotations not mounted in some Terraform code blocks
+ * Fixed #3698: Annotations not mounted in long code blocks (8.2.5 regression)
+
+mkdocs-material-8.2.5+insiders-4.11.0 (2022-03-06)
+
+ * Added support for excluding external assets from privacy plugin
+
+mkdocs-material-8.2.5 (2022-03-06)
+
+ * Fixed #3596: Mermaid not working when headline with name 'Mermaid' present
+ * Fixed #3643: Reduce time to render pages with thousands of code blocks
+ * Fixed #3665: Missing styles for Mermaid.js flowcharts cluster labels
+
+mkdocs-material-8.2.4+insiders-4.10.1 (2022-03-02)
+
+ * Added missing build dependencies to Dockerfile
+ * Fixed encoding issues in privacy plugin, now forcing UTF-8 encoding
+ * Fixed #3624: Scroll to active navigation item unreliable in Firefox
+ * Fixed #3642: Privacy plugin errors when font setting was omitted
+
+mkdocs-material-8.2.4 (2022-03-02)
+
+ * Fixed malformed Google Fonts URL when a font setting was omitted
+ * Fixed #3648: Fixed specificity issue with admonitions in lists
+ * Fixed #3653: Invalid outdated version banner URL when using instant loading
+
+mkdocs-material-8.2.3+insiders-4.10.0 (2022-02-27)
+
+ * Added support for offline plugin (supersedes offline search support)
+ * Improved built-in privacy plugin to download nested JavaScript assets
+ * Refactored configuration of built-in privacy plugin
+
+mkdocs-material-8.2.3 (2022-02-27)
+
+ * Fixed #3578: Active element in table of contents off-by-one on large screens
+
+mkdocs-material-8.2.2 (2022-02-26)
+
+ * Added automatic removal of query parameter when search is closed
+ * Fixed #3599: Anchors always overridden when using navigation tracking
+
+mkdocs-material-8.2.1+insiders-4.9.1 (2022-02-21)
+
+ * Fixed #3610: missing lxml dependency for privacy plugin
+ * Fixed error when charset is missing in content-type header
+
+mkdocs-material-8.2.1+insiders-4.9.0 (2022-02-20)
+
+ * Added privacy plugin: automatic downloading of external assets
+
+mkdocs-material-8.2.1 (2022-02-17)
+
+ * Fixed module 'material.plugins' not being found (8.2.0 regression)
+
+mkdocs-material-8.2.0 (2022-02-17)
+
+ * Added native support for Mermaid.js diagrams
+ * Added native support for tags (with search integration)
+ * Added support for staying on page when switching versions
+
+mkdocs-material-8.1.11+insiders-4.8.3 (2022-02-13)
+
+ * Fixed #3560: Mermaid diagrams don't render for file:// locations
+
+mkdocs-material-8.1.11+insiders-4.8.2 (2022-02-10)
+
+ * Fixed #3559: Mermaid diagrams don't render inside closed details
+
+mkdocs-material-8.1.11 (2022-02-10)
+
+ * Added Portuguese (Brasilian) translations
+ * Updated FontAwesome to v6 (might lead to missing icons)
+ * Fixed #3545: Color palette toggle and search overlaying version selector
+
+mkdocs-material-8.1.10+insiders-4.8.1 (2022-02-06)
+
+ * Fixed jump back to top on mobile when using anchor following
+
+mkdocs-material-8.1.10+insiders-4.8.0 (2022-02-06)
+
+ * Added support for anchor following table of contents (= auto scroll)
+
+mkdocs-material-8.1.10 (2022-02-06)
+
+ * Fixed cutoff of very wide logos in the sidebar on mobile
+
+mkdocs-material-8.1.9+insiders-4.7.2 (2022-02-02)
+
+ * Fixed #3526: Transparent sidebar title due to Safari bug
+ * Fixed #3528: Firefox sometimes clips text in flow chart diagrams
+
+mkdocs-material-8.1.9+insiders-4.7.1 (2022-01-30)
+
+ * Fixed #3506: Tags index not respecting title set via front matter
+
+mkdocs-material-8.1.9 (2022-01-30)
+
+ * Added support for mkdocs.yml validation and auto-complete
+ * Fixed errors in Latvian translations
+
+mkdocs-material-8.1.8+insiders-4.7.0 (2022-01-25)
+
+ * Added native support for offline search
+
+mkdocs-material-8.1.8 (2022-01-23)
+
+ * Added Latvian translations
+ * Updated Giscus example integration with dynamic theme change support
+ * Fixed #3479: Back-to-top button not hidden when using sticky navigation tabs
+ * Fixed #3491: Logo in header and drawer doesn't honor aspect ratio
+
+mkdocs-material-8.1.7+insiders-4.6.1 (2022-01-16)
+
+ * Fixed #3459: Section index pages picking up wrong title
+
+mkdocs-material-8.1.7 (2022-01-16)
+
+ * Improved back-to-top button behavior - now not shown on anchor jump
+
+mkdocs-material-8.1.6-insiders-4.6.0 (2022-01-11)
+
+ * Added support for annotations (outside of code blocks)
+
+mkdocs-material-8.1.6 (2022-01-11)
+
+ * Fixed spacing of blockquotes (8.1.5 regression)
+ * Fixed edge cases for rounded corners on code blocks (8.1.5 regression)
+ * Fixed rendering issues with code annotation line heights
+
+mkdocs-material-8.1.5 (2022-01-09)
+
+ * Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+
+ * Improved rendering of inline code blocks in headlines
+ * Added Bahasa Malaysian translations
+ * Fixed #3354: MathJax formulas show vertical scrollbar
+
+mkdocs-material-8.1.4+insiders-4.5.2 (2022-01-08)
+
+ * Fixed #3440: Content tab indicator not moving when using linking
+ * Fixed #3445: Content tab switch flickers/jitters when using linking
+
+mkdocs-material-8.1.4+insiders-4.5.1 (2022-01-02)
+
+ * Added support for setting initial state of cookie consent
+ * Fixed #3396: Disappearing link in navigation due to Safari bug
+
+mkdocs-material-8.1.4 (2022-01-02)
+
+ * Added indicator to navigation expander icon
+ * Improved support for reduced motion preference
+ * Fixed jitter of active content tab indicator
+
+mkdocs-material-8.1.3 (2021-12-19)
+
+ * Added animation to active content tab indicator
+ * Fixed #3360: Highlighted lines add blank lines in copied text
+ * Fixed usage of subsequent index files when using section index pages
+
+mkdocs-material-8.1.2+insiders-4.5.0 (2021-12-16)
+
+ * Added support for navigation icons
+
+mkdocs-material-8.1.2 (2021-12-15)
+
+ * Switched CSS sources to logical properties
+ * Added transformation of logical properties to ltr/rtl equivalents
+ * Fixed spacing for admonitions inside lists (8.1.1 regression)
+
+mkdocs-material-8.1.1 (2021-12-13)
+
+ * Added support for #only-light and #only-dark image hash fragments
+ * Fixed copy-to-clipboard adding blank lines when using line anchors
+ * Fixed code annotation directionality for right-to-left languages
+ * Fixed header title positioning for right-to-left languages
+ * Fixed admonition borders for right-to-left languages (8.0.0 regression)
+ * Fixed footer navigation link positioning (8.0.0 regression)
+ * Fixed footer navigation title breaking out of container when too long
+ * Fixed shrinking arrow in navigation title when too long
+ * Fixed #3343: Filtered stopwords appear as missing search terms
+ * Fixed #3346: Site unusable due to usage of :not() (Firefox 78 ESR)
+
+mkdocs-material-8.1.0+insiders-4.4.0 (2021-12-10)
+
+ * Added support for code annotation anchor links (deep linking)
+ * Added new code annotation syntax modifier to strip comment
+ * Updated German translations for cookie consent
+
+mkdocs-material-8.1.0 (2021-12-10)
+
+ * Added basic support for code block line anchors
+ * Switched code annotation markers to + signs to improve usability
+ * Switched main site title to bold font
+ * Improved admonition icon positioning to align when font-size is increased
+ * Improved and simplified footnotes CSS
+ * Improved and simplified code annotation positioning
+ * Fixed syntax error in Russian translations
+
+mkdocs-material-8.0.5 (2021-12-04)
+
+ * Fixed #3302: Footer refactoring induced ellipsis in some browsers
+ * Fixed #3313: Details always rendered closed on load (8.0.4 regression)
+
+mkdocs-material-8.0.4+insiders-4.3.0 (2021-12-05)
+
+ * Added support for custom fonts in social cards
+ * Fixed #3300: Announcement bar reappearing when using instant loading
+
+mkdocs-material-8.0.4 (2021-12-04)
+
+ * Improved support for deeply nested code annotations
+ * Improved code annotation and copy-to-clipboard interop
+ * Improved styling for code annotations inside admonitions
+ * Fixed #3274: Invalid anchor positioning when using instant loading
+ * Fixed #3294: Lists after code blocks without code annotations disappearing
+ * Fixed several positioning issues for code annotations
+ * Fixed JavaScript source map roots
+
+mkdocs-material-8.0.3+insiders-4.2.0 (2021-12-02)
+
+ * Added support for dismissible announcement bar
+ * Added support for named placeholders in feedback widget
+
+mkdocs-material-8.0.3 (2021-12-02)
+
+ * Removed deprecated google_analytics setting (was forgotten in 8.0.0)
+ * Fixed syntax error in Swedish and Polish translations
+ * Fixed #3283: Invalid back-to-top button position with sticky navigation tabs
+ * Fixed #3285: Default details marker showing due to Safari bug
+
+mkdocs-material-8.0.2+insiders-4.1.0 (2021-11-30)
+
+ * Added support for passing page title to feedback forms
+
+mkdocs-material-8.0.2 (2021-11-30)
+
+ * Fixed #3275: Code annotations always disappear on click
+
+mkdocs-material-8.0.1 (2021-11-28)
+
+ * Improved rendering of code annotation markers
+ * Fixed #3265: Wrong margin on nested admonitions
+ * Fixed wrong box-sizing for code annotations in details
+
+mkdocs-material-8.0.0 (2021-11-28)
+
+ * Added support for code annotations
+ * Added support for anchor tracking
+ * Added support for version warning
+ * Added copyright partial for easier override
+ * Removed deprecated content tabs legacy implementation
+ * Removed deprecated seealso admonition type
+ * Removed deprecated site_keywords setting (unsupported by MkDocs)
+ * Removed deprecated prebuilt search index support
+ * Removed deprecated web app manifest – use customization
+ * Removed extracopyright variable – use new copyright partial
+ * Removed Disqus integration – use customization
+ * Switched to :is() selectors for simple selector lists
+ * Switched autoprefixer from last 4 years to last 2 years
+ * Improved CSS overall to match modern standards
+ * Improved CSS variable semantics for fonts
+ * Improved extensibility by restructuring partials
+ * Improved handling of details when printing
+ * Improved keyboard navigation for footnotes
+ * Fixed #3214: Search highlighting breaks site when empty
+
+mkdocs-material-7.3.6+insiders-3.2.3 (2021-11-20)
+
+ * Updated Swedish and French translations
+ * Removed support for .mermaid-experimental class (now .mermaid)
+ * Fixed #3202: Cookie consent not dismissible on file:// locations
+ * Fixed #3216: Cookie consent not dismissed when invoked via anchor
+ * Fixed #3232: Mermaid.js sometimes runs twice (race condition)
+
+mkdocs-material-7.3.6+insiders-3.2.2 (2021-11-06)
+
+ * Fixed always last feedback rating being sent
+ * Fixed #3145: Code annotations eat whole comment lines
+ * Fixed #3170: Feedback widget doesn't send data to GA4
+
+mkdocs-material-7.3.6+insiders-3.2.1 (2021-11-04)
+
+ * Added support for custom Mermaid.js version via additional JavaScript
+ * Fixed some configuration edge cases for tags plugin (3.1.5 regression)
+ * Fixed feedback widget title not being centered in Firefox
+ * Fixed #3179: Safari doesn't send request for feedback widget
+
+mkdocs-material-7.3.6+insiders-3.2.0 (2021-10-31)
+
+ * Added support for feedback widget (Was this page helpful?)
+
+mkdocs-material-7.3.6 (2021-10-30)
+
+ * Added support for adding titles to code blocks
+
+mkdocs-material-7.3.5+insiders-3.1.5 (2021-10-28)
+
+ * Fixed #3144: Rogue link when using tags with auto-populated navigation
+ * Fixed #3147: Code block line numbers appear in search results
+ * Fixed #3158: Social cards do not strip HTML tags from title
+
+mkdocs-material-7.3.5 (2021-10-27)
+
+ * Added support for setting table of contents title via mkdocs.yml
+ * Fixed back-to-top button position for right-to-left languages
+
+mkdocs-material-7.3.4+insiders-3.1.4 (2021-10-17)
+
+ * Fixed #2974: Text cropped with other fonts than Roboto in social plugin
+ * Fixed #3099: Encoding problems with non-latin character in social plugin
+ * Fixed #3112: Japanese segmenter not executed as part of new tokenizer
+ * Fixed tags (front matter) appearing in search with disabled tags plugin
+
+mkdocs-material-7.3.4 (2021-10-17)
+
+ * Bumped MkDocs version to 1.2.3 to mitigate CVE-2021-40978
+ * Fixed spacing issues when using integrate table of contents with tabs
+ * Fixed some spacings issues for right-to-left languages
+ * Fixed race condition in search initialization
+
+mkdocs-material-7.3.3+insiders-3.1.3 (2021-10-12)
+
+ * Added warnings to search plugin for unsupported options and syntax
+ * Fixed #3503: Search sometimes returns entire page
+ * Fixed #3089: Single-line code annotations disappear when printing
+
+mkdocs-material-7.3.3 (2021-10-11)
+
+ * Rewrite of entire documentation
+ * Adjusted height of new content tabs to match single line code blocks
+ * Fixed new content tabs missing right padding in some browsers on overflow
+ * Fixed new content tabs bleeding out of flex container on overflow
+ * Fixed new content tabs overflow scrolling bugs on some browsers
+ * Fixed new content tabs stealing keyboard access when active
+ * Fixed some spacings issues for right-to-left languages
+
+mkdocs-material-7.3.2+insiders-3.1.2 (2021-10-06)
+
+ * Fixed incorrect path separators for social cards on Windows
+
+mkdocs-material-7.3.2 (2021-10-06)
+
+ * Deprecated prebuilding of search index
+ * Improved graceful handling of broken search for file://
+ * Added minimum Jinja version to list of requirements
+ * Fixed #3071: Section index pages render empty directories
+ * Fixed margin issues when using navigation tabs (7.3.1 regression)
+ * Fixed search placeholder sometimes being shown too early
+
+mkdocs-material-7.3.1 (2021-10-02)
+
+ * Added new experimental content tabs implementation
+ * Fixed #3069: GitHub stats broken for users/orgs (7.1.0 regression)
+ * Fixed #3070: Sections not linking to index page
+ * Fixed title not linking to index page when using tabs
+ * Fixed Disqus integration when using instant loading
+ * Fixed some spacing issues for right-to-left languages
+ * Fixed syntax error in Serbian translations
+
+mkdocs-material-7.3.0+insiders-3.1.1 (2021-09-26)
+
+ * Fixed ordering bug in search exclusion logic
+
+mkdocs-material-7.3.0+insiders-3.1.0 (2021-09-26)
+
+ * Added support for excluding pages, sections, and elements from search
+ * Fixed #2803: Code block annotations not visible when printing
+
+mkdocs-material-7.3.0 (2021-09-23)
+
+ * Added support for sticky navigation tabs
+ * Added support for section index pages
+ * Added support for removing generator notice
+
+mkdocs-material-7.2.8 (2021-09-20)
+
+ * Fixed #3039: Search modal overlays menu on mobile (7.2.7 regression)
+
+mkdocs-material-7.2.7+insiders-3.0.1 (2021-09-19)
+
+ * Added support for using literal h1-6 tags for search plugin
+ * Fixed search plugin breaking on void elements without slashes
+ * Fixed search plugin filtering link contents from headlines
+ * Fixed search plugin handling of multiple h1 headlines
+ * Fixed search plugin handling of missing h1 headlines
+
+mkdocs-material-7.2.7 (2021-09-19)
+
+ * Updated Serbian and Serbo-Croatian translations
+ * Improved appearance of outline on details
+ * Fixed #2934: Scrollbar when header is hidden on some mobile browsers
+ * Fixed #3032: Anchor in details doesn't open on load (7.0.0 regression)
+ * Fixed back-to-top button being focusable when invisible
+ * Fixed broken admonition icons (removed in upstream)
+
+mkdocs-material-7.2.6+insiders-3.0.0 (2021-09-13)
+
+ * Rewrite of MkDocs' search plugin
+ * Added support for rich search previews
+ * Added support for tokenizer with lookahead
+ * Improved search indexing performance (twice as fast)
+ * Improved search highlighting
+
+mkdocs-material-7.2.6+insiders-2.13.3 (2021-09-01)
+
+ * Added support for disabling social card generation
+
+mkdocs-material-7.2.6 (2021-09-01)
+
+ * Fixed rendering of blockquote elements (7.0.0 regression)
+ * Fixed #2973: Custom search worker setting ignored
+
+mkdocs-material-7.2.5+insiders-2.13.2 (2021-08-25)
+
+ * Fixed #2965: Social plugin error when primary color is not defined
+
+mkdocs-material-7.2.5 (2021-08-25)
+
+ * Updated Portuguese translations
+ * Fixed execution of RxJS teardown logic (7.2.3 regression)
+ * Fixed #2970: Search results show escaped characters (7.2.2 regression)
+
+mkdocs-material-7.2.4+insiders-2.13.1 (2021-08-22)
+
+ * Fixed #2948: Social cards are not cached
+ * Fixed #2953: Mermaid.js diagrams can't be centered anymore
+
+mkdocs-material-7.2.4 (2021-08-11)
+
+ * Fixed #2926: Version selector not working (7.2.3 regression)
+ * Fixed #2929: Missing CSS class for banner (consistency with Insiders)
+
+mkdocs-material-7.2.3 (2021-08-09)
+
+ * Slight facelift of data tables, now closer to Material Design
+ * Fixed instant loading not respecting clicks on search results
+ * Fixed #2881: Invalid anchor offsets when using instant loading
+
+mkdocs-material-7.2.2+insiders-2.13.0 (2021-08-07)
+
+ * Added support for custom colors in social cards
+
+mkdocs-material-7.2.2+insiders-2.12.2 (2021-08-04)
+
+ * Fixed #2891: Division by zero error in social plugin
+
+mkdocs-material-7.2.2 (2021-07-31)
+
+ * Updated Korean translations
+ * Fixed #2879: Search highlighting does not properly escape HTML
+
+mkdocs-material-7.2.1+insiders-2.12.1 (2021-07-26)
+
+ * Fixed error in social plugin when site_description was not set
+ * Fixed error in social plugin for non-ASCII characters
+
+mkdocs-material-7.2.1+insiders-2.12.0 (2021-07-25)
+
+ * Added support for social cards
+
+mkdocs-material-7.2.1 (2021-07-25)
+
+ * Fixed #2862: Back-to-top button overlays active search bar
+
+mkdocs-material-7.2.0 (2021-07-21)
+
+ * Added support for search suggestions to save keystrokes
+ * Added support for search highlighting
+ * Added support for search sharing (i.e. deep linking)
+
+mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20)
+
+ * Fixed order of tags index, now sorted alphabetically
+
+mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18)
+
+ * Improved Mermaid.js integration, now stable
+ * Added support for sequence diagrams
+ * Added support for entity relationship diagrams
+ * Added support for cookie consent configuration
+ * Added feature flag to always enable annotations
+
+mkdocs-material-7.1.11 (2021-07-18)
+
+ * Updated Spanish and Galician translations
+
+mkdocs-material-7.1.10+insiders-2.10.0 (2021-07-10)
+
+ * Added support for cookie consent
+ * Fixed #2807: Back-to-top button not hidden when using sticky tabs
+
+mkdocs-material-7.1.10 (2021-07-10)
+
+ * Refactored appearance of back-to-top button
+ * Fixed graceful handling of search when browsing locally
+
+mkdocs-material-7.1.9 (2021-06-25)
+
+ * Improved search language support for Thai and Hindi
+ * Fixed #2761: License comments lined up at end of file
+
+mkdocs-material-7.1.8 (2021-06-12)
+
+ * Refactored analytics integration (because of MkDocs 1.2)
+ * Added support for Google Analytics 4 (gtag.js)
+ * Fixed missing escape for aria-label in footer links
+
+mkdocs-material-7.1.7 (2021-06-06)
+
+ * Improved screen reader support
+
+mkdocs-material-7.1.6+insiders-2.9.2 (2021-05-30)
+
+ * Moved tags to partial for easier customization
+ * Added support for hiding tags on any page
+
+mkdocs-material-7.1.6 (2021-05-30)
+
+ * Deprecated seealso admonition qualifier
+ * Added Mongolian and updated Chinese translations
+ * Fixed #2429: Version selector not touch-friendly on Android devices
+ * Fixed #2703: Printed 'Initializing search' albeit ready on mobile
+
+mkdocs-material-7.1.5+insiders-2.9.1 (2021-05-24)
+
+ * Added missing guard for linking of content tabs
+
+mkdocs-material-7.1.5+insiders-2.9.0 (2021-05-23)
+
+ * Added support for linking of content tabs
+
+mkdocs-material-7.1.5 (2021-05-19)
+
+ * Fixed #2655: Details breaking page margins on print
+
+mkdocs-material-7.1.4+insiders-2.8.0 (2021-05-12)
+
+ * Added support for boosting pages in search
+
+mkdocs-material-7.1.4+insiders-2.7.2 (2021-05-08)
+
+ * Fixed #2638: Warnings shown when using tags plugin without directory URLs
+
+mkdocs-material-7.1.4 (2021-05-06)
+
+ * Added support for git-revision-date-localized plugin creation date
+ * Improved footnote styles on :target and :focus
+
+mkdocs-material-7.1.3+insiders-2.7.1 (2021-05-03)
+
+ * Fixed git-revision-date-localized plugin integration (2.7.0 regression)
+
+mkdocs-material-7.1.3+insiders-2.7.0 (2021-05-01)
+
+ * Added support for tags (with search integration)
+
+mkdocs-material-7.1.3 (2021-04-24)
+
+ * Fixed #2586: Empty table of contents shown (7.1.2 regression)
+
+mkdocs-material-7.1.2 (2021-04-18)
+
+ * Fixed #2554: List markers sometimes overlap floated elements
+ * Fixed #2563: Adding a class to a h1 breaks the table of contents
+ * Fixed #2566: Back-to-top button clickable when invisible
+
+mkdocs-material-7.1.1+insiders-2.6.0 (2021-04-11)
+
+ * Stay on page when switching versions
+
+mkdocs-material-7.1.1 (2021-04-10)
+
+ * Fixed #2501: Nested definition lists compound bottom margin
+ * Fixed #2508: Switch extracopyright block to template variable
+ * Fixed #2533: Search (and other parts) not working in Safari <14
+ * Fixed #2538: Visual quirk when opening language selector
+
+mkdocs-material-7.1.0 (2021-03-29)
+
+ * Added support for color palette toggle
+ * Added support for back-to-top button
+ * Added latest release to repository info (GitHub)
+ * Slight facelift of repository info (lighter fonts, spacing and icons)
+
+mkdocs-material-7.0.7+insiders-2.5.0 (2021-03-28)
+
+ * Added support for version warning
+
+mkdocs-material-7.0.7 (2021-03-28)
+
+ * Updated Hungarian translations
+ * Fixed #2466: Docker image not based on latest Python and Alpine
+ * Fixed #2488: Inconsistent header shadow behavior
+ * Fixed #2492: Inline code blocks in admonition titles missing background
+
+mkdocs-material-7.0.6+insiders-2.4.0 (2021-03-20)
+
+ * Added support for custom admonition icons
+ * Fixed #2444: Code block annotations with extra comments have wrong index
+
+mkdocs-material-7.0.6+insiders-2.3.1 (2021-03-14)
+
+ * Fixed anchor offset for permalinks when using sticky navigation tabs
+
+mkdocs-material-7.0.6 (2021-03-14)
+
+ * Added trailing slash to version selector URL
+ * Added support for out-of-order anchors in table of contents
+ * Added extra.homepage option to link logo to arbitrary URL
+ * Improved security of Docker image (always update apk)
+ * Fixed horizontal spacing for nested inline admonitions
+ * Fixed text color of nested code blocks inside links
+ * Fixed version selector to always use version title
+ * Fixed logo link when using versioning with instant loading
+
+mkdocs-material-7.0.5+insiders-2.3.0 (2021-03-13)
+
+ * Added support for back-to-top button
+
+mkdocs-material-7.0.5 (2021-03-07)
+
+ * Added extracopyright block to allow for custom copyright info
+ * Fixed evaluation of third-party scripts when using instant loading
+ * Fixed edge cases when using instant loading without directory URLs
+ * Fixed handling of version selector when using instant loading
+ * Fixed regression with header title not being updated correctly
+ * Fixed expanded sections not opening on first click (7.0.4 regression)
+
+mkdocs-material-7.0.4+insiders-2.2.1 (2021-03-04)
+
+ * Fixed #2382: Repository stats failing when no release tag is present
+
+mkdocs-material-7.0.4 (2021-03-04)
+
+ * Added Icelandic translations
+ * Fixed #2386: Section close requires two clicks (navigation expansion)
+ * Fixed console error when search is disabled (7.0.0 regression)
+ * Fixed localsearch integration (7.0.0 regression)
+
+mkdocs-material-7.0.3+insiders-2.2.0 (2021-02-28)
+
+ * Added support for code block annotations
+
+mkdocs-material-7.0.3+insiders-2.1.0 (2021-02-26)
+
+ * Added support for anchor tracking
+
+mkdocs-material-7.0.3 (2021-02-26)
+
+ * Fixed JavaScript errors in older browsers (target ES2020 -> ES2015)
+
+mkdocs-material-7.0.2 (2021-02-25)
+
+ * Fixed #2343: Invalid source map URLs for JS and CSS files
+ * Fixed #2347: Version selector missing when using versioning
+
+mkdocs-material-7.0.1+insiders-2.0.0 (2021-02-24)
+
+ * Migrated Insiders to the new architecture
+ * Swapped color palette toggle configuration
+
+mkdocs-material-7.0.1 (2021-02-24)
+
+ * Fixed #2334: Google Analytics triggers page view twice (7.0.0 regression)
+ * Fixed #2336: Details bleed into inline admonitions
+ * Fixed #2337: Images don't align correctly (7.0.0 regression)
+
+mkdocs-material-7.0.0 (2021-02-22)
+
+ * Added support for deploying multiple versions
+ * Added support for integrating a language selector
+ * Added support for rendering admonitions as inline blocks
+ * Rewrite of the underlying reactive architecture
+ * Removed Webpack in favor of reactive build strategy (-480 dependencies)
+ * Fixed keyboard navigation for code blocks after content tabs switch
+
+mkdocs-material-6.2.8 (2021-02-04)
+
+ * Updated Japanese and Polish translations
+ * Fixed #2261: Print dialog auto-closing when using instant loading
+
+mkdocs-material-6.2.7+insiders-1.17.0 (2021-01-31)
+
+ * Added support for section index pages
+
+mkdocs-material-6.2.7 (2021-01-31)
+
+ * Fixed #2251: Updated Docker image to latest Alpine Linux
+
+mkdocs-material-6.2.6+insiders-1.16.1 (2021-01-26)
+
+ * Fixed #2249: Instant loading + sticky tabs result in invalid links
+ * Fixed #2248: Search highlighting URL parameter always added
+ * Fixed #2235: Version selector doesn't select current version for aliases
+
+mkdocs-material-6.2.6 (2021-01-26)
+
+ * Added Bulgarian translations
+ * Fixed #2233: Search not shown when using header autohiding
+
+mkdocs-material-6.2.5+insiders-1.16.0 (2021-01-17)
+
+ * Added latest release to repository info (GitHub)
+ * Slight facelift of repository info (lighter fonts, spacing and icons)
+
+mkdocs-material-6.2.5 (2021-01-17)
+
+ * Fixed syntax error in Swedish translations
+ * Optimized navigation partials to improve build speed for huge docs
+
+mkdocs-material-6.2.4 (2021-01-09)
+
+ * Fixed #2156: Missing syntax highlighting for binary numbers
+ * Fixed #2186: Disqus showing on 404 page
+
+mkdocs-material-6.2.3+insiders-1.15.0 (2021-01-02)
+
+ * Added support for native Mermaid.js integration
+
+mkdocs-material-6.2.3+insiders-1.14.0 (2020-12-30)
+
+ * Added support for sharing searches
+
+mkdocs-material-6.2.3 (2020-12-27)
+
+ * Added back hidden overflow on root container
+ * Fixed #2142: MathJax formulas sometimes have vertical scrollbars
+
+mkdocs-material-6.2.2+insiders-1.13.2 (2020-12-22)
+
+ * Fixed version selector + sticky tabs navigation rendering issues
+ * Fixed version selector wrapping
+
+mkdocs-material-6.2.2 (2020-12-22)
+
+ * Removed Markdown version range limit (6.2.0 regression)
+
+mkdocs-material-6.2.1 (2020-12-22)
+
+ * Fixed all import and asset paths in templates (6.2.0 regression)
+ * Downgraded webpack-asset-manifest-plugin - broke all asset paths
+
+mkdocs-material-6.2.0 (2020-12-22)
+
+ * Added support for navigation sections
+ * Added support for navigation expansion
+ * Added support for integrating table of contents into navigation
+ * Added support for autohiding header on scroll
+ * Added support for hiding navigation and table of contents per page
+ * Added support for arbitrary items in navigation tabs
+ * Refactored navigation tabs to simplify grouping behavior
+ * Fixed anchor offset for permalinks in Safari (partial revert)
+ * Fixed #2098: Active tab sometimes not highlighted correctly
+ * Improved appearance for horizontal rulers
+ * Improved Spanish and Swedish translations
+
+mkdocs-material-6.1.7+insiders-1.13.1 (2020-12-20)
+
+ * Fixed horizontal scrollbars for language and version selection
+ * Fixed type conversion in JavaScript config (#6)
+
+mkdocs-material-6.1.7+insiders-1.13.0 (2020-12-13)
+
+ * Added support for sticky navigation tabs
+ * Added support for arbitrary links in navigation tabs
+ * Refactored navigation tabs to simplify grouping behavior
+ * Fixed #2098: Subsequent active subsection not highlighted correctly
+
+mkdocs-material-6.1.7+insiders-1.12.1 (2020-12-08)
+
+ * Fixed empty language selector being shown
+
+mkdocs-material-6.1.7+insiders-1.12.0 (2020-12-06)
+
+ * Added support for adding a language selector
+
+mkdocs-material-6.1.7 (2020-12-06)
+
+ * Fixed #2081: Fixed stats for private GitHub repositories
+ * Fixed alignment for admonition icon alignment for right-to-left languages
+
+mkdocs-material-6.1.6+insiders-1.11.2 (2020-11-29)
+
+ * Fixed #2068: Search highlight interprets code blocks as JavaScript
+
+mkdocs-material-6.1.6+insiders-1.11.1 (2020-11-29)
+
+ * Refactored styling to be more stable and easier to adjust
+ * Fixed some styling regressions from latest features
+
+mkdocs-material-6.1.6+insiders-1.11.0 (2020-11-22)
+
+ * Added support for rendering admonitions as inline blocks
+
+mkdocs-material-6.1.6 (2020-11-22)
+
+ * Fixed #2048: Math formulas show scrollbars (Windows)
+
+mkdocs-material-6.1.5+insiders-1.10.0 (2020-11-15)
+
+ * Added support for integrating table of contents into navigation
+
+mkdocs-material-6.1.5 (2020-11-15)
+
+ * Fixed search reset button not showing/hiding correctly
+
+mkdocs-material-6.1.4+insiders-1.9.0 (2020-11-07)
+
+ * Added support for hiding navigation and table of contents on any page
+ * Removed autohiding table of contents when empty
+
+mkdocs-material-6.1.4 (2020-11-07)
+
+ * Fixed sidebar jitter when scrolling footer into view
+
+mkdocs-material-6.1.3 (2020-11-05)
+
+ * Added support for keywords meta tag
+ * Fixed #2027: Line numbers don't scale with smaller font size
+ * Fixed link colors for black and white on slate color scheme
+ * Removed focus outline on scrolling code blocks for pointer devices
+
+mkdocs-material-6.1.2+insiders-1.8.0 (2020-11-01)
+
+ * Added support for navigation sections
+ * Fixed appearance of inactive search suggestions
+
+mkdocs-material-6.1.2 (2020-10-31)
+
+ * Fixed sizing of icons in admonitions, task lists, etc. (6.1.1 regression)
+
+mkdocs-material-6.1.1 (2020-10-31)
+
+ * Fixed #2019: Page title not correctly updated when using instant loading
+
+mkdocs-material-6.1.0+insiders-1.7.0 (2020-10-25)
+
+ * Added support for deploying multiple versions
+ * Fixed alignment of sidebar when content area is too small
+
+mkdocs-material-6.1.0 (2020-10-17)
+
+ * Fixed #1973: Added support for printing in dark mode
+ * Fixed #1974: Added support for printing content tabs
+ * Fixed #1995: Improved customizability of details extension
+
+mkdocs-material-6.0.2+insiders-1.6.0 (2020-10-11)
+
+ * Added support for search suggestions to save keystrokes
+ * Added support for removing 'Made with Material for MkDocs' from footer
+ * Fixed #1915: search should go to first result by pressing Enter
+
+mkdocs-material-6.0.2 (2020-10-04)
+
+ * Added Georgian translations
+ * Added escaping for link title attributes where necessary
+ * Fixed #1956: Pages with whitespace in names have invalid links in search
+ * Removed unnecessary (duplicated) link title attributes
+
+mkdocs-material-6.0.1 (2020-09-26)
+
+ * Fixed stemmer support for file:// protocol through iframe-worker
+ * Fixed details marker showing for search result in Firefox
+ * Fixed tabbing behavior when search query is not empty
+ * Switched TypeScript compilation target to ES2015
+ * Reduced size of JavaScript by 30% (176kb → 124kb)
+ * Removed mkdocs and readthedocs themes from Docker image
+
+mkdocs-material-6.0.0 (2020-09-25)
+
+ * Improved search result look and feel
+ * Improved search result stability while typing
+ * Improved search result grouping (pages + headings)
+ * Improved search result relevance and scoring
+ * Added display of missing query terms to search results
+ * Reduced size of vendor bundle by 25% (84kb → 67kb)
+ * Reduced size of the Docker image to improve CI build performance
+ * Removed hero partial in favor of custom implementation
+ * Removed deprecated front matter features
+
+mkdocs-material-5.5.14 (2020-09-23)
+
+ * Improved spacing around image captions
+ * Fixed #1939: Long tables cause header overlap in print view
+
+mkdocs-material-5.5.13+insiders-1.5.1 (2020-09-21)
+
+ * Fixed content area stretching to whole width for long code blocks
+
+mkdocs-material-5.5.13+insiders-1.5.0 (2020-09-19)
+
+ * Added support for autohiding table of contents when empty
+
+mkdocs-material-5.5.13 (2020-09-19)
+
+ * Improved abbreviations on touch devices
+
+mkdocs-material-5.5.12+insiders-1.4.1 (2020-09-06)
+
+ * Improved typeahead and search result relevance and scoring
+
+mkdocs-material-5.5.12 (2020-08-31)
+
+ * Fixed #1638: occasional 404 for images when using instant loading
+
+mkdocs-material-5.5.11+insiders-1.4.0 (2020-08-30)
+
+ * Added support for autohiding header on scroll
+
+mkdocs-material-5.5.11 (2020-08-28)
+
+ * Fixed Disqus integration, as the minifier killed the config
+
+mkdocs-material-5.5.10 (2020-08-28)
+
+ * Improved rendering by moving Disqus integration after page load
+ * Fixed #1887: Moved navigation icons to CSS to reduce size of HTML
+
+mkdocs-material-5.5.9+insiders-1.3.0 (2020-08-26)
+
+ * Added support for user-selectable color palettes
+
+mkdocs-material-5.5.9 (2020-08-26)
+
+ * Added Esperanto translations
+ * Fixed #1884: External links not included in navigation tabs
+
+mkdocs-material-5.5.8 (2020-08-23)
+
+ * Removed focus outline on details and content tabs for pointer devices
+ * Improved accessibility of content tabs (now navigable via arrow keys)
+ * Fixed #1877: 404 on search index when search is disabled
+ * Fixed some memleaks in observable subscriptions
+ * Fixed color definitions for theme-color meta tag
+
+mkdocs-material-5.5.7 (2020-08-16)
+
+ * Improved contrast ratio to 4.5:1 for syntax highlighting
+ * Improved contrast ratio to 4.5:1 for table of contents
+
+mkdocs-material-5.5.6 (2020-08-12)
+
+ * Switched base template for 404.html to main.html
+ * Fixed #1864: GitHub organisation stats not loading
+
+mkdocs-material-5.5.5+insiders-1.2.0 (2020-08-11)
+
+ * Added feature to expand navigation by default
+
+mkdocs-material-5.5.5 (2020-08-11)
+
+ * Fixed missing vendor and worker distribution files
+
+mkdocs-material-5.5.4 (2020-08-11)
+
+ * Added support for sortable data tables
+
+mkdocs-material-5.5.3 (2020-08-04)
+
+ * Fixed search for languages other than English (5.5.1 regression)
+
+mkdocs-material-5.5.2+insiders-1.1.0 (2020-08-03)
+
+ * Added highlighting of search results
+
+mkdocs-material-5.5.2 (2020-08-03)
+
+ * Improved highlight colors and spacing for ins, del and mark
+ * Changed some keyboard symbols for better equivalents
+ * Removed focus outline for details and code blocks on touch devices
+ * Fixed margins for admonitions (5.5.1 regression)
+ * Fixed too small content tab labels (5.5.1 regression)
+ * Fixed icon repeating for custom admonition icons
+
+mkdocs-material-5.5.1 (2020-08-01)
+
+ * Improved typesetting by basing font-size and spacings on em
+ * Improved print view by slightly scaling down font-size
+ * Changed custom site title (metadata) to be suffixed with site name
+ * Fixed top- and bottom spacing of paragraphs inside table cells
+
+mkdocs-material-5.5.0 (2020-07-24)
+
+ * Rewrite of entire documentation
+ * Rewrite of syntax highlighting to be customizable with CSS variables
+ * Improved syntax highlighting to work with light and dark theme
+ * Improved slate color scheme to be more customizable and easier on the eyes
+ * Added licenses of icon sets to distribution files
+ * Fixed stale document titles in Google Analytics when using instant loading
+ * Fixed width of previous and next footer links for tablet and above
+ * Fixed issues with top scroll margin for footnotes
+ * Fixed top margin for tabbed content when using a JavaScript highlighter
+ * Deprecated metadata-based redirects, source links and heroes
+
+mkdocs-material-5.4.0+insiders-1.0.0 (2020-07-14)
+
+ * Added grouping of search results
+ * Added missing query terms to search result
+ * Improved search result relevance and scoring
+
+mkdocs-material-5.4.0 (2020-06-29)
+
+ * Added support to wrap searches in quotes to switch from OR to AND
+ * Fixed highlighting of numbers in search results
+
+mkdocs-material-5.3.3 (2020-06-24)
+
+ * Added Bengali translations
+ * Fixed #1773: Search for numbers does not return any result (regression)
+
+mkdocs-material-5.3.2 (2020-06-21)
+
+ * Improved search typeahead experience with non-Latin characters
+ * Fixed #1753: Japanese search doesn't work anymore
+
+mkdocs-material-5.3.1 (2020-06-20)
+
+ * Fixed #1761: Duplication of search worker when subscribing to observable
+
+mkdocs-material-5.3.0 (2020-06-15)
+
+ * Added support for color schemes based on user preference
+ * Fixed #1755: Tokenizer separator setting ignored
+
+mkdocs-material-5.2.3 (2020-06-07)
+
+ * Improved search typeahead behavior for some languages (de, fr, ...)
+ * Improved styles for scrollbars on Firefox
+ * Fixed #1741: Removed preconnect hint for Google Analytics
+
+mkdocs-material-5.2.2 (2020-05-26)
+
+ * Fixed #1728: Legacy Edge doesn't support deg values in hsla colors
+
+mkdocs-material-5.2.1 (2020-05-22)
+
+ * Fixed color of links in table headers, e.g. footnotes
+ * Fixed color scheme not being applied without primary or accent color
+ * Fixed hover delay for links inside code blocks
+
+mkdocs-material-5.2.0 (2020-05-18)
+
+ * Added color schemes implementation + dark mode
+ * Fixed #1583: Missing option for separate link colors
+
+mkdocs-material-5.1.7 (2020-05-16)
+
+ * Added keyboard focus support for overflowing code blocks
+ * Fixed #1696: Infinite loop in some cases when using instant loading
+
+mkdocs-material-5.1.6 (2020-05-09)
+
+ * Added Burmese translations
+ * Added general anchor offset solution using scroll-margin-top
+ * Fixed #1653: Instant loading shouldn't intercept links to *.html files
+
+mkdocs-material-5.1.5 (2020-05-03)
+
+ * Added name attribute for social links to set link title
+ * Fixed #1623: Allow arbitrary links in social links
+ * Fixed #1664: Height of iframe is not adjustable
+ * Fixed #1667: Sidebars are scrolled to bottom on load (bug in Chrome 81+)
+
+mkdocs-material-5.1.4 (2020-04-30)
+
+ * Switched to @mdi/svg Material Design icon package
+ * Fixed #1655: Navigation may disappear after switching viewports
+ * Fixed #1659: Unnecessary scrollbar for search results on Windows
+ * Fixed occasional distortions for images with explicit dimensions
+ * Fixed errors in German translations
+
+mkdocs-material-5.1.3 (2020-04-26)
+
+ * Fixed overflowing content area after switch to flexbox
+
+mkdocs-material-5.1.2 (2020-04-26)
+
+ * Added status information to search observable
+ * Added status information to search modal
+ * Removed announcement bar from print media
+ * Removed media query packing logic due to race conditions
+ * Fixed #1520: Gracefully disable search on file:// if Worker fails
+ * Fixed re-submission of query after search is initialized
+ * Fixed jitter of sidebars on all browsers by switching to sticky
+
+mkdocs-material-5.1.1 (2020-04-17)
+
+ * Added new FontAwesome icons
+ * Fixed #1609: Instant loading doesn't honor target=_blank
+ * Fixed GitHub stars count rounding errors
+ * Fixed GitLab stars count retrieval
+
+mkdocs-material-5.1.0 (2020-04-12)
+
+ * Added support for icons from Markdown through mkdocs-material-extensions
+
+mkdocs-material-5.0.2 (2020-04-10)
+
+ * Added CSS source maps to distribution files
+ * Fixed errors in Chinese (Traditional) translations
+ * Fixed creation of stale directory on installation from git
+ * Improved overflow scrolling behavior on iOS (reduced bundle size by 4kb)
+
+mkdocs-material-5.0.1 (2020-04-07)
+
+ * Fixed syntax error in Spanish translations
+
+mkdocs-material-5.0.0 (2020-04-07)
+
+ * Reactive architecture – try app.dialog$.next("Hi!") in the console
+ * Instant loading – make Material behave like a Single Page Application
+ * Improved CSS customization with CSS variables – set your brand's colors
+ * Improved CSS resilience, e.g. proper sidebar locking for customized headers
+ * Improved icon integration and configuration – now including over 5k icons
+ * Added possibility to use any icon for logo, repository and social links
+ * Search UI does not freeze anymore (moved to web worker)
+ * Search index built only once when using instant loading
+ * Improved extensible keyboard handling
+ * Support for prebuilt search indexes
+ * Support for displaying stars and forks for GitLab repositories
+ * Support for scroll snapping of sidebars and search results
+ * Reduced HTML and CSS footprint due to deprecation of IE support
+ * Slight facelifting of some UI elements (admonitions, tables, ...)
+
+mkdocs-material-4.6.3 (2020-02-14)
+
+ * Removed optional third-party plugins from requirements.txt
+ * Updated Docker image to contain all supported third-party plugins
+
+mkdocs-material-4.6.2 (2020-02-08)
+
+ * Added Romanian translations
+ * Fixed #1451: Inconsistent spacing for fenced code blocks
+
+mkdocs-material-4.6.1 (2020-02-08)
+
+ * Fixed #1324: Metadata author only rendering first character
+ * Fixed #1393: Set tabindex to 0 for skip to content link
+ * Fixed code blocks after Markdown 3.2 release
+ * Fixed errors in Japanese translations
+ * Improved Google Lighthouse score
+
+mkdocs-material-4.6.0 (2019-12-11)
+
+ * Added support for mkdocs-git-revision-date-localized-plugin
+ * Fixed invalid character in Google Fonts URL
+
+mkdocs-material-4.5.1 (2019-12-02)
+
+ * Added Thai translations
+ * Fixed missing assets in GitHub release .zip and .tar.gz
+
+mkdocs-material-4.5.0 (2019-11-16)
+
+ * Fixed #1330: Upgraded EmojiOne to Tweomji due to licensing issues
+ * Fixed #1339: Temporarily pinned PyMdown and Markdown due to
+ * Fixed errors in Greek translations
+ * Improved GitHub statistics retrieval
+
+mkdocs-material-4.4.3 (2019-10-03)
+
+ * Added Estonian translations
+ * Fixed removal of copyright banners in minified JavaScript
+ * Removed unnecessary title attributes from links in table of contents
+
+mkdocs-material-4.4.2 (2019-08-27)
+
+ * Added Afrikaans translations
+ * Fixed broken page title when h1 contained HTML tags
+ * Improved accessibility for IE users
+ * Removed unnecessary title attributes from links in navigation
+
+mkdocs-material-4.4.1 (2019-08-22)
+
+ * Added support for black as a primary color
+ * Fixed broken footer bar when h1 contained HTML tags
+
+mkdocs-material-4.4.0 (2019-06-15)
+
+ * Added Slovenian translations
+ * Reverted template minification in favor of mkdocs-minify-plugin
+ * Fixed #1114: Tabs don't reappear when default font-size is smaller than 16
+
+mkdocs-material-4.3.1 (2019-05-23)
+
+ * Fixed spelling error in Danish translations
+
+mkdocs-material-4.3.0 (2019-05-17)
+
+ * Added support for changing header through metadata title property
+ * Added font-display: swap to Google Font loading logic
+ * Removed whitespace from templates, saving 4kb (.7kb gzipped) per request
+ * Fixed alignment of repository icons on tablet and desktop
+
+mkdocs-material-4.2.0 (2019-04-28)
+
+ * Added Norwegian (Nynorsk) translations
+ * Fixed loss of focus in non-form input elements due to search hotkeys
+ * Fixed #1067: Search hotkeys not working for mobile/tablet screensize
+ * Fixed #1068: Search not correctly aligned for tablet screensize
+
+mkdocs-material-4.1.2 (2019-04-16)
+
+ * Fixed #1072: HTML tags appearing in navigation link titles
+
+mkdocs-material-4.1.1 (2019-03-28)
+
+ * Fixed minor CSS errors detected during validation
+
+mkdocs-material-4.1.0 (2019-03-22)
+
+ * Fixed #1023: Search for Asian languages broken after Lunr.js update
+ * Fixed #1026: contenteditable elements loose focus on hotkeys
+
+mkdocs-material-4.0.2 (2019-03-01)
+
+ * Fixed #1012: HTML character entities appear in search result titles
+
+mkdocs-material-4.0.1 (2019-02-13)
+
+ * Fixed #762, #816: Glitch in sidebar when collapsing items
+ * Fixed #869: Automatically expand details before printing
+
+mkdocs-material-4.0.0 (2019-02-13)
+
+ * Added background on hover for table rows
+ * Removed Google Tag Manager and reverted to Google Analytics
+ * Removed blocks in partials - Jinja doesn't support them
+ * Fixed #911: Chrome breaks layout if system language is Chinese [BREAKING]
+ * Fixed #976: Removed FastClick
+
+mkdocs-material-3.3.0 (2019-01-29)
+
+ * Moved Google Analytics integration into head using Google Tag Manager
+ * Fixed #972: Unicode slugifier breaks table of contents blur on scroll
+ * Fixed #974: Additional links in table of contents break blur on scroll
+
+mkdocs-material-3.2.0 (2018-12-28)
+
+ * Added support for redirects using metadata refresh
+ * Fixed #921: Load Google Analytics snippet asynchronously
+
+mkdocs-material-3.1.0 (2018-11-17)
+
+ * Added support for Progressive Web App Manifest
+ * Fixed #915: Search bug in Safari (upgraded Lunr.js)
+
+mkdocs-material-3.0.6 (2018-10-26)
+
+ * Added Taiwanese translations
+ * Fixed #906: JavaScript code blocks evaluated in search results
+
+mkdocs-material-3.0.5 (2018-10-23)
+
+ * Added Croatian and Indonesian translations
+ * Fixed #899: Skip-to-content link invalid from 2nd level on
+ * Fixed #902: Missing URL filter in footer for FontAwesome link
+
+mkdocs-material-3.0.4 (2018-09-03)
+
+ * Updated Dutch translations
+ * Fixed #856: Removed preconnect meta tag if Google Fonts are disabled
+
+mkdocs-material-3.0.3 (2018-08-07)
+
+ * Fixed #841: Additional path levels for extra CSS and JS
+
+mkdocs-material-3.0.2 (2018-08-06)
+
+ * Fixed #839: Lunr.js stemmer imports incorrect
+
+mkdocs-material-3.0.1 (2018-08-05)
+
+ * Fixed #838: Search result links incorrect
+
+mkdocs-material-3.0.0 (2018-08-05)
+
+ * Upgraded MkDocs to 1.0 [BREAKING]
+ * Upgraded Python in official Docker image to 3.6
+ * Added Serbian and Serbo-Croatian translations
+
+mkdocs-material-2.9.4 (2018-07-29)
+
+ * Fixed build error after MkDocs upgrade
+
+mkdocs-material-2.9.3 (2018-07-29)
+
+ * Added link to home for logo in drawer
+ * Fixed dependency problems between MkDocs and Tornado
+
+mkdocs-material-2.9.2 (2018-06-29)
+
+ * Added Hindi and Czech translations
+
+mkdocs-material-2.9.1 (2018-06-18)
+
+ * Added support for different spellings for theme color
+ * Fixed #799: Added support for webfont minification in production
+ * Fixed #800: Added .highlighttable as an alias for .codehilitetable
+
+mkdocs-material-2.9.0 (2018-06-13)
+
+ * Added support for theme color on Android
+ * Fixed #796: Rendering of nested tabbed code blocks
+
+mkdocs-material-2.8.0 (2018-06-10)
+
+ * Added support for grouping code blocks with tabs
+ * Added Material and FontAwesome icon fonts to distribution files (GDPR)
+ * Added note on compliance with GDPR
+ * Added Slovak translations
+ * Fixed #790: Prefixed id attributes with "__" to avoid name clashes
+
+mkdocs-material-2.7.3 (2018-04-26)
+
+ * Added Finnish translations
+
+mkdocs-material-2.7.2 (2018-04-09)
+
+ * Fixed rendering issue for details on Edge
+
+mkdocs-material-2.7.1 (2018-03-21)
+
+ * Added Galician translations
+ * Fixed #730: Scroll chasing error on home page if Disqus is enabled
+ * Fixed #736: Reset drawer and search upon back button invocation
+
+mkdocs-material-2.7.0 (2018-03-06)
+
+ * Added ability to set absolute URL for logo
+ * Added Hebrew translations
+
+mkdocs-material-2.6.6 (2018-02-22)
+
+ * Added preconnect for Google Fonts for faster loading
+ * Fixed #710: With tabs sidebar disappears if JavaScript is not available
+
+mkdocs-material-2.6.5 (2018-02-22)
+
+ * Reverted --dev-addr flag removal from Dockerfile
+
+mkdocs-material-2.6.4 (2018-02-21)
+
+ * Added Catalan translations
+ * Fixed incorrect margins for buttons in Firefox and Safari
+ * Replaced package manager yarn with npm 5.6
+ * Reverted GitHub stars rounding method
+ * Removed --dev-addr flag from Dockerfile for Windows compatibility
+
+mkdocs-material-2.6.3 (2018-02-18)
+
+ * Added Vietnamese translations
+
+mkdocs-material-2.6.2 (2018-02-12)
+
+ * Added Arabic translations
+ * Fixed incorrect rounding of amount of GitHub stars
+ * Fixed double-layered borders for tables
+
+mkdocs-material-2.6.1 (2018-02-11)
+
+ * Added ability to override Disqus integration using metadata
+ * Fixed #690: Duplicate slashes in source file URLs
+ * Fixed #696: Active page highlight not working with default palette
+ * Adjusted German translations
+
+mkdocs-material-2.6.0 (2018-02-02)
+
+ * Moved default search configuration to default translation (English)
+ * Added support to automatically set text direction from translation
+ * Added support to disable search stop word filter in translation
+ * Added support to disable search trimmer in translation
+ * Added Persian translations
+ * Fixed support for Polish search
+ * Fixed disappearing GitHub, GitLab and Bitbucket repository icons
+
+mkdocs-material-2.5.5 (2018-01-31)
+
+ * Added Hungarian translations
+
+mkdocs-material-2.5.4 (2018-01-29)
+
+ * Fixed #683: gh-deploy fails inside Docker
+
+mkdocs-material-2.5.3 (2018-01-25)
+
+ * Added Ukrainian translations
+
+mkdocs-material-2.5.2 (2018-01-22)
+
+ * Added default search language mappings for all localizations
+ * Fixed #673: Error loading non-existent search language
+ * Fixed #675: Uncaught reference error when search plugin disabled
+
+mkdocs-material-2.5.1 (2018-01-20)
+
+ * Fixed permalink for main headline
+ * Improved missing translation handling with English as a fallback
+ * Improved accessibility with skip-to-content link
+
+mkdocs-material-2.5.0 (2018-01-13)
+
+ * Added support for right-to-left languages
+
+mkdocs-material-2.4.0 (2018-01-11)
+
+ * Added focus state for clipboard buttons
+ * Fixed #400: Search bar steals tab focus
+ * Fixed search not closing on ENTER when result is selected
+ * Fixed search not closing when losing focus due to TAB
+ * Fixed collapsed navigation links getting focus
+ * Fixed outline being cut off on TAB focus of navigation links
+ * Fixed bug with first search result navigation being ignored
+ * Removed search result navigation via TAB (use UP and DOWN)
+ * Removed outline resets for links
+ * Improved general tabbing behavior on desktop
+
+mkdocs-material-2.3.0 (2018-01-09)
+
+ * Added example (synonym: snippet) style for admonitions
+ * Added synonym abstract for summary style for admonitions
+
+mkdocs-material-2.2.6 (2017-12-27)
+
+ * Added Turkish translations
+ * Fixed unclickable area below header in case JavaScript is not available
+
+mkdocs-material-2.2.5 (2017-12-18)
+
+ * Fixed #639: Broken default favicon
+
+mkdocs-material-2.2.4 (2017-12-18)
+
+ * Fixed #638: Build breaks with Jinja < 2.9
+
+mkdocs-material-2.2.3 (2017-12-13)
+
+ * Fixed #630: Admonition sets padding on any last child
+ * Adjusted Chinese (Traditional) translations
+
+mkdocs-material-2.2.2 (2017-12-08)
+
+ * Added Dutch translations
+ * Adjusted targeted link and footnote offsets
+ * Simplified admonition styles and fixed padding bug
+
+mkdocs-material-2.2.1 (2017-12-02)
+
+ * Fixed #616: Minor styling error with title-only admonitions
+ * Removed border for table of contents and improved spacing
+
+mkdocs-material-2.2.0 (2017-11-22)
+
+ * Added support for hero teaser
+ * Added Portuguese translations
+ * Fixed #586: Footnote backref target offset regression
+ * Fixed #605: Search stemmers not correctly loaded
+
+mkdocs-material-2.1.1 (2017-11-21)
+
+ * Replaced deprecated babel-preset-es2015 with babel-preset-env
+ * Refactored Gulp build pipeline with Webpack
+ * Removed right border on sidebars
+ * Fixed broken color transition on header
+
+mkdocs-material-2.1.0 (2017-11-19)
+
+ * Added support for white as a primary color
+ * Added support for sliding site name and title
+ * Fixed redundant clipboard button when using line numbers on code blocks
+ * Improved header appearance by making it taller
+ * Improved tabs appearance
+ * Improved CSS customizability by leveraging inheritance
+ * Removed scroll shadows via background-attachment
+ * Removed breadcrumbs from header
+
+mkdocs-material-2.0.4 (2017-11-05)
+
+ * Fixed details not opening with footnote reference
+
+mkdocs-material-2.0.3 (2017-11-05)
+
+ * Added Japanese translations
+ * Fixed #540: Jumping to anchor inside details doesn't open it
+ * Fixed active link colors in footer
+
+mkdocs-material-2.0.2 (2017-11-01)
+
+ * Added Russian translations
+ * Fixed #542: Horizontal scrollbar between 1220px and 1234px
+ * Fixed #553: Metadata values only rendering first character
+ * Fixed #558: Flash of unstyled content
+ * Fixed favicon regression caused by deprecation upstream
+
+mkdocs-material-2.0.1 (2017-10-31)
+
+ * Fixed error when initializing search
+ * Fixed styles for link to edit the current page
+ * Fixed styles on nested admonition in details
+
+mkdocs-material-2.0.0 (2017-10-31)
+
+ * Added support for MkDocs 0.17.1 theme configuration options
+ * Added support for easier configuration of search tokenizer
+ * Added support to disable search
+ * Added Korean translations
+ * Removed support for MkDocs 0.16.x [BREAKING]
+
+mkdocs-material-1.12.2 (2017-10-26)
+
+ * Added Italian, Norwegian, French and Chinese translations
+
+mkdocs-material-1.12.1 (2017-10-22)
+
+ * Added Polish, Swedish and Spanish translations
+ * Improved downward compatibility with custom partials
+ * Temporarily pinned MkDocs version within Docker image to 0.16.3
+ * Fixed #519: Missing theme configuration file
+
+mkdocs-material-1.12.0 (2017-10-20)
+
+ * Added support for setting language(s) via mkdocs.yml
+ * Added support for default localization
+ * Added German and Danish translations
+ * Fixed #374: Search bar misalignment on big screens
+
+mkdocs-material-1.11.0 (2017-10-19)
+
+ * Added localization to clipboard
+ * Refactored localization logic
+
+mkdocs-material-1.10.4 (2017-10-18)
+
+ * Improved print styles of code blocks
+ * Improved search UX (don't close on enter if no selection)
+ * Fixed #495: Vertical scrollbar on short pages
+
+mkdocs-material-1.10.3 (2017-10-11)
+
+ * Fixed #484: Vertical scrollbar on some MathJax formulas
+ * Fixed #483: Footnote backref target offset regression
+
+mkdocs-material-1.10.2 (2017-10-06)
+
+ * Fixed #468: Sidebar shows scrollbar if content is shorter (in Safari)
+
+mkdocs-material-1.10.1 (2017-09-14)
+
+ * Fixed #455: Bold code blocks rendered with normal font weight
+
+mkdocs-material-1.10.0 (2017-09-01)
+
+ * Added support to make logo default icon configurable
+ * Fixed uninitialized overflow scrolling on main pane for iOS
+ * Fixed error in mobile navigation in case JavaScript is not available
+ * Fixed incorrect color transition for nested panes in mobile navigation
+ * Improved checkbox styles for Tasklist from PyMdown Extension package
+
+mkdocs-material-1.9.0 (2017-08-29)
+
+ * Added info (synonym: todo) style for admonitions
+ * Added question (synonym: help, faq) style for admonitions
+ * Added support for Details from PyMdown Extensions package
+ * Improved admonition styles to match details
+ * Improved styles for social links in footer
+ * Replaced ligatures with Unicode code points to avoid broken layout
+ * Upgraded PyMdown Extensions package dependency to >= 3.4
+
+mkdocs-material-1.8.1 (2017-08-07)
+
+ * Fixed #421: Missing pagination for GitHub API
+
+mkdocs-material-1.8.0 (2017-08-02)
+
+ * Added support for lazy-loading of search results for better performance
+ * Added support for customization of search tokenizer/separator
+ * Fixed #424: Search doesn't handle capital letters anymore
+ * Fixed #419: Search doesn't work on whole words
+
+mkdocs-material-1.7.5 (2017-07-25)
+
+ * Fixed #398: Forms broken due to search shortcuts
+ * Improved search overall user experience
+ * Improved search matching and highlighting
+ * Improved search accessibility
+
+mkdocs-material-1.7.4 (2017-06-21)
+
+ * Fixed functional link colors in table of contents for active palette
+ * Fixed #368: Compatibility issues with IE11
+
+mkdocs-material-1.7.3 (2017-06-07)
+
+ * Fixed error when setting language to Japanese for site search
+
+mkdocs-material-1.7.2 (2017-06-06)
+
+ * Fixed offset of search box when repo_url is not set
+ * Fixed non-disappearing tooltip
+
+mkdocs-material-1.7.1 (2017-06-01)
+
+ * Fixed wrong z-index order of header, overlay and drawer
+ * Fixed wrong offset of targeted footnote back references
+
+mkdocs-material-1.7.0 (2017-06-01)
+
+ * Added "copy to clipboard" buttons to code blocks
+ * Added support for multilingual site search
+ * Fixed search term highlighting for non-latin languages
+
+mkdocs-material-1.6.4 (2017-05-24)
+
+ * Fixed #337: JavaScript error for GitHub organization URLs
+
+mkdocs-material-1.6.3 (2017-05-16)
+
+ * Fixed #329: Broken source stats for private or unknown GitHub repos
+
+mkdocs-material-1.6.2 (2017-05-15)
+
+ * Fixed #316: Fatal error for git clone on Windows
+ * Fixed #320: Chrome 58 creates double underline for abbr tags
+ * Fixed #323: Ligatures rendered inside code blocks
+ * Fixed miscalculated sidebar height due to missing margin collapse
+ * Changed deprecated MathJax CDN to Cloudflare
+
+mkdocs-material-1.6.1 (2017-04-23)
+
+ * Fixed following of active/focused element if search input is focused
+ * Fixed layer order of search component elements
+
+mkdocs-material-1.6.0 (2017-04-22)
+
+ * Added build test for Docker image on Travis
+ * Added search overlay for better user experience (focus)
+ * Added language from localizations to html tag
+ * Fixed #270: Source links broken for absolute URLs
+ * Fixed missing top spacing for first targeted element in content
+ * Fixed too small footnote divider when using larger font sizes
+
+mkdocs-material-1.5.5 (2017-04-20)
+
+ * Fixed #282: Browser search (META+F) is hijacked
+
+mkdocs-material-1.5.4 (2017-04-08)
+
+ * Fixed broken highlighting for two or more search terms
+ * Fixed missing search results when only a h1 is present
+ * Fixed unresponsive overlay on Android
+
+mkdocs-material-1.5.3 (2017-04-07)
+
+ * Fixed deprecated calls for template variables
+ * Fixed wrong palette color for focused search result
+ * Fixed JavaScript errors on 404 page
+ * Fixed missing top spacing on 404 page
+ * Fixed missing right spacing on overflow of source container
+
+mkdocs-material-1.5.2 (2017-04-05)
+
+ * Added requirements as explicit dependencies in setup.py
+ * Fixed non-synchronized transitions in search form
+
+mkdocs-material-1.5.1 (2017-03-30)
+
+ * Fixed rendering and offset of targeted footnotes
+ * Fixed #238: Link on logo is not set to site_url
+
+mkdocs-material-1.5.0 (2017-03-24)
+
+ * Added support for localization of search placeholder
+ * Added keyboard events for quick access of search
+ * Added keyboard events for search control
+ * Added opacity on hover for search buttons
+ * Added git hook to skip CI build on non-src changes
+ * Fixed non-resetting search placeholder when input is cleared
+ * Fixed error for unescaped parentheses in search term
+ * Fixed #229: Button to clear search missing
+ * Fixed #231: Escape key doesn't exit search
+ * Removed old-style figures from font feature settings
+
+mkdocs-material-1.4.1 (2017-03-16)
+
+ * Fixed invalid destructuring attempt on NodeList (in Safari, Edge, IE)
+
+mkdocs-material-1.4.0 (2017-03-16)
+
+ * Added support for grouping searched sections by documents
+ * Added support for highlighting of search terms
+ * Added support for localization of search results
+ * Fixed #216: table of contents icon doesn't show if h1 is not present
+ * Reworked style and layout of search results for better usability
+
+mkdocs-material-1.3.0 (2017-03-11)
+
+ * Added support for page-specific title and description using metadata
+ * Added support for linking source files to documentation
+ * Fixed jitter and offset of sidebar when zooming browser
+ * Fixed incorrectly initialized tablet sidebar height
+ * Fixed regression for #1: GitHub stars break if the repo_url ends with a '/'
+ * Fixed undesired white line below copyright footer due to base font scaling
+ * Fixed issue with whitespace in path for scripts
+ * Fixed #205: support non-fixed (static) header
+ * Refactored footnote references for better visibility
+ * Reduced repaints to a minimum for non-tabs configuration
+ * Reduced contrast of edit button (slightly)
+
+mkdocs-material-1.2.0 (2017-03-03)
+
+ * Added quote (synonym: cite) style for admonitions
+ * Added help message to build pipeline
+ * Fixed wrong navigation link colors when applying palette
+ * Fixed #197: Link missing in tabs navigation on deeply nested items
+ * Removed unnecessary dev dependencies
+
+mkdocs-material-1.1.1 (2017-02-26)
+
+ * Fixed incorrectly displayed nested lists when using tabs
+
+mkdocs-material-1.1.0 (2017-02-26)
+
+ * Added tabs navigation feature (optional)
+ * Added Disqus integration (optional)
+ * Added a high resolution Favicon with the new logo
+ * Added static type checking using Facebook's Flow
+ * Fixed #173: Dictionary elements have no bottom spacing
+ * Fixed #175: Tables cannot be set to 100% width
+ * Fixed race conditions in build related to asset revisioning
+ * Fixed accidentally re-introduced Permalink on top-level headline
+ * Fixed alignment of logo in drawer on IE11
+ * Refactored styles related to tables
+ * Refactored and automated Docker build and PyPI release
+ * Refactored build scripts
+
+mkdocs-material-1.0.5 (2017-02-18)
+
+ * Fixed #153: Sidebar flows out of constrained area in Chrome 56
+ * Fixed #159: Footer jitter due to JavaScript if content is short
+
+mkdocs-material-1.0.4 (2017-02-16)
+
+ * Fixed #142: Documentation build errors if h1 is defined as raw HTML
+ * Fixed #164: PyPI release does not build and install
+ * Fixed offsets of targeted headlines
+ * Increased sidebar font size by 0.12rem
+
+mkdocs-material-1.0.3 (2017-01-22)
+
+ * Fixed #117: Table of contents items don't blur on fast scrolling
+ * Refactored sidebar positioning logic
+ * Further reduction of repaints
+
+mkdocs-material-1.0.2 (2017-01-15)
+
+ * Fixed #108: Horizontal scrollbar in content area
+
+mkdocs-material-1.0.1 (2017-01-14)
+
+ * Fixed massive repaints happening when scrolling
+ * Fixed footer back reference positions in case of overflow
+ * Fixed header logo from showing when the menu icon is rendered
+ * Changed scrollbar behavior to only show when content overflows
+
+mkdocs-material-1.0.0 (2017-01-13)
+
+ * Introduced Webpack for more sophisticated JavaScript bundling
+ * Introduced ESLint and Stylelint for code style checks
+ * Introduced more accurate Material Design colors and shadows
+ * Introduced modular scales for harmonic font sizing
+ * Introduced git-hooks for better development workflow
+ * Rewrite of CSS using the BEM methodology and SassDoc guidelines
+ * Rewrite of JavaScript using ES6 and Babel as a transpiler
+ * Rewrite of Admonition, Permalinks and CodeHilite integration
+ * Rewrite of the complete typographical system
+ * Rewrite of Gulp asset pipeline in ES6 and separation of tasks
+ * Removed Bower as a dependency in favor of NPM
+ * Removed custom icon build in favor of the Material Design icon set
+ * Removed _blank targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
+ * Removed unversioned assets from build directory
+ * Restructured templates into base templates and partials
+ * Added build and watch scripts in package.json
+ * Added support for Metadata and Footnotes Markdown extensions
+ * Added support for PyMdown Extensions package
+ * Added support for collapsible sections in navigation
+ * Added support for separate table of contents
+ * Added support for better accessibility through REM-based layout
+ * Added icons for GitHub, GitLab and BitBucket integrations
+ * Added more detailed documentation on specimen, extensions etc.
+ * Added a 404.html error page for deployment on GitHub Pages
+ * Fixed live reload chain in watch mode when saving a template
+ * Fixed variable references to work with MkDocs 0.16
+
+mkdocs-material-0.2.4 (2016-06-26)
+
+ * Fixed improperly set default favicon
+ * Fixed #33: Protocol relative URL for webfonts doesn't work with file://
+ * Fixed #34: IE11 on Windows 7 doesn't honor max-width on main tag
+ * Fixed #35: Add styling for blockquotes
+
+mkdocs-material-0.2.3 (2016-05-16)
+
+ * Fixed #25: Highlight inline fenced blocks
+ * Fixed #26: Better highlighting for keystrokes
+ * Fixed #30: Suboptimal syntax highlighting for PHP
+
+mkdocs-material-0.2.2 (2016-03-20)
+
+ * Fixed #15: Document Pygments dependency for CodeHilite
+ * Fixed #16: Favicon could not be set through mkdocs.yml
+ * Fixed #17: Put version into own container for styling
+ * Fixed #20: Fix rounded borders for tables
+
+mkdocs-material-0.2.1 (2016-03-12)
+
+ * Fixed #10: Invisible header after closing search bar with ESC key
+ * Fixed #13: Table cells don't wrap
+ * Fixed empty list in table of contents when no headline is defined
+ * Corrected wrong path for static asset monitoring in Gulpfile.js
+ * Set up tracking of site search for Google Analytics
+
+mkdocs-material-0.2.0 (2016-02-24)
+
+ * Fixed #6: Include multiple color palettes via mkdocs.yml
+ * Fixed #7: Better colors for links inside admonition notes and warnings
+ * Fixed #9: Text for prev/next footer navigation should be customizable
+ * Refactored templates (replaced if/else with modifiers where possible)
+
+mkdocs-material-0.1.3 (2016-02-21)
+
+ * Fixed #3: Ordered lists within an unordered list have ::before content
+ * Fixed #4: Click on Logo/Title without Github-Repository: "None"
+ * Fixed #5: Page without headlines renders empty list in table of contents
+ * Moved Modernizr to top to ensure basic usability in IE8
+
+mkdocs-material-0.1.2 (2016-02-16)
+
+ * Fixed styles for deep navigational hierarchies
+ * Fixed webfont delivery problem when hosted in subdirectories
+ * Fixed print styles in mobile/tablet configuration
+ * Added option to configure fonts in mkdocs.yml with fallbacks
+ * Changed styles for admonition notes and warnings
+ * Set download link to latest version if available
+ * Set up tracking of outgoing links and actions for Google Analytics
+
+mkdocs-material-0.1.1 (2016-02-11)
+
+ * Fixed #1: GitHub stars don't work if the repo_url ends with a '/'
+ * Updated NPM and Bower dependencies to most recent versions
+ * Changed footer/copyright link to Material theme to GitHub pages
+ * Made MkDocs building/serving in build process optional
+ * Set up continuous integration with Travis
+
+mkdocs-material-0.1.0 (2016-02-09)
+
+ * Initial release
diff --git a/mkdocs-material/CODE_OF_CONDUCT.md b/mkdocs-material/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..c0ab1ca
--- /dev/null
+++ b/mkdocs-material/CODE_OF_CONDUCT.md
@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for our community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team privately at hello@squidfunk.com. The
+project team will review and investigate all complaints, and will respond in a
+way that it deems appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an
+incident. Further details of specific enforcement policies may be posted
+separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/mkdocs-material/CONTRIBUTING.md b/mkdocs-material/CONTRIBUTING.md
new file mode 100644
index 0000000..f24beff
--- /dev/null
+++ b/mkdocs-material/CONTRIBUTING.md
@@ -0,0 +1,62 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly improved project
+that serves a diverse user base with varying backgrounds and needs. In order to
+effectively address the needs of all our users, evaluate change requests, and
+fix bugs, we maintainers need to put in a lot of work. We have devoted
+significant effort to creating better templates for our issue tracker,
+optimizing the processes for our users to report bugs, request features or
+changes, contribute to the project, or exchange with our community.
+
+Given the wealth of valuable knowledge contained in numerous issues and
+discussions, we consider our [issue tracker] and [discussion board] to serve as
+a crucial __knowledge base__ that is an important addition to our [documentation]
+and brings value to both new and experienced users of Material for MkDocs.
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+
+## How to contribute
+
+### Creating an issue
+
+- #### [Report a bug]
+
+ __Something is not working?__ Report a bug in Material for MkDocs by
+ creating an issue with a reproduction
+
+- #### [Report a docs issue]
+
+ __Missing information in our docs?__ Report missing information or
+ potential inconsistencies in our documentation
+
+- #### [Request a change]
+
+ __Want to submit an idea?__ Propose a change, feature request, or
+ suggest an improvement
+
+- #### [Ask a question]
+
+ __Have a question or need help?__ Ask a question on our [discussion board]
+ and get in touch with our community
+
+### Contributing
+
+- #### [Add a translation]
+
+ __Missing support for your language?__ Add missing translations for a new
+ or already supported language
+
+- #### [Create a pull request]
+
+ __Want to create a pull request?__ Learn how to create a comprehensive
+ and useful pull request (PR)s
+
+ [Report a bug]: docs/contributing/reporting-a-bug.md
+ [Report a docs issue]: docs/contributing/reporting-a-docs-issue.md
+ [Request a change]: docs/contributing/requesting-a-change.md
+ [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+ [Add a translation]: docs/contributing/adding-translations
+ [Create a pull request]: docs/contributing/making-a-pull-request.md
+
diff --git a/mkdocs-material/Dockerfile b/mkdocs-material/Dockerfile
new file mode 100644
index 0000000..b042e38
--- /dev/null
+++ b/mkdocs-material/Dockerfile
@@ -0,0 +1,102 @@
+# Copyright (c) 2016-2024 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+FROM python:3.11-alpine3.19
+
+# Build-time flags
+ARG WITH_PLUGINS=true
+
+# Environment variables
+ENV PACKAGES=/usr/local/lib/python3.11/site-packages
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Set build directory
+WORKDIR /tmp
+
+# Copy files necessary for build
+COPY material material
+COPY package.json package.json
+COPY README.md README.md
+COPY *requirements.txt ./
+COPY pyproject.toml pyproject.toml
+
+# Perform build and cleanup artifacts and caches
+RUN \
+ apk upgrade --update-cache -a \
+&& \
+ apk add --no-cache \
+ cairo \
+ freetype-dev \
+ git \
+ git-fast-import \
+ jpeg-dev \
+ openssh \
+ tini \
+ zlib-dev \
+&& \
+ apk add --no-cache --virtual .build \
+ gcc \
+ g++ \
+ libffi-dev \
+ musl-dev \
+&& \
+ pip install --no-cache-dir --upgrade pip \
+&& \
+ pip install --no-cache-dir . \
+&& \
+ if [ "${WITH_PLUGINS}" = "true" ]; then \
+ pip install --no-cache-dir \
+ mkdocs-material[recommended] \
+ mkdocs-material[imaging]; \
+ fi \
+&& \
+ if [ -e user-requirements.txt ]; then \
+ pip install -U -r user-requirements.txt; \
+ fi \
+&& \
+ apk del .build \
+&& \
+ for theme in mkdocs readthedocs; do \
+ rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
+ ln -s \
+ ${PACKAGES}/material/templates \
+ ${PACKAGES}/mkdocs/themes/$theme; \
+ done \
+&& \
+ rm -rf /tmp/* /root/.cache \
+&& \
+ find ${PACKAGES} \
+ -type f \
+ -path "*/__pycache__/*" \
+ -exec rm -f {} \; \
+&& \
+ git config --system --add safe.directory /docs \
+&& \
+ git config --system --add safe.directory /site
+
+# Set working directory
+WORKDIR /docs
+
+# Expose MkDocs development server port
+EXPOSE 8000
+
+# Start development server by default
+ENTRYPOINT ["/sbin/tini", "--", "mkdocs"]
+CMD ["serve", "--dev-addr=0.0.0.0:8000"]
diff --git a/mkdocs-material/LICENSE b/mkdocs-material/LICENSE
new file mode 100644
index 0000000..fb988d0
--- /dev/null
+++ b/mkdocs-material/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2016-2024 Martin Donath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/mkdocs-material/README.md b/mkdocs-material/README.md
new file mode 100644
index 0000000..e880dbb
--- /dev/null
+++ b/mkdocs-material/README.md
@@ -0,0 +1,349 @@
+
+
+ A powerful documentation framework on top of
+ MkDocs
+
+
+
+
+
+
+
+
+
+
+
+
+ Write your documentation in Markdown and create a professional static site for
+ your Open Source or commercial project in minutes – searchable, customizable,
+ more than 60 languages, for all devices.
+
+
+## Everything you would expect
+
+### It's just Markdown
+
+Focus on the content of your documentation and create a professional static site
+in minutes. No need to know HTML, CSS or JavaScript – let Material for MkDocs do
+the heavy lifting for you.
+
+### Works on all devices
+
+Serve your documentation with confidence – Material for MkDocs automatically
+adapts to perfectly fit the available screen estate, no matter the type or size
+of the viewing device. Desktop. Tablet. Mobile. All great.
+
+### Made to measure
+
+Make it yours – change the colors, fonts, language, icons, logo, and more with
+a few lines of configuration. Material for MkDocs can be easily extended and
+provides many options to alter appearance and behavior.
+
+### Fast and lightweight
+
+Don't let your users wait – get incredible value with a small footprint by using
+one of the fastest themes available with excellent performance, yielding optimal
+search engine rankings and happy users that return.
+
+### Built for everyone
+
+Make accessibility a priority – users can navigate your documentation with touch
+devices, keyboards, and screen readers. Semantic markup ensures that your
+documentation works for everyone.
+
+### Open Source
+
+Trust 20,000+ users – choose a mature and actively maintained solution built
+with state-of-the-art Open Source technologies. Keep ownership of your content
+without fear of vendor lock-in. Licensed under MIT.
+
+## Quick start
+
+Material for MkDocs can be installed with `pip`:
+
+``` sh
+pip install mkdocs-material
+```
+
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ name: material
+```
+
+For detailed installation instructions, configuration options, and a demo, visit
+[squidfunk.github.io/mkdocs-material][Material for MkDocs]
+
+ [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+
+## Trusted by ...
+
+### ... industry leaders
+
+[ArXiv](https://info.arxiv.org),
+[Atlassian](https://atlassian.github.io/data-center-helm-charts/),
+[AWS](https://aws.github.io/copilot-cli/),
+[Bloomberg](https://bloomberg.github.io/selekt/),
+[CERN](http://abpcomputing.web.cern.ch/),
+[CloudFlare](https://cloudflare.github.io/itty-router-openapi/),
+[Datadog](https://datadoghq.dev/integrations-core/),
+[Google](https://google.github.io/accompanist/),
+[Harvard](https://informatics.fas.harvard.edu/),
+[Hewlett Packard](https://hewlettpackard.github.io/squest/),
+[HSBC](https://hsbc.github.io/pyratings/),
+[ING](https://ing-bank.github.io/baker/),
+[Intel](https://open-amt-cloud-toolkit.github.io/docs/),
+[JetBrains](https://jetbrains.github.io/projector-client/mkdocs/),
+[LinkedIn](https://linkedin.github.io/school-of-sre/),
+[Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
+[Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
+[Netflix](https://netflix.github.io/titus/),
+[Red Hat](https://ansible.readthedocs.io/projects/lint/),
+[Roboflow](https://inference.roboflow.com/),
+[Salesforce](https://policy-sentry.readthedocs.io/),
+[SIEMENS](https://opensource.siemens.com/),
+[Slack](https://slackhq.github.io/circuit/),
+[Square](https://square.github.io/okhttp/),
+[Uber](https://uber-go.github.io/fx/),
+[Zalando](https://opensource.zalando.com/skipper/)
+
+### ... and successful Open Source projects
+
+[Amp](https://amp.rs/docs/),
+[Arduino](https://arduino.github.io/arduino-cli/),
+[Auto-GPT](https://docs.agpt.co/),
+[AutoKeras](https://autokeras.com/),
+[BFE](https://www.bfe-networks.net/),
+[CentOS](https://docs.infra.centos.org/),
+[Crystal](https://crystal-lang.org/reference/),
+[eBPF](https://ebpf-go.dev/),
+[Electron](https://www.electron.build/),
+[FastAPI](https://fastapi.tiangolo.com/),
+[Freqtrade](https://www.freqtrade.io/en/stable/),
+[GoReleaser](https://goreleaser.com/),
+[HedgeDoc](https://docs.hedgedoc.org/),
+[Hummingbot](https://hummingbot.org/),
+[Knative](https://knative.dev/docs/),
+[Kubernetes](https://kops.sigs.k8s.io/),
+[kSQL](https://docs.ksqldb.io/),
+[NetBox](https://netboxlabs.com/docs/netbox/en/stable/),
+[Nokogiri](https://nokogiri.org/),
+[OpenFaaS](https://docs.openfaas.com/),
+[Orchard Core](https://docs.orchardcore.net/en/latest/),
+[Percona](https://docs.percona.com/percona-monitoring-and-management/),
+[Pi-Hole](https://docs.pi-hole.net/),
+[Pydantic](https://pydantic-docs.helpmanual.io/),
+[PyPI](https://docs.pypi.org/),
+[Renovate](https://docs.renovatebot.com/),
+[RetroPie](https://retropie.org.uk/docs/),
+[Supervision](https://supervision.roboflow.com/latest/),
+[Traefik](https://docs.traefik.io/),
+[Trivy](https://aquasecurity.github.io/trivy/),
+[Typer](https://typer.tiangolo.com/),
+[tinygrad](https://docs.tinygrad.org/),
+[Ultralytics](https://docs.ultralytics.com/),
+[Vapor](https://docs.vapor.codes/),
+[WebKit](https://docs.webkit.org/),
+[WTF](https://wtfutil.com/),
+[ZeroNet](https://zeronet.io/docs/)
+
+## License
+
+**MIT License**
+
+Copyright (c) 2016-2024 Martin Donath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/mkdocs-material/docs/alternatives.md b/mkdocs-material/docs/alternatives.md
new file mode 100644
index 0000000..dcfbda7
--- /dev/null
+++ b/mkdocs-material/docs/alternatives.md
@@ -0,0 +1,112 @@
+# Alternatives
+
+There are tons of static site generators and themes out there and choosing the
+right one for your tech stack is a tough decision. If you're unsure if Material
+for MkDocs is the right solution for you, this section should help you evaluate
+alternative solutions.
+
+## Docusaurus
+
+[Docusaurus] by Facebook is a very popular documentation generator and a good
+choice if you or your company are already using [React] to build your site.
+It will generate a [single page application] which is fundamentally different
+from the site Material for MkDocs generates for you.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Provides many components that aid in technical writing
+- Large and rich ecosystem, backed by Facebook
+
+__Challenges__
+
+- High learning curve, JavaScript knowledge mandatory
+- JavaScript ecosystem is very volatile, rather high maintenance
+- More time needed to get up and running
+
+While [Docusaurus] is one of the best choices when it comes to documentation
+sites that output a single page application, there are many more solutions,
+including [Docz], [Gatsby], [Vuepress] and [Docsify] that approach
+this problem similarly.
+
+ [Docusaurus]: https://docusaurus.io/
+ [React]: https://reactjs.org/
+ [single page application]: https://en.wikipedia.org/wiki/Single-page_application
+ [Docz]: https://www.docz.site/
+ [Gatsby]: https://www.gatsbyjs.com/
+ [VuePress]: https://vuepress.vuejs.org/
+ [Docsify]: https://docsify.js.org/
+
+## Jekyll
+
+[Jekyll] is probably one of the most mature and widespread static site
+generators and is written in [Ruby]. It is not specifically geared towards
+technical project documentation and has many themes to choose from, which
+can be challenging.
+
+__Advantages__
+
+- Battle-tested, rich ecosystem, many themes to choose from
+- Brings great capabilities for blogging (permalinks, tags, etc.)
+- Generates a SEO-friendly site, similar to Material for MkDocs
+
+__Challenges__
+
+- Not specifically geared towards technical project documentation
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- More time needed to get up and running
+
+ [Jekyll]: https://jekyllrb.com/
+ [Ruby]: https://www.ruby-lang.org/de/
+
+## Sphinx
+
+[Sphinx] is an alternative static site generator specifically geared towards
+generating reference documentation, offering powerful capabilities that are
+lacking in MkDocs. It uses [reStructured text], a format similar to Markdown,
+which some users find harder to use.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Generates reference documentation from [Python docstrings]
+- Large and rich ecosystem, used by many Python projects
+
+__Challenges__
+
+- High learning curve, [reStructured text] syntax might be challenging
+- Search is less powerful than the one provided by MkDocs
+- More time needed to get up and running
+
+If you're considering using Sphinx because you need to generate reference
+documentation, you should give [mkdocstrings] a try – an actively maintained
+and popular framework building on top of MkDocs, implementing Sphinx-like
+functionality.
+
+ [Sphinx]: https://www.sphinx-doc.org/
+ [reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText
+ [Python docstrings]: https://www.python.org/dev/peps/pep-0257/
+ [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
+
+## GitBook
+
+[GitBook] offers a hosted documentation solution that generates a beautiful and
+functional site from Markdown files in your GitHub repository. However, it was
+once Open Source, but turned into a closed source solution some time ago.
+
+__Advantages__
+
+- Hosted solution, minimal technical knowledge required
+- Custom domains, authentication and other enterprise features
+- Great collaboration features for teams
+
+__Challenges__
+
+- Closed source, not free for proprietary projects
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- Many Open Source projects moved away from GitBook
+
+Many users switched from [GitBook] to Material for MkDocs, as they want to keep
+control and ownership of their documentation, favoring an Open Source solution.
+
+ [GitBook]: https://www.gitbook.com/
diff --git a/mkdocs-material/docs/assets/favicon.png b/mkdocs-material/docs/assets/favicon.png
new file mode 100644
index 0000000..6771c11
Binary files /dev/null and b/mkdocs-material/docs/assets/favicon.png differ
diff --git a/mkdocs-material/docs/assets/images/illustration.png b/mkdocs-material/docs/assets/images/illustration.png
new file mode 100644
index 0000000..69f739c
Binary files /dev/null and b/mkdocs-material/docs/assets/images/illustration.png differ
diff --git a/mkdocs-material/docs/assets/images/zelda-dark-world.png b/mkdocs-material/docs/assets/images/zelda-dark-world.png
new file mode 100644
index 0000000..275f858
Binary files /dev/null and b/mkdocs-material/docs/assets/images/zelda-dark-world.png differ
diff --git a/mkdocs-material/docs/assets/images/zelda-light-world.png b/mkdocs-material/docs/assets/images/zelda-light-world.png
new file mode 100644
index 0000000..aaf9f71
Binary files /dev/null and b/mkdocs-material/docs/assets/images/zelda-light-world.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/annotations.png b/mkdocs-material/docs/assets/screenshots/annotations.png
new file mode 100644
index 0000000..a4422bc
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/annotations.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/back-to-top.png b/mkdocs-material/docs/assets/screenshots/back-to-top.png
new file mode 100644
index 0000000..6771bad
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/back-to-top.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/consent.png b/mkdocs-material/docs/assets/screenshots/consent.png
new file mode 100644
index 0000000..2ab700a
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/consent.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/content-tabs-link.png b/mkdocs-material/docs/assets/screenshots/content-tabs-link.png
new file mode 100644
index 0000000..c0edb59
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/content-tabs-link.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/content-tabs.png b/mkdocs-material/docs/assets/screenshots/content-tabs.png
new file mode 100644
index 0000000..1c68d5b
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/content-tabs.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/creating-your-site.png b/mkdocs-material/docs/assets/screenshots/creating-your-site.png
new file mode 100644
index 0000000..0243b61
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/creating-your-site.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/feedback-report.png b/mkdocs-material/docs/assets/screenshots/feedback-report.png
new file mode 100644
index 0000000..eb7e3be
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/feedback-report.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/hide-navigation-toc.png b/mkdocs-material/docs/assets/screenshots/hide-navigation-toc.png
new file mode 100644
index 0000000..12fd440
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/hide-navigation-toc.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/hide-navigation.png b/mkdocs-material/docs/assets/screenshots/hide-navigation.png
new file mode 100644
index 0000000..e6c8b34
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/hide-navigation.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/hide-toc.png b/mkdocs-material/docs/assets/screenshots/hide-toc.png
new file mode 100644
index 0000000..ab94778
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/hide-toc.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/language-selection.png b/mkdocs-material/docs/assets/screenshots/language-selection.png
new file mode 100644
index 0000000..964c671
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/language-selection.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-expand.png b/mkdocs-material/docs/assets/screenshots/navigation-expand.png
new file mode 100644
index 0000000..a37c66a
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-expand.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-index-off.png b/mkdocs-material/docs/assets/screenshots/navigation-index-off.png
new file mode 100644
index 0000000..ab3751c
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-index-off.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-index-on.png b/mkdocs-material/docs/assets/screenshots/navigation-index-on.png
new file mode 100644
index 0000000..819069c
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-index-on.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-path-off.png b/mkdocs-material/docs/assets/screenshots/navigation-path-off.png
new file mode 100644
index 0000000..b212e78
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-path-off.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-path-on.png b/mkdocs-material/docs/assets/screenshots/navigation-path-on.png
new file mode 100644
index 0000000..0afb80f
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-path-on.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-sections.png b/mkdocs-material/docs/assets/screenshots/navigation-sections.png
new file mode 100644
index 0000000..b0edf57
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-sections.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-tabs-collapsed.png b/mkdocs-material/docs/assets/screenshots/navigation-tabs-collapsed.png
new file mode 100644
index 0000000..1c5d64e
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-tabs-collapsed.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-tabs-sticky.png b/mkdocs-material/docs/assets/screenshots/navigation-tabs-sticky.png
new file mode 100644
index 0000000..b8bd595
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-tabs-sticky.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation-tabs.png b/mkdocs-material/docs/assets/screenshots/navigation-tabs.png
new file mode 100644
index 0000000..96af83d
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation-tabs.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/navigation.png b/mkdocs-material/docs/assets/screenshots/navigation.png
new file mode 100644
index 0000000..82864b5
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/navigation.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/search-highlighting.png b/mkdocs-material/docs/assets/screenshots/search-highlighting.png
new file mode 100644
index 0000000..69556e7
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/search-highlighting.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/search-share.png b/mkdocs-material/docs/assets/screenshots/search-share.png
new file mode 100644
index 0000000..0271ba1
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/search-share.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/search-suggestions.png b/mkdocs-material/docs/assets/screenshots/search-suggestions.png
new file mode 100644
index 0000000..20ccde9
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/search-suggestions.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-accent.png b/mkdocs-material/docs/assets/screenshots/social-cards-accent.png
new file mode 100644
index 0000000..8531f69
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-accent.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-debug.png b/mkdocs-material/docs/assets/screenshots/social-cards-debug.png
new file mode 100644
index 0000000..bef1c0a
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-debug.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-invert.png b/mkdocs-material/docs/assets/screenshots/social-cards-invert.png
new file mode 100644
index 0000000..156a4e9
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-invert.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-0.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-0.png
new file mode 100644
index 0000000..063d5f9
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-0.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-1.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-1.png
new file mode 100644
index 0000000..af66e76
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-1.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-2.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-2.png
new file mode 100644
index 0000000..05efa9d
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-2.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-3.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-3.png
new file mode 100644
index 0000000..1511b99
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-3.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-4.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-4.png
new file mode 100644
index 0000000..45ad3cd
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-4.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-5.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-5.png
new file mode 100644
index 0000000..7595600
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-5.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-color.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-color.png
new file mode 100644
index 0000000..95ade51
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-color.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-image.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-image.png
new file mode 100644
index 0000000..d66cff1
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background-image.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-background.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background.png
new file mode 100644
index 0000000..11d0f99
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-background.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon-circles.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon-circles.png
new file mode 100644
index 0000000..c30d86f
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon-circles.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon.png
new file mode 100644
index 0000000..d3b82ac
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-icon.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-size.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-size.png
new file mode 100644
index 0000000..a0a260e
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-size.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-align.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-align.png
new file mode 100644
index 0000000..e05e4ab
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-align.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-ellipsis.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-ellipsis.png
new file mode 100644
index 0000000..34750ae
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-ellipsis.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-shrink.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-shrink.png
new file mode 100644
index 0000000..82670c3
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography-shrink.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography.png b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography.png
new file mode 100644
index 0000000..c4e97c7
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-layer-typography.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards-variant.png b/mkdocs-material/docs/assets/screenshots/social-cards-variant.png
new file mode 100644
index 0000000..7bdaae3
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards-variant.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/social-cards.png b/mkdocs-material/docs/assets/screenshots/social-cards.png
new file mode 100644
index 0000000..40c51d7
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/social-cards.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/tags-index.png b/mkdocs-material/docs/assets/screenshots/tags-index.png
new file mode 100644
index 0000000..35de440
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/tags-index.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/tags-search.png b/mkdocs-material/docs/assets/screenshots/tags-search.png
new file mode 100644
index 0000000..4bea802
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/tags-search.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/tags.png b/mkdocs-material/docs/assets/screenshots/tags.png
new file mode 100644
index 0000000..9e93a9c
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/tags.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/toc-integrate.png b/mkdocs-material/docs/assets/screenshots/toc-integrate.png
new file mode 100644
index 0000000..04fe87d
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/toc-integrate.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/version-warning.png b/mkdocs-material/docs/assets/screenshots/version-warning.png
new file mode 100644
index 0000000..d7262c4
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/version-warning.png differ
diff --git a/mkdocs-material/docs/assets/screenshots/versioning.png b/mkdocs-material/docs/assets/screenshots/versioning.png
new file mode 100644
index 0000000..114334c
Binary files /dev/null and b/mkdocs-material/docs/assets/screenshots/versioning.png differ
diff --git a/mkdocs-material/docs/blog/.authors.yml b/mkdocs-material/docs/blog/.authors.yml
new file mode 100644
index 0000000..722d92d
--- /dev/null
+++ b/mkdocs-material/docs/blog/.authors.yml
@@ -0,0 +1,16 @@
+authors:
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://avatars.githubusercontent.com/u/932156
+ url: https://github.com/squidfunk
+ alexvoss:
+ name: Alex Voss
+ description: Solutions Architect
+ avatar: https://avatars.githubusercontent.com/u/4134224
+ url: https://github.com/alexvoss
+ katharinalisalin:
+ name: Kathi
+ description: Communications
+ avatar: https://avatars.githubusercontent.com/u/105352741
+ url: https://github.com/katharinalisalin
diff --git a/mkdocs-material/docs/blog/.meta.yml b/mkdocs-material/docs/blog/.meta.yml
new file mode 100644
index 0000000..ea01dc9
--- /dev/null
+++ b/mkdocs-material/docs/blog/.meta.yml
@@ -0,0 +1,3 @@
+comments: true
+hide:
+ - feedback
diff --git a/mkdocs-material/docs/blog/index.md b/mkdocs-material/docs/blog/index.md
new file mode 100644
index 0000000..05761ac
--- /dev/null
+++ b/mkdocs-material/docs/blog/index.md
@@ -0,0 +1 @@
+# Blog
diff --git a/mkdocs-material/docs/blog/posts/adding-a-badge-to-your-project.md b/mkdocs-material/docs/blog/posts/adding-a-badge-to-your-project.md
new file mode 100644
index 0000000..26fd7bd
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/adding-a-badge-to-your-project.md
@@ -0,0 +1,37 @@
+---
+title: Adding a badge to your project
+date: 2023-11-30
+authors: [squidfunk]
+slug: adding-a-badge-to-your-project
+description: >
+ Share the love – you can now add a badge to your README, showing that your
+ project is built with Material for MkDocs
+categories:
+ - General
+---
+
+# Adding a :simple-materialformkdocs: badge to your project
+
+__You enjoy working with Material for MkDocs? Share the love! You can now add
+a badge to your project's README, showing that your project is built with
+Material for MkDocs.__
+
+Material for MkDocs' logo was just added to [Simple Icons], which is used by
+[Shields.io] to include logos in badges. We generated a badge for you, which
+you can add to your project's README:
+
+[![Material for MkDocs][badge]](#usage)
+
+
+
+## Usage
+
+Just copy the following snippet and paste it into your project's `README.md`:
+
+``` markdown
+[](https://squidfunk.github.io/mkdocs-material/)
+```
+
+ [Simple Icons]: https://simpleicons.org/
+ [Shields.io]: https://shields.io/
+ [badge]: https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white
diff --git a/mkdocs-material/docs/blog/posts/blog-support-just-landed.md b/mkdocs-material/docs/blog/posts/blog-support-just-landed.md
new file mode 100644
index 0000000..8d83ecf
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/blog-support-just-landed.md
@@ -0,0 +1,228 @@
+---
+date: 2022-09-12
+authors: [squidfunk]
+description: >
+ Our new blog is built with the brand new built-in blog plugin. You can build
+ a blog alongside your documentation or standalone
+categories:
+ - Blog
+links:
+ - setup/setting-up-a-blog.md
+ - plugins/blog.md
+---
+
+# Blog support just landed
+
+__Hey there! You're looking at our new blog, built with the brand new
+[built-in blog plugin]. With this plugin, you can easily build a blog alongside
+your documentation or standalone.__
+
+Proper support for blogging, as requested by many users over the past few years,
+was something that was desperately missing from Material for MkDocs' feature set.
+While everybody agreed that blogging support was a blind spot, it was not
+obvious whether MkDocs could be extended in a way to allow for blogging as we
+know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is,
+after all, possible to build a blogging engine on top of MkDocs, in order to
+create a technical blog alongside your documentation, or as the main thing.
+
+
+
+_This article explains how to build a standalone blog with Material for MkDocs.
+If you want to build a blog alongside your documentation, please refer to
+[the plugin's documentation][built-in blog plugin]._
+
+ [built-in blog plugin]: ../../plugins/blog.md
+ [Jekyll]: https://jekyllrb.com/
+
+## Quick start
+
+### Creating a standalone blog
+
+You can bootstrap a new project using the `mkdocs` executable:
+
+```
+mkdocs new .
+```
+
+This will create the following structure:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+#### Configuration
+
+In this article, we're going to build a standalone blog, which means that the
+blog lives at the root of your project. For this reason, open `mkdocs.yml`,
+and replace its contents with:
+
+``` yaml
+site_name: My Blog
+theme:
+ name: material
+ features:
+ - navigation.sections
+plugins:
+ - blog:
+ blog_dir: . # (1)!
+ - search
+ - tags
+nav:
+ - index.md
+```
+
+1. This is the important part – we're hosting the blog at the root of the
+ project, and not in a subdirectory. For more information, see the
+ [`blog_dir`][blog_dir] configuration option.
+
+ [blog_dir]: ../../plugins/blog.md#config.blog_dir
+
+#### Blog setup
+
+The blog index page lives in `docs/index.md`. This page was pre-filled by
+MkDocs with some content, so we're going to replace it with what we need to
+bootstrap the blog:
+
+``` markdown
+# Blog
+```
+
+That's it.
+
+### Writing your first post
+
+Now that we have set up the [built-in blog plugin], we can start writing our
+first post. All blog posts are written with the [exact same Markdown flavor] as
+already included with Material for MkDocs. First, create a folder called `posts`
+with a file called `hello-world.md`:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ ├─ posts/
+│ │ └─ hello-world.md # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. If you'd like to arrange posts differently, you're free to do so. The URLs
+ are built from the format specified in [`post_url_format`][post slugs] and
+ the titles and dates of posts, no matter how they are organized
+ inside the `posts` directory.
+
+Then, open up `hello-world.md`, and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2022-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
+maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
+erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
+Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
+Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
+sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
+metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.
+
+
+
+Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
+massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
+tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
+molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.
+
+Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
+In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
+pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
+arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
+In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
+tellus id elit ultricies, vel finibus erat cursus.
+```
+
+1. If you mark a post as a [draft], a red marker appears next to the post date
+ on index pages. When the site is built, drafts are not included in the
+ output. [This behavior can be changed], e.g. for rendering drafts when
+ building deploy previews.
+
+When you spin up the [live preview server], you should be greeted by your first
+post! You'll also realize, that [archive] and [category] indexes have been
+automatically generated for you:
+
+ ![Blog]
+
+However, this is just the start. The [built-in blog plugin] packs a lot of
+functionality needed in day-to-day blogging. Visit the documentation of the
+plugin to learn about the following topics:
+
+
+
+- [Adding an excerpt]
+- [Adding authors]
+- [Adding categories]
+- [Adding tags]
+- [Adding related links]
+- [Linking from and to posts]
+- [Setting the reading time]
+- [Setting defaults]
+
+
+
+Additionally, the [built-in blog plugin] has dozens of [configuration options]
+which allow for fine-tuning the output. You can configure post slugs, general
+behavior and much more.
+
+ [exact same Markdown flavor]: ../../reference/index.md
+ [post slugs]: ../../plugins/blog.md#config.post_url_format
+ [draft]: ../../plugins/blog.md#meta.draft
+ [This behavior can be changed]: ../../plugins/blog.md#config.draft
+ [live preview server]: ../../creating-your-site.md#previewing-as-you-write
+ [archive]: ../../plugins/blog.md#config.archive
+ [category]: ../../plugins/blog.md#config.categories
+ [Blog]: blog-support-just-landed/blog.png
+ [Blog post]: blog-support-just-landed/blog-post.png
+ [Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt
+ [Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors
+ [Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories
+ [Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags
+ [Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links
+ [Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts
+ [Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time
+ [Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults
+ [configuration options]: ../../setup/setting-up-a-blog.md#configuration
+
+## What's next?
+
+Getting basic blogging support out the door was quite a challenge – the
+[built-in blog plugin] is probably the biggest release this year and already
+packs a lot of functionality. However, Material for MkDocs is used in many
+different contexts, which is why we'd expect to iterate, as always.
+
+Some ideas already proposed by users:
+
+- __Blog series__: Authors should be able to create so called blog series and
+ assign posts to a blog series using simple identifiers. For each post that is
+ part of a series, a list with links to all other posts should be included in
+ the post's content.
+
+- __Author indexes__: Besides [archive] and [category] indexes, authors should
+ be able to create per-author indexes, which list all posts linked to an
+ author. Additionally, a profile should be created for each author and linked
+ from posts.
+
+- __Social share buttons__: It should be easy to share blog posts via social
+ media or other ways. For this reason, it should be possible to automatically
+ include social sharing buttons with each post.
+
+What's still missing from the brand new [built-in blog plugin]? Feel free to
+share your ideas in the comments. Together, we can build one of the best modern
+engines for technical blogging!
diff --git a/mkdocs-material/docs/blog/posts/blog-support-just-landed/blog.png b/mkdocs-material/docs/blog/posts/blog-support-just-landed/blog.png
new file mode 100644
index 0000000..a1ea1ea
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/blog-support-just-landed/blog.png differ
diff --git a/mkdocs-material/docs/blog/posts/chinese-search-support.md b/mkdocs-material/docs/blog/posts/chinese-search-support.md
new file mode 100644
index 0000000..c1ab7b7
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/chinese-search-support.md
@@ -0,0 +1,83 @@
+---
+date: 2022-05-05
+authors: [squidfunk]
+title: Chinese search support
+description: >
+ Insiders adds Chinese language support for the built-in search plugin – a
+ feature that has been requested many times
+categories:
+ - Search
+links:
+ - blog/posts/search-better-faster-smaller.md
+ - plugins/search.md#segmentation
+ - insiders/how-to-sponsor.md
+---
+
+# Chinese search support – 中文搜索支持
+
+__Insiders adds experimental Chinese language support for the [built-in search
+plugin] – a feature that has been requested for a long time given the large
+number of Chinese users.__
+
+After the United States and Germany, the third-largest country of origin of
+Material for MkDocs users is China. For a long time, the [built-in search plugin]
+didn't allow for proper segmentation of Chinese characters, mainly due to
+missing support in [lunr-languages] which is used for search tokenization and
+stemming. The latest Insiders release adds long-awaited Chinese language support
+for the built-in search plugin, something that has been requested by many users.
+
+
+
+_Material for MkDocs終於支持中文了!文本被正確分割並且更容易找到。_
+{ style="display: inline" }
+
+_This article explains how to set up Chinese language support for the built-in
+search plugin in a few minutes._
+{ style="display: inline" }
+
+ [built-in search plugin]: ../../plugins/search.md
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+
+## Configuration
+
+Chinese language support for Material for MkDocs is provided by [jieba], an
+excellent Chinese text segmentation library. If [jieba] is installed, the
+built-in search plugin automatically detects Chinese characters and runs them
+through the segmenter. You can install [jieba] with:
+
+```
+pip install jieba
+```
+
+The next step is only required if you specified the [`separator`][separator]
+configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace]
+characters, so it renders exactly the same in the search modal. Adjust
+`mkdocs.yml` so that the [`separator`][separator] includes the `\u200b`
+character:
+
+``` yaml
+plugins:
+ - search:
+ separator: '[\s\u200b\-]'
+```
+
+That's all that is necessary.
+
+## Usage
+
+If you followed the instructions in the configuration guide, Chinese words will
+now be tokenized using [jieba]. Try searching for
+[:octicons-search-24: 支持][q=支持] to see how it integrates with the
+built-in search plugin.
+
+---
+
+Note that this is an experimental feature, and I, @squidfunk, am not
+proficient in Chinese (yet?). If you find a bug or think something can be
+improved, please [open an issue].
+
+ [jieba]: https://pypi.org/project/jieba/
+ [zero-width whitespace]: https://en.wikipedia.org/wiki/Zero-width_space
+ [separator]: ../../plugins/search.md#config.separator
+ [q=支持]: ?q=支持
+ [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
diff --git a/mkdocs-material/docs/blog/posts/excluding-content-from-search.md b/mkdocs-material/docs/blog/posts/excluding-content-from-search.md
new file mode 100644
index 0000000..85428ea
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/excluding-content-from-search.md
@@ -0,0 +1,207 @@
+---
+date: 2021-09-26
+authors: [squidfunk]
+description: >
+ Three new simple ways to exclude dedicated parts of a document from the search
+ index, allowing for more fine-grained control
+categories:
+ - Search
+links:
+ - blog/posts/search-better-faster-smaller.md
+ - setup/setting-up-site-search.md#search-exclusion
+ - insiders/how-to-sponsor.md
+---
+
+# Excluding content from search
+
+__The latest Insiders release brings three new simple ways to exclude
+dedicated parts of a document from the search index, allowing for more
+fine-grained control.__
+
+Two weeks ago, Material for MkDocs Insiders shipped a [brand new search
+plugin], yielding [massive improvements in usability], but also in [speed
+and size] of the search index. Interestingly, as discussed in the previous
+blog article, we only scratched the surface of what's now possible. This
+release brings some useful features that enhance the writing experience,
+allowing for more fine-grained control of what pages, sections and blocks of a
+Markdown file should be indexed by the built-in search functionality.
+
+
+
+_The following section discusses existing solutions for excluding pages and
+sections from the search index. If you immediately want to learn what's new,
+skip to the [section just after that][what's new]._
+
+ [brand new search plugin]: search-better-faster-smaller.md
+ [massive improvements in usability]: search-better-faster-smaller.md#whats-new
+ [speed and size]: search-better-faster-smaller.md#benchmarks
+ [what's new]: #whats-new
+
+## Prior art
+
+MkDocs has a rich and thriving ecosystem of [plugins], and it comes as no
+surprise that there's already a fantastic plugin by @chrieke to exclude specific
+sections of a Markdown file – the [mkdocs-exclude-search] plugin. It can be
+installed with:
+
+```
+pip install mkdocs-exclude-search
+```
+
+__How it works__: the plugin post-processes the `search_index.json` file that
+is generated by the built-in search plugin, giving the author the ability to
+exclude certain pages and sections by adding a few lines of configuration to
+`mkdocs.yml`. An example:
+
+``` yaml
+plugins:
+ - search
+ - exclude-search:
+ exclude:
+ - page.md
+ - page.md#section
+ - directory/*
+ - /*/page.md
+```
+
+It's easy to see that the plugin follows a configuration-centric approach, which
+adds support for advanced filtering techniques like infix- and suffix-filtering
+using wildcards. While this is a very powerful idea, it comes with some
+downsides:
+
+1. __Exclusion patterns and content are not co-located__: exclusion patterns
+ need to be defined in `mkdocs.yml`, and not as part of the respective
+ document or section to be excluded. This might result in stale exclusion
+ patterns, leading to unintended behavior:
+
+ - When a headline is changed, its slug (permalink) also changes, which might
+ suddenly match (or unmatch) a pattern, e.g., when an author fixes a typo
+ in a headline.
+
+ - As exclusion patterns support the use of wildcards, different authors
+ might overwrite each other's patterns without any immediate feedback since
+ the plugin does only report the number of excluded documents – not _what_
+ has been excluded.[^1]
+
+ [^1]:
+ When the log level is set to `DEBUG`, the plugin will report exactly which
+ pages and sections have been excluded from the search index, but MkDocs will
+ now flood the terminal with debug output from its core and other plugins.
+
+2. __Exclusion control might be too coarse__: The [mkdocs-exclude-search]
+ plugin only allows for the exclusion of pages and sections. It's not
+ possible to exclude parts of a section, e.g., content that is irrelevant
+ to search but must be included as part of the documentation.
+
+ [plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+ [mkdocs-exclude-search]: https://github.com/chrieke/mkdocs-exclude-search
+
+## What's new?
+
+The latest Insiders release brings fine-grained control for [__excluding pages,
+sections, and blocks__][search exclusion] from the search index, implemented
+through front matter, as well as the [Attribute Lists]. Note that it doesn't
+replace the [mkdocs-exclude-search] plugin but __complements__ it.
+
+ [search exclusion]: ../../setup/setting-up-site-search.md#search-exclusion
+ [Attribute Lists]: ../../setup/extensions/python-markdown.md#attribute-lists
+
+### Excluding pages
+
+An entire page can be excluded from the search index by adding a simple
+directive to the front matter of the respective Markdown file. The good thing
+is that the author now only has to check the top of the document to learn
+whether it is excluded or not:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
+
+### Excluding sections
+
+If a section should be excluded, the author can use the [Attribute Lists]
+extension to add a __pragma__ called `data-search-exclude` at the end of a
+heading. The pragma is not included in the final HTML, as search pragmas are
+filtered by the search plugin before the page is rendered:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ ## Section 1
+
+ The content of this section is included
+
+ ## Section 2 { data-search-exclude }
+
+ The content of this section is excluded
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"",
+ "title":"Document title"
+ },
+ {
+ "location":"page/#section-1",
+ "text":"
The content of this section is included
",
+ "title":"Section 1"
+ }
+ ]
+ }
+ ```
+
+### Excluding blocks
+
+If even more fine-grained control is desired, the __pragma__ can be added to
+any [block-level element] or [inline-level element] that is officially
+supported by the [Attribute Lists] extension:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ The content of this block is included
+
+ The content of this block is excluded
+ { data-search-exclude }
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"
The content of this block is included
",
+ "title":"Document title"
+ },
+ ]
+ }
+ ```
+
+ [block-level element]: https://python-markdown.github.io/extensions/attr_list/#block-level
+ [inline-level element]: https://python-markdown.github.io/extensions/attr_list/#inline
+
+## Conclusion
+
+The latest release brings three simple ways to control more precisely what goes
+into the search index and what doesn't. It complements the already very powerful
+[mkdocs-exclude-search] plugin, allowing for new methods of shaping the
+structure, size and content of the search index.
diff --git a/mkdocs-material/docs/blog/posts/git-sparse-checkout.md b/mkdocs-material/docs/blog/posts/git-sparse-checkout.md
new file mode 100644
index 0000000..e16b2a6
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/git-sparse-checkout.md
@@ -0,0 +1,100 @@
+---
+date: 2023-09-22
+authors: [squidfunk]
+categories:
+ - Build
+ - Performance
+links:
+ - publishing-your-site.md#with-github-actions
+ - creating-your-site.md#building-your-site
+---
+
+# Using `git sparse-checkout` for faster documentation builds
+
+__Leveraging `git sparse-checkout` in GitHub Actions enabled us to speed up
+documentation builds in our repository, cutting checkout times from 20 to 30
+seconds to just 2 seconds.__
+
+Developing an efficient approach to build documentation in CI workflows is
+essential, especially when working in large repositories with thousands of
+commits, like ours. Of course, we want to build documentation quickly and
+efficiently, ensuring fast and productive workflows. When using both the
+wonderful [`git-committers`][git-committers] and [`git-revision-date-localized`]
+[git-revision-date-localized] plugins to display [document contributors] and
+[dates] at the bottom of each page, we are required to set `fetch-depth: 0`,
+which resulted in checkout times of 20 to 30 seconds on our repository. By
+leveraging [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions],
+check out time was brought down to 2 seconds.
+
+ [git sparse-checkout]: https://git-scm.com/docs/git-sparse-checkout
+ [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+ [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+ [git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
+ [document contributors]: ../../setup/adding-a-git-repository.md#document-contributors
+ [dates]: ../../setup/adding-a-git-repository.md#document-dates
+
+
+
+## A Primer
+
+[`git sparse-checkout`][git sparse-checkout] allows you to check out only a
+subset of the files in a repository, making it incredibly useful for large
+repositories where a full checkout takes long and includes many files that are
+not relevant when building documentation.
+
+## GitHub Actions
+
+To enable [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions]
+and ensure that you are only building the documentation that you need, add the
+following lines to your workflow file:
+
+``` yaml
+- uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+```
+
+[`git sparse-checkout`][git sparse-checkout] always checks out all files
+residing in the repository’s root. This means that regardless of the specified
+paths or directories for sparse checkout, the files located in the root of the
+repository will always be included in the checkout process.
+
+Thus, you only need to specify the directories that are necessary for building
+documentation. In our case, we only need the `docs` and `includes` folders,
+but if you need additional directories, you can just add them to the end of the
+list. A complete example workflow for [GitHub Actions]:
+
+``` yaml hl_lines="13-18"
+name: documentation
+on:
+ push:
+ branches:
+ - master
+ - main
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3.x
+ - run: pip install mkdocs-material
+ - run: mkdocs gh-deploy --force
+```
+
+## Conclusion
+
+That's all there is! We're super happy with the results and hope that this will
+help you to speed up your documentation builds in [GitHub Actions] as well. As
+always, feel free to share your thoughts and experiences in the comments below.
diff --git a/mkdocs-material/docs/blog/posts/search-better-faster-smaller.md b/mkdocs-material/docs/blog/posts/search-better-faster-smaller.md
new file mode 100644
index 0000000..dcdeec9
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/search-better-faster-smaller.md
@@ -0,0 +1,630 @@
+---
+date: 2021-09-13
+authors: [squidfunk]
+readtime: 15
+description: >
+ How we rebuilt client-side search, delivering a better user experience while
+ making it faster and smaller at the same time
+categories:
+ - Search
+ - Performance
+links:
+ - plugins/search.md
+ - insiders/how-to-sponsor.md
+---
+
+# Search: better, faster, smaller
+
+__This is the story of how we managed to completely rebuild client-side search,
+delivering a significantly better user experience while making it faster and
+smaller at the same time.__
+
+The [search] of Material for MkDocs is by far one of its best and most-loved
+assets: [multilingual], [offline-capable], and most importantly: _all
+client-side_. It provides a solution to empower the users of your documentation
+to find what they're searching for instantly without the headache of managing
+additional servers. However, even though several iterations have been made,
+there's still some room for improvement, which is why we rebuilt the search
+plugin and integration from the ground up. This article shines some light on the
+internals of the new search, why it's much more powerful than the previous
+version, and what's about to come.
+
+
+
+_The next section discusses the architecture and issues of the current search
+implementation. If you immediately want to learn what's new, skip to the
+[section just after that][what's new]._
+
+ [search]: ../../setup/setting-up-site-search.md
+ [multilingual]: ../../plugins/search.md#config.lang
+ [offline-capable]: ../../setup/building-for-offline-usage.md
+ [what's new]: #whats-new
+
+## Architecture
+
+Material for MkDocs uses [lunr] together with [lunr-languages] to implement
+its client-side search capabilities. When a documentation page is loaded and
+JavaScript is available, the search index as generated by the
+[built-in search plugin] during the build process is requested from the
+server:
+
+``` ts
+const index$ = document.forms.namedItem("search")
+ ? __search?.index || requestJSON(
+ new URL("search/search_index.json", config.base)
+ )
+ : NEVER
+```
+
+ [lunr]: https://lunrjs.com
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+ [built-in search plugin]: ../../plugins/search.md
+
+### Search index
+
+The search index includes a stripped-down version of all pages. Let's take a
+look at an example to understand precisely what the search index contains from
+the original Markdown file:
+
+??? example "Expand to inspect example"
+
+ === ":octicons-file-code-16: `docs/page.md`"
+
+ ```` markdown
+ # Example
+
+ ## Text
+
+ It's very easy to make some words **bold** and other words *italic*
+ with Markdown. You can even add [links](#), or even `code`:
+
+ ```
+ if (isAwesome) {
+ return true
+ }
+ ```
+
+ ## Lists
+
+ Sometimes you want numbered lists:
+
+ 1. One
+ 2. Two
+ 3. Three
+
+ Sometimes you want bullet points:
+
+ * Start a line with a star
+ * Profit!
+ ````
+
+ === ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ "config": {
+ "indexing": "full",
+ "lang": [
+ "en"
+ ],
+ "min_search_length": 3,
+ "prebuild_index": false,
+ "separator": "[\\s\\-]+"
+ },
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ },
+ {
+ "location": "page/#example",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
+ },
+ {
+ "location": "page/#lists",
+ "title": "Lists",
+ "text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ }
+ ]
+ }
+ ```
+
+If we inspect the search index, we immediately see several problems:
+
+ 1. __All content is included twice__: the search index contains one entry
+ with the entire contents of the page, and one entry for each section of
+ the page, i.e., each block preceded by a headline or subheadline. This
+ significantly contributes to the size of the search index.
+
+ 2. __All structure is lost__: when the search index is built, all structural
+ information like HTML tags and attributes are stripped from the content.
+ While this approach works well for paragraphs and inline formatting, it
+ might be problematic for lists and code blocks. An excerpt:
+
+ ```
+ … links , or even code : if (isAwesome) { … } Lists Sometimes you want …
+ ```
+
+ - __Context__: for an untrained eye, the result can look like gibberish, as
+ it's not immediately apparent what classifies as text and what as code.
+ Furthermore, it's not clear that `Lists` is a headline as it's merged
+ with the code block before and the paragraph after it.
+
+ - __Punctuation__: inline elements like links that are immediately followed
+ by punctuation are separated by whitespace (see `,` and `:` in the
+ excerpt). This is because all extracted text is joined with a whitespace
+ character during the construction of the search index.
+
+It's not difficult to see that it can be quite challenging to implement a good
+search experience for theme authors, which is why Material for MkDocs (up to
+now) did some [monkey patching] to be able to render slightly more
+meaningful search previews.
+
+ [monkey patching]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/document/index.ts#L68-L71
+
+### Search worker
+
+The actual search functionality is implemented as part of a web worker[^1],
+which creates and manages the [lunr] search index. When search is initialized,
+the following steps are taken:
+
+ [^1]:
+ Prior to , search was carried out in the main
+ thread which locked up the browser, rendering it unusable. This problem was
+ first reported in #904 and, after some back and forth, fixed and released in
+ .
+
+1. __Linking sections with pages__: The search index is parsed, and each
+ section is linked to its parent page. The parent page itself is _not
+ indexed_, as it would lead to duplicate results, so only the sections
+ remain. Linking is necessary, as search results are grouped by page.
+
+2. __Tokenization__: The `title` and `text` values of each section are split
+ into tokens by using the [`separator`][separator] as configured in
+ `mkdocs.yml`. Tokenization itself is carried out by
+ [lunr's default tokenizer][default tokenizer], which doesn't allow for
+ lookahead or separators spanning multiple characters.
+
+ > Why is this important and a big deal? We will see later how much more we
+ > can achieve with a tokenizer that is capable of separating strings with
+ > lookahead.
+
+3. __Indexing__: As a final step, each section is indexed. When querying the
+ index, if a search query includes one of the tokens as returned by step 2.,
+ the section is considered to be part of the search result and passed to the
+ main thread.
+
+Now, that's basically how the search worker operates. Sure, there's a little
+more magic involved, e.g., search results are [post-processed] and [rescored] to
+account for some shortcomings of [lunr], but in general, this is how data gets
+into and out of the index.
+
+ [separator]: ../../plugins/search.md#config.separator
+ [default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
+ [post-processed]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L249-L272
+ [rescored]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L274-L275
+
+### Search previews
+
+Users should be able to quickly scan and evaluate the relevance of a search
+result in the given context, which is why a concise summary with highlighted
+occurrences of the search terms found is an essential part of a great search
+experience.
+
+This is where the current search preview generation falls short, as some of the
+search previews appear not to include any occurrence of any of the search
+terms. This was due to the fact that search previews were [truncated after a
+maximum of 320 characters][truncated], as can be seen here:
+
+
+
+![search preview]
+
+
+
+The first two results look like they're not relevant, as they don't seem to
+include the query string the user just searched for. Yet, they are.
+
+
+
+
+A better solution to this problem has been on the roadmap for a very, very long
+time, but in order to solve this once and for all, several factors need to be
+carefully considered:
+
+1. __Word boundaries__: some themes[^2] for static site generators generate
+ search previews by expanding the text left and right next to an occurrence,
+ stopping at a whitespace character when enough words have been consumed. A
+ preview might look like this:
+
+ ```
+ … channels, e.g., or which can be configured via mkdocs.yml …
+ ```
+
+ While this may work for languages that use whitespace as a separator
+ between words, it breaks down for languages like Japanese or Chinese[^3],
+ as they have non-whitespace word boundaries and use dedicated segmenters to
+ split strings into tokens.
+
+ [^2]:
+ At the time of writing, [Just the Docs] and [Docusaurus] use this method
+ for generating search previews. Note that the latter also integrates with
+ Algolia, which is a fully managed server-based solution.
+
+ [^3]:
+ China and Japan are both within the top 5 countries of origin of users of
+ Material for MkDocs.
+
+ [truncated]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/javascripts/templates/search/index.tsx#L90
+ [search preview]: search-better-faster-smaller/search-preview.png
+ [Just the Docs]: https://pmarsceill.github.io/just-the-docs/
+ [Docusaurus]: https://github.com/lelouch77/docusaurus-lunr-search
+
+1. __Context-awareness__: Although whitespace doesn't work for all languages,
+ one could argue that it could be a good enough solution. Unfortunately, this
+ is not necessarily true for code blocks, as the removal of whitespace might
+ change meaning in some languages.
+
+3. __Structure__: Preserving structural information is not a must, but
+ apparently beneficial to build more meaningful search previews which allow
+ for a quick evaluation of relevance. If a word occurrence is part of a code
+ block, it should be rendered as a code block.
+
+## What's new?
+
+After we built a solid understanding of the problem space and before we dive
+into the internals of our new search implementation to see which of the
+problems it already solves, a quick overview of what features and improvements
+it brings:
+
+- __Better__: support for [rich search previews], preserving the structural
+ information of code blocks, inline code, and lists, so they are rendered
+ as-is, as well as [lookahead tokenization], [more accurate highlighting], and
+ improved stability of typeahead. Also, a [slightly better UX].
+- __Faster__ and __smaller__: significant decrease in search index size of up
+ to 48% due to improved extraction and construction techniques, resulting in a
+ search experience that is up to 95% faster, which is particularly helpful for
+ large documentation projects.
+
+ [rich search previews]: #rich-search-previews
+ [lookahead tokenization]: #tokenizer-lookahead
+ [more accurate highlighting]: #accurate-highlighting
+ [slightly better UX]: #user-interface
+
+### Rich search previews
+
+As we rebuilt the search plugin from scratch, we reworked the construction of
+the search index to preserve the structural information of code blocks, inline
+code, as well as unordered and ordered lists. Using the example from the
+[search index] section, here's how it looks:
+
+=== "Now"
+
+ ![search preview now]
+
+=== "Before"
+
+ ![search preview before]
+
+Now, __code blocks are first-class citizens of search previews__, and even
+inline code formatting is preserved. Let's take a look at the new structure of
+the search index to understand why:
+
+??? example "Expand to inspect search index"
+
+ === "Now"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "
It's very easy to make some words bold and other words italic with Markdown. You can even add links, or even code:
"
+ }
+ ]
+ }
+ ```
+
+ === "Before"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ },
+ {
+ "location": "page/#example",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
+ },
+ {
+ "location": "page/#lists",
+ "title": "Lists",
+ "text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ }
+ ]
+ }
+ ```
+
+If we inspect the search index again, we can see how the situation improved:
+
+1. __Content is included only once__: the search index does not include the
+ content of the page twice, as only the sections of a page are part of the
+ search index. This leads to a significant reduction in size, fewer bytes to
+ transfer, and a smaller search index.
+
+2. __Some structure is preserved__: each section of the search index includes
+ a small subset of HTML to provide the necessary structure to allow for more
+ sophisticated search previews. Revisiting our example from before, let's
+ look at an excerpt:
+
+ === "Now"
+
+ ``` html
+ … links, or even code:
if (isAwesome){ … }\n
+ ```
+
+ === "Before"
+
+ ```
+ … links , or even code : if (isAwesome) { … }
+ ```
+
+ The punctuation issue is gone, as no additional whitespace is inserted, and
+ the preserved markup yields additional context to make scanning search
+ results more effective.
+
+On to the next step in the process: __tokenization__.
+
+ [search index]: #search-index
+ [search preview now]: search-better-faster-smaller/search-preview-now.png
+ [search preview before]: search-better-faster-smaller/search-preview-before.png
+
+### Tokenizer lookahead
+
+The [default tokenizer] of [lunr] uses a regular expression to split a given
+string by matching each character against the [`separator`][separator] as
+defined in `mkdocs.yml`. This doesn't allow for more complex separators based
+on lookahead or multiple characters.
+
+Fortunately, __our new search implementation provides an advanced tokenizer__
+that doesn't have these shortcomings and supports more complex regular
+expressions. As a result, Material for MkDocs just changed its own separator
+configuration to the following value:
+
+```
+[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;
+```
+
+While the first part up to the first `|` contains a list of single control
+characters at which the string should be split, the following three sections
+explain the remainder of the regular expression.[^4]
+
+ [^4]:
+ As a fun fact: the [`separator`][separator] [default value] of the search
+ plugin being `[\s\-]+` always has been kind of irritating, as it suggests
+ that multiple characters can be considered being a separator. However, the
+ `+` is completely irrelevant, as regular expression groups involving
+ multiple characters were never supported by
+ [lunr's default tokenizer][default tokenizer].
+
+ [default value]: https://www.mkdocs.org/user-guide/configuration/#separator
+
+#### Case changes
+
+Many programming languages use `PascalCase` or `camelCase` naming conventions.
+When a user searches for the term `case`, it's quite natural to expect for
+`PascalCase` and `camelCase` to show up. By adding the following match group to
+the separator, this can now be achieved with ease:
+
+```
+(?!\b)(?=[A-Z][a-z])
+```
+
+This regular expression is a combination of a negative lookahead (`\b`, i.e.,
+not a word boundary) and a positive lookahead (`[A-Z][a-z]`, i.e., an uppercase
+character followed by a lowercase character), and has the following behavior:
+
+- `PascalCase` :octicons-arrow-right-24: `Pascal`, `Case`
+- `camelCase` :octicons-arrow-right-24: `camel`, `Case`
+- `UPPERCASE` :octicons-arrow-right-24: `UPPERCASE`
+
+Searching for [:octicons-search-24: searchHighlight][q=searchHighlight]
+now brings up the section discussing the `search.highlight` feature flag, which
+also demonstrates that this now even works properly for search queries.[^5]
+
+ [^5]:
+ Previously, the search query was not correctly tokenized due to the way
+ [lunr] treats wildcards, as it disables the pipeline for search terms that
+ contain wildcards. In order to provide a good typeahead experience,
+ Material for MkDocs adds wildcards to the end of each search term not
+ explicitly preceded with `+` or `-`, effectively disabling tokenization.
+
+ [q=searchHighlight]: ?q=searchHighlight
+
+#### Version numbers
+
+Indexing version numbers is another problem that can be solved with a small
+lookahead. Usually, `.` should be considered a separator to split words like
+`search.highlight`. However, splitting version numbers at `.` will make them
+undiscoverable. Thus, the following expression:
+
+```
+\.(?!\d)
+```
+
+This regular expression matches a `.` only if not immediately followed by a
+digit `\d`, which leaves version numbers discoverable. Searching for
+[:octicons-search-24: 7.2.6][q=7.2.6] brings up the [7.2.6] release notes.
+
+ [q=7.2.6]: ?q=7.2.6
+ [7.2.6]: ../../changelog/index.md#7.2.6
+
+#### HTML/XML tags
+
+If your documentation includes HTML/XML code examples, you may want to allow
+users to find specific tag names. Unfortunately, the `<` and `>` control
+characters are encoded in code blocks as `<` and `>`. Now, adding the
+following expression to the separator allows for just that:
+
+```
+&[lg]t;
+```
+
+---
+
+_We've only just begun to scratch the surface of the new possibilities
+tokenizer lookahead brings. If you found other useful expressions, you're
+invited to share them in the comment section._
+
+### Accurate highlighting
+
+Highlighting is the last step in the process of search and involves the
+highlighting of all search term occurrences in a given search result. For a
+long time, highlighting was implemented through dynamically generated
+[regular expressions].[^6]
+
+This approach has some problems with non-whitespace languages like Japanese or
+Chinese[^3] since it only works if the highlighted term is at a word boundary.
+However, Asian languages are tokenized using a [dedicated segmenter], which
+cannot be modeled with regular expressions.
+
+ [^6]:
+ Using the separator as defined in `mkdocs.yml`, a regular expression was
+ constructed that was trying to mimic the tokenizer. As an example, the
+ search query `search highlight` was transformed into the rather cumbersome
+ regular expression `(^|)(search|highlight)`, which only matches
+ at word boundaries.
+
+Now, as a direct result of the [new tokenization approach], __our new search
+implementation uses token positions for highlighting__, making it exactly as
+powerful as tokenization:
+
+1. __Word boundaries__: as the new highlighter uses token positions, word
+ boundaries are equal to token boundaries. This means that more complex cases
+ of tokenization (e.g., [case changes], [version numbers], [HTML/XML tags]),
+ are now all highlighted accurately.
+
+2. __Context-awareness__: as the new search index preserves some of the
+ structural information of the original document, the content of a section
+ is now divided into separate content blocks – paragraphs, code blocks, and
+ lists.
+
+ Now, only the content blocks that actually contain occurrences of one of
+ the search terms are considered for inclusion into the search preview. If a
+ term only occurs in a code block, it's the code block that gets rendered,
+ see, for example, the results of
+ [:octicons-search-24: twitter][q=twitter].
+
+ [regular expressions]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/highlighter/index.ts#L61-L91
+ [dedicated segmenter]: http://chasen.org/~taku/software/TinySegmenter/
+ [new tokenization approach]: #tokenizer-lookahead
+ [case changes]: #case-changes
+ [version numbers]: #version-numbers
+ [HTML/XML tags]: #htmlxml-tags
+ [q=twitter]: ?q=twitter
+
+### Benchmarks
+
+We conducted two benchmarks – one with the documentation of Material for MkDocs
+itself, and one with a very massive corpus of Markdown files with more than
+800,000 words – a size most documentation projects will likely never
+reach:
+
+
+
+| | Before | Now | Relative |
+| ----------------------- | -------: | -------------: | -----------: |
+| __Material for MkDocs__ | | | |
+| Index size | 573 kB | __335 kB__ | __–42%__ |
+| Index size (`gzip`) | 105 kB | __78 kB__ | __–27%__ |
+| Indexing time[^7] | 265 ms | __177 ms__ | __–34%__ |
+| __KJV Markdown[^8]__ | | | |
+| Index size | 8.2 MB | __4.4 MB__ | __–47%__ |
+| Index size (`gzip`) | 2.3 MB | __1.2 MB__ | __–48%__ |
+| Indexing time | 2,700 ms | __1,390 ms__ | __–48%__ |
+
+
+
Benchmark results
+
+
+
+
+ [^7]:
+ Smallest value of ten distinct runs.
+
+ [^8]:
+ We agnostically use [KJV Markdown] as a tool for testing to learn how
+ Material for MkDocs behaves on large corpora, as it's a very large set of
+ Markdown files with over 800k words.
+
+The results show that indexing time, which is the time that it takes to set up
+the search when the page is loaded, has dropped by up to 48%, which means __the
+new search is up to 95% faster__. This is a significant improvement,
+particularly relevant for large documentation projects.
+
+While 1,3s still may sound like a long time, using the new client-side search
+together with [instant loading] only creates the search index on the initial
+page load. When navigating, the search index is preserved across pages, so the
+cost does only have to be paid once.
+
+ [KJV Markdown]: https://github.com/arleym/kjv-markdown
+ [instant loading]: ../../setup/setting-up-navigation.md#instant-loading
+
+### User interface
+
+Additionally, some small improvements have been made, most prominently the
+__more results on this page__ button, which now sticks to the top of the search
+result list when open. This enables the user to jump out of the list more
+quickly.
+
+## What's next?
+
+Our new search implementation is a big improvement to Material for MkDocs. It
+solves some long-standing issues which needed to be tackled for years. Yet,
+it's only the start of a search experience that is going to get better and
+better. Next up:
+
+- __Context-aware search summarization__: currently, the first two matching
+ content blocks are rendered as a search preview. With the new tokenization
+ technique, we laid the groundwork for more sophisticated shortening and
+ summarization methods, which we're tackling next.
+
+- __User interface improvements__: as we now gained full control over the
+ search plugin, we can now add meaningful metadata to provide more context and
+ a better experience. We'll explore some of those paths in the future.
+
+If you've made it this far, thank you for your time and interest in Material
+for MkDocs! This is the first blog article that I decided to write after a
+short [Twitter survey] made me to. You're invited to leave a comment
+to share your experiences with the new search implementation.
+
+ [X survey]: https://x.com/squidfunk/status/1434477478823743488
diff --git a/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-before.png b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-before.png
new file mode 100644
index 0000000..7f6fcc8
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-before.png differ
diff --git a/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-now.png b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-now.png
new file mode 100644
index 0000000..0935166
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview-now.png differ
diff --git a/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview.png b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview.png
new file mode 100644
index 0000000..7ca97e1
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/search-better-faster-smaller/search-preview.png differ
diff --git a/mkdocs-material/docs/blog/posts/sunsetting-gitter.md b/mkdocs-material/docs/blog/posts/sunsetting-gitter.md
new file mode 100644
index 0000000..4cc9660
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/sunsetting-gitter.md
@@ -0,0 +1,96 @@
+---
+date: 2023-10-02
+authors: [squidfunk, alexvoss]
+categories:
+ - General
+---
+
+# Sunsetting Gitter: Towards Efficient Community Engagement
+
+__As we're starting to build a team around Material for MkDocs, we've decided to
+sunset and archive our [Gitter] channel on October 13, 2023 in favor of
+[GitHub Discussions].__
+
+As part of our efforts to improve the processes for maintaining Material for
+MkDocs and for supporting the community, we have reviewed the use of different
+communication channels. At the moment, both [Gitter] and [GitHub Discussions]
+allow to ask the community for support and to discuss ideas and issues. In the
+past weeks, we have begun to question whether this duplication is in the best
+interest of our project. This post explains the rationale behind our decision.
+
+ [Gitter]: https://gitter.im/squidfunk/mkdocs-material
+ [GitHub discussions]: https://github.com/squidfunk/mkdocs-material/discussions
+
+
+
+## The Constraints of Gitter
+
+In the first years of Material for MkDocs, [Gitter] served as a helpful platform
+for quick community interactions and questions. However, there are some inherent
+constraints that necessitated a shift. Here's a breakdown of the challenges we
+encountered:
+
+1. __Thread utilization__ –
+ Even with the introduction of threads, many Gitter users were reticent to
+ use them, leading to cluttered and disconnected conversations, making it
+ difficult to follow.
+
+2. __Search and discovery__ –
+ Gitter's structure and interface makes it cumbersome to search for and
+ retrieve past messages, resulting in lost insights and repeated conversations.
+
+1. __User interface__ –
+ After the acquisition by [Element], the user interface of Gitter has
+ experienced a severe decline, becoming more complicated, less intuitive and
+ user-friendly.
+
+1. __Access mandate__ –
+ The necessity for users to grant access to their GitHub accounts to use
+ Gitter posed an unnecessary access barrier and potential security concerns.
+
+ [Element]: https://element.io/blog/gitter-is-joining-element/
+
+## GitHub Discussions
+
+Thankfully, [GitHub Discussions] emerged and continues to evolve to be a much
+better alternative, eliminating many of Gitter's constraints and offering
+enhanced functionality:
+
+1. __Threaded conversations__ –
+ GitHub Discussions supports structured, threaded conversations, ensuring
+ discussions are coherent, contextual, and easy to follow for everyone.
+
+2. __Integration and linking__ –
+ the platform facilitates seamless linking to other discussions, issues, code,
+ and much more, enriching conversations and providing comprehensive context.
+
+3. __A unified platform__ –
+ GitHub acts as a one-stop shop for support, allowing users to access varied
+ resources and support channels in one place, greatly improving user
+ experience.
+
+4. __Discoverability__ –
+ GitHub Discussions are easily searchable and allow for categorization,
+ preventing loss of valuable insights and fostering knowledge sharing.
+
+## Conclusion
+
+Sunsetting [Gitter] is a leap towards creating more efficient, user-friendly,
+and enriched community interactions. By consolidating communication to
+[GitHub Discussions], we seek to mitigate the fragmentation of information,
+ease the user journey, and fortify the bonds within our community.
+
+This concentrated approach enables us to provide consistent, fast and quality
+support to our users. In the past, the nature of queries raised on Gitter
+typically necessitated supplementary information or reproductions, prompting us
+to advise users to initiate a discussion subsequently. The shift to a
+centralized discussion forum is designed to simplify and accelerate this
+procedure, ensuring swift and efficient resolutions for our community. It is a
+testament to our ongoing commitment to support the community that helps Material
+for MkDocs flourish.
+
+We are confident that this streamlined approach will spur more
+fruitful discussions, innovative ideas, and collective growth, and we are
+excited to continue our journey with the unwavering support and active
+participation of our community.
+
diff --git a/mkdocs-material/docs/blog/posts/the-past-present-and-future.md b/mkdocs-material/docs/blog/posts/the-past-present-and-future.md
new file mode 100644
index 0000000..1179d39
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/the-past-present-and-future.md
@@ -0,0 +1,265 @@
+---
+date: 2021-12-27
+authors: [squidfunk]
+description: >
+ 2021 was a fantastic year for this project as we shipped many new awesome
+ features and made this project sustainable
+categories:
+ - General
+---
+
+# The past, present and future
+
+__2021 was a fantastic year for this project as we shipped many new awesome
+features, saw significant user growth and leveraged GitHub Sponsors to make the
+project sustainable.__
+
+Today, together, [MkDocs] and Material for MkDocs are among the most popular
+options when it comes to choosing a static site generator and theme for your
+technical documentation project. Material for MkDocs ensures that your
+content is always perfectly presented to your audience, regardless of screen
+resolution or device capabilities. It has evolved to a framework for technical
+writing, offering many features, some of which are yet to be found in other
+static site generators. However, we're far from the end, as 2022 is going to
+bring some interesting new capabilities.
+
+
+
+_This article showcases all features that were added in 2021 and gives an
+outlook on what's going to drop in 2022. Additionally, it provides some context
+on the history of the project._
+
+ [MkDocs]: https://www.mkdocs.org
+
+## A little history
+
+In 2015, albeit 10 years in the industry, I was still quite new in Open Source.
+I wanted to release my latest Open Source project [protobluff], a zero-copy
+Protocol Buffers implementation for C, which I've created as part of my former
+startup. As the project has a significant degree of complexity, I quickly
+realized that I was in need of good user documentation.
+
+After evaluating static site generators in general and Hugo, Sphinx and MkDocs
+in particular, I quickly decided that MkDocs seemed a good choice, as it was
+specifically aimed at technical project documentation and easy to use.
+Unfortunately, all of the available themes looked dated and given that I'm a
+very visual person, I just couldn't convince myself to call it a day.
+
+I _had_ to build a theme.
+
+Months later, in February 2016, I released [the first version] of Material for
+MkDocs (and with it, [protobluff], the project I wanted to release in the first
+place), and it looked like this:
+
+![Material for MkDocs 0.1.0][Material for MkDocs 0.1.0]
+
+It was already fully responsive and overall, well, quite okayish, but barely
+customizable, as only the logo could be changed. Beyond that, it had no options:
+No color or navigation options, no instant loading, etc. The search was very
+rudimentary and only supported section titles:
+
+![Material for MkDocs 0.1.0 Search][Material for MkDocs 0.1.0 Search]
+
+It's important to know that at this point in time I've built Material for
+MkDocs for [protobluff], the project I was really caring about. Almost 6 years
+later, nobody knows protobluff, but this little side project has taken off. If
+back in those days, you would've told me big organizations like AWS,
+Microsoft and CERN, as well as extremely popular Open Source projects like
+FastAPI and Kubernetes will be using this project in the future – I would've
+declared you insane.
+
+I still find the success of this project quite surprising, as I thought that
+themes exist in abundance and are very much a solved problem. There's no glory
+in themes, no stars to earn (remember that I was new in Open Source, so this was
+the metric I was optimizing for), as there are thousands and thousands of
+options. However, as the years progressed, I learned that _execution matters_:
+although Material for MkDocs solves a problem for which thousands of solutions
+exist, it excels in a specific niche, and that niche is to be known as
+_technical project documentation_.
+
+Today, this project is not only popular but funded by almost 300 individuals
+and organizations, resulting in a yearly budget of more than $50,000. This
+allows me to set aside enough time for the development of new features,
+bug fixing, stability improvement, issue triage and general support and still
+feels like a dream to me, as there are many failed stories of Open Source
+funding and people telling you: _don't do Open Source, you'll be working for
+free._
+
+Making Open Source sustainable is, after all, possible in 2021.
+
+ [the first version]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+ [Material for MkDocs 0.1.0]: the-past-present-and-future/mkdocs-material-0.1.0.png
+ [Material for MkDocs 0.1.0 Search]: the-past-present-and-future/mkdocs-material-0.1.0-search.png
+ [protobluff]: https://github.com/squidfunk/protobluff
+
+## 2021 in numbers
+
+2021 was an exciting year, as the project has seen significant growth.
+
+__166k people__ visited the official documentation in 2021, totalling in __1,6m
+page views__ which is an increase of 83% when compared to 2020. The average
+visitor spends __1,5min__ on the site. While mobile phones make up 12% of
+visits, tablets only account for 0.6%. Visitors come from as many as __213
+countries__, which covers almost the whole world.
+
+### Features
+
+It's absolutely mind-blowing that __38 new features__ were added to Material
+for MkDocs throughout 2021 – __that's a new feature every 9,6 days__ –
+which was only possible because of the constantly improving funding situation.
+Following is a list of all features shipped in alphabetical order, some of which
+are still exclusively available to sponsors as part of [Insiders]:
+
+
+
+Additionally, a lot of bugs were fixed in the __1,000 commits__ that were pushed
+to the repository this year. The [changelog] includes a list of all fixes.
+Furthermore, a large amount of time was invested into refactoring the code base
+to keep it in good shape. While the `mkdocs-material` package was released
+__55__ times, `mkdocs-material-insiders` was shipped __72__ times.
+
+ [Insiders]: ../../insiders/index.md
+ [Admonition inline blocks]: ../../reference/admonitions.md#inline-blocks
+ [Advanced search highlighting]: search-better-faster-smaller.md#accurate-highlighting
+ [Anchor tracking]: ../../setup/setting-up-navigation.md#anchor-tracking
+ [Back-to-top button]: ../../setup/setting-up-navigation.md#back-to-top-button
+ [Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting
+ [Brand new search plugin]: search-better-faster-smaller.md
+ [Code annotations]: ../../reference/code-blocks.md#adding-annotations
+ [Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
+ [Code block titles]: ../../reference/code-blocks.md#adding-a-title
+ [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#+pymdownx.highlight.anchor_linenums
+ [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle
+ [Content tabs: improved support]: ../../reference/content-tabs.md
+ [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs
+ [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent
+ [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons
+ [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
+ [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read
+ [Excluding content from search]: ../../setup/setting-up-site-search.md#search-exclusion
+ [Mermaid.js integration]: ../../reference/diagrams.md
+ [Navigation icons]: ../../reference/index.md#setting-the-page-icon
+ [Remove generator notice]: ../../setup/setting-up-the-footer.md#generator-notice
+ [Rich search previews]: search-better-faster-smaller.md#rich-search-previews
+ [Search highlighting]: ../../setup/setting-up-site-search.md#search-highlighting
+ [Search sharing]: ../../setup/setting-up-site-search.md#search-sharing
+ [Search suggestions]: ../../setup/setting-up-site-search.md#search-suggestions
+ [Section index pages]: ../../setup/setting-up-navigation.md#section-index-pages
+ [Site language selection]: ../../setup/changing-the-language.md#site-language-selector
+ [Social cards]: ../../setup/setting-up-social-cards.md
+ [Sticky navigation tabs]: ../../setup/setting-up-navigation.md#sticky-navigation-tabs
+ [Tags with search integration]: ../../setup/setting-up-tags.md
+ [Tokenizer with lookahead]: search-better-faster-smaller.md#tokenizer-lookahead
+ [Versioning]: ../../setup/setting-up-versioning.md#versioning
+ [Version warning]: ../../setup/setting-up-versioning.md#version-warning
+ [Was this page helpful?]: ../../setup/setting-up-site-analytics.md#was-this-page-helpful
+ [changelog]: ../../changelog/index.md
+
+### Funding
+
+In 2021, monthly funding increased from $1,050 in the beginning of January to
+more than $4,300 (Dec 27, 2021), totaling in a yearly budget of more than
+$50,000. Compared to last year, __revenue from funding has increased by 617%__
+– which is absolutely unbelievable:
+
+![Funding]
+
+ [Funding]: the-past-present-and-future/funding.png
+
+I'm solely providing these numbers to fulfill the transparency pledge I'm giving
+to my [awesome sponsors], and to show that it's possible to make existing Open
+Source projects sustainable by following a well-designed release strategy.
+
+You can learn about the strategy in the [Insiders] guide.
+
+ [awesome sponsors]: ../../insiders/how-to-sponsor.md
+
+## 2022
+
+Standing at the verge of the next year, it's safe to say that the project will
+continue to prosper and evolve, yielding many awesome features that will make
+technical writing more comfortable and flexible. Here's an excerpt of the
+features that will see the light of day in 2022:
+
+- __Instant previews__: [instant previews] will render a specific page section
+ inside a tooltip when hovering an internal link, which will allow to implement
+ things like glossaries. Further support for improving glossary functionality
+ will also be investigated.
+
+- __Text annotations__: as a logical progression of [code annotations] which
+ were added in 2021, authors will be able to add annotations to plain text,
+ yielding excellent opportunities for side content. Of course, text annotations
+ will be as easy to use as code annotations.
+
+- __Navigation pruning__: to optimize large documentation projects, Material
+ for MkDocs will introduce a new feature flag called `navigation.prune` that
+ will lead to significantly smaller HTML files for documentation projects with
+ huge navigation hierarchies.
+
+- __Navigation status badge__: as an addition to the recently added
+ [navigation icon][Navigation icons] support, a status will be attributable to
+ each page, allowing to mark a page in the navigation tree with an icon as
+ :material-alert-decagram: __new__ or :material-trash-can: __deprecated__.
+ Custom status types will also be supported.
+
+- __Card grids__: as a further component in the toolkit of technical writing,
+ [card grids] will allow arranging content in grids, which is especially
+ useful for overview pages. They will allow to arrange arbitrary content,
+ including code blocks, admonitions, etc.
+
+- __Blog support__: blogging support is still [under investigation] and expected
+ to be one of the major additions in 2022. Blogging will perfectly integrate
+ with writing documentation, allowing to use all components available in
+ Material for MkDocs.
+
+This list is incomplete. Additionally, many new smaller features will be added
+next year, just as in 2021. You can follow [@squidfunk on X] to stay
+updated.
+
+__Happy new year!__ :tada:
+
+ [Instant previews]: https://x.com/squidfunk/status/1466794654213492743
+ [card grids]: https://github.com/squidfunk/mkdocs-material/issues/3018
+ [under investigation]: https://github.com/squidfunk/mkdocs-material/issues/3353
+ [@squidfunk on X]: https://x.com/squidfunk
diff --git a/mkdocs-material/docs/blog/posts/the-past-present-and-future/funding.png b/mkdocs-material/docs/blog/posts/the-past-present-and-future/funding.png
new file mode 100644
index 0000000..d6cf219
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/the-past-present-and-future/funding.png differ
diff --git a/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png b/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png
new file mode 100644
index 0000000..22ab104
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png differ
diff --git a/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png b/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png
new file mode 100644
index 0000000..d00c685
Binary files /dev/null and b/mkdocs-material/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png differ
diff --git a/mkdocs-material/docs/blog/posts/transforming-material-for-mkdocs.md b/mkdocs-material/docs/blog/posts/transforming-material-for-mkdocs.md
new file mode 100644
index 0000000..d1df193
--- /dev/null
+++ b/mkdocs-material/docs/blog/posts/transforming-material-for-mkdocs.md
@@ -0,0 +1,213 @@
+---
+date: 2024-08-19
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+categories:
+ - General
+description: >
+ We are transforming Material for MkDocs to ensure its community continues to thrive and doubling down on our commitment to Open Source.
+title: How we're transforming Material for MkDocs
+---
+
+# Transforming Material for MkDocs
+
+__We are working on an amazing set of features which has required some behind-the-scenes work we are now ready to share in a series of posts. Here, we give an overview of our goals, features in the making, things that kept us up at night, and our commitment to Open Source.__
+
+We know it's been quite a while since our last update, which is why we're eager to share what's happening in and around Material for MkDocs with you. For the largest part of 2024, we've been focused on transforming the core of Material for MkDocs preparing the ground for new, interconnected features that are amongst the most frequently requested.
+
+This article is the first in a series where we'll explore how we aim to support our users through improved information retrieval, provide better support for multi-lingual sites and versioning, as well as improve the overall authoring experience. We outline our vision for the projects' evolution and describe what we have been working on. In this and the coming blog posts, we will share our progress with you, and we're excited to hear your thoughts.
+
+
+
+_Please note that this post includes several technical details in the footnotes, specifically on challenges. Feel free to skip them if you're not interested in the specifics._
+
+## A success story
+
+In 2024, Material for MkDocs has firmly established itself as a leading tool in the documentation framework landscape, with more than 5 million downloads each month as of this writing. What began as @squidfunk's personal project has evolved into a versatile resource for creating comprehensive documentation sites, personal websites, blogs, and notably, for managing knowledge both within and outside of organizations.
+
+With almost [50,000] public GitHub projects depending on Material for MkDocs, it's clear that the framework has made a substantial impact. Tens of thousands of authors rely on us to deliver documentation to millions of users each month.[^1] Beyond its adoption by [many popular Open Source projects], Material for MkDocs is trusted and financially supported by major corporations such as [AWS], [Microsoft], and [Siemens], among many other companies and individuals. We're very grateful for the continued support we receive, which allows us to devote our time to this project, making writing documentation enjoyable.
+
+ [^1]:
+ We've collected invaluable feedback from enterprises and other Open Source maintainers, which revealed that the actual numbers are even higher. Many organizations leverage the framework within private infrastructures, such as self-hosted platforms like GitLab, for internal knowledge management. This suggests that the true reach of Material for MkDocs extends far beyond what is publicly visible.
+
+ [50,000]: https://github.com/squidfunk/mkdocs-material/network/dependents
+ [many popular Open Source projects]: https://github.com/squidfunk/mkdocs-material?tab=readme-ov-file#trusted-by-
+ [AWS]: https://x.com/squidfunk/status/1740389441284579767
+ [Microsoft]: https://x.com/squidfunk/status/1801909506391105840
+ [Siemens]: https://x.com/squidfunk/status/1699799988069646761
+
+Our users particularly appreciate Material for MkDocs for its ease of use and straightforward setup. It simplifies the process by handling the complexities of web technologies for you, so you can build a production-ready static site in minutes without needing to invest years into mastering frontend development or JavaScript. This makes it accessible to a wide range of users, regardless of their technical background. Additionally, Material for MkDocs is MIT-licensed and free to use, which has contributed to its widespread adoption, and allows everybody to build sophisticated documentation sites at no cost.
+
+Our vision is to provide you with the tools that allow you to __own your docs__, enable you to develop your own processes for producing amazing documentation and to avoid being locked into costly subscription services even for doing simple things. We believe it is important that these tools should be easy to set up and configure to suit your needs but should also give you the freedom to adapt them further, if needed. This is why we are always striving to ensure our architectures are modular and future-proof.[^2]
+
+ [^2]:
+ The [built-in plugins] that Material for MkDocs ships perfectly outline this principle, as they are complementary to each other and can be used in combination to build sophisticated pipelines. This modular design allows users to pick and choose the features they need, ensuring that the framework remains lightweight and flexible.
+
+ For instance, the [privacy plugin] can work together with the [optimize plugin] so that external assets can be passed through the same optimization pipeline as the rest of your documentation. This means you can store and edit unoptimized files outside of your repository, and let both plugins automatically build an optimized site for you.
+
+ [built-in plugins]: ../../plugins/index.md
+ [privacy plugin]: ../../plugins/privacy.md
+ [optimize plugin]: ../../plugins/optimize.md
+
+## Challenges
+
+Now, let's talk about our journey and the particular challenges we're addressing. With "we", we're referring to the incredible team that @squidfunk was fortunate to build around his original work, thanks to the financial support he receives from his [sponsors]. This remarkable team includes @alexvoss and @katharinalisalin, whose invaluable contributions in research, development, and community support have been essential to the project's ongoing success.
+
+Together, we've started exploring new technologies, incorporating the feedback we received from our users, and rethinking critical components from first principles, serving our growing community one of the best frameworks to create documentation.
+
+ [sponsors]: https://github.com/sponsors/squidfunk
+
+This section highlights the key areas we've been focusing on.
+
+### Search and discovery
+
+From our perspective, search is a cornerstone of any effective documentation site, enabling users to swiftly locate the information they need. From the start, we've relied on [Lunr.js], a popular client-side search library that has streamlined the deployment of documentation sites without needing an external service. Over the years, Lunr.js has served us well by answering millions of queries on sites built with Material for MkDocs. Yet, as our users' needs evolved, we encountered limitations that proved difficult to overcome.
+
+ [Lunr.js]: https://github.com/olivernn/lunr.js
+
+We learned that the [BM25 ranking algorithm] at the core of Lunr.js (as in many other search implementations) isn't well-suited for effective and stable typeahead. Adding new documents can influence existing rankings, requiring manual adjustments[^3] that are cumbersome and hard to scale. Furthermore, Lunr.js has performance issues that stem from its design not fully leveraging modern JavaScript engines and optimizations, making it slower and memory-intensive.[^4]
+
+ [^3]:
+ Boosting documents in [BM25][BM25 ranking algorithm] can lead to challenges, particularly with a changing corpus of documents. Relevance is calculated based on term frequency and the importance of terms across the entire corpus. Boosting a document involves adjusting its weight to make it more prominent in search results.
+
+ As new documents are added or existing ones are modified, the overall distribution of term frequencies and their importance can shift. This recalibration can diminish the effectiveness of the boost, making it harder to maintain consistent ranking across a changing dataset. Essentially, the boosted documents may not stay as prominent or relevant as intended, leading to imbalances and scalability issues in search results.
+
+ [^4]:
+ Lunr.js uses JavaScript objects to index and manage search data, which introduces inefficiencies due to how JavaScript engines handle object operations. JavaScript engines optimize performance using techniques like inline caching and object shape optimization. However, these optimizations rely on predictable and consistent object structures.
+
+ The dynamic nature of Lunr.js' indexing — where documents can have varying structures — prevents the engine from applying these optimizations effectively. This means that while JavaScript engines can optimize for fixed, predictable object structures, they struggle with the polymorphic and fluid nature of Lunr.js's indexing, leading to performance issues as the amount of data grows.
+
+ [BM25 ranking algorithm]: https://en.wikipedia.org/wiki/Okapi_BM25
+
+Over the last years, we've invested substantially into [improving the search experience]. For instance, expanding Lunr.js' functionality to add support for [rich search previews] and [tokenizer lookahead] demanded substantial engineering effort. Lunr.js allows to customize tasks such as stemming, stopword filtering, and trimming with [pipeline functions], but it makes it particularly hard to add extensions like term highlighting or alternative ranking methods. Compounded by the fact that Lunr.js has been [unmaintained since 2020], it became clear that we needed to find a more powerful solution. We've looked at alternative JavaScript-based libraries to keep our client-side search, but none met our requirements or lived up to our expectations.
+
+ [improving the search experience]: search-better-faster-smaller.md
+ [rich search previews]: search-better-faster-smaller.md#rich-search-previews
+ [tokenizer lookahead]: search-better-faster-smaller.md#tokenizer-lookahead
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+ [unmaintained since 2020]: https://github.com/olivernn/lunr.js/releases/tag/
+
+To address these challenges, we've embarked on developing a new search system from first principles that not only matches but already exceeds the capabilities of Lunr.js. Built from the ground up, this system is faster, more compact, and most importantly: modular. It is based on a growing core evolving around two core concepts we isolated to be essential – engines and plugins – allowing for flexible configuration and assembly of components like text indexing, vector embeddings, filtering, ranking, highlighting, and more. Every part of it can be replaced or extended, enabling users to tailor the search system to their specific needs.
+
+Our new search system, which we will release as a separate MIT-licensed Open Source project, is designed to handle a wide range of scenarios — from small blogs to large documentation projects. Of course, it supports offline use and integrates seamlessly with both client and server environments. The advanced ranking system provides fine-tuned control, and integration with third-party services is now more straightforward.
+
+__:octicons-goal-16: Goal – Empower users to quickly find the information they need while freeing authors from managing external services, by providing a search system that adapts to diverse content types.__
+
+You might wonder why it's not yet available. The process of developing this system from scratch and uncovering its potential has led us to re-evaluate core concepts of Material for MkDocs. As a result, we've decided to postpone the release of the new search system to integrate it into the broader update that we've started to work on. If you keep on reading, you'll learn about further reasons why we've decided to follow this approach.
+
+We're excited to share more details about this update in one of the next posts in this series.
+
+### Translations and versioning
+
+Supporting multi-language sites in MkDocs is the [most requested feature on our discussion board] and in conversations with users, yet it presents significant challenges, as MkDocs does not natively support it. The same applies to versioning, which also involves synchronisation of multi-project builds. While the MkDocs ecosystem has developed [various plugins and tools] to address these issues, there is still substantial untapped potential. We began exploring these areas but quickly encountered problems that hindered our progress.
+
+ [most requested feature on our discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/2346
+ [various plugins and tools]: https://github.com/mkdocs/catalog?tab=readme-ov-file#-site-building-site-management
+
+As you may know, our initial effort involved the [projects plugin] that aims to extend MkDocs to add support for multi-project environments as a solid foundation to support multi-language sites and versioning. Unfortunately, we encountered significant challenges due to MkDocs' internal architecture and design constraints, which we're working actively on resolving.[^5]
+
+ [^5]:
+ When developing the [projects plugin], we initially made [good progress], including adding support for nested projects and allowing for a tree structure where sub-projects can have further sub-projects. However, we quickly encountered difficulties, particularly with cross-project navigation. To illustrate, imagine that each project can link to any other project, which makes handling these interconnections complex, especially when dealing with circular dependencies — such as Project A linking to Project B and vice versa.
+
+ Implementing multi-project support in MkDocs is particularly challenging due to the lack of an official programmatic API, which complicates efforts to extend its functionality. Moreover, resolving navigation issues before building projects is crucial for ensuring proper interconnectivity. These challenges combined made the development of the projects plugin a complex endeavor.
+
+ [projects plugin]: ../../plugins/projects.md
+ [good progress]: https://github.com/squidfunk/mkdocs-material/discussions/5800
+
+__:octicons-goal-16: Goal – Enable scaling documentation to any size or team structure by offering seamless methods for integrating multiple documentation projects, whether they involve different languages, versions, or distinct sections of an overall body of work.__
+
+As a result, we are developing a new approach to offer a more comprehensive and robust solution for both multi-language support and versioning. This new approach also intersects with adjacent functionalities like search, as many of our users are interested in [federated search] capabilities that combine results from multiple documentation sites into a unified search interface. Overcoming this challenge is one of the major hurdles we need to address before releasing the new search system.
+
+ [federated search]: https://github.com/squidfunk/mkdocs-material/issues/5230
+
+### Editing and collaboration
+
+We had considered developing a live editor in response to MkDocs' [performance issues with large projects], which in most cases stem from compute-intensive plugins that don't employ caching. A [proof of concept] based on [Pyodide] (= running Python in the browser) [generated significant interest] among users and prompted many organizations and individuals to share their collaborative workflows for feedback. Sadly, implementing this live editor proved to be very challenging, as it would require rebuilding substantial parts of MkDocs.[^6] After discontinuing work on this approach, our progress with multi-project support has renewed our belief that we can finally solve the sluggish editing experience that was reported several times over the last years.[^7]
+
+ [performance issues with large projects]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2093299518
+ [proof of concept]: https://x.com/squidfunk/status/1338252230265360391
+ [Pyodide]: https://pyodide.org/
+ [generated significant interest]: https://github.com/squidfunk/mkdocs-material/issues/2110
+
+ [^6]:
+ Our [proof of concept] supported some features of Material for MkDocs but didn't cover them all. For instance, integrating support for icons or linking between documents would have necessitated reimplementing parts of MkDocs to bypass a full rebuild — something we obviously wanted to avoid. Additionally, certain links, such as those to blog posts generated from schemas, are not merely translated but computed dynamically, which means they cannot be inferred by replacing the `.md` extension with `.html`.
+
+ [^7]:
+ After [we raised this issue] with the maintainers of MkDocs again[^8], and [maintainership changed] mid 2024, work on a [ground-up rewrite] that aims to address slow reloads by [rendering only the page currently being built] has started. It's still unclear how this rewrite will integrate with the requirements of existing plugins. Complex plugins such as [mkdocstrings], or our [built-in blog] and [tags] plugins require a coordinated build of all pages to accurately resolve links between pages and to computed resources, which cannot be determined without building the entire project.
+
+ __Update__{ title="August 21, 2024" }: The new maintainer now publicly stated that he's working towards a new version of MkDocs that [does not require or support plugins], and mentions it will be equally capable through offering customization via templating, themes, and styling, which he also mentioned to us and several other users in [a team call on August 1]. In this call, [we raised objections multiple times] in regards to how this will impact the ecosystem, to no avail. No intention or roadmap for plugin support was provided. This development is orthogonal to our goal empowering users and organizations to adapt the core framework to their requirements by the means of modularity. We're working on resolving this situation, and will provide a way forward for our community.
+
+ [we raised this issue]: https://github.com/mkdocs/mkdocs/issues/3695
+ [maintainership changed]: https://github.com/mkdocs/mkdocs/discussions/3677
+ [ground-up rewrite]: https://github.com/mkdocs/sketch
+ [rendering only the page currently being built]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2117939743
+ [mkdocstrings]: https://mkdocstrings.github.io/
+ [built-in blog]: ../../plugins/blog.md
+ [tags]: ../../plugins/tags.md
+ [does not require or support plugins]: https://github.com/mkdocs/mkdocs/discussions/3815#discussioncomment-10398312
+ [a team call on August 1]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
+ [we raised objections multiple times]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10215445
+
+ [^8]:
+ Previously raised issues include [#2418], [#2384], and [#1900].
+
+ [#1900]: https://github.com/mkdocs/mkdocs/issues/1900
+ [#2384]: https://github.com/mkdocs/mkdocs/issues/2384
+ [#2418]: https://github.com/mkdocs/mkdocs/issues/2418
+
+This brings us to collaboration, which wasn't initially on our list of priorities. However, throughout 2024, conversations with various organizations and maintainers of popular Open Source projects highlighted a frequent request for enhanced collaboration features. Many users expressed a need for capabilities that would allow non-technical team members to suggest and make changes to the documentation. We're genuinely grateful for this feedback, as it has come at a pivotal time. We recognize the need to streamline tracking and discussing changes, as well as to facilitate drive-by contributions.
+
+__:octicons-goal-16: Goal – Everyone, regardless of their technical skill level, can easily work on and improve the documentation and contribute to a growing corpus of knowledge.__[^9]
+
+ [^9]:
+ We are actively aligning our future development efforts to address this, recognizing it as a key area for improvement. While it's not something we can deliver immediately, we are committed to making this vision a reality in our work.
+
+This focus on collaboration aligns with how knowledge is managed in enterprises. In large organizations, documentation often exists in [information silos] — decentralized yet essential repositories of information. We understand the need to be able to unify these disparate sources into a coherent body of knowledge while preserving decentralized ownership. This also nicely aligns with our previously outlined work on multi-project support, as well as the new search system to implement [federated search] among multiple projects.
+
+ [information silos]: https://en.wikipedia.org/wiki/Information_silo
+
+### Large Language Models (LLMs)
+
+Almost a year ago, we introduced an [experimental chatbot] on our documentation site. It quickly became one of the most anticipated features, with users requesting the ability to deploy similar functionality on their own sites, underscoring the growing demand for interactive documentation tools. However, we found that adding to the myriad of existing chat solutions and simply building another thin wrapper on top of ChatGPT is nonsense.
+
+__:octicons-goal-16: Goal – We're envisioning creating a unified interface that seamlessly integrates advanced search, chat, and summarization features, providing an interactive documentation experience.__
+
+ [experimental chatbot]: https://github.com/squidfunk/mkdocs-material/discussions/6240
+
+As we delved into this ambitious project, we gained valuable insights from user feedback. Users began interacting with the chatbot in their native languages, an outcome we hadn't anticipated given that our documentation is in English. Remarkably (or obviously to those that work on LLMs year round), the chatbot responded in the same language. This ability of LLMs is one of the genuinely exciting features of these machine learning models as it has the potential to improve the accessibility of the documentation. However, while we employed state-of-the-art RAG methodologies, the results were mixed, and occasional hallucinations surfaced.
+
+These experiences led us to prioritize enhancing our search capabilities before integrating LLM-based features. Building a search engine from scratch was already a substantial effort, and adding more complexity without a solid search foundation would be premature. By rearchitecting our search functionalities, we aim to create a robust platform that will seamlessly support advanced information retrieval and deliver a cohesive interactive documentation experience.
+
+## Team, transparency, and growth
+
+While we navigate the challenges and explore the opportunities of this project, we consider it essential to demonstrate how we're building a solid foundation for its continued growth and success. Please consider this an overview rather than a formal roadmap — our detailed plans are in the works. The goals we've highlighted represent the most impactful areas we aim to address.
+
+Thanks to the generous support from our sponsors, we're fortunate to be assembling a team capable of dedicating significant time and expertise to this endeavor. This newfound capacity allows us to delve deeper into core development while also engaging more comprehensively with our user community. A special mention goes to @kamilkrzyskow, one of our invaluable [community experts], who has been essential in supporting users and fostering discussions on our platform.
+
+ [community experts]: http://localhost:3000/mkdocs-material/insiders/community-experts-program/
+
+With the team's support, @squidfunk can concentrate on the heart of development, while we have begun investing in user research. This effort is helping us understand how organizations and individuals interact with our tools, guiding the project's future direction based on real feedback from numerous conversations with users and companies.
+
+Looking to expand our team further, we are committed to improving transparency and communication. Our previous work often happened behind the scenes due to time constraints, but we're now focused on making our processes more open and inviting for new contributors. By embracing this collaborative approach, we aim to enhance our tools and ensure they meet the evolving needs of our community.
+
+## What's ahead of us
+
+As we look into the future, some of the groundwork we're laying now is crucial for the exciting developments on the horizon. Many of the initiatives we've discussed represent foundational work that will set the stage for much more ambitious and innovative features. Once these core elements are in place, we'll deliver a range of exciting new functionalities that align with our vision and goals.
+
+In the coming months, we'll be sharing more details about our plans and how they will contribute to our overarching objectives. While growth and innovation are at the forefront of our plans, we want to assure you that our core values remain unchanged. We are committed to maintaining the principles that have guided us thus far, ensuring that our growth is both healthy and consistent:
+
+- Against recent industry trends with companies moving away from core ideas of Open Source, we are doubling down on our commitment to Open Source because we believe it's at the heart of the value proposition of our work and the [docs as code] approach.
+
+ [docs as code]: https://www.writethedocs.org/guide/docs-as-code/
+
+- Our [organic approach to growth] is part of this strategy as it keeps us independent of individual funding sources and pressures to provide a return on investment, which is what causes many other projects to turn away from the principles of Open Source.
+
+ [organic approach to growth]: https://star-history.com/#squidfunk/mkdocs-material
+
+- Likewise, we are driven by the needs of the community for a rich ecosystem of adaptations of the core framework. Extensibility and modularity are key for this and we are working hard to improve the developer experience by providing clear interfaces.
+
+Stay tuned for updates as we continue to build on our progress and explore new possibilities. We're excited about the future and look forward to sharing more with you as we advance.
+
+_Martin, Alex and Kathi_ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
diff --git a/mkdocs-material/docs/browser-support.md b/mkdocs-material/docs/browser-support.md
new file mode 100644
index 0000000..7cf4f5a
--- /dev/null
+++ b/mkdocs-material/docs/browser-support.md
@@ -0,0 +1,67 @@
+# Browser support
+
+Material for MkDocs goes at great lengths to support the largest possible range
+of browsers while retaining the simplest possibilities for customization via
+modern CSS features like [custom properties] and [mask images].
+
+ [custom properties]: https://caniuse.com/css-variables
+ [mask images]: https://caniuse.com/mdn-css_properties_mask-image
+
+## Supported browsers
+
+The following table lists all browsers for which Material for MkDocs offers full
+support, so it can be assumed that all features work without degradation. If you
+find that something doesn't look right in a browser which is in the supported
+version range, please [open an issue]:
+
+
+
+| Browser | Version | Release date | | | Usage |
+| ------------------------------------ | ------: | -----------: | ------: | -----: | ---------: |
+| | | | desktop | mobile | overall |
+| :fontawesome-brands-chrome: Chrome | 49+ | 03/2016 | 25.65% | 38.33% | 63.98% |
+| :fontawesome-brands-safari: Safari | 10+ | 09/2016 | 4.63% | 14.96% | 19.59% |
+| :fontawesome-brands-edge: Edge | 79+ | 01/2020 | 3.95% | n/a | 3.95% |
+| :fontawesome-brands-firefox: Firefox | 53+ | 04/2017 | 3.40% | .30% | 3.70% |
+| :fontawesome-brands-opera: Opera | 36+ | 03/2016 | 1.44% | .01% | 1.45% |
+| | | | | | __92.67%__ |
+
+
+
+Browser support matrix sourced from [caniuse.com].[^1]
+
+
+
+
+ [^1]:
+ The data was collected from [caniuse.com] in January 2022, and is primarily
+ based on browser support for [custom properties], [mask images] and the
+ [:is pseudo selector] which are not entirely polyfillable. Browsers with a
+ cumulated market share of less than 1% were not considered, but might still
+ be fully or partially supported.
+
+Note that the usage data is based on global browser market share, so it could
+in fact be entirely different for your target demographic. It's a good idea to
+check the distribution of browser types and versions among your users.
+
+ [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
+ [caniuse.com]: https://caniuse.com/
+ [:is pseudo selector]: https://caniuse.com/css-matches-pseudo
+ [browser support]: #supported-browsers
+ [built-in privacy plugin]: plugins/privacy.md
+
+## Other browsers
+
+Albeit your site might not look as perfect as when viewed with a modern browser,
+the following older browser versions might work with some additional effort:
+
+- :fontawesome-brands-firefox: __Firefox 31-52__ – icons will render as little
+ boxes due to missing support for [mask images]. While this cannot be
+ polyfilled, it might be mitigated by hiding the icons altogether.
+- :fontawesome-brands-edge: __Edge 16-18__ – the spacing of some elements might
+ be a little off due to missing support for the [:is pseudo selector], which
+ can be mitigated with some additional effort.
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ - no support,
+ mainly due to missing support for [custom properties]. The last version of
+ Material for MkDocs to support Internet Explorer is
+ .
diff --git a/mkdocs-material/docs/changelog/index.md b/mkdocs-material/docs/changelog/index.md
new file mode 100644
index 0000000..29e712c
--- /dev/null
+++ b/mkdocs-material/docs/changelog/index.md
@@ -0,0 +1,2451 @@
+# Changelog
+
+## Material for MkDocs
+
+### 9.5.43 October 31, 2024 { id="9.5.43" }
+
+- Added support for external images in SVGs in privacy plugin
+- Fixed #7651: Privacy plugin doesn't handle quoted URLs in CSS
+
+### 9.5.42 October 20, 2024 { id="9.5.42" }
+
+- Fixed #7625: Invalid encoding of boolean attributes in privacy plugin
+- Fixed #7624: Crash when disabling privacy plugin (9.5.41 regression)
+
+### 9.5.41 October 15, 2024 { id="9.5.41" }
+
+- Fixed #7619: Improved tooltip on logo disappears after instant navigation
+- Fixed #7616: Race condition in built-in privacy plugin when inlining assets
+- Fixed #7615: Comments and "Was this page helpful?" visible when printing
+
+### 9.5.40 October 10, 2024 { id="9.5.40" }
+
+- Updated Latvian translations
+- Fixed #7597: Social cards not using site name on home page
+
+### 9.5.39 September 29, 2024 { id="9.5.39" }
+
+- Fixed #7226: not staying on page when using mike's canonical versioning
+
+### 9.5.38 September 26, 2024 { id="9.5.38" }
+
+- Added Albanian translations
+
+### 9.5.37 September 25, 2024 { id="9.5.37" }
+
+- Added 4th and 5th level ordered list styles
+- Fixed #7548: Tags have no spacing in search
+
+### 9.5.36 September 21, 2024 { id="9.5.36" }
+
+- Fixed #7544: Social cards incorrectly rendering HTML entities
+- Fixed #7542: Improved support for setting custom list styles
+
+### 9.5.35 September 18, 2024 { id="9.5.35" }
+
+- Fixed #7498: Search not showing for Vietnamese language
+
+### 9.5.34 August 31, 2024 { id="9.5.34" }
+
+- Updated Mermaid.js to version 11 (latest)
+
+### 9.5.33 August 23, 2024 { id="9.5.33" }
+
+- Fixed #7453: Incorrect position of tooltip when sorting table
+
+### 9.5.32 August 19, 2024 { id="9.5.32" }
+
+- Fixed RXSS vulnerability via deep link in search results
+- Added support for fetching latest release from GitLab
+
+### 9.5.31 August 2, 2024 { id="9.5.31" }
+
+- Fixed #7405: DockerHub missing images > 9.5.27 due to change in Alpine/APK
+
+### 9.5.30 July 23, 2024 { id="9.5.30" }
+
+- Fixed #7380: Navigation icons disappearing on hover in Safari
+- Fixed #7367: Blog readtime computation includes SVG text content
+
+### 9.5.29 July 14, 2024 { id="9.5.29" }
+
+- Updated Galician translations
+- Fixed #7362: Annotations in figure captions rendering incorrectly
+
+### 9.5.28 July 2, 2024 { id="9.5.28" }
+
+- Fixed #7313: Improved tooltips mounted in sidebar when feature is disabled
+
+### 9.5.27 June 16, 2024 { id="9.5.27" }
+
+- Updated Estonian translations
+
+### 9.5.26 June 6, 2024 { id="9.5.26" }
+
+- Fixed #7232: Tab switches on scroll when linking tabs (9.5.19 regression)
+- Fixed #7230: Blog author avatar broken when referring to local file
+
+### 9.5.25 May 27, 2024 { id="9.5.25" }
+
+- Fixed #7209: Tags plugin crashing on numeric tags
+
+### 9.5.24 May 20, 2024 { id="9.5.24" }
+
+- Fixed #7187: Version selector title rendering issue
+
+### 9.5.23 May 15, 2024 { id="9.5.23" }
+
+- Fixed #7183: Edge case in anchor navigation when using instant navigation
+- Fixed #6436: Version selector not showing version alias
+
+### 9.5.22 May 12, 2024 { id="9.5.22" }
+
+- Fixed #7170: Copy button adds empty lines for line spans (9.5.18 regression)
+- Fixed #7160: Version switching doesn't stay on page (9.5.5 regression)
+- Fixed #5619: Links in Mermaid.js diagrams not discernible
+
+### 9.5.21 May 3, 2024 { id="9.5.21" }
+
+- Fixed #7133: Ensure latest version of Mermaid.js is used
+- Fixed #7125: Added warning for dotfiles in info plugin
+
+### 9.5.20 April 29, 2024 { id="9.5.20" }
+
+- Fixed deprecation warning in privacy plugin (9.5.19 regression)
+- Fixed #7119: Tags plugin emits deprecation warning (9.5.19 regression)
+- Fixed #7118: Social plugin crashes if fonts are disabled (9.5.19 regression)
+- Fixed #7085: Social plugin crashes on Windows when downloading fonts
+
+### 9.5.19 April 25, 2024 { id="9.5.19" }
+
+- Updated MkDocs to 1.6 and limited version to < 2
+- Updated Docker image to latest Alpine Linux
+- Removed `setup.py`, now that GitHub fully understands `pyproject.toml`
+- Improved interop of social plugin with third-party MkDocs themes
+- Fixed #7099: Blog reading time not rendered correctly for Japanese
+- Fixed #7097: Improved resilience of tags plugin when no tags are given
+- Fixed #7090: Active tab indicator in nested content tabs rendering bug
+
+### 9.5.18 April 16, 2024 { id="9.5.18" }
+
+- Refactored tooltips implementation to fix positioning issues
+- Fixed #7044: Rendering glitch when hovering contributor avatar in Chrome
+- Fixed #7043: Highlighted lines in code blocks cutoff on mobile
+- Fixed #6910: Incorrect position of tooltip for page status in sidebar
+- Fixed #6760: Incorrect position and overly long tooltip in tables
+- Fixed #6488: Incorrect position and cutoff tooltip in content tabs
+
+### 9.5.17 April 2, 2024 { id="9.5.17" }
+
+- Updated Serbian translations
+- Fixed #7003: Confusing keyboard interaction for palette toggle
+- Fixed #7001: Blog posts now show time by default (9.5.16 regression)
+- Fixed edge case in backport of social plugin font loading logic
+
+### 9.5.16 March 31, 2024 { id="9.5.16" }
+
+- Updated Russian translations
+- Improved error handling and reporting in social plugin
+- Improved error handling and reporting in privacy plugin
+- Fixed blog plugin not allowing to use time in format strings
+- Fixed #6983: Social plugin crashes because of Google Fonts API change
+
+### 9.5.15 March 23, 2024 { id="9.5.15" }
+
+- Reverted fix for transparent iframes (9.5.14)
+- Fixed #6929: Interference of social plugin and auto dark mode
+- Fixed #6938: Giscus shows dark background in light mode (9.5.14 regression)
+
+### 9.5.14 March 18, 2024 { id="9.5.14" }
+
+- Added support for hiding versions from selector when using mike
+- Added init system to improve signal handling in Docker image
+- Fixed edge cases in exclusion logic of info plugin
+- Fixed inability to reset pipeline in search plugin
+- Fixed syntax error in Finnish translations
+- Fixed #6917: UTF-8 encoding problems in blog plugin on Windows
+- Fixed #6889: Transparent iframes get background color
+
+### 9.5.13 March 6, 2024 { id="9.5.13" }
+
+- Updated Slovak translations
+- Improved info plugin interop with projects plugin
+- Improved info plugin inclusion/exclusion logic
+- Fixed info plugin not gathering files recursively
+- Fixed #6750: Ensure info plugin packs up all necessary files
+
+### 9.5.12 February 29, 2024 { id="9.5.12" }
+
+- Fixed #6846: Some meta tags removed on instant navigation (9.4.2 regression)
+- Fixed #6823: KaTex not rendering on instant navigation (9.5.5 regression)
+- Fixed #6821: Privacy plugin doesn't handle URLs with encoded characters
+
+### 9.5.11 February 24, 2024 { id="9.5.11" }
+
+- Updated Finnish translation
+
+### 9.5.10 February 19, 2024 { id="9.5.10" }
+
+- Updated Bahasa Malaysia translations
+- Fixed #6783: Hide continue reading link for blog posts without separators
+- Fixed #6779: Incorrect positioning of integrated table of contents
+
+### 9.5.9 February 10, 2024 { id="9.5.9" }
+
+- Fixed navigation pruning with tabs and sections enabled
+
+### 9.5.8 February 7, 2024 { id="9.5.8" }
+
+- Added Tamil translations
+- Updated Esperanto translations
+- Fixed relative images not being resolved for instant navigation
+
+### 9.5.7 February 3, 2024 { id="9.5.7" }
+
+- Fixed #6731: Small images in figures are not centered
+- Fixed #6719: Instant navigation breaks table of contents (9.5.5 regression)
+
+### 9.5.6 January 28, 2024 { id="9.5.6" }
+
+- Fixed #6700: Missing styles for Mermaid.js labels with Markdown
+
+### 9.5.5 January 24, 2024 { id="9.5.5" }
+
+- Updated Tagalog translations
+- Updated Pillow to 10.2 to mitigate security vulnerabilities
+- Improved resilience of instant navigation
+- Fixed #6687: Updated Mermaid.js to version 10.7.0 (latest)
+- Fixed #6652: Keyboard events in custom elements captured
+- Fixed #6582: Instant navigation doesn't correctly handle alternate URLs
+- Fixed #6565: Instant navigation doesn't allow for `onclick` handlers
+- Fixed #6345: Instant navigation sometimes breaks browser back button
+- Fixed #6334: Instant navigation doesn't correctly position anchors (Safari)
+- Fixed #6275: Instant navigation doesn't correctly resolve after 404
+- Fixed #6102: Instant navigation reloads page on same link navigation
+
+### 9.5.4 January 15, 2024 { id="9.5.4" }
+
+- Fixed #6645: Local storage with invalid value can break site
+- Fixed #6635: Tags icons before default ignored if default is set
+
+### 9.5.3 December 23, 2023 { id="9.5.3" }
+
+- Limited version range of MkDocs to < 1.6
+- Updated Macedonian translations
+- Fixed #6520: Group plugin crashes when using mike
+- Fixed #6494: Hide author's email address if disabled in git-authors plugin
+
+### 9.5.2 December 11, 2023 { id="9.5.2" }
+
+- Fixed types for `slugify` settings in blog plugin config
+- Fixed #6469: Horizontal scrollbars on MathJax containers
+
+### 9.5.1 December 8, 2023 { id="9.5.1" }
+
+- Updated Greek translations
+- Fixed #6464: Privacy plugin cannot be enabled
+- Fixed #6461: Sorting blog posts ignores time component in date
+
+### 9.5.0 December 7, 2023 { id="9.5.0" }
+
+Merged Insiders features of 'Goat's Horn' funding goal
+
+- Added privacy plugin: automatic downloading of external assets
+- Added support for card grids and grid layouts
+- Added support for improved tooltips
+- Added support for content tabs anchor links (deep linking)
+- Added support for automatic dark/light mode
+- Added support for document contributors
+
+### 9.4.14 November 26, 2023 { id="9.4.14" }
+
+- Added support for linking authors in blog posts
+
+### 9.4.13 November 26, 2023 { id="9.4.13" }
+
+- Fixed #6365: Blog plugin pagination links to previous pages broken
+- Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
+
+### 9.4.12 November 24, 2023 { id="9.4.12" }
+
+- Improved blog plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of categories in blog plugin
+
+### 9.4.11 November 23, 2023 { id="9.4.11" }
+
+- Fixed #6364: Search plugin crashing when enabling theme while serving
+- Fixed blog plugin crashing when disabling pagination
+
+### 9.4.10 November 19, 2023 { id="9.4.10" }
+
+- Fixed #6356: Version selector can't be disabled via mike's configuration
+- Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
+- Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
+
+### 9.4.9 November 17, 2023 { id="9.4.9" }
+
+- Fixed #6344: Long entries cutoff in table of contents
+- Fixed #6336: Custom template for glob archive not working with pagination
+- Fixed #6328: Blog plugin crashes for locales with dashes, e.g. `pt-BR`
+- Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
+- Fixed #6302: Version strings not matched when using mike, only aliases
+- Fixed instant navigation progress indicator for gzipped content in Chrome
+- Fixed rendering bug on details marker rotation in Firefox
+
+### 9.4.8 November 5, 2023 { id="9.4.8" }
+
+- Fixed invalid local address replacement when using instant loading
+- Fixed #6275: Crash after navigation caused 404 when using instant loading
+
+### 9.4.7 October 27, 2023 { id="9.4.7" }
+
+- Added Azerbaijani translations
+
+### 9.4.6 October 14, 2023 { id="9.4.6" }
+
+- Updated Danish and Norwegian (Nynorsk) translations
+- Fixed #6169: Blog post metadata layout overflows on small screens
+
+### 9.4.5 October 10, 2023 { id="9.4.5" }
+
+- Fixed sidebar auto-positioning (9.4.2 regression)
+- Fixed #6166: Improve group plugin compatibility with Python < 3.10
+- Fixed #6157: Hiding tags does not work (9.4.3 regression)
+
+### 9.4.4 October 5, 2023 { id="9.4.4" }
+
+- Added support for overriding text to be copied for code blocks
+- Fixed broken layout in some browsers at breakpoints when using zoom
+- Fixed #6132: Incomplete search highlighting for code blocks in titles
+
+### 9.4.3 October 2, 2023 { id="9.4.3" }
+
+- Added support for instant navigation progress indicator
+- Improved spacing and alignment of tags
+- Moved back-to-top button into separate partial
+- Fixed #6104: Indentation for some code blocks lost in search
+- Fixed #6094: Blog post metadata overlaps with footer on small screens
+- Fixed #6069: Blog plugin crashes for categories with non-ASCII names
+
+__Updated templates__ ([diff](https://github.com/squidfunk/mkdocs-material/compare/9.4.2...9.4.3))
+
+- `base.html`
+
+### 9.4.2 September 25, 2023 { id="9.4.2" }
+
+- Updated Slovenian translations
+- Added animation to sidebar navigation expansion and collapse
+- Added support for auto-replacement of document head for instant navigation
+- Improved compatibility of new emoji extension with Python < 3.10
+- Switched regex dependency to use minimal version
+- Refactored alignment and spacing of sidebar navigation
+- Fixed expansion button not focusable via keyboard in sidebar navigation
+- Fixed viewport offset restoration on first load when using instant navigation
+- Fixed accidental highlight of non-clickable elements in blog plugin sidebar
+- Fixed #6041: Blog plugin crashes when `nav` is defined and blog not included
+- Fixed #5972: Blog plugin ignores section index pages in paginated views
+- Fixed #5954: Repeated click on anchor ignored when using instant navigation
+- Fixed #5742: Keyboard navigation broken when using instant navigation
+
+__Updated templates__ ([diff](https://github.com/squidfunk/mkdocs-material/compare/9.4.1...9.4.2))
+
+- `partials/nav-item.html`
+- `blog-post.html`
+
+### 9.4.1 September 22, 2023 { id="9.4.1" }
+
+- Improved colors and contrast in dark mode
+- Improved admonition borders to match font weight
+- Switched content tabs to neutral color
+
+### 9.4.0 September 21, 2023 { id="9.4.0" }
+
+- Added Belarusian translations
+- Added version info to entrypoint of package
+- Added emoji extension as a replacement for `materialx`
+- Improved slate color scheme (dark mode) - now even darker
+- Restructured project to improve development experience
+- Updated MkDocs to 1.5.3
+- Fixed #3890: Development mode crash on Linux
+
+### 9.3.2 September 19, 2023 { id="9.3.2" }
+
+- Updated Slovenian translations
+- Updated Python dependencies in requirements to use minimum versions
+- Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
+- Fixed #6001: Contributor avatars display incorrectly in Firefox
+- Fixed #6000: Blog post drafts are included in navigation
+
+### 9.3.1 September 11, 2023 { id="9.3.1" }
+
+- Fixed crash of group plugin when used together with hooks
+
+### 9.3.0 September 11, 2023 { id="9.3.0" }
+
+- Improved configuration sharing between Community and Insiders edition
+- Added experimental built-in group plugin for enabling plugins conditionally
+- Added new settings in tags plugin for enabling/disabling
+- Dropped support for Python 3.7 (EOL)
+
+### 9.2.8 September 4, 2023 { id="9.2.8" }
+
+- Updated Italian and Russian translations
+- Fixed #5952: Combining blog and tags plugin leads to wrong links
+- Fixed #5951: Blog plugin ignores post title in metadata
+- Fixed #5949: Blog plugin ignores post linked in nav
+
+### 9.2.7 September 2, 2023 { id="9.2.7" }
+
+- Switched dependencies to compatible release clauses
+- Removed `readtime` and `lxml` dependencies for blog plugin
+- Reduced size of Docker image to improve CI build performance
+- Fixed #5945: Incorrect footer navigation for sibling pages of blog
+- Fixed #5939: Page jumps when changing color palette (Firefox 117)
+- Fixed #5901: Announcement bar reappears when using instant loading
+- Fixed #5824: Allow to customize styles of sequence diagrams
+
+### 9.2.6 August 31, 2023 { id="9.2.6" }
+
+- Added Basque translations
+- Added template for simple redirects
+- Improved blog plugin interop by moving view generation to `on_files`
+- Fixed #5924: Social plugin still checks dependencies when disabled
+- Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
+
+### 9.2.5 August 27, 2023 { id="9.2.5" }
+
+- Fixed error in dirty serve mode when using blog plugin
+- Fixed page title not being consistent in blog plugin pagination
+- Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
+
+### 9.2.4 August 26, 2023 { id="9.2.4" }
+
+- Added version to bug report name in info plugin
+- Updated Afrikaans translations
+
+### 9.2.3 August 22, 2023 { id="9.2.3" }
+
+- Fixed blog plugin rendering wrongly with `markdown.extensions.toc`
+- Fixed blog plugin entrypoint generation
+
+### 9.2.2 August 22, 2023 { id="9.2.2" }
+
+- Fixed #5880: Blog plugin failing when building a standalone blog
+- Fixed #5881: Blog plugin not compatible with Python < 3.10
+
+### 9.2.1 August 21, 2023 { id="9.2.1" }
+
+- Fixed #5879: Blog plugin failing when building a standalone blog
+- Fixed error in blog plugin when using draft tagging on future date
+- Fixed error in blog plugin when toc extension is not enabled
+
+### 9.2.0 August 21, 2023 { id="9.2.0" }
+
+__Additions and improvements__
+
+- Added blogging support via built-in blog plugin
+- Added support for Chinese language segmentaiton in search plugin
+- Added support for adding custom dates to blog posts
+- Added support for paginating archive and category pages
+- Added support for annotations (outside of code blocks)
+- Added support for navigation icons
+- Added support for navigation pruning
+- Added support for navigation status
+- Added support for customizing site icons
+- Added support for customizing (code) annotation icons
+- Added focus outline to admonitions and details
+- Added prompt for bug report name to info plugin
+- Added Luxembourgish translations
+- Improved rendering of (code) annotation markers
+- Improved print styles for (code) annotations
+- Improved customizability of navigation tabs
+- Improved interop of plugins with external tools like mike
+- Improved interop of blog plugin with awesome pages plugin
+- Improved header partial by moving buttons into separate partials
+- Improved clarity of `site_url` warning in social plugin
+- Improved blog plugin to automatically setup directory structure
+- Switched info plugin to `importlib` to mitigate deprecations
+- Automatically download ResizeObserver polyfill when necessary
+- Automatically add iframe-worker polyfill when necessary in offline plugin
+- Automatically focus and bring up keyboard on touch devices
+- Updated Serbo-Croatian translations
+- Updated MkDocs to 1.5.2
+
+__Removals__
+
+- Removed Universal Analytics integration
+- Removed ancient polyfills to reduce size of bundled JavaScript by 20%
+- Removed necessity for `Array.flat` and `Array.flatMap` polyfill
+- Removed announcement bar button when JavaScript is not available
+
+__Fixes__
+
+- Fixed rendering of tags when announcement bar is present
+- Fixed tags plugin rendering pages excluded by other plugins
+- Fixed #5132: Blog plugin requires `nav` entry in `mkdocs.yml`
+- Fixed #5599: Insufficient contrast for default link color
+- Fixed #5715: Blog plugin missing integrated table of contents in pagination
+- Fixed #5806: Version selector not hoverable on some Android devices
+- Fixed #5826: Blog post drafts with tags show up in tags index
+
+### 9.1.21 July 27, 2023 { id="9.1.21" }
+
+- Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
+### 9.1.20 July 27, 2023 { id="9.1.20" }
+
+- Updated Sanskrit translations
+- Fixed deprecation warnings for social plugin
+
+### 9.1.19 July 18, 2023 { id="9.1.19" }
+
+- Added support for MkDocs 1.5+
+- Fixed #5699: Improve error reporting in social plugin
+
+### 9.1.18 July 3, 2023 { id="9.1.18" }
+
+- Updated Danish translations
+- Added support for installing user requirements in Docker image
+- Fixed #5655: Search separator with lookbehind breaks highlighting
+
+### 9.1.17 June 23, 2023 { id="9.1.17" }
+
+- Fixed #5633: Code annotations with nested lists incorrectly mounted
+- Fixed #5628: Regression in new social plugin configuration scheme
+
+### 9.1.16 June 15, 2023 { id="9.1.16" }
+
+- Updated Indonesian translations
+- Ensure scroll bar follows color scheme of operating system
+
+### 9.1.15 May 29, 2023 { id="9.1.15" }
+
+- Fixed #5566: Indicate color scheme to operating system
+- Fixed #5565: Update `Dockerfile` to latest version of base image
+- Fixed #5554: Add additional version tags (`9`, `9.1`) to Docker image
+- Fixed #5536: Strip tags of ARIA labels in table of contents
+
+### 9.1.14 May 20, 2023 { id="9.1.14" }
+
+- Updated Armenian and Greek translations
+
+### 9.1.13 May 16, 2023 { id="9.1.13" }
+
+- Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+### 9.1.12 May 12, 2023 { id="9.1.12" }
+
+- Updated Bengali (Bangla) translations
+- Fixed #5503: Docker image publish errors on uppercase characters
+- Fixed #5407: Auto-pause media when in hidden content tabs
+
+### 9.1.11 May 8, 2023 { id="9.1.11" }
+
+- Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+### 9.1.10 May 8, 2023 { id="9.1.10" }
+
+- Added `cards_layout_options` setting for social cards
+- Deprecated `cards_color` and `cards_font` setting for social cards
+
+### 9.1.9 May 2, 2023 { id="9.1.9" }
+
+- Added Telugu, Kannada and Sanskrit translations
+- Fixed #5428: Fixed margins for light/dark mode images in figures
+- Fixed #5420: Social plugin crashing for some specific Google Fonts
+- Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+- Fixed #4920: Social plugin not loading logo from custom icon set
+- Fixed social plugin crashing when only code font is specified
+
+### 9.1.8 April 24, 2023 { id="9.1.8" }
+
+- Fixed #5417: Theme breaks when `palette` is not defined (9.1.7 regression)
+
+### 9.1.7 April 22, 2023 { id="9.1.7" }
+
+- Updated Persian (Farsi) and Turkish translations
+- Fixed #5401: Added missing flag to disable built-in tags plugin
+- Fixed #5206: Ensure defaults are set for primary and accent colors
+- Fixed unnecessary inclusion of palette CSS when unused
+
+### 9.1.6 April 7, 2023 { id="9.1.6" }
+
+- Updated Persian (Farsi) translations
+- Fixed #5300: Boxes in Mermaid sequence diagrams not color-abiding
+
+### 9.1.5 March 31, 2023 { id="9.1.5" }
+
+- Updated Lithuanian and Japanese translations
+- Updated Mermaid.js to version 9.4.3
+- Fixed #5290: Footer previous/next labels cut-off for short page titles
+
+### 9.1.4 March 24, 2023 { id="9.1.4" }
+
+- Fixed #5239: Instant loading breaks anchors in details (9.1.1 regression)
+- Fixed #5211: Anchor following not working for Chinese (9.1.2 regression)
+
+### 9.1.3 March 14, 2023 { id="9.1.3" }
+
+- Added Kurdish (Soranî) translations
+- Updated Norwegian (Bokmål), Portuguese and Romanian translations
+- Improved compatibility with `mkdocs-jupyter` plugin
+- Fixed #5198: Built-in search plugin not filtering `script` and `style` tags
+- Fixed #5176: Back-to-top + instant loading not working (9.1.1 regression)
+
+### 9.1.2 March 9, 2023 { id="9.1.2" }
+
+- Updated Icelandic, Korean and Swedish translations
+- Fixed #5168: Mermaid text boxes overflow (9.0.13 regression)
+- Fixed #5155: Table of contents not highlighting percent-encoded URLs
+
+### 9.1.1 March 5, 2023 { id="9.1.1" }
+
+- Updated Czech and Thai translations
+- Improved instant loading (scroll restoration, slow connections)
+- Fixed #5023: Instant loading not allowing to go back to initial page
+- Fixed #3797: Instant loading does not work with section anchors in Safari
+
+### 9.1.0 March 2, 2023 { id="9.1.0" }
+
+- Docker image now available for `amd64`, `arm64` and `arm/v7`
+- Updated Chinese (Taiwanese) translations
+- Generalized tag identifier implementation
+- Fixed flickering of header shadow on load
+- Fixed occasional flickering of announcement bar
+
+### 9.0.15 February 26, 2023 { id="9.0.15" }
+
+- Updated Chinese (Traditional) translations
+- Updated Hebrew translations
+
+### 9.0.14 February 23, 2023 { id="9.0.14" }
+
+- Fixed #5072: Rendering bug on navigation expand button in Firefox
+
+### 9.0.13 February 18, 2023 { id="9.0.13" }
+
+- Updated Uzbek translations
+- Switched back to pre-9.0.0 headline detection in `content` partial
+- Fixed #5062: Version warning not readable when using slate scheme
+- Fixed #5061: Improved discernibility of table row hover color
+- Fixed #5034: Sequence actors in Mermaid diagrams not color-abiding
+- Fixed #4919: Allow to hide version warning in multiple versions
+
+### 9.0.12 February 9, 2023 { id="9.0.12" }
+
+- Updated Catalan translations
+- Fixed #4975: Mermaid entity relationship rendering diagrams bug
+- Fixed #4924: Header title not reset when using instant loading
+
+### 9.0.11 February 3, 2023 { id="9.0.11" }
+
+- Added Mastodon verification for social links (`rel=me`)
+- Updated Italian translations
+
+### 9.0.10 February 2, 2023 { id="9.0.10" }
+
+- Updated Arabic translations
+- Updated Korean translations
+- Updated Hungarian translations
+- Updated Russian translations
+- Fixed #4977: Improved accessibility for content tabs
+- Fixed #4960: Sometimes anchor following doesn't bring last item into view
+
+### 9.0.9 January 30, 2023 { id="9.0.9" }
+
+- Updated Bulgarian translations
+- Updated Chinese (Simplified) translations
+- Updated Dutch translations
+- Updated Hindi translations
+- Updated Japanese translations
+- Updated Polish translations
+
+### 9.0.8 January 29, 2023 { id="9.0.8" }
+
+- Updated Croatian translations
+- Updated French translations
+- Updated Hungarian translations
+- Updated Portuguese (Brasilian) translations
+- Updated Spanish translations
+- Updated Ukrainian translations
+- Updated Urdu translations
+- Updated Vietnamese translations
+
+### 9.0.7 January 28, 2023 { id="9.0.7" }
+
+- Improved accessibility of sidebar navigation
+- Moved all translations into Community edition
+- Updated Polish and Portuguese (Brasilian) translations
+- Fixed info plugin terminating on subsequent reload when serving
+- Fixed #4910: Sidebar navigation labels have invalid ARIA roles
+- Fixed #4884: Search query terms can't be separated by colons
+
+### 9.0.6 January 19, 2023 { id="9.0.6" }
+
+- Fixed #4883: Automatically disable info plugin when serving
+- Fixed #4885: Search plugin crashes in some exotic cases (9.0.3 regression)
+
+### 9.0.5 January 14, 2023 { id="9.0.5" }
+
+- Fixed #4842: Improved accessibility of search result list
+
+### 9.0.4 January 12, 2023 { id="9.0.4" }
+
+- Fixed #4823: Improved contrast ratio in footer (9.0.2 regression)
+- Fixed #4832: Set navigation items back to black (9.0.3 regression)
+- Fixed #4843: Emojis broken due to maxcdn.com shutting down
+- Upgraded Python Markdown Extensions to 9.9.1
+
+### 9.0.3 January 8, 2023 { id="9.0.3" }
+
+- Improved discernibility of section index pages in navigation
+- Improved collapsing of adjacent whitespace in search plugin
+- Updated Indonesian translations
+- Fixed view source of this page button when edit URL points to blob
+- Fixed #4829: Search overlay does not close for active anchor result
+- Fixed #4824: Search plugin crashes for `h[1-6]` contained in other elements
+- Fixed #4804: Nested navigation items not expandable with keyboard
+- Fixed #4689: anchor tracking not working for anchors in tables
+- Upgraded to Mermaid 9.3.0
+
+### 9.0.2 January 4, 2023 { id="9.0.2" }
+
+- Fixed #4823: Improved contrast ratio in footer to meet WCAG guidelines
+- Fixed #4819: Social plugin crashes when card generation is disabled
+- Fixed #4817: Search plugin crashes on numeric page titles in `nav`
+
+### 9.0.1 January 3, 2023 { id="9.0.1" }
+
+- Removed `pipdeptree` dependency for built-in info plugin
+- Fixed appearance of linked tags when hovered (9.0.0 regression)
+- Fixed #4810: Abbreviations run out of screen on touch devices
+- Fixed #4813: View source and edit button links are the same
+
+### 9.0.0 January 2, 2023 { id="9.0.0" }
+
+__Additions and improvements__
+
+- Added support for rich search previews
+- Added support for tokenizer lookahead
+- Added support for better search highlighting
+- Added support for excluding content from search
+- Added support for configurable search pipeline
+- Added support for offline search via offline plugin
+- Added support for multiple instances of built-in tags plugin
+- Added support for removing copy-to-clipboard button
+- Added support for removing footer navigation
+- Added support for button to view the source of a page
+- Improved readability of query string for search sharing
+- Improved stability of search plugin when using `--dirtyreload`
+- Improved search result group button, now sticky and stable
+- Updated Norwegian translations
+- Updated MkDocs to 1.4.2
+
+__Removals__
+
+- Removed deprecated alternative admonition qualifiers
+- Removed `:is()` selectors (in output) for easier overriding
+- Removed `.title` suffix on translations
+- Removed legacy method for providing page title in feedback URL
+- Removed support for indexing only titles in search
+- Removed support for custom search transforms
+- Removed support for custom search workers
+- Removed temporary snow feature (easter egg)
+
+__Fixes__
+
+- Fixed Norwegian and Korean language code
+- Fixed detection of composition events in search interface
+- Fixed search plugin not using title set via front matter
+- Fixed search highlighting of tags
+- Fixed search sharing URL using post transformed string
+- Fixed theme-color meta tag getting out-of-sync with palette toggle
+- Fixed prev/next page keyboard navigation when footer is not present
+- Fixed overflowing navigation tabs not being scrollable
+- Fixed inclusion of code block line numbers from search
+
+---
+
+### 8.5.11 November 30, 2022 { id="8.5.11" }
+
+- Let it snow, see https://x.com/squidfunk/status/1597939243090788352
+
+### 8.5.10 November 11, 2022 { id="8.5.10" }
+
+- Adjusted CSS to better allow for custom primary and accent colors
+- Fixed #4620: Primary color is not applied (8.5.9 regression)
+
+### 8.5.9 November 8, 2022 { id="8.5.9" }
+
+- Fixed #4600: Illegible link colors for black and white primary colors
+- Fixed #4594: Need to set schema to change link color
+
+### 8.5.8 November 3, 2022 { id="8.5.8" }
+
+- Added support for always showing settings in cookie consent
+- Fixed #4571: Buttons invisible if primary color is `white` or `black`
+- Fixed #4517: Illegible note in sequence diagram when using `slate` scheme
+
+### 8.5.7 October 22, 2022 { id="8.5.7" }
+
+- Deprecated additional admonition qualifiers to reduce size of CSS
+- Fixed #4511: Search boost does not apply to sections
+
+### 8.5.6 October 2, 2022 { id="8.5.6" }
+
+- Modernized appearance of admonitions (with fallback, see docs)
+- Improved appearance of inline code blocks in admonition titles
+
+### 8.5.5 October 1, 2022 { id="8.5.5" }
+
+- Updated MkDocs to 1.4
+- Fixed compatibility issues with MkDocs 1.4
+- Fixed #4430: build error when enabling consent without repository URL
+
+### 8.5.4 September 30, 2022 { id="8.5.4" }
+
+- Fixed expand icons shift on sidebar overflow (using `scrollbar-gutter`)
+- Fixed #4429: Text in sequence diagrams overflows in Firefox
+
+### 8.5.3 September 20, 2022 { id="8.5.3" }
+
+- Fixed build error when enabling cookie consent without analytics
+- Fixed #4381: Code blocks render ligatures for some fonts
+
+### 8.5.2 September 18, 2022 { id="8.5.2" }
+
+- Updated Mermaid.js to version 9.1.7
+- Fixed overly large headlines in search results (8.5.0 regression)
+- Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+- Fixed #4356: GitHub repository statistics fetched before cookie consent
+
+### 8.5.1 September 15, 2022 { id="8.5.1" }
+
+- Fixed #4366: Removed dependencies with native extensions
+
+### 8.5.0 September 13, 2022 { id="8.5.0" }
+
+- Added support for social cards
+- Added support for code annotation anchor links (deep linking)
+- Added support for code annotation comment stripping (syntax modifier)
+- Added support for sidebars scrolling automatically to active item
+- Added support for anchor following table of contents (= auto scroll)
+- Added support for tag icons
+
+### 8.4.4 September 12, 2022 { id="8.4.4" }
+
+- Moved comments integration to separate partial (`comments.html`)
+
+### 8.4.3 September 7, 2022 { id="8.4.3" }
+
+- Added Simple Icons to bundled icons (+2,300 icons)
+- Added support for changing edit icon
+- Moved page actions to separate partial (`actions.html`)
+- Fixed #4291: Version switching doesn't stay on page when anchors are used
+- Fixed #4327: Links in data tables do not receive link styling
+
+### 8.4.2 August 27, 2022 { id="8.4.2" }
+
+- Updated Slovenian translations
+- Fixed #4277: Feedback widget hidden after navigation with instant loading
+- Fixed numeric tags in front matter breaking search functionality
+
+### 8.4.1 August 21, 2022 { id="8.4.1" }
+
+- Updated Croatian and Hebrew translations
+
+### 8.4.0 August 13, 2022 { id="8.4.0" }
+
+- Added support for cookie consent
+- Added support for feedback widget (Was this page helpful?)
+- Added support for dismissible announcement bar
+- Added Armenian, Lithuanian, Tagalog, and Urdu translations
+
+### 8.3.9 July 4, 2022 { id="8.3.9" }
+
+- Updated Taiwanese translations for search
+- Allow ids for content tabs with special characters (for mkdocstrings)
+- Fixed #4083: home not clickable when using versioning (8.3.5 regression)
+
+### 8.3.8 June 24, 2022 { id="8.3.8" }
+
+- Fixed #4053: Limit width of videos to content area
+- Fixed empty tags in front matter breaking search
+
+### 8.3.7 June 22, 2022 { id="8.3.7" }
+
+- Fixed search being stuck initializing when using tags (8.3.4 regression)
+
+### 8.3.6 June 16, 2022 { id="8.3.6" }
+
+- Fixed #4028: Links not clickable when using versioning (8.3.5 regression)
+
+### 8.3.5 June 14, 2022 { id="8.3.5" }
+
+- Fixed #4012: Stay on page not working for alias of active version
+
+### 8.3.4 June 11, 2022 { id="8.3.4" }
+
+- Fixed #4004: Tags with multiple words not searchable
+
+### 8.3.3 June 7, 2022 { id="8.3.3" }
+
+- Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression)
+
+### 8.3.2 June 5, 2022 { id="8.3.2" }
+
+- Fixed #3987: Custom admonition icons don't work when defining color palette
+
+### 8.3.1 June 4, 2022 { id="8.3.1" }
+
+- Bump required Jinja version to 3.0.2
+- Removed unnecessary conditions in templates
+- Fixed scroll offset when content tabs are brought into view
+- Fixed #3977: Content tabs snapping oddly in Firefox
+- Fixed #3983: Missing condition in footer partial (8.3.0 regression)
+
+### 8.3.0 June 2, 2022 { id="8.3.0" }
+
+- Added support for custom admonition icons
+- Added support for linking of content tabs
+- Added support for boosting pages in search
+- Added support for hiding footer navigation
+- Added previous/next indicators to content tabs
+- Improved typeset link colors in light and dark modes
+
+### 8.2.16 May 28, 2022 { id="8.2.16" }
+
+- Fixed #3957: Only animate code annotations when visible (save CPU cycles)
+
+### 8.2.15 May 14, 2022 { id="8.2.15" }
+
+- Added Uzbek translations
+- Fixed spacing for code block results in content tabs
+
+### 8.2.14 May 8, 2022 { id="8.2.14" }
+
+- Fixed missing top right rounded border on admonition
+- Fixed #3886: `4xx` status codes not handled when using instant loading
+
+### 8.2.13 May 2, 2022 { id="8.2.13" }
+
+- Fixed #3865: Tags index links to tagged pages 404 on Windows
+- Fixed #3866: Bump required Python version from 3.6+ to 3.7+
+
+### 8.2.12 April 30, 2022 { id="8.2.12" }
+
+- Added support for GitHub-style hash fragments for dark/light images
+- Improved rendering of nested code blocks in content tabs and annotations
+- Fixed #3862: Upgraded to latest Pygments and Python Markdown Extensions
+
+### 8.2.11 April 25, 2022 { id="8.2.11" }
+
+- Temporarily pinned Pygments to `<2.12`
+- Temporarily pinned Python Markdown Extensions to `<9.4`
+- Improved rendering of code annotation markers
+
+### 8.2.10 April 24, 2022 { id="8.2.10" }
+
+- Added Macedonian translations
+- Updated Mermaid.js to version 9.0.1
+- Switched sidebar title in mobile navigation to bold font
+- Fixed color of arrows in class and state diagrams for dark mode
+- Fixed #3836: Inline admonitions overlayed by code block titles
+
+### 8.2.9 April 8, 2022 { id="8.2.9" }
+
+- Mitigate flicker on color palette switch by disabling all transitions
+- Fixed search suggestions not triggered when following deep link
+- Fixed incorrectly computed header height when using instant loading
+- Fixed #3782: Admonition titles have extra pixels on wide screens in Firefox
+- Fixed #3802: Always render table of contents container (except when hidden)
+
+### 8.2.8 March 27, 2022 { id="8.2.8" }
+
+- Bumped MkDocs version to 1.3.0 to mitigate breaking changes in Jinja
+- Reverted Jinja version range limitation (added in 8.2.7)
+- Improved styling of annotations and fixed borders of code blocks in tabs
+- Added background color to code blocks in focused/hovered links
+- Added check in tags plugin whether tags overview page exists
+- Fixed #3744: Content tab indicator on wrong position when using back button
+
+### 8.2.7 March 24, 2022 { id="8.2.7" }
+
+- Temporarily limit Jinja version range to < 3.1 due to breaking changes
+
+### 8.2.6 March 23, 2022 { id="8.2.6" }
+
+- Fixed #3695: Deprecation warning for unescaped backslashes in templates
+- Fixed #3696: Annotations not mounted in some Terraform code blocks
+- Fixed #3698: Annotations not mounted in long code blocks (8.2.5 regression)
+
+### 8.2.5 March 6, 2022 { id="8.2.5" }
+
+- Fixed #3596: Mermaid not working when headline with name 'Mermaid' present
+- Fixed #3643: Reduce time to render pages with thousands of code blocks
+- Fixed #3665: Missing styles for Mermaid.js flowcharts cluster labels
+
+### 8.2.4 March 2, 2022 { id="8.2.4" }
+
+- Fixed malformed Google Fonts URL when a font setting was omitted
+- Fixed #3648: Fixed specificity issue with admonitions in lists
+- Fixed #3653: Invalid outdated version banner URL when using instant loading
+
+### 8.2.3 February 27, 2022 { id="8.2.3" }
+
+- Fixed #3578: Active element in table of contents off-by-one on large screens
+
+### 8.2.2 February 26, 2022 { id="8.2.2" }
+
+- Added automatic removal of query parameter when search is closed
+- Fixed #3599: Anchors always overridden when using navigation tracking
+
+### 8.2.1 February 17, 2022 { id="8.2.1" }
+
+- Fixed module `material.plugins` not being found (8.2.0 regression)
+
+### 8.2.0 February 17, 2022 { id="8.2.0" }
+
+- Added native support for Mermaid.js diagrams
+- Added native support for tags (with search integration)
+- Added support for staying on page when switching versions
+
+### 8.1.11 February 10, 2022 { id="8.1.11" }
+
+- Added Portuguese (Brasilian) translations
+- Updated FontAwesome to v6 – [check which icons were renamed here]
+- Fixed #3545: Color palette toggle and search overlaying version selector
+
+ [check which icons were renamed here]: https://fontawesome.com/docs/web/setup/upgrade/whats-changed#icons-renamed-in-version-6
+
+### 8.1.10 February 6, 2022 { id="8.1.10" }
+
+- Fixed cutoff of very wide logos in the sidebar on mobile
+
+### 8.1.9 January 30, 2022 { id="8.1.9" }
+
+- [Added support for `mkdocs.yml` validation and auto-complete][validation]
+- Fixed errors in Latvian translations
+
+ [validation]: ../creating-your-site.md#minimal-configuration
+
+### 8.1.8 January 23, 2022 { id="8.1.8" }
+
+- Added Latvian translations
+- Updated Giscus example integration with dynamic theme change support
+- Fixed #3479: Back-to-top button not hidden when using sticky navigation tabs
+- Fixed #3491: Logo in header and drawer doesn't honor aspect ratio
+
+### 8.1.7 January 16, 2022 { id="8.1.7" }
+
+- Improved back-to-top button behavior - now not shown on anchor jump
+
+### 8.1.6 January 11, 2022 { id="8.1.6" }
+
+- Fixed spacing of blockquotes (8.1.5 regression)
+- Fixed edge cases for rounded corners on code blocks (8.1.5 regression)
+- Fixed issues with code annotation line heights
+
+### 8.1.5 January 9, 2022 { id="8.1.5" }
+
+- Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+
+- Improved rendering of inline code blocks in headlines
+- Added Bahasa Malaysian translations
+- Fixed #3354: MathJax formulas show vertical scrollbar
+
+### 8.1.4 January 2, 2022 { id="8.1.4" }
+
+- Added indicator to navigation expander icon
+- Improved support for reduced motion preference
+- Fixed jitter of active content tab indicator
+
+### 8.1.3 December 19, 2021 { id="8.1.3" }
+
+- Added animation to active content tab indicator
+- Fixed #3360: Highlighted lines add blank lines in copied text
+- Fixed usage of subsequent index files when using section index pages
+
+### 8.1.2 December 15, 2021 { id="8.1.2" }
+
+- Switched CSS sources to logical properties
+- Added transformation of logical properties to `ltr`/`rtl` equivalents
+- Fixed spacing for admonitions inside lists (8.1.1 regression)
+
+### 8.1.1 December 13, 2021 { id="8.1.1" }
+
+- Added support for `#only-light` and `#only-dark` image hash fragments
+- Fixed copy-to-clipboard adding blank lines when using line anchors
+- Fixed code annotation directionality for right-to-left languages
+- Fixed header title positioning for right-to-left languages
+- Fixed admonition borders for right-to-left languages (8.0.0 regression)
+- Fixed footer navigation link positioning (8.0.0 regression)
+- Fixed footer navigation title breaking out of container when too long
+- Fixed shrinking arrow in navigation title when too long
+- Fixed #3343: Filtered stopwords appear as missing search terms
+- Fixed #3346: Site unusable due to usage of `:not()` (Firefox 78 ESR)
+
+### 8.1.0 December 10, 2021 { id="8.1.0" }
+
+- Added basic support for code block line anchors
+- Switched code annotation markers to `+` signs to improve usability
+- Switched main site title to bold font
+- Improved admonition icon positioning to align when `font-size` is increased
+- Improved and simplified footnotes CSS
+- Improved and simplified code annotation positioning
+- Fixed syntax error in Russian translations
+
+### 8.0.5 December 6, 2021 { id="8.0.5" }
+
+- Fixed #3302: Footer refactoring induced ellipsis in some browsers
+- Fixed #3313: Details always rendered closed on load (8.0.4 regression)
+
+### 8.0.4 December 4, 2021 { id="8.0.4" }
+
+- Improved support for deeply nested code annotations
+- Improved code annotation and copy-to-clipboard interop
+- Improved styling for code annotations inside admonitions
+- Fixed #3274: Invalid anchor positioning when using instant loading
+- Fixed #3294: Lists after code blocks without code annotations disappearing
+- Fixed several positioning issues for code annotations
+- Fixed JavaScript source map roots
+
+### 8.0.3 December 2, 2021 { id="8.0.3" }
+
+- Removed deprecated `google_analytics` setting (was forgotten in 8.0.0)
+- Fixed syntax error in Swedish and Polish translations
+- Fixed #3283: Invalid back-to-top button position with sticky navigation tabs
+- Fixed #3285: Default details marker showing due to Safari bug
+
+### 8.0.2 November 30, 2021 { id="8.0.2" }
+
+- Fixed #3275: Code annotations always disappear on click
+
+### 8.0.1 November 28, 2021 { id="8.0.1" }
+
+- Improved rendering of code annotation markers
+- Fixed #3265: Wrong margin on nested admonitions
+- Fixed wrong `box-sizing` for code annotations in details
+
+### 8.0.0 November 28, 2021 { id="8.0.0" }
+
+- Added support for code annotations
+- Added support for anchor tracking
+- Added support for version warning
+- Added `copyright` partial for easier override
+- Removed deprecated content tabs legacy implementation
+- Removed deprecated `seealso` admonition type
+- Removed deprecated `site_keywords` setting (unsupported by MkDocs)
+- Removed deprecated prebuilt search index support
+- Removed deprecated web app manifest – use customization
+- Removed `extracopyright` variable – use new `copyright` partial
+- Removed Disqus integration – use customization
+- Switched to `:is()` selectors for simple selector lists
+- Switched autoprefixer from `last 4 years` to `last 2 years`
+- Improved CSS overall to match modern standards
+- Improved CSS variable semantics for fonts
+- Improved extensibility by restructuring partials
+- Improved handling of `details` when printing
+- Improved keyboard navigation for footnotes
+- Fixed #3214: Search highlighting breaks site when empty
+
+---
+
+### 7.3.6 October 30, 2021 { id="7.3.6" }
+
+- Added support for adding titles to code blocks
+
+### 7.3.5 October 27, 2021 { id="7.3.5" }
+
+- Added support for setting table of contents title via `mkdocs.yml`
+- Fixed back-to-top button position for right-to-left languages
+
+### 7.3.4 October 17, 2021 { id="7.3.4" }
+
+- Bumped MkDocs version to 1.2.3 to mitigate [CVE-2021-40978]
+- Fixed spacing issues when using integrate table of contents with tabs
+- Fixed some spacings issues for right-to-left languages
+- Fixed race condition in search initialization
+
+ [CVE-2021-40978]: https://nvd.nist.gov/vuln/detail/CVE-2021-40978
+
+### 7.3.3 October 11, 2021 { id="7.3.3" }
+
+- Rewrite of entire documentation
+- Adjusted height of new content tabs to match single line code blocks
+- Fixed new content tabs missing right padding in some browsers on overflow
+- Fixed new content tabs bleeding out of flex container on overflow
+- Fixed new content tabs overflow scrolling bugs on some browsers
+- Fixed new content tabs stealing keyboard access when active
+- Fixed some spacings issues for right-to-left languages
+
+### 7.3.2 October 6, 2021 { id="7.3.2" }
+
+- Deprecated prebuilding of search index
+- Improved graceful handling of broken search for `file://`
+- Added minimum Jinja version to list of requirements
+- Fixed #3071: Section index pages render empty directories
+- Fixed margin issues when using navigation tabs (7.3.1 regression)
+- Fixed search placeholder sometimes being shown too early
+
+### 7.3.1 October 2, 2021 { id="7.3.1" }
+
+- Added new experimental content tabs implementation
+- Fixed #3069: GitHub stats broken for users/orgs (7.1.0 regression)
+- Fixed #3070: Sections not linking to index page
+- Fixed title not linking to index page when using tabs
+- Fixed Disqus integration when using instant loading
+- Fixed some spacing issues for right-to-left languages
+- Fixed syntax error in Serbian translations
+
+### 7.3.0 September 23, 2021 { id="7.3.0" }
+
+- Added support for sticky navigation tabs
+- Added support for section index pages
+- Added support for removing generator notice
+
+### 7.2.8 September 20, 2021 { id="7.2.8" }
+
+- Fixed #3039: Search modal overlays menu on mobile (7.2.7 regression)
+
+### 7.2.7 September 19, 2021 { id="7.2.7" }
+
+- Updated Serbian and Serbo-Croatian translations
+- Improved appearance of outline on details
+- Fixed #2934: Scrollbar when header is hidden on some mobile browsers
+- Fixed #3032: Anchor in details doesn't open on load (7.0.0 regression)
+- Fixed back-to-top button being focusable when invisible
+- Fixed broken admonition icons (removed in upstream)
+
+### 7.2.6 September 1, 2021 { id="7.2.6" }
+
+- Fixed rendering of `blockquote` elements (7.0.0 regression)
+- Fixed #2973: Custom search worker setting ignored
+
+### 7.2.5 August 25, 2021 { id="7.2.5" }
+
+- Updated Portuguese translations
+- Fixed execution of RxJS teardown logic (7.2.3 regression)
+- Fixed #2970: Search results show escaped characters (7.2.2 regression)
+
+### 7.2.4 August 11, 2021 { id="7.2.4" }
+
+- Fixed #2926: Version selector not working (7.2.3 regression)
+- Fixed #2929: Missing CSS class for banner (consistency with Insiders)
+
+### 7.2.3 August 9, 2021 { id="7.2.3" }
+
+- Slight facelift of data tables, now closer to Material Design
+- Fixed instant loading not respecting clicks on search results
+- Fixed #2881: Invalid anchor offsets when using instant loading
+
+### 7.2.2 July 31, 2021 { id="7.2.2" }
+
+- Updated Korean translations
+- Fixed #2879: Search highlighting does not properly escape HTML
+
+### 7.2.1 July 25, 2021 { id="7.2.1" }
+
+- Fixed #2862: Back-to-top button overlays active search bar
+
+### 7.2.0 July 21, 2021 { id="7.2.0" }
+
+- Added support for search suggestions to save keystrokes
+- Added support for search highlighting
+- Added support for search sharing (i.e. deep linking)
+
+### 7.1.11 July 18, 2021 { id="7.1.11" }
+
+- Updated Spanish and Galician translations
+
+### 7.1.10 July 10, 2021 { id="7.1.10" }
+
+- Refactored appearance of back-to-top button
+- Fixed graceful handling of search when browsing locally
+
+### 7.1.9 June 25, 2021 { id="7.1.9" }
+
+- Improved search language support for Thai and Hindi
+- Fixed #2761: License comments lined up at end of file
+
+### 7.1.8 June 12, 2021 { id="7.1.8" }
+
+- Refactored analytics integration (because of MkDocs 1.2)
+- Added support for Google Analytics 4 (`gtag.js`)
+- Fixed missing escape for `aria-label` in footer links
+
+### 7.1.7 June 6, 2021 { id="7.1.7" }
+
+- Improved screen reader support
+
+### 7.1.6 May 30, 2021 { id="7.1.6" }
+
+- Deprecated `seealso` admonition qualifier
+- Added Mongolian and updated Chinese translations
+- Fixed #2429: Version selector not touch-friendly on Android devices
+- Fixed #2703: Printed 'Initializing search' albeit ready on mobile
+
+### 7.1.5 May 19, 2021 { id="7.1.5" }
+
+- Fixed #2655: Details breaking page margins on print
+
+### 7.1.4 May 6, 2021 { id="7.1.4" }
+
+- Added support for git-revision-date-localized plugin creation date
+- Improved footnote styles on `:target` and `:focus`
+
+### 7.1.3 April 24, 2021 { id="7.1.3" }
+
+- Fixed #2586: Empty table of contents shown (7.1.2 regression)
+
+### 7.1.2 April 18, 2021 { id="7.1.2" }
+
+- Fixed #2554: List markers sometimes overlap floated elements
+- Fixed #2563: Adding a class to a `h1` breaks the table of contents
+- Fixed #2566: Back-to-top button clickable when invisible
+
+### 7.1.1 April 10, 2021 { id="7.1.1" }
+
+- Fixed #2501: Nested definition lists compound bottom margin
+- Fixed #2508: Switch `extracopyright` block to template variable
+- Fixed #2533: Search (and other parts) not working in Safari <14
+- Fixed #2538: Visual quirk when opening language selector
+
+### 7.1.0 March 29, 2021 { id="7.1.0" }
+
+- Added support for back-to-top button
+- Added support for color palette toggle
+- Added latest release to repository info (GitHub)
+- Slight facelift of repository info (lighter fonts, spacing and icons)
+
+### 7.0.7 March 28, 2021 { id="7.0.7" }
+
+- Updated Hungarian translations
+- Fixed #2466: Docker image not based on latest Python and Alpine
+- Fixed #2488: Inconsistent header shadow behavior
+- Fixed #2492: Inline code blocks in admonition titles missing background
+
+### 7.0.6 March 14, 2021 { id="7.0.6" }
+
+- Added trailing slash to version selector URL
+- Added support for out-of-order anchors in table of contents
+- Added `extra.homepage` option to link logo to arbitrary URL
+- Improved security of Docker image (always update apk)
+- Fixed horizontal spacing for nested inline admonitions
+- Fixed text color of nested code blocks inside links
+- Fixed version selector to always use version title
+- Fixed logo link when using versioning with instant loading
+
+### 7.0.5 March 7, 2021 { id="7.0.5" }
+
+- Added `extracopyright` block to allow for custom copyright info
+- Fixed evaluation of third-party scripts when using instant loading
+- Fixed edge cases when using instant loading without directory URLs
+- Fixed handling of version selector when using instant loading
+- Fixed regression with header title not being updated correctly
+- Fixed expanded sections not opening on first click (7.0.4 regression)
+
+### 7.0.4 March 4, 2021 { id="7.0.4" }
+
+- Added Icelandic translations
+- Fixed #2386: Section close requires two clicks (navigation expansion)
+- Fixed console error when search is disabled (7.0.0 regression)
+- Fixed localsearch integration (7.0.0 regression)
+
+### 7.0.3 February 26, 2021 { id="7.0.3" }
+
+- Fixed JavaScript errors in older browsers (target ES2020 -> ES2015)
+
+### 7.0.2 February 25, 2021 { id="7.0.2" }
+
+- Fixed #2343: Invalid source map URLs for JS and CSS files
+- Fixed #2347: Version selector missing when using versioning
+
+### 7.0.1 February 24, 2021 { id="7.0.1" }
+
+- Fixed #2334: Google Analytics triggers page view twice (7.0.0 regression)
+- Fixed #2336: Details bleed into inline admonitions
+- Fixed #2337: Images don't align correctly (7.0.0 regression)
+
+### 7.0.0 February 22, 2021 { id="7.0.0" }
+
+- Added support for deploying multiple versions
+- Added support for integrating a language selector
+- Added support for rendering admonitions as inline blocks
+- Rewrite of the underlying reactive architecture
+- Removed Webpack in favor of reactive build strategy (-480 dependencies)
+- Fixed keyboard navigation for code blocks after content tabs switch
+
+### 6.2.8 February 4, 2021 { id="6.2.8" }
+
+- Updated Japanese and Polish translations
+- Fixed #2261: Print dialog auto-closing when using instant loading
+
+### 6.2.7 January 31, 2021 { id="6.2.7" }
+
+- Fixed #2251: Updated Docker image to latest Alpine Linux
+
+### 6.2.6 January 26, 2021 { id="6.2.6" }
+
+- Added Bulgarian translations
+- Fixed #2233: Search not shown when using header autohiding
+
+### 6.2.5 January 17, 2021 { id="6.2.5" }
+
+- Fixed syntax error in Swedish translations
+- Optimized navigation partials to improve build speed for huge docs
+
+### 6.2.4 January 9, 2021 { id="6.2.4" }
+
+- Fixed #2156: Missing syntax highlighting for binary numbers
+- Fixed #2186: Disqus showing on 404 page
+
+### 6.2.3 December 27, 2020 { id="6.2.3" }
+
+- Added back hidden overflow on root container
+- Fixed #2142: MathJax formulas sometimes have vertical scrollbars
+
+### 6.2.2 December 22, 2020 { id="6.2.2" }
+
+- Removed Markdown version range limit (6.2.0 regression)
+
+### 6.2.1 December 22, 2020 { id="6.2.1" }
+
+- Fixed all import and asset paths in templates (6.2.0 regression)
+- Downgraded webpack-asset-manifest-plugin - broke all asset paths
+
+### 6.2.0 December 22, 2020 { id="6.2.0" }
+
+- Added support for navigation sections
+- Added support for navigation expansion
+- Added support for integrating table of contents into navigation
+- Added support for autohiding header on scroll
+- Added support for hiding navigation and table of contents per page
+- Added support for arbitrary items in navigation tabs
+- Refactored navigation tabs to simplify grouping behavior
+- Fixed anchor offset for permalinks in Safari (partial revert)
+- Fixed #2098: Active tab sometimes not highlighted correctly
+- Improved appearance for horizontal rulers
+- Improved Spanish and Swedish translations
+
+### 6.1.7 December 6, 2020 { id="6.1.7" }
+
+- Fixed #2081: Fixed stats for private GitHub repositories
+- Fixed alignment for admonition icon alignment for right-to-left languages
+
+### 6.1.6 November 22, 2020 { id="6.1.6" }
+
+- Fixed #2048: Math formulas show scrollbars (Windows)
+
+### 6.1.5 November 15, 2020 { id="6.1.5" }
+
+- Fixed search reset button not showing/hiding correctly
+
+### 6.1.4 November 7, 2020 { id="6.1.4" }
+
+- Fixed sidebar jitter when scrolling footer into view
+
+### 6.1.3 November 5, 2020 { id="6.1.3" }
+
+- Added support for keywords `meta` tag
+- Fixed #2027: Line numbers don't scale with smaller font size
+- Fixed link colors for black and white on `slate` color scheme
+- Removed focus outline on scrolling code blocks for pointer devices
+
+### 6.1.2 October 31, 2020 { id="6.1.2" }
+
+- Fixed sizing of icons in admonitions, task lists, etc. (6.1.1 regression)
+
+### 6.1.1 October 31, 2020 { id="6.1.1" }
+
+- Fixed #2019: Page title not correctly updated when using instant loading
+
+### 6.1.0 October 17, 2020 { id="6.1.0" }
+
+- Fixed #1973: Added support for printing in dark mode
+- Fixed #1974: Added support for printing content tabs
+- Fixed #1995: Improved customizability of details extension
+
+### 6.0.2 October 4, 2020 { id="6.0.2" }
+
+- Added Georgian translations
+- Added escaping for link `title` attributes where necessary
+- Fixed #1956: Pages with whitespace in names have invalid links in search
+- Removed unnecessary (duplicated) link `title` attributes
+
+### 6.0.1 September 26, 2020 { id="6.0.1" }
+
+- Fixed stemmer support for `file://` protocol through `iframe-worker`
+- Fixed details marker showing for search result in Firefox
+- Fixed tabbing behavior when search query is not empty
+- Switched TypeScript compilation target to ES2015
+- Reduced size of JavaScript by 30% (`176kb` → `124kb`)
+- Removed `mkdocs` and `readthedocs` themes from Docker image
+
+### 6.0.0 September 25, 2020 { id="6.0.0" }
+
+- Improved search result look and feel
+- Improved search result stability while typing
+- Improved search result grouping (pages + headings)
+- Improved search result relevance and scoring
+- Added display of missing query terms to search results
+- Reduced size of vendor bundle by 25% (`84kb` → `67kb`)
+- Reduced size of the Docker image to improve CI build performance
+- Removed hero partial in favor of custom implementation
+- Removed deprecated front matter features
+
+---
+
+### 5.5.14 September 23, 2020 { id="5.5.14" }
+
+- Improved spacing around image captions
+- Fixed #1939: Long tables cause header overlap in print view
+
+### 5.5.13 September 19, 2020 { id="5.5.13" }
+
+- Improved abbreviations on touch devices
+
+### 5.5.12 August 31, 2020 { id="5.5.12" }
+
+- Fixed #1638: occasional `404` for images when using instant loading
+
+### 5.5.11 August 28, 2020 { id="5.5.11" }
+
+- Fixed Disqus integration, as the minifier killed the config
+
+### 5.5.10 August 28, 2020 { id="5.5.10" }
+
+- Improved rendering by moving Disqus integration after page load
+- Fixed #1887: Moved navigation icons to CSS to reduce size of HTML
+
+### 5.5.9 August 26, 2020 { id="5.5.9" }
+
+- Added Esperanto translations
+- Fixed #1884: External links not included in navigation tabs
+
+### 5.5.8 August 23, 2020 { id="5.5.8" }
+
+- Removed focus outline on `details` and content tabs for pointer devices
+- Improved accessibility of content tabs (now navigable via arrow keys)
+- Fixed #1877: `404` on search index when search is disabled
+- Fixed some memleaks in observable subscriptions
+- Fixed color definitions for `theme-color` meta tag
+
+### 5.5.7 August 16, 2020 { id="5.5.7" }
+
+- Improved contrast ratio to 4.5:1 for syntax highlighting
+- Improved contrast ratio to 4.5:1 for table of contents
+
+### 5.5.6 August 12, 2020 { id="5.5.6" }
+
+- Switched base template for `404.html` to `main.html`
+- Fixed #1864: GitHub organisation stats not loading
+
+### 5.5.5 August 11, 2020 { id="5.5.5" }
+
+- Fixed missing vendor and worker distribution files
+
+### 5.5.4 August 11, 2020 { id="5.5.4" }
+
+- Added support for sortable data tables
+
+### 5.5.3 August 4, 2020 { id="5.5.3" }
+
+- Fixed search for languages other than English (5.5.1 regression)
+
+### 5.5.2 August 3, 2020 { id="5.5.2" }
+
+- Improved highlight colors and spacing for `ins`, `del` and `mark`
+- Changed some keyboard symbols for better equivalents
+- Removed focus `outline` for details and code blocks on touch devices
+- Fixed margins for admonitions (5.5.1 regression)
+- Fixed too small content tab labels (5.5.1 regression)
+- Fixed icon repeating for custom admonition icons
+
+### 5.5.1 August 1, 2020 { id="5.5.1" }
+
+- Improved typesetting by basing `font-size` and spacings on `em`
+- Improved print view by slightly scaling down `font-size`
+- Changed custom site title (metadata) to be suffixed with site name
+- Fixed top- and bottom spacing of paragraphs inside table cells
+
+### 5.5.0 July 24, 2020 { id="5.5.0" }
+
+- Rewrite of entire documentation
+- Rewrite of syntax highlighting to be customizable with CSS variables
+- Improved syntax highlighting to work with light and dark theme
+- Improved `slate` color scheme to be more customizable and easier on the eyes
+- Added licenses of icon sets to distribution files
+- Fixed stale document titles in Google Analytics when using instant loading
+- Fixed width of previous and next footer links for tablet and above
+- Fixed issues with top scroll margin for footnotes
+- Fixed top margin for tabbed content when using a JavaScript highlighter
+- Deprecated metadata-based redirects, source links and heroes
+
+### 5.4.0 June 29, 2020 { id="5.4.0" }
+
+- Added support to wrap searches in quotes to switch from `OR` to `AND`
+- Fixed highlighting of numbers in search results
+
+### 5.3.3 June 24, 2020 { id="5.3.3" }
+
+- Added Bengali translations
+- Fixed #1773: Search for numbers does not return any result (regression)
+
+### 5.3.2 June 21, 2020 { id="5.3.2" }
+
+- Improved search typeahead experience with non-Latin characters
+- Fixed #1753: Japanese search doesn't work anymore
+
+### 5.3.1 June 20, 2020 { id="5.3.1" }
+
+- Fixed #1761: Duplication of search worker when subscribing to observable
+
+### 5.3.0 June 15, 2020 { id="5.3.0" }
+
+- Added support for color schemes based on user preference
+- Fixed #1755: Tokenizer separator setting ignored
+
+### 5.2.3 June 6, 2020 { id="5.2.3" }
+
+- Improved search typeahead behavior for some languages (`de`, `fr`, ...)
+- Improved styles for scrollbars on Firefox
+- Fixed #1741: Removed `preconnect` hint for Google Analytics
+
+### 5.2.2 May 26, 2020 { id="5.2.2" }
+
+- Fixed #1728: Legacy Edge doesn't support `deg` values in `hsla` colors
+
+### 5.2.1 May 22, 2020 { id="5.2.1" }
+
+- Fixed color of links in table headers, e.g. footnotes
+- Fixed color scheme not being applied without primary or accent color
+- Fixed hover delay for links inside code blocks
+
+### 5.2.0 May 18, 2020 { id="5.2.0" }
+
+- Added color schemes implementation + dark mode
+- Fixed #1583: Missing option for separate link colors
+
+### 5.1.7 May 16, 2020 { id="5.1.7" }
+
+- Added keyboard focus support for overflowing code blocks
+- Fixed #1696: Infinite loop in some cases when using instant loading
+
+### 5.1.6 May 9, 2020 { id="5.1.6" }
+
+- Added Burmese translations
+- Added general anchor offset solution using `scroll-margin-top`
+- Fixed #1653: Instant loading shouldn't intercept links to `*.html` files
+
+### 5.1.5 May 3, 2020 { id="5.1.5" }
+
+- Added `name` attribute for social links to set link `title`
+- Fixed #1623: Allow arbitrary links in social links
+- Fixed #1664: Height of `iframe` is not adjustable
+- Fixed #1667: Sidebars are scrolled to bottom on load (bug in Chrome 81+)
+
+### 5.1.4 April 30, 2020 { id="5.1.4" }
+
+- Switched to [@mdi/svg] Material Design icon package
+- Fixed #1655: Navigation may disappear after switching viewports
+- Fixed #1659: Unnecessary scrollbar for search results on Windows
+- Fixed occasional distortions for images with explicit dimensions
+- Fixed errors in German translations
+
+ [@mdi/svg]: https://github.com/Templarian/MaterialDesign-SVG
+
+### 5.1.3 April 26, 2020 { id="5.1.3" }
+
+- Fixed overflowing content area after switch to flexbox
+
+### 5.1.2 April 26, 2020 { id="5.1.2" }
+
+- Added status information to search observable
+- Added status information to search modal
+- Removed announcement bar from print media
+- Removed media query packing logic due to race conditions
+- Fixed #1520: Gracefully disable search on `file://` if Worker fails
+- Fixed re-submission of query after search is initialized
+- Fixed jitter of sidebars on all browsers by switching to `sticky`
+
+### 5.1.1 April 17, 2020 { id="5.1.1" }
+
+- Added new FontAwesome icons
+- Fixed #1609: Instant loading doesn't honor `target=_blank`
+- Fixed GitHub stars count rounding errors
+- Fixed GitLab stars count retrieval
+
+### 5.1.0 April 12, 2020 { id="5.1.0" }
+
+- Added support for icons from Markdown through [mkdocs-material-extensions]
+
+ [mkdocs-material-extensions]: https://github.com/facelessuser/mkdocs-material-extensions
+
+### 5.0.2 April 10, 2020 { id="5.0.2" }
+
+- Added CSS source maps to distribution files
+- Fixed errors in Chinese (Traditional) translations
+- Fixed creation of stale directory on installation from git
+- Improved overflow scrolling behavior on iOS (reduced bundle size by `4kb`)
+
+### 5.0.1 April 7, 2020 { id="5.0.1" }
+
+- Fixed syntax error in Spanish translation
+
+### 5.0.0 April 7, 2020 { id="5.0.0" }
+
+- Reactive architecture – try `app.dialog$.next("Hi!")` in the console
+- Instant loading – make Material behave like a Single Page Application
+- Improved CSS customization with CSS variables – set your brand's colors
+- Improved CSS resilience, e.g. proper sidebar locking for customized headers
+- Improved icon integration and configuration – now including over 5k icons
+- Added possibility to use any icon for logo, repository and social links
+- Search UI does not freeze anymore (moved to web worker)
+- Search index built only once when using instant loading
+- Improved extensible keyboard handling
+- Support for prebuilt search indexes
+- Support for displaying stars and forks for GitLab repositories
+- Support for scroll snapping of sidebars and search results
+- Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
+- Slight facelifting of some UI elements (admonitions, tables, ...)
+
+### 4.6.3 February 14, 2020 { id="4.6.3" }
+
+- Removed optional third-party plugins from `requirements.txt`
+- Updated Docker image to contain all supported third-party plugins
+
+### 4.6.2 February 8, 2020 { id="4.6.2" }
+
+- Added Romanian translations
+- Fixed #1451: Inconsistent spacing for fenced code blocks
+
+### 4.6.1 February 8, 2020 { id="4.6.1" }
+
+- Fixed #1324: Metadata author only rendering first character
+- Fixed #1393: Set `tabindex` to `0` for skip to content link
+- Fixed code blocks after Markdown 3.2 release
+- Fixed errors in Japanese translations
+- Improved Google Lighthouse score
+
+### 4.6.0 December 11, 2019 { id="4.6.0" }
+
+- Added support for [git-revision-date-localized-plugin]
+- Fixed invalid character in Google Fonts URL
+
+ [git-revision-date-localized-plugin]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+
+### 4.5.1 December 2, 2019 { id="4.5.1" }
+
+- Added Thai translations
+- Fixed missing assets in GitHub release `.zip` and `.tar.gz`
+
+### 4.5.0 November 16, 2019 { id="4.5.0" }
+
+- Fixed #1330: Upgraded EmojiOne to Tweomji due to licensing issues
+- Fixed #1339: Temporarily pinned PyMdown and Markdown due to
+- Fixed errors in Greek translations
+- Improved GitHub statistics retrieval
+
+### 4.4.3 October 3, 2019 { id="4.4.3" }
+
+- Added Estonian translations
+- Fixed removal of copyright banners in minified JavaScript
+- Removed unnecessary title attributes from links in table of contents
+
+### 4.4.2 August 27, 2019 { id="4.4.2" }
+
+- Added Afrikaans translations
+- Fixed broken page title when `h1` contained HTML tags
+- Improved accessibility for IE users
+- Removed unnecessary `title` attributes from links in navigation
+
+### 4.4.1 August 22, 2019 { id="4.4.1" }
+
+- Added support for `black` as a primary color
+- Fixed broken footer bar when `h1` contained HTML tags
+
+### 4.4.0 June 15, 2019 { id="4.4.0" }
+
+- Added Slovenian translations
+- Reverted template minification in favor of `mkdocs-minify-plugin`
+- Fixed #1114: Tabs don't reappear when default `font-size` is smaller than `16`
+
+### 4.3.1 May 23, 2019 { id="4.3.1" }
+
+- Fixed spelling error in Danish translations
+
+### 4.3.0 May 17, 2019 { id="4.3.0" }
+
+- Added support for changing header through metadata title property
+- Added `font-display: swap` to Google Font loading logic
+- Removed whitespace from templates, saving `4kb` (`.7kb` gzipped) per request
+- Fixed alignment of repository icons on tablet and desktop
+
+### 4.2.0 April 28, 2019 { id="4.2.0" }
+
+- Added Norwegian (Nynorsk) translations
+- Fixed loss of focus in non-form input elements due to search hotkeys
+- Fixed #1067: Search hotkeys not working for mobile/tablet screensize
+- Fixed #1068: Search not correctly aligned for tablet screensize
+
+### 4.1.2 April 16, 2019 { id="4.1.2" }
+
+- Fixed #1072: HTML tags appearing in navigation link titles
+
+### 4.1.1 March 28, 2019 { id="4.1.1" }
+
+- Fixed minor CSS errors detected during validation
+
+### 4.1.0 March 22, 2019 { id="4.1.0" }
+
+- Fixed #1023: Search for Asian languages broken after Lunr.js update
+- Fixed #1026: contenteditable elements loose focus on hotkeys
+
+### 4.0.2 March 1, 2019 { id="4.0.2" }
+
+- Fixed #1012: HTML character entities appear in search result titles
+
+### 4.0.1 February 13, 2019 { id="4.0.1" }
+
+- Fixed #762, #816: Glitch in sidebar when collapsing items
+- Fixed #869: Automatically expand details before printing
+
+### 4.0.0 February 13, 2019 { id="4.0.0" }
+
+- Added background on hover for table rows
+- Removed Google Tag Manager and reverted to Google Analytics
+- Removed blocks in partials - Jinja doesn't support them
+- Fixed #911: Chrome breaks layout if system language is Chinese (**BREAKING**)
+- Fixed #976: Removed FastClick
+
+---
+
+### 3.3.0 January 29, 2019 { id="3.3.0" }
+
+- Moved Google Analytics integration into `head` using Google Tag Manager
+- Fixed #972: Unicode slugifier breaks table of contents blur on scroll
+- Fixed #974: Additional links in table of contents break blur on scroll
+
+### 3.2.0 December 28, 2018 { id="3.2.0" }
+
+- Added support for redirects using metadata refresh
+- Fixed #921: Load Google Analytics snippet asynchronously
+
+### 3.1.0 November 17, 2018 { id="3.1.0" }
+
+- Added support for Progressive Web App Manifest
+- Fixed #915: Search bug in Safari (upgraded Lunr.js)
+
+### 3.0.6 October 26, 2018 { id="3.0.6" }
+
+- Added Taiwanese translations
+- Fixed #906: JavaScript code blocks evaluated in search results
+
+### 3.0.5 October 23, 2018 { id="3.0.5" }
+
+- Added Croatian and Indonesian translations
+- Fixed #899: Skip-to-content link invalid from 2nd level on
+- Fixed #902: Missing URL filter in footer for FontAwesome link
+
+### 3.0.4 September 3, 2018 { id="3.0.4" }
+
+- Updated Dutch translations
+- Fixed #856: Removed preconnect meta tag if Google Fonts are disabled
+
+### 3.0.3 August 7, 2018 { id="3.0.3" }
+
+- Fixed #841: Additional path levels for extra CSS and JS
+
+### 3.0.2 August 6, 2018 { id="3.0.2" }
+
+- Fixed #839: Lunr.js stemmer imports incorrect
+
+### 3.0.1 August 5, 2018 { id="3.0.1" }
+
+- Fixed #838: Search result links incorrect
+
+### 3.0.0 August 5, 2018 { id="3.0.0" }
+
+- Upgraded MkDocs to 1.0 (**BREAKING**)
+- Upgraded Python in official Docker image to 3.6
+- Added Serbian and Serbo-Croatian translations
+
+---
+
+### 2.9.4 July 29, 2018 { id="2.9.4" }
+
+- Fixed build error after MkDocs upgrade
+
+### 2.9.3 July 29, 2018 { id="2.9.3" }
+
+- Added link to home for logo in drawer
+- Fixed dependency problems between MkDocs and Tornado
+
+### 2.9.2 June 29, 2018 { id="2.9.2" }
+
+- Added Hindi and Czech translations
+
+### 2.9.1 June 18, 2018 { id="2.9.1" }
+
+- Added support for different spellings for theme color
+- Fixed #799: Added support for webfont minification in production
+- Fixed #800: Added `.highlighttable` as an alias for `.codehilitetable`
+
+### 2.9.0 June 13, 2018 { id="2.9.0" }
+
+- Added support for theme color on Android
+- Fixed #796: Rendering of nested tabbed code blocks
+
+### 2.8.0 June 10, 2018 { id="2.8.0" }
+
+- Added support for grouping code blocks with tabs
+- Added Material and FontAwesome icon fonts to distribution files (GDPR)
+- Added note on compliance with GDPR
+- Added Slovak translations
+- Fixed #790: Prefixed `id` attributes with `__` to avoid name clashes
+
+### 2.7.3 April 26, 2018 { id="2.7.3" }
+
+- Added Finnish translations
+
+### 2.7.2 April 9, 2018 { id="2.7.2" }
+
+- Fixed rendering issue for `details` on Edge
+
+### 2.7.1 March 21, 2018 { id="2.7.1" }
+
+- Added Galician translations
+- Fixed #730: Scroll chasing error on home page if Disqus is enabled
+- Fixed #736: Reset drawer and search upon back button invocation
+
+### 2.7.0 March 6, 2018 { id="2.7.0" }
+
+- Added ability to set absolute URL for logo
+- Added Hebrew translations
+
+### 2.6.6 February 22, 2018 { id="2.6.6" }
+
+- Added preconnect for Google Fonts for faster loading
+- Fixed #710: With tabs sidebar disappears if JavaScript is not available
+
+### 2.6.5 February 22, 2018 { id="2.6.5" }
+
+- Reverted `--dev-addr` flag removal from `Dockerfile`
+
+### 2.6.4 February 21, 2018 { id="2.6.4" }
+
+- Added Catalan translations
+- Fixed incorrect margins for buttons in Firefox and Safari
+- Replaced package manager `yarn` with `npm 5.6`
+- Reverted GitHub stars rounding method
+- Removed `--dev-addr` flag from `Dockerfile` for Windows compatibility
+
+### 2.6.3 February 18, 2018 { id="2.6.3" }
+
+- Added Vietnamese translations
+
+### 2.6.2 February 12, 2018 { id="2.6.2" }
+
+- Added Arabic translations
+- Fixed incorrect rounding of amount of GitHub stars
+- Fixed double-layered borders for tables
+
+### 2.6.1 February 11, 2018 { id="2.6.1" }
+
+- Added ability to override Disqus integration using metadata
+- Fixed #690: Duplicate slashes in source file URLs
+- Fixed #696: Active page highlight not working with default palette
+- Adjusted German translations
+
+### 2.6.0 February 2, 2018 { id="2.6.0" }
+
+- Moved default search configuration to default translation (English)
+- Added support to automatically set text direction from translation
+- Added support to disable search stop word filter in translation
+- Added support to disable search trimmer in translation
+- Added Persian translations
+- Fixed support for Polish search
+- Fixed disappearing GitHub, GitLab and Bitbucket repository icons
+
+### 2.5.5 January 31, 2018 { id="2.5.5" }
+
+- Added Hungarian translations
+
+### 2.5.4 January 29, 2018 { id="2.5.4" }
+
+- Fixed #683: `gh-deploy` fails inside Docker
+
+### 2.5.3 January 25, 2018 { id="2.5.3" }
+
+- Added Ukrainian translations
+
+### 2.5.2 January 22, 2018 { id="2.5.2" }
+
+- Added default search language mappings for all localizations
+- Fixed #673: Error loading non-existent search language
+- Fixed #675: Uncaught reference error when search plugin disabled
+
+### 2.5.1 January 20, 2018 { id="2.5.1" }
+
+- Fixed permalink for main headline
+- Improved missing translation handling with English as a fallback
+- Improved accessibility with skip-to-content link
+
+### 2.5.0 January 13, 2018 { id="2.5.0" }
+
+- Added support for right-to-left languages
+
+### 2.4.0 January 11, 2018 { id="2.4.0" }
+
+- Added focus state for clipboard buttons
+- Fixed #400: Search bar steals tab focus
+- Fixed search not closing on ++enter++ when result is selected
+- Fixed search not closing when losing focus due to ++tab++
+- Fixed collapsed navigation links getting focus
+- Fixed `outline` being cut off on ++tab++ focus of navigation links
+- Fixed bug with first search result navigation being ignored
+- Removed search result navigation via ++tab++ (use ++up++ and ++down++)
+- Removed `outline` resets for links
+- Improved general tabbing behavior on desktop
+
+### 2.3.0 January 9, 2018 { id="2.3.0" }
+
+- Added `example` (synonym: `snippet`) style for admonitions
+- Added synonym `abstract` for `summary` style for admonitions
+
+### 2.2.6 December 27, 2017 { id="2.2.6" }
+
+- Added Turkish translations
+- Fixed unclickable area below header in case JavaScript is not available
+
+### 2.2.5 December 18, 2017 { id="2.2.5" }
+
+- Fixed #639: Broken default favicon
+
+### 2.2.4 December 18, 2017 { id="2.2.4" }
+
+- Fixed #638: Build breaks with Jinja < 2.9
+
+### 2.2.3 December 13, 2017 { id="2.2.3" }
+
+- Fixed #630: Admonition sets padding on any last child
+- Adjusted Chinese (Traditional) translations
+
+### 2.2.2 December 8, 2017 { id="2.2.2" }
+
+- Added Dutch translations
+- Adjusted targeted link and footnote offsets
+- Simplified admonition styles and fixed padding bug
+
+### 2.2.1 December 2, 2017 { id="2.2.1" }
+
+- Fixed #616: Minor styling error with title-only admonitions
+- Removed border for table of contents and improved spacing
+
+### 2.2.0 November 22, 2017 { id="2.2.0" }
+
+- Added support for hero teaser
+- Added Portuguese translations
+- Fixed #586: Footnote backref target offset regression
+- Fixed #605: Search stemmers not correctly loaded
+
+### 2.1.1 November 21, 2017 { id="2.1.1" }
+
+- Replaced deprecated `babel-preset-es2015` with `babel-preset-env`
+- Refactored Gulp build pipeline with Webpack
+- Removed right border on sidebars
+- Fixed broken color transition on header
+
+### 2.1.0 November 19, 2017 { id="2.1.0" }
+
+- Added support for `white` as a primary color
+- Added support for sliding site name and title
+- Fixed redundant clipboard button when using line numbers on code blocks
+- Improved header appearance by making it taller
+- Improved tabs appearance
+- Improved CSS customizability by leveraging inheritance
+- Removed scroll shadows via `background-attachment`
+
+### 2.0.4 November 5, 2017 { id="2.0.4" }
+
+- Fixed `details` not opening with footnote reference
+
+### 2.0.3 November 5, 2017 { id="2.0.3" }
+
+- Added Japanese translations
+- Fixed #540: Jumping to anchor inside `details` doesn't open it
+- Fixed active link colors in footer
+
+### 2.0.2 November 1, 2017 { id="2.0.2" }
+
+- Added Russian translations
+- Fixed #542: Horizontal scrollbar between `1220px` and `1234px`
+- Fixed #553: Metadata values only rendering first character
+- Fixed #558: Flash of unstyled content
+- Fixed favicon regression caused by deprecation upstream
+
+### 2.0.1 October 31, 2017 { id="2.0.1" }
+
+- Fixed error when initializing search
+- Fixed styles for link to edit the current page
+- Fixed styles on nested admonition in details
+
+### 2.0.0 October 31, 2017 { id="2.0.0" }
+
+- Upgraded MkDocs to 0.17.1 (__BREAKING__)
+- Added support for easier configuration of search tokenizer
+- Added support to disable search
+- Added Korean translations
+
+---
+
+### 1.12.2 October 26, 2017 { id="1.12.2" }
+
+- Added Italian, Norwegian, French and Chinese translations
+
+### 1.12.1 October 22, 2017 { id="1.12.1" }
+
+- Added Polish, Swedish and Spanish translations
+- Improved downward compatibility with custom partials
+- Temporarily pinned MkDocs version within Docker image to 0.16.3
+- Fixed #519: Missing theme configuration file
+
+### 1.12.0 October 20, 2017 { id="1.12.0" }
+
+- Added support for setting language(s) via `mkdocs.yml`
+- Added support for default localization
+- Added German and Danish translations
+- Fixed #374: Search bar misalignment on big screens
+
+### 1.11.0 October 19, 2017 { id="1.11.0" }
+
+- Added localization to clipboard
+- Refactored localization logic
+
+### 1.10.4 October 18, 2017 { id="1.10.4" }
+
+- Improved print styles of code blocks
+- Improved search UX (don't close on enter if no selection)
+- Fixed #495: Vertical scrollbar on short pages
+
+### 1.10.3 October 11, 2017 { id="1.10.3" }
+
+- Fixed #484: Vertical scrollbar on some MathJax formulas
+- Fixed #483: Footnote backref target offset regression
+
+### 1.10.2 October 6, 2017 { id="1.10.2" }
+
+- Fixed #468: Sidebar shows scrollbar if content is shorter (in Safari)
+
+### 1.10.1 September 14, 2017 { id="1.10.1" }
+
+- Fixed #455: Bold code blocks rendered with normal font weight
+
+### 1.10.0 September 1, 2017 { id="1.10.0" }
+
+- Added support to make logo default icon configurable
+- Fixed uninitialized overflow scrolling on main pane for iOS
+- Fixed error in mobile navigation in case JavaScript is not available
+- Fixed incorrect color transition for nested panes in mobile navigation
+- Improved checkbox styles for Tasklist from PyMdown Extension package
+
+### 1.9.0 August 29, 2017 { id="1.9.0" }
+
+- Added `info` (synonym: `todo`) style for admonitions
+- Added `question` (synonym: `help`, `faq`) style for admonitions
+- Added support for Details from PyMdown Extensions package
+- Improved admonition styles to match details
+- Improved styles for social links in footer
+- Replaced ligatures with Unicode code points to avoid broken layout
+- Upgraded PyMdown Extensions package dependency to >= 3.4
+
+### 1.8.1 August 7, 2017 { id="1.8.1" }
+
+- Fixed #421: Missing pagination for GitHub API
+
+### 1.8.0 August 2, 2017 { id="1.8.0" }
+
+- Added support for lazy-loading of search results for better performance
+- Added support for customization of search tokenizer/separator
+- Fixed #424: Search doesn't handle capital letters anymore
+- Fixed #419: Search doesn't work on whole words
+
+### 1.7.5 July 25, 2017 { id="1.7.5" }
+
+- Fixed #398: Forms broken due to search shortcuts
+- Improved search overall user experience
+- Improved search matching and highlighting
+- Improved search accessibility
+
+### 1.7.4 June 21, 2017 { id="1.7.4" }
+
+- Fixed functional link colors in table of contents for active palette
+- Fixed #368: Compatibility issues with IE11
+
+### 1.7.3 June 7, 2017 { id="1.7.3" }
+
+- Fixed error when setting language to Japanese for site search
+
+### 1.7.2 June 6, 2017 { id="1.7.2" }
+
+- Fixed offset of search box when `repo_url` is not set
+- Fixed non-disappearing tooltip
+
+### 1.7.1 June 1, 2017 { id="1.7.1" }
+
+- Fixed wrong `z-index` order of header, overlay and drawer
+- Fixed wrong offset of targeted footnote back references
+
+### 1.7.0 June 1, 2017 { id="1.7.0" }
+
+- Added "copy to clipboard" buttons to code blocks
+- Added support for multilingual site search
+- Fixed search term highlighting for non-latin languages
+
+### 1.6.4 May 24, 2017 { id="1.6.4" }
+
+- Fixed #337: JavaScript error for GitHub organization URLs
+
+### 1.6.3 May 16, 2017 { id="1.6.3" }
+
+- Fixed #329: Broken source stats for private or unknown GitHub repos
+
+### 1.6.2 May 15, 2017 { id="1.6.2" }
+
+- Fixed #316: Fatal error for git clone on Windows
+- Fixed #320: Chrome 58 creates double underline for `abbr` tags
+- Fixed #323: Ligatures rendered inside code blocks
+- Fixed miscalculated sidebar height due to missing margin collapse
+- Changed deprecated MathJax CDN to Cloudflare
+
+### 1.6.1 April 23, 2017 { id="1.6.1" }
+
+- Fixed following of active/focused element if search input is focused
+- Fixed layer order of search component elements
+
+### 1.6.0 April 22, 2017 { id="1.6.0" }
+
+- Added build test for Docker image on Travis
+- Added search overlay for better user experience (focus)
+- Added language from localizations to `html` tag
+- Fixed #270: source links broken for absolute URLs
+- Fixed missing top spacing for first targeted element in content
+- Fixed too small footnote divider when using larger font sizes
+
+### 1.5.5 April 20, 2017 { id="1.5.5" }
+
+- Fixed #282: Browser search (Meta+F) is hijacked
+
+### 1.5.4 April 8, 2017 { id="1.5.4" }
+
+- Fixed broken highlighting for two or more search terms
+- Fixed missing search results when only a `h1` is present
+- Fixed unresponsive overlay on Android
+
+### 1.5.3 April 7, 2017 { id="1.5.3" }
+
+- Fixed deprecated calls for template variables
+- Fixed wrong palette color for focused search result
+- Fixed JavaScript errors on 404 page
+- Fixed missing top spacing on 404 page
+- Fixed missing right spacing on overflow of source container
+
+### 1.5.2 April 5, 2017 { id="1.5.2" }
+
+- Added requirements as explicit dependencies in `setup.py`
+- Fixed non-synchronized transitions in search form
+
+### 1.5.1 March 30, 2017 { id="1.5.1" }
+
+- Fixed rendering and offset of targeted footnotes
+- Fixed #238: Link on logo is not set to `site_url`
+
+### 1.5.0 March 24, 2017 { id="1.5.0" }
+
+- Added support for localization of search placeholder
+- Added keyboard events for quick access of search
+- Added keyboard events for search control
+- Added opacity on hover for search buttons
+- Added git hook to skip CI build on non-src changes
+- Fixed non-resetting search placeholder when input is cleared
+- Fixed error for unescaped parentheses in search term
+- Fixed #229: Button to clear search missing
+- Fixed #231: Escape key doesn't exit search
+- Removed old-style figures from font feature settings
+
+### 1.4.1 March 16, 2017 { id="1.4.1" }
+
+- Fixed invalid destructuring attempt on NodeList (in Safari, Edge, IE)
+
+### 1.4.0 March 16, 2017 { id="1.4.0" }
+
+- Added support for grouping searched sections by documents
+- Added support for highlighting of search terms
+- Added support for localization of search results
+- Fixed #216: table of contents icon doesn't show if `h1` is not present
+- Reworked style and layout of search results for better usability
+
+### 1.3.0 March 11, 2017 { id="1.3.0" }
+
+- Added support for page-specific title and description using metadata
+- Added support for linking source files to documentation
+- Fixed jitter and offset of sidebar when zooming browser
+- Fixed incorrectly initialized tablet sidebar height
+- Fixed regression for #1: GitHub stars break if `repo_url` ends with a `/`
+- Fixed undesired white line below copyright footer due to base font scaling
+- Fixed issue with whitespace in path for scripts
+- Fixed #205: support non-fixed (static) header
+- Refactored footnote references for better visibility
+- Reduced repaints to a minimum for non-tabs configuration
+- Reduced contrast of edit button (slightly)
+
+### 1.2.0 March 3, 2017 { id="1.2.0" }
+
+- Added `quote` (synonym: `cite`) style for admonitions
+- Added help message to build pipeline
+- Fixed wrong navigation link colors when applying palette
+- Fixed #197: Link missing in tabs navigation on deeply nested items
+- Removed unnecessary dev dependencies
+
+### 1.1.1 February 26, 2017 { id="1.1.1" }
+
+- Fixed incorrectly displayed nested lists when using tabs
+
+### 1.1.0 February 26, 2017 { id="1.1.0" }
+
+- Added tabs navigation feature (optional)
+- Added Disqus integration (optional)
+- Added a high resolution Favicon with the new logo
+- Added static type checking using Facebook's Flow
+- Fixed #173: Dictionary elements have no bottom spacing
+- Fixed #175: Tables cannot be set to 100% width
+- Fixed race conditions in build related to asset revisioning
+- Fixed accidentally re-introduced Permalink on top-level headline
+- Fixed alignment of logo in drawer on IE11
+- Refactored styles related to tables
+- Refactored and automated Docker build and PyPI release
+- Refactored build scripts
+
+### 1.0.5 February 18, 2017 { id="1.0.5" }
+
+- Fixed #153: Sidebar flows out of constrained area in Chrome 56
+- Fixed #159: Footer jitter due to JavaScript if content is short
+
+### 1.0.4 February 16, 2017 { id="1.0.4" }
+
+- Fixed #142: Documentation build errors if `h1` is defined as raw HTML
+- Fixed #164: PyPI release does not build and install
+- Fixed offsets of targeted headlines
+- Increased sidebar font size by `0.12rem`
+
+### 1.0.3 January 22, 2017 { id="1.0.3" }
+
+- Fixed #117: Table of contents items don't blur on fast scrolling
+- Refactored sidebar positioning logic
+- Further reduction of repaints
+
+### 1.0.2 January 15, 2017 { id="1.0.2" }
+
+- Fixed #108: Horizontal scrollbar in content area
+
+### 1.0.1 January 14, 2017 { id="1.0.1" }
+
+- Fixed massive repaints happening when scrolling
+- Fixed footer back reference positions in case of overflow
+- Fixed header logo from showing when the menu icon is rendered
+- Changed scrollbar behavior to only show when content overflows
+
+### 1.0.0 January 13, 2017 { id="1.0.0" }
+
+- Introduced Webpack for more sophisticated JavaScript bundling
+- Introduced ESLint and Stylelint for code style checks
+- Introduced more accurate Material Design colors and shadows
+- Introduced modular scales for harmonic font sizing
+- Introduced git-hooks for better development workflow
+- Rewrite of CSS using the BEM methodology and SassDoc guidelines
+- Rewrite of JavaScript using ES6 and Babel as a transpiler
+- Rewrite of Admonition, Permalinks and CodeHilite integration
+- Rewrite of the complete typographical system
+- Rewrite of Gulp asset pipeline in ES6 and separation of tasks
+- Removed Bower as a dependency in favor of NPM
+- Removed custom icon build in favor of the Material Design icon set
+- Removed `_blank` targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
+- Removed unversioned assets from build directory
+- Restructured templates into base templates and partials
+- Added build and watch scripts in `package.json`
+- Added support for Metadata and Footnotes Markdown extensions
+- Added support for PyMdown Extensions package
+- Added support for collapsible sections in navigation
+- Added support for separate table of contents
+- Added support for better accessibility through REM-based layout
+- Added icons for GitHub, GitLab and BitBucket integrations
+- Added more detailed documentation on specimen, extensions etc.
+- Added a `404.html` error page for deployment on GitHub Pages
+- Fixed live reload chain in watch mode when saving a template
+- Fixed variable references to work with MkDocs 0.16
+
+---
+
+### 0.2.4 June 26, 2016 { id="0.2.4" }
+
+- Fixed improperly set default favicon
+- Fixed #33: Protocol relative URL for webfonts doesn't work with `file://`
+- Fixed #34: IE11 on Windows 7 doesn't honor `max-width` on `main` tag
+- Fixed #35: Add styling for blockquotes
+
+### 0.2.3 May 16, 2016 { id="0.2.3" }
+
+- Fixed #25: Highlight inline fenced blocks
+- Fixed #26: Better highlighting for keystrokes
+- Fixed #30: Suboptimal syntax highlighting for PHP
+
+### 0.2.2 March 20, 2016 { id="0.2.2" }
+
+- Fixed #15: Document Pygments dependency for CodeHilite
+- Fixed #16: Favicon could not be set through `mkdocs.yml`
+- Fixed #17: Put version into own container for styling
+- Fixed #20: Fix rounded borders for tables
+
+### 0.2.1 March 12, 2016 { id="0.2.1" }
+
+- Fixed #10: Invisible header after closing search bar with ESC key
+- Fixed #13: Table cells don't wrap
+- Fixed empty list in table of contents when no headline is defined
+- Corrected wrong path for static asset monitoring in Gulpfile.js
+- Set up tracking of site search for Google Analytics
+
+### 0.2.0 February 24, 2016 { id="0.2.0" }
+
+- Fixed #6: Include multiple color palettes via `mkdocs.yml`
+- Fixed #7: Better colors for links inside admonition notes and warnings
+- Fixed #9: Text for prev/next footer navigation should be customizable
+- Refactored templates (replaced `if`/`else` with modifiers where possible)
+
+### 0.1.3 February 21, 2016 { id="0.1.3" }
+
+- Fixed #3: Ordered lists within an unordered list have `::before` content
+- Fixed #4: Click on Logo/Title without Github-Repository: `"None"`
+- Fixed #5: Page without headlines renders empty list in table of contents
+- Moved Modernizr to top to ensure basic usability in IE8
+
+### 0.1.2 February 16, 2016 { id="0.1.2" }
+
+- Fixed styles for deep navigational hierarchies
+- Fixed webfont delivery problem when hosted in subdirectories
+- Fixed print styles in mobile/tablet configuration
+- Added option to configure fonts in `mkdocs.yml` with fallbacks
+- Changed styles for admonition notes and warnings
+- Set download link to latest version if available
+- Set up tracking of outgoing links and actions for Google Analytics
+
+### 0.1.1 February 11, 2016 { id="0.1.1" }
+
+- Fixed #1: GitHub stars don't work if the repo_url ends with a `/`
+- Updated NPM and Bower dependencies to most recent versions
+- Changed footer/copyright link to Material theme to GitHub pages
+- Made MkDocs building/serving in build process optional
+- Set up continuous integration with Travis
+
+### 0.1.0 February 9, 2016 { id="0.1.0" }
+
+- Initial release
diff --git a/mkdocs-material/docs/contributing/adding-translations.md b/mkdocs-material/docs/contributing/adding-translations.md
new file mode 100644
index 0000000..dbbc4ed
--- /dev/null
+++ b/mkdocs-material/docs/contributing/adding-translations.md
@@ -0,0 +1,125 @@
+# Translations
+
+It's unbelievable – with the help of international community contributions,
+Material for MkDocs has been translated into 60+ languages. As you can imagine,
+it's impossible for us maintainers to keep all languages up-to-date, and new
+features sometimes require new translations.
+
+If you would like to help us to make Material for MkDocs even more globally
+accessible and have noticed a missing translation in your language, or would
+like to add a new language, you can help us by following the steps of the guide
+below.
+
+## Before creating an issue
+
+Translations change frequently, which is why we want to make sure that you don't
+invest your time in duplicating work. Before adding translations, please check
+the following things:
+
+### Check language availability
+
+With more than 60 languages, the chances are good that your language is already
+supported by Material for MkDocs. You can check if your language is available,
+or needs improvements or additional translations by inspecting the list of
+[supported languages]:
+
+- __Your language is already supported__ – in this case, you can check if there
+ are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
+
+- __Your language is missing__ – in that case, you can help us add support
+ for your language to Material for MkDocs! Read on, to learn how to do this.
+
+ [supported languages]: ../setup/changing-the-language.md#site-language
+
+### Search our issue tracker
+
+Another user might have already created an issue supplying the missing
+translations for your language that still needs to be integrated by us
+maintainers. To avoid investing your time in duplicated work, please search the
+[issue tracker] beforehand.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+---
+
+At this point, when you have made sure that Material for MkDocs doesn't already
+support your language, you can add new translations for it by following the
+issue template.
+
+## Issue template
+
+We have created an issue template that makes contributing translations as simple
+as possible. It is the result of our experience with 60+ language contributions
+and updates over the last couple of years, and consists of the following parts:
+
+- [Title]
+- [Translations]
+- [Country flag] optional
+- [Checklist]
+
+ [Title]: #title
+ [Translations]: #translations
+ [Country flag]: #country-flag
+ [Checklist]: #checklist
+
+### Title
+
+When you update an already existing language, you can just leave the title as it
+is. Adding support for a new language, replace the `...` in the pre-filled title
+with the name of your language.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Translations
+
+If a translation contains an :arrow_left: icon on the right side, it is missing.
+You can translate this line and remove the :arrow_left: icon. If you don't know
+how to translate specific lines, simply leave them for other contributors to
+complete. To ensure the accuracy of your translation, consider double-checking the
+context of the words by looking at our [English translations].
+
+[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
+### Country flag optional { #country-flag }
+
+For a better overview, our list of [supported languages] includes country flags
+next to the language names. You can help us select a flag for your language by
+adding the shortcode for the country flag to this field. Go to our
+[emoji search] and enter `flag` to find all available shortcodes.
+
+!!! question "What if my flag is not available?"
+
+ [Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
+ such as states, provinces, or regions, are not supported. If you're adding
+ translations for a subdivision, please choose the most appropriate available
+ flag.
+
+ [Twemoji]: https://twemoji.twitter.com/
+ [emoji search]: ../reference/icons-emojis.md#search
+
+> __Why this might be helpful__: adding a country flag next to the country name
+> can be helpful for you and for others to find the language in the list of
+> supported languages faster and easier. If your country's flag is not supported
+> by [Twemoji], you can help us choose an alternative.
+
+### Checklist
+
+Thanks for following the guide and helping us to add new translations to Material
+for MkDocs – you are almost done. The checklist ensures that you have read this
+guide and have worked to your best knowledge to provide us with everything we need
+to integrate your contribution.
+
+__We'll take it from here.__
+
+---
+
+## Attribution
+
+If you submit a translation using the template above, you will be __credited as
+a co-author__ in the commit, so you don't need to open a pull request. You have
+done a significant contribution to the project, making Material for MkDocs
+accessible to more people around the world. Thank you!
diff --git a/mkdocs-material/docs/contributing/index.md b/mkdocs-material/docs/contributing/index.md
new file mode 100644
index 0000000..fe84fd5
--- /dev/null
+++ b/mkdocs-material/docs/contributing/index.md
@@ -0,0 +1,269 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly evolving project
+serving a diverse user base with versatile backgrounds and needs. In order to
+efficiently address the requirements of all our users, evaluate change requests,
+and fix bugs, we put in a lot of work.
+
+Our ever-growing community includes many active users, who open new
+issues and discussions several times a day, evolving our [issue tracker] and
+[discussion board] into a knowledge base – an important addition to
+our [documentation] – yielding value to both new and experienced users.
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+
+## How you can contribute
+
+We understand that reporting bugs, raising change requests, as well as engaging
+in discussions can be time-consuming, which is why we've carefully optimized our
+issue templates and defined guidelines to improve the overall interaction
+within the project. We've invested a lot of time and effort into making our
+[issue tracker] and [discussion board] as efficient as possible.
+
+Our goal is to ensure that our documentation, as well as issue tracker and
+discussion board, are __well-structured__, __easy to navigate__, and
+__searchable__, so you can find what you need quickly and efficiently. Thus,
+when you follow our guidelines, we can help you much faster.
+
+In this section, we guide your through our processes.
+
+### Creating an issue
+
+
+
+- :material-bug-outline:
+ __Something is not working?__
+
+ ---
+
+ Report a bug in Material for MkDocs by creating an issue with a
+ reproduction
+
+ ---
+
+ [:octicons-arrow-right-24: Report a bug][report a bug]
+
+- :material-file-document-remove-outline:
+ __Missing information in our docs?__
+
+ ---
+
+ Report missing information or potential inconsistencies in our
+ documentation
+
+ ---
+
+ [:octicons-arrow-right-24: Report a docs issue][report a docs issue]
+
+- :material-lightbulb-on-20:
+ __Want to submit an idea?__
+
+ ---
+
+ Propose a change, feature request, or suggest an improvement
+
+ ---
+
+ [:octicons-arrow-right-24: Request a change][request a change]
+
+- :material-account-question-outline:
+ __Have a question or need help?__
+
+ ---
+
+ Ask a question on our [discussion board] and get in touch with our
+ community
+
+ ---
+
+ [:octicons-arrow-right-24: Ask a question][discussion board]
+
+
+
+### Contributing
+
+
+
+- :material-translate:
+ __Missing support for your language?__
+
+ ---
+
+ Add or improve translations for a new or already supported language
+
+ ---
+
+ [:octicons-arrow-right-24: Add translations][add translations]
+
+- :material-source-pull:
+ __Want to create a pull request?__
+
+ ---
+
+ Learn how to create a comprehensive and useful pull request (PR)
+
+ ---
+
+ [:octicons-arrow-right-24: Create a pull request][create a pull request]
+
+
+
+ [report a bug]: reporting-a-bug.md
+ [report a docs issue]: reporting-a-docs-issue.md
+ [request a change]: requesting-a-change.md
+ [add translations]: adding-translations.md
+ [create a pull request]: making-a-pull-request.md
+
+## Checklist
+
+Before interacting within the project, please take a moment to consider the
+following questions. By doing so, you can ensure that you are using the correct
+issue template and that you provide all necessary information when interacting
+with our community.
+
+!!! warning "Issues, discussions, and comments are forever"
+
+ Please note that everything you write is permanent and will remain
+ for everyone to read – forever. Therefore, please always be nice and
+ constructive, follow our contribution guidelines, and comply with our
+ [Code of Conduct].
+
+### Before creating an issue
+
+- Are you using the appropriate issue template, or is there another issue
+ template that better fits the context of your request?
+
+- Have you checked if a similar bug report or change request has already been
+ created, or have you stumbled upon something that might be related?
+
+- Did your fill out every field as requested and did you provide all additional
+ information we maintainers need to comprehend your request?
+
+### Before asking a question
+
+- Is the topic a question for our [discussion board], or is it a bug report or
+ change request that should better be raised on our [issue tracker]?
+
+- Is there an open discussion on the topic of your request? If the answer is yes,
+ does your question match the direction of the discussion, or should you open a
+ new discussion?
+
+- Did your provide our community with all the necessary information to
+ understand your question and help you quickly, or can you make it easier to
+ help you?
+
+### Before commenting
+
+- Is your comment relevant to the topic of the current page, post, issue, or
+ discussion, or is it a better idea to create a new issue or discussion?
+
+- Does your comment add value to the conversation? Is it constructive and
+ respectful to our community and us maintainers? Could you just use a
+ [:octicons-smiley-16: reaction][reaction] instead?
+
+ [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
+ [reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
+
+## Rights and responsibilities
+
+As maintainers, we are entrusted with the __responsibility__ to moderate
+communication within our community, including the authority to close, remove,
+reject, or edit issues, discussions, comments, commits, and to block users who
+__do not align__ with our contribution guidelines and our [Code of Conduct].
+This role requires us to be actively involved in maintaining the integrity and
+positive atmosphere of our community. Upholding these standards decisively
+ensures a respectful and inclusive environment for all members.
+
+
+### Code of Conduct
+
+Our [Code of Conduct] outlines the expectation for all community members to
+treat one another with respect, employing inclusive and welcoming language. Our
+commitment is to foster a positive and supportive environment, free of
+inappropriate, offensive, or harmful behavior.
+
+We take any violations seriously and will take appropriate action in response to
+uphold these values.[^1]
+
+ [^1]:
+ __Warning and blocking policy:__
+ Given the increasing popularity of our project and our commitment to a
+ healthy community, we've defined clear guidelines on how we proceed with
+ violations:
+
+ 1.1. __First warning:__ Users displaying repeated inappropriate, offensive,
+ or harmful behavior will receive a first warning. This warning serves as a
+ formal notice that their behavior is not in alignment with our community
+ standards and Code of Conduct. The first warning is permanent.
+
+ 1.2. __Second warning and opportunity for resolution:__ If the behavior
+ persists, a second warning will be issued. Upon receiving the second
+ warning, the user will be given a 5-day period for reflection, during which
+ they are encouraged to publicly explain or apologize for their actions.
+ This period is designed to offer an opportunity for openly clearing out any
+ misunderstanding.
+
+ 1.3. __Blocking:__ Should there be no response or improvement in behavior
+ following the second warning, we reserve the right to block the user from
+ the community and repository. Blocking is considered a last resort, used
+ only when absolutely necessary to protect the community's integrity and
+ positive atmosphere.
+
+ Blocking has been an exceptionally rare necessity in our overwhelmingly
+ positive community, highlighting our preference for constructive dialogue
+ and mutual respect. It aims to protect our community members and team.
+
+### Incomplete issues and duplicates
+
+We have invested significant time and effort in the setup of our contribution
+process, ensuring that we assess the essential requirements for reviewing and
+responding to issues effectively. Each field in our issue templates is
+thoughtfully designed to help us fully understand your concerns and the nature
+of your matter. We encourage all members to utilize the search function before
+submitting new issues or starting discussions to help avoid duplicates. Your
+cooperation is crucial in keeping our community's discussions constructive and
+organized.
+
+ - __Mandatory completion of issue templates:__ We need all of the information
+ required in our issue templates because it ensures that every user and
+ maintainer, regardless of their experience, can understand the content and
+ severity of your bug report or change request.
+
+ - __Closing incomplete issues:__
+ We _reserve the right to close issues lacking essential information_, such as
+ but not limited to [minimal reproductions] or those not adhering to the
+ quality standards and requirements specified in our issue templates. Such
+ issues can be reopened once the missing information has been provided.
+
+ - __Handling duplicates:__ To maintain organized and efficient
+ communication within our [issue tracker] and [discussion board], we
+ _reserve the right to close any duplicated issues or lock duplicated
+ discussions_. Opening multiple channels to ask the same question or report the
+ same issue across different forums hinders our ability to manage and address
+ community concerns effectively. This approach is vital for efficient time
+ management, as duplicated questions can consume the time of multiple team
+ members simultaneously. Ensuring that each issue or discussion is unique and
+ progresses with new information helps us to maintain focus and support our
+ community.
+
+ We further _reserve the right to immediately close discussions or issues that
+ are reopened without providing new information_ or simply because users have
+ not yet received a response to their issue/question, as the issue is marked as
+ incomplete.
+
+ - __Limitations of automated tools:__ While we believe in the value and
+ efficiency that automated tools bring to identifying potential issues (such
+ as those identified by Lighthouse, Accessibility tools, and others), simply
+ submitting an issue generated by these tools does not constitute a complete
+ bug report. These tools sometimes produce verbose outputs and may include
+ false positives, which necessitate a critical evaluation. You are of course
+ welcome to attach generated reports to your issue. However, this does not
+ substitute the requirement for a minimal reproduction or a thorough discussion
+ of the findings. _We reserve the right to mark these issues as incomplete and
+ close them._ This practice ensures that we are addressing genuine concerns
+ with precision and clarity, rather than navigating through extensive automated
+ outputs.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
diff --git a/mkdocs-material/docs/contributing/making-a-pull-request.md b/mkdocs-material/docs/contributing/making-a-pull-request.md
new file mode 100644
index 0000000..d1be831
--- /dev/null
+++ b/mkdocs-material/docs/contributing/making-a-pull-request.md
@@ -0,0 +1,423 @@
+# Pull Requests
+
+You can contribute to Material for MkDocs by making a [pull request] that
+will be reviewed by maintainers and integrated into the main repository when
+the changes made are approved. You can contribute bug fixes, changes to the
+documentation, or new functionality you have developed.
+
+[pull request]: https://docs.github.com/en/pull-requests
+
+!!! note "Considering a pull request"
+
+ Before deciding to spend effort on making changes and creating a pull
+ request, please discuss what you intend to do. If you are responding to
+ what you think might be a bug, please issue a [bug report] first. If you
+ intend to work on documentation, create a [documentation issue]. If you
+ want to work on a new feature, please create a [change request].
+
+ Keep in mind the guidance given and let people advise you. It might be that
+ there are easier solutions to the problem you perceive and want to address.
+ It might be that what you want to achieve can already be done by
+ configuration or [customization].
+
+[bug report]: reporting-a-bug.md
+[documentation issue]: reporting-a-docs-issue.md
+[change request]: requesting-a-change.md
+[customization]: ../customization.md
+
+## Learning about pull requests
+
+Pull requests are a concept layered on top of Git by services that provide Git
+hosting. Before you consider making a pull request, you should familiarize
+yourself with the documentation on GitHub, the service we are using. The
+following articles are of particular importance:
+
+1. [Forking a repository]
+2. [Creating a pull request from a fork]
+3. [Creating a pull request]
+
+Note that they provide tailored documentation for different operating systems
+and different ways of interacting with GitHub. We do our best in the
+documentation here to describe the process as it applies to Material for MkDocs
+but cannot cover all possible combinations of tools and ways of doing things.
+It is also important that you understand the concept of a pull-request in
+general before continuing.
+
+[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
+[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+## Pull request process
+
+In the following, we describe the general process for making pull requests. The
+aim here is to provide the 30k ft overview before describing details later on.
+
+### Preparing changes and draft PR
+
+The diagram below describes what typically happens to repositories in the
+process or preparing a pull request. We will be discussing the review-revise
+process below. It is important that you understand the overall process first
+before you worry about specific commands. This is why we cover this first before
+providing instructions below.
+
+``` mermaid
+sequenceDiagram
+ autonumber
+
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ mkdocs-material ->> fork: fork on GitHub
+ fork ->> local: clone to local
+ local ->> local: branch
+ loop prepare
+ loop push
+ loop edit
+ local ->> local: commit
+ end
+ local ->> fork: push
+ end
+ mkdocs-material ->> fork: merge in any changes
+ fork ->>+ PR: create draft PR
+ PR ->> PR: review your changes
+ end
+```
+
+1. The first step is that you create a fork of the Material for MkDocs
+ repository, either [mkdocs-material] or [mkdocs-material-insiders]
+ (only accessible to sponsors). This provides you with a repository that you
+ can push changes to. Note that it is not possible to have more than one fork
+ of a given repository at any point in time. So, the fork you create will be
+ *the* fork you have.
+
+2. Once it is made, clone it to your local machine so you can start working on
+ your changes.
+
+3. All contributions should be made through a 'topic branch' with a name that
+ describes the work being done. This allows you to have more than one piece
+ of work in progress and, if you are working with the public version, also
+ shows others clearly that the code contained is work in progress. The topic
+ branch will be relatively short-lived and will disappear at the end, when
+ your changes have been incorporated into the codebase.
+
+4. If you intend to make any code changes, as opposed to working on
+ documentation only, you will need to [set up a development
+ environment](#setting-up-a-development-environment).
+
+5. Next comes the iterative process of making edits, committing them to your
+ clone. Please commit in sensible chunks that constitute a piece of work
+ instead of committing everything in one go.
+
+ Remember that fine-grained, incremental commits are much easier to
+ review in than large changes all over the place and with many files involved.
+ Try to keep your changes as small and localized as possible and keep the
+ reviewer in mind when committing. In particular, make sure to write
+ meaningful commit messages.
+
+6. Push your work up to your fork regularly.
+
+7. You should also keep an eye on changes in the Material for MkDocs repository
+ you cloned. This is especially important if you work takes a while. Please
+ try and merge any concurrent changes into your fork and into your branch
+ regularly. You *must* do this at least once before creating a pull request,
+ so make your life easier and do it more often so as to minimize the risk of
+ conflicting changes.
+
+8. Once you are happy that your changes are in a state that you can describe
+ them in a *draft* pull request, you should create this. Make sure to
+ reference any previous discussions or issues that gave rise to your work.
+ Creating a draft is a good way to get *early* feedback on your work from the
+ maintainer or others. You can explicitly request reviews at points where you
+ think this would be important.
+
+9. Review your work as if you were the reviewer and fix any issues with your
+ work so far. Look critically at the diffs of the files that you have changed.
+ In particular, pay attention to whether the changes are as small as possible
+ and whether you have follow the general coding style used in the project.
+ If you received feedback, iterate over the process so far as necessary.
+
+ You should choose a number of projects to test your changes with. You should
+ definitely make sure that the changes do not break the building of the
+ documentation for Material for MkDocs, which you can find in the `docs`
+ folder. You may also want to make sure that relevant examples from the
+ [examples repository] still build fine.
+
+[mkdocs-material]: https://github.com/squidfunk/mkdocs-material
+[mkdocs-material-insiders]: https://github.com/squidfunk/mkdocs-material-insiders/
+[examples repository]: https://github.com/mkdocs-material/examples
+
+### Finalizing
+
+Once you are happy with your changes, you can move to the next step, finalizing
+your pull request and asking for a more formal and detailed review. The diagram
+below shows the process:
+
+``` mermaid
+sequenceDiagram
+ autonumber
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ activate PR
+ PR ->> PR : finalize PR
+ loop review
+ loop discuss
+ PR ->> PR: request review
+ PR ->> PR: discussion
+ local ->> fork: push further changes
+ end
+ PR ->> mkdocs-material: merge (and squash)
+ deactivate PR
+ fork ->> fork: delete branch
+ mkdocs-material ->> fork: pull
+ local ->> local: delete branch
+ fork ->> local: pull
+ end
+```
+
+1. When you are happy that the changes you made amount to a contribution that
+ the maintainer(s) could integrate into the codebase, finalize the pull
+ request. This signals to everyone that consider the work 'done' and that it
+ can be reviewed with a view to accepting and integrating it.
+
+2. Request a review from the maintainer, `@squidfunk`.
+
+3. The maintainer may make comments on your code, which you should discuss with
+ them. Bear in mind when doing this that the maintainer may have a different
+ point of view compared to yours. They will often take a more long-term
+ perspective of maintaining the project in the years to come while you may be
+ more focused on the specific issue or feature that you worked on. Please keep
+ the discussion respectful at all times.
+
+ It is important to note that not all pull requests get incorporated int the
+ codebase. The reasons can vary. The work may bring to light other issues that
+ block integration of the pull request. Sometimes it helps uncover better ways of
+ doing things or shows that a more general approach is needed. All of this is
+ fine and helps the project progress, even if specific changes are not,
+ ultimately, accepted.
+
+4. Make any requested changes by committing them to your local clone and
+ pushing them up to your fork. This will automatically update the pull request.
+ It may well take a few iterations to get your contributions to an acceptable
+ state. You can help the process along by carefully reading comments made and
+ making changes with care.
+
+5. Once the reviewer is fully satisfied with the changes, they can merge them
+ into the main branch (or 'master'). In the process, they may 'squash' your
+ commits together into a smaller number of commits and may edit the messages
+ that describe them. Congratulations, you have now contributed to this project
+ and should see the changes in the main branch under your name.
+
+6. You can now delete the fork and your local repository and start afresh again
+ next time around. Alternatively, you can keep the repository and local clone
+ around but it is important that you keep them in sync with the upstream
+ repository for any subsequent work. We recommend that you start by deleting
+ the branch you used on your fork.
+
+7. To make sure you have the changes you produced, pull them from the main
+ repository into the main branch of your fork.
+
+8. Similarly, delete the topic branch from your local clone and...
+
+9. pull the changes to its master branch.
+
+## Steps
+
+Now that the overall process is outlined, here are specific instructions and
+tips. There are many choices to be made when describing a process for
+contributing to a project via a pull request. In the following, we assume that
+you are working with the Git command-line tools. For most alternatives (such as
+using IDEs or using functionality provided through the GitHub web interface),
+the translation from the command-line instructions should be simple enough. We
+will add notes only where really necessary to keep the complexity of this to a
+reasonable level.
+
+### Forking the repository
+
+To make changes to Material for MkDocs, you would first fork one of its
+repositories on GitHub. This is so that you have a repository on GitHub that
+you can push changes to (only maintainers and collaborators have write access
+to the original repositories).
+
+Fork the [repository for the public version] if you want to make changes to
+code that is in the public version or if you want to make changes to the
+documentation. It is a good idea to change the name of the repository by
+appending `-fork` so that people who come across it know that they have found a
+temporary fork rather then the original or a permanent fork of the project.
+You may also want to add a description that clarifies what the repository is for.
+
+[repository for the public version]: https://github.com/squidfunk/mkdocs-material
+
+To make changes to functionality available only within the Insiders version,
+fork [the Insiders repository]. Note that the fork will be a private repository.
+Please respect the [terms of the Insiders program] and the spirit of the
+Sponsorware approach used to maintain and develop Material for MkDocs.
+
+[the Insiders repository]: https://github.com/squidfunk/mkdocs-material-insiders/
+[terms of the Insiders program]: http://localhost:8000/mkdocs-material/insiders/faq/sponsoring/#licensing
+
+### Setting up a development environment
+
+From this point onwards, please follow the [instructions for setting up the
+development environment]. They will take you through the process of setting up
+an environment in which you can make changes and review/test them.
+
+[instructions for setting up the development environment]: ../customization.md#environment-setup
+
+### Making changes
+
+When you make changes to the code or the documentation please follow the
+established style used in the project. Doing so increases readability and
+also helps with making diffs easier to read for those who will review the pull
+request. Avoid making any large-scale style changes such as asking your IDE
+to re-format all code.
+
+Study the code that you are modifying well to ensure that you fully understand
+how it works before you try to change it. This will not only help you solve the
+problem you are trying to address but also minimize the risks of creating
+unintended side effects.
+
+### Committing to a branch
+
+Development for pull requests is best done in a topic branch separate from the
+`master` branch. Create a new local branch with `git switch -c ` and
+commit your changes to this branch.
+
+When you want to push commits to your fork, you can do so with
+`git push -u origin `. The `-u` argument is the short version of
+`--set-upstream`, which makes the newly created branch 'track' the branch with
+the same `` in your fork. This means that then `pull` and `push` commands
+will work against that branch in your fork by default.
+
+### Merging concurrent changes
+
+If the work you do takes some time then the chances increase that changes will
+be made to the main repository while you work.It is probably a good idea to set
+up the original Material for MkDocs repository as an `upstream` repository for
+your local clone.
+
+This is what it might look like:
+
+```bash hl_lines="4"
+$ git remote -v
+origin git@github.com:/mkdocs-material-fork.git (fetch)
+origin git@github.com:/mkdocs-material-fork.git (push)
+$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
+$ git remote -v
+origin git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
+origin git@github.com:alexvoss/mkdocs-material-fork.git (push)
+upstream https://github.com/squidfunk/mkdocs-material.git (fetch)
+upstream https://github.com/squidfunk/mkdocs-material.git (push)
+```
+
+After you have done this, you can pull any concurrent changes from the upstream
+repository directly into your clone and do any necessary merges there, then push
+them up to your fork. You will need to be explicit about which remote repository
+you want to use when you are doing a `pull`:
+
+```bash
+# making and committing some local changes
+push pull upstream master
+```
+
+This fetches changes from the `master` branch into your topic branch and merges
+them.
+
+### Testing and reviewing changes
+
+Before you commit any changes, you should make sure that they work as expected
+and do not create any unintended side effects. You should test them on at least
+these three [smoke tests]:
+
+- The documentation of Material for MkDocs itself. If you set up and run the
+development environment as outlined in the [instructions for setting up the
+development environment], `mkdocs serve` should be running and continuously
+building the documentation. Check that there are no error messages and, ideally,
+no (new) warnings.
+
+- Test on a project that represents the problem or a test for a newly developed
+feature. You may already have this if you have filed a bug report and created
+a [minimal reproduction]. If you are working on a new feature then you may need
+to build a project to serve as a test suite. It can double as documentation that
+shows how your new feature is meant to work.
+
+- Test with relevant examples from the [Material for MkDocs Examples]
+ repository. Note that to build all examples in one go you need the projects
+ plugin from Insiders but you can always build the examples individually
+ using the public version.
+
+[smoke tests]: https://en.wikipedia.org/wiki/Smoke_testing_(software)
+[minimal reproduction]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
+[Material for MkDocs Examples]: https://github.com/mkdocs-material/examples
+
+- Ideally, also test the examples in the [examples repository]. If you are
+working on the Insiders edition of Material for MkDocs, you can simply start a
+build at the top level and the [projects plugin] will build all of the examples
+for you. If you are on the public version, you will need to build each
+sub-project individually. We appreciate that this is a growing collection of
+examples and you may want to prioritize those that are most relevant to the
+functionality you change.
+
+[examples repository]: https://github.com/mkdocs-material/examples
+[projects plugin]: https://squidfunk.github.io/mkdocs-material/plugins/projects/
+
+### Creating the pull request
+
+Initially, create the pull request **as a draft**. You do this [through the
+various interfaces that GitHub provides]. Which one you use is entirely up to
+you. We do not provide specific instructions for using the interfaces as GitHub
+provide all the information that should be necessary.
+
+[through the various interfaces that GitHub provides]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+### Commits, messages, mistakes and 'squash'
+
+### Deleting branches
+
+Once the pull request has been merged into the master branch of the Material
+for MkDocs repository, you should remove the branch both from the fork on
+GitHub and from the local clone on your computer. This avoids possible
+confusion about the state of development.
+
+First, switch back to the `master` branch with `git switch master` and then
+delete the branch used for the PR using `git branch -d `.
+
+### Subsequent Pull Requests
+
+It is important that subsequent pull requests are started from an up-to-date
+history of the `master` branch. One way to achieve this is to delete the fork
+and start with an entirely new one next time round.
+
+If you contribute to Material for MkDocs more often or just happen to be
+doing two or more pull requests in succession, you can also just make sure
+to sync your fork (using the GitHub UI) and pull from it into your local
+repository. So, just delete the topic branch you created (both locally and in
+your fork) and pull from the main repository's `master` branch into your
+`master` branch before starting work on a new pull request.
+
+## Dos and Don'ts
+
+1. **Don't** just create a pull request with changes that are not explained.
+
+2. **Do** discuss what you intend to do with people in the discussions so that the
+ rational for any changes is clear before you write or modify code.
+
+3. **Do** link to the discussion or any issues to provide the context for a pull
+ request.
+
+4. **Do** ask questions if you are uncertain about anything.
+
+5. **Do** ask yourself if what you are doing benefits the wider community and
+ makes Material for MkDocs a better product.
+
+6. **Do** ask yourself if the cost of making the changes stands in a good
+ relation to the benefits they will bring. Some otherwise sensible changes can
+ add complexity for comparatively little gain, might break existing behaviour
+ or might be brittle when other changes need to be made.
+
+7. **Do** merge in concurrent changes frequently to minimize the chance of
+ conflicting changes that may be difficult to resolve.
diff --git a/mkdocs-material/docs/contributing/reporting-a-bug.md b/mkdocs-material/docs/contributing/reporting-a-bug.md
new file mode 100644
index 0000000..8c84f8a
--- /dev/null
+++ b/mkdocs-material/docs/contributing/reporting-a-bug.md
@@ -0,0 +1,313 @@
+# Bug reports
+
+Material for MkDocs is an actively maintained project that we constantly strive
+to improve. With a project of this size and complexity, bugs may occur. If you
+think you have discovered a bug, you can help us by submitting an issue in our
+public [issue tracker], following this guide.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+With more than 20,000 users, issues are created every other day. The maintainers
+of this project are trying very hard to keep the number of open issues down by
+fixing bugs as fast as possible. By following this guide, you will know exactly
+what information we need to help you quickly.
+
+__But first, please do the following things before creating an issue.__
+
+### Upgrade to latest version
+
+Chances are that the bug you discovered was already fixed in a subsequent
+version. Thus, before reporting an issue, ensure that you're running the
+[latest version] of Material for MkDocs. Please consult our [upgrade guide] to
+learn how to upgrade to the latest version.
+
+!!! warning "Bug fixes are not backported"
+
+ Please understand that only bugs that occur in the latest version of
+ Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
+ fixes cannot be backported to earlier versions.
+
+### Remove customizations
+
+If you're using [customizations] like [additional CSS], [JavaScript], or
+[theme extension], please remove them from `mkdocs.yml` before reporting a bug.
+We can't offer official support for bugs that might hide in your overrides, so
+make sure to omit the following settings from `mkdocs.yml`:
+
+ - [`theme.custom_dir`][theme.custom_dir]
+ - [`hooks`][hooks]
+ - [`extra_css`][extra_css]
+ - [`extra_javascript`][extra_javascript]
+
+If, after removing those settings, the bug is gone, the bug is likely caused by
+your customizations. A good idea is to add them back gradually to narrow down
+the root cause of the problem. If you did a major version upgrade, make sure you
+adjusted all partials you have overridden.
+
+!!! warning "Customizations mentioned in our documentation"
+
+ A handful of the features Material for MkDocs offers can only be implemented
+ with customizations. If you find a bug in any of the customizations [that
+ our documentation explicitly mentions], you are, of course, encouraged to
+ report it.
+
+__Don't be shy to ask on our [discussion board] for help if you run into
+problems.__
+
+ [latest version]: ../changelog/index.md
+ [upgrade guide]: ../upgrade.md
+ [Customizations]: ../customization.md
+ [additional CSS]: ../customization.md#additional-css
+ [JavaScript]: ../customization.md#additional-javascript
+ [theme extension]: ../customization.md#extending-the-theme
+ [theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+ [hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
+ [extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
+ [extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [StackOverflow]: https://stackoverflow.com
+ [that our documentation explicitly mentions]: ?q="extends+base"
+
+### Search for solutions
+
+At this stage, we know that the problem persists in the latest version and is
+not caused by any of your customizations. However, the problem might result from
+a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
+
+Now, before you go through the trouble of creating a bug report that is answered
+and closed right away with a link to the relevant documentation section or
+another already reported or closed issue or discussion, you can save time for
+us and yourself by doing some research:
+
+1. [Search our documentation] and look for the relevant sections that could
+ be related to your problem. If found, make sure that you configured
+ everything correctly.[^1]
+
+ [^1]:
+ When adding lines to `mkdocs.yml`, make sure you are preserving the
+ indentation as mentioned in the documentation since YAML is a
+ whitespace-sensitive language. Many reported issues turn out to be
+ configuration errors.
+
+1. [Search our issue tracker][issue tracker], as another user might already
+ have reported the same problem, and there might even be a known workaround
+ or fix for it. Thus, no need to create a new issue.
+
+2. [Search our discussion board][discussion board] to learn if other users
+ are struggling with similar problems and work together with our great
+ community towards a solution. Many problems are solved here.
+
+__Keep track of all search terms and relevant links, you'll need
+them in the bug report.__[^2]
+
+ [^2]:
+ We might be using terminology in our documentation different from yours,
+ but we mean the same. When you include the search terms and related links
+ in your bug report, you help us to adjust and improve the documentation.
+
+---
+
+At this point, when you still haven't found a solution to your problem, we
+encourage you to create an issue because it's now very likely that you
+stumbled over something we don't know yet. Read the following section to learn
+how to create a complete and helpful bug report.
+
+ [Search our documentation]: ?q=
+
+## Issue template
+
+We have created a new issue template to make the bug reporting process as simple
+as possible and more efficient for our community and us. It is the result of
+our experience answering and fixing more than 1,600 issues (and counting) and
+consists of the following parts:
+
+- [Title]
+- [Context] optional
+- [Bug description]
+- [Related links]
+- [Reproduction]
+- [Steps to reproduce]
+- [Browser] optional
+- [Checklist]
+
+ [Title]: #title
+ [Context]: #context
+ [Bug description]: #bug-description
+ [Related links]: #related-links
+ [Reproduction]: #reproduction
+ [Steps to reproduce]: #steps-to-reproduce
+ [Browser]: #browser
+ [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the issue, so the impact and severity of the bug you want to report
+can be inferred from the title.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
+| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Context optional { #context }
+
+Before describing the bug, you can provide additional context for us to
+understand what you were trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the bug here.
+
+> __Why this might be helpful__: some errors only manifest in specific settings,
+> environments or edge cases, for example, when your documentation contains
+> thousands of documents.
+
+### Bug description
+
+Now, to the bug you want to report. Provide a clear, focused, specific, and
+concise summary of the bug you encountered. Explain why you think this is a bug
+that should be reported to Material for MkDocs, and not to one of its
+dependencies.[^3] Adhere to the following principles:
+
+ [^3]:
+ Sometimes, users report bugs on our [issue tracker] that are caused by one
+ of our upstream dependencies, including [MkDocs], [Python Markdown],
+ [Python Markdown Extensions] or third-party plugins. A good rule of thumb is
+ to change the [`theme.name`][theme.name] to `mkdocs` or `readthedocs` and
+ check if the problem persists. If it does, the problem is likely not
+ related to Material for MkDocs and should be reported upstream. When in
+ doubt, use our [discussion board] to ask for help.
+
+- __Explain the what, not the how__ – don't explain
+ [how to reproduce the bug][Steps to reproduce] here, we're getting there.
+ Focus on articulating the problem and its impact as clearly as possible.
+
+- __Keep it short and concise__ – if the bug can be precisely explained in one
+ or two sentences, perfect. Don't inflate it – maintainers and future users
+ will be grateful for having to read less.
+
+- __One bug at a time__ – if you encounter several unrelated bugs, please
+ create separate issues for them. Don't report them in the same issue, as
+ this makes attribution difficult.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
+the bug, you can help other users temporarily mitigate the problem before
+we maintainers can fix the bug in our code base.
+
+> __Why we need this__: in order for us to understand the problem, we
+> need a clear description of it and quantify its impact, which is essential
+> for triage and prioritization.
+
+ [MkDocs]: https://www.mkdocs.org
+ [Python Markdown]: https://python-markdown.github.io/extensions/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
+
+### Related links
+
+Of course, prior to reporting a bug, you have read our documentation and
+[could not find a working solution][search for solutions]. Please share links
+to all sections of our documentation that might be relevant to the bug, as it
+helps us gradually improve it.
+
+Additionally, since you have searched our [issue tracker] and [discussion board]
+before reporting an issue, and have possibly found several issues or
+discussions, include those as well. Every link to an issue or discussion creates
+a backlink, guiding us maintainers and other users in the future.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you also include the search terms you
+used when [searching for a solution][search for solutions] to your problem, you
+make it easier for us maintainers to improve the documentation.
+
+> __Why we need this__: related links help us better understand what you were
+> trying to achieve and whether sections of our documentation need to be
+> adjusted, extended, or overhauled.
+
+ [search for solutions]: #search-for-solutions
+
+### Reproduction
+
+A minimal reproduction is at the heart of every well-written bug report, as
+it allows us maintainers to instantly recreate the necessary conditions to
+inspect the bug to quickly find its root cause. It's a proven fact that issues
+with concise and small reproductions can be fixed much faster.
+
+[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
+
+---
+
+After you have created the reproduction, you should have a `.zip` file, ideally
+not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
+will automatically upload it to GitHub.
+
+> __Why we need this__: if an issue contains no minimal reproduction or just
+> a link to a repository with thousands of files, the maintainers would need to
+> invest a lot of time into trying to recreate the right conditions to even
+> inspect the bug, let alone fix it.
+
+!!! warning "Don't share links to repositories"
+
+ While we know that it is a good practice among developers to include a link
+ to a repository with the bug report, we currently don't support those in our
+ process. The reason is that the reproduction, which is automatically
+ produced by the [built-in info plugin] contains all of the necessary
+ environment information that is often forgotten to be included.
+
+ Additionally, there are many non-technical users of Material for MkDocs that
+ have trouble creating repositories.
+
+ [Create reproduction]: ../guides/creating-a-reproduction.md
+ [built-in info plugin]: ../plugins/info.md
+
+### Steps to reproduce
+
+At this point, you provided us with enough information to understand the bug
+and provided us with a reproduction that we could run and inspect. However, when
+we run your reproduction, it might not be immediately apparent how we can see
+the bug in action.
+
+Thus, please list the specific steps we should follow when running your
+reproduction to observe the bug. Keep the steps short and concise, and make sure
+not to leave anything out. Use simple language as you would explain it to a
+five-year-old, and focus on continuity.
+
+> __Why we need this__: we must know how to navigate your reproduction in order
+> to observe the bug, as some bugs only occur at certain viewports or in
+> specific conditions.
+
+### Browser optional { #browser }
+
+If you're reporting a bug that only occurs in one or more _specific_ browsers,
+we need to know which browsers are affected. This field is optional, as it is
+only relevant when the bug you are reporting does not involve a crash when
+[previewing] or [building] your site.
+
+---
+
+:material-incognito: __Incognito mode__ – Please verify that a the bug is
+not caused by a browser extension. Switch to incognito mode and try to reproduce
+the bug. If it's gone, it's caused by an extension.
+
+> __Why we need this__: some bugs only occur in specific browsers or versions.
+> Since now, almost all browsers are evergreen, we usually don't need to know the
+> version in which it occurs, but we might ask for it later. When in doubt, add
+> the browser version as the first step in the field above.
+
+ [previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
+ [building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality and complete bug
+report – you are almost done. The checklist ensures that you have read this guide
+and have worked to your best knowledge to provide us with everything we need to
+know to help you.
+
+__We'll take it from here.__
diff --git a/mkdocs-material/docs/contributing/reporting-a-docs-issue.md b/mkdocs-material/docs/contributing/reporting-a-docs-issue.md
new file mode 100644
index 0000000..460aadf
--- /dev/null
+++ b/mkdocs-material/docs/contributing/reporting-a-docs-issue.md
@@ -0,0 +1,91 @@
+# Documentation issues
+
+Our documentation is composed of more than 80 pages and includes extensive
+information on features, configurations, customizations, and much more. If you
+have found an inconsistency or see room for improvement, please follow this
+guide to submit an issue on our [issue tracker].
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Issue template
+
+Reporting a documentation issue is usually less involved than reporting a bug,
+as we don't need a [reproduction]. Please thoroughly read this guide before
+creating a new documentation issue, and provide the following information as
+part of the issue:
+
+- [Title]
+- [Description]
+- [Related links]
+- [Proposed change] optional
+- [Checklist]
+
+ [reproduction]: ../guides/creating-a-reproduction.md
+ [Title]: #title
+ [Description]: #description
+ [Related links]: #related-links
+ [Proposed change]: #proposed-change
+ [Checklist]: #checklist
+
+### Title
+
+A good title should be a short, one-sentence description of the issue, contain
+all relevant information and, in particular, keywords to simplify the search in
+our issue tracker.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Description
+
+Provide a clear and concise summary of the inconsistency or issue you
+encountered in the documentation or the documentation section that needs
+improvement. Explain why you think the documentation should be adjusted and
+describe the severity of the issue:
+
+- __Keep it short and concise__ – if the inconsistency or issue can be
+ precisely explained in one or two sentences, perfect. Maintainers and future
+ users will be grateful for having to read less.
+
+- __One issue at a time__ – if you encounter several unrelated inconsistencies,
+ please create separate issues for them. Don't report them in the same issue
+ – it makes attribution difficult.
+
+> __Why we need this__: describing the problem clearly and concisely is a
+> prerequisite for improving our documentation – we need to understand what's
+> wrong, so we can fix it.
+
+### Related links
+
+After you described the documentation section that needs to be adjusted above,
+we now ask you to share the link to this specific documentation section and
+other possibly related sections. Make sure to use anchor links (permanent links)
+where possible, as it simplifies discovery.
+
+> __Why we need this__: providing the links to the documentation help us
+> understand which sections of our documentation need to be adjusted, extended,
+> or overhauled.
+
+
+### Proposed change optional { #proposed-change }
+
+Now that you have provided us with the description and links to the
+documentation sections, you can help us, maintainers, and the community by
+proposing an improvement. You can sketch out rough ideas or write a concrete
+proposal. This field is optional but very helpful.
+
+> __Why we need this__: an improvement proposal can be beneficial for other
+> users who encounter the same issue, as they offer solutions before we
+> maintainers can update the documentation.
+
+### Checklist
+
+Thanks for following the guide and providing valuable feedback for our
+documentation – you are almost done. The checklist ensures that you have read
+this guide and have worked to your best knowledge to provide us with every piece
+of information we need to improve it.
+
+__We'll take it from here.__
diff --git a/mkdocs-material/docs/contributing/requesting-a-change.md b/mkdocs-material/docs/contributing/requesting-a-change.md
new file mode 100644
index 0000000..a708ae5
--- /dev/null
+++ b/mkdocs-material/docs/contributing/requesting-a-change.md
@@ -0,0 +1,241 @@
+# Change requests
+
+Material for MkDocs is a powerful tool for creating beautiful and functional
+documentation. With more than 20,000 users, we understand that our project
+serves a wide range of use cases, which is why we have created the following
+guide.
+
+---
+
+Put yourself in our shoes – with a project of this size, it can be challenging
+to maintain existing functionality while constantly adding new features at the
+same time. We highly value every idea or contribution from our community, and
+we kindly ask you to take the time to read the following guidelines before
+submitting your change request in our public [issue tracker]. This will help us
+better understand the proposed change and how it will benefit our community.
+
+This guide is our best effort to explain the criteria and reasoning behind our
+decisions when evaluating change requests and considering them for
+implementation.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+Before you invest your time to fill out and submit a change request, we kindly
+ask you to do some preliminary work by answering some questions to determine if
+your idea is a good fit for Material for MkDocs and matches the project's
+[philosophy] and tone.
+
+__Please do the following things before creating an issue.__
+
+ [philosophy]: ../philosophy.md
+
+### It's not a bug, it's a feature
+
+Change requests are intended to suggest minor adjustments, ideas for new
+features, or to kindly influence the project's direction and vision. It is
+important to note that change requests are not intended for reporting bugs, as
+they're missing essential information for debugging.
+
+If you want to report a bug, please refer to our [bug reporting guide] instead.
+
+ [bug reporting guide]: reporting-a-bug.md
+
+### Look for sources of inspiration
+
+If you have seen your idea implemented in another static site generator or
+theme, make sure to collect enough information on its implementation before
+submitting, as this allows us to evaluate potential fit more quickly. Explain
+what you like and dislike about the implementation.
+
+### Connect with our community
+
+Our [discussion board] is the best place to connect with our community. When
+evaluating new ideas, it's essential to seek input from other users and consider
+alternative viewpoints. This approach helps to implement new features in a way
+that benefits a large number of users.
+
+__Keep track of all search terms and relevant links, you'll need
+them in the change request.__[^1]
+
+ [^1]:
+ We might be using terminology in our documentation different from yours,
+ but we mean the same. When you include the search terms and related links
+ in your change request, you help us to adjust and improve the documentation.
+
+[:octicons-comment-discussion-16: Start a discussion][discussion board]{ .md-button .md-button--primary }
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Issue template
+
+Now that you have taken the time to do the necessary preliminary work and ensure
+that your idea meets our requirements, you are invited to create a change
+request. The following guide will walk you through all the necessary steps to
+help you submit a comprehensive and useful issue:
+
+- [Title]
+- [Context] optional
+- [Description]
+- [Related links]
+- [Use cases]
+- [Visuals] optional
+- [Checklist]
+
+ [Title]: #title
+ [Context]: #context
+ [Description]: #description
+ [Related links]: #related-links
+ [Use cases]: #use-cases
+ [Visuals]: #visuals
+ [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the idea, so the potential impact and benefit for our community can
+be inferred from the title.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
+| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Context optional { #context }
+
+Before describing your idea, you can provide additional context for us to
+understand what you are trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the change request here.
+
+> __Why this might be helpful__: some ideas might only benefit specific
+> settings, environments, or edge cases, for example, when your documentation
+> contains thousands of documents. With a little context, change requests
+> can be prioritized more accurately.
+
+### Description
+
+Next, provide a detailed and clear description of your idea. Explain why your
+idea is relevant to Material for MkDocs and must be implemented here and not
+in one of its dependencies:[^2]
+
+ [^2]:
+ Sometimes, users suggest ideas on our [issue tracker] that concern one of
+ our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
+ [Python Markdown Extensions] or third-party plugins. It's a good idea to
+ think about whether your idea is beneficial to other themes, upstreaming
+ change requests for a bigger impact.
+
+- __Explain the what, not the why__ – don't explain
+ [the benefits of your idea][Use cases] here, we're getting there.
+ Focus on describing the proposed change request as precisely as possible.
+
+- __Keep it short and concise__ – be brief and to the point when describing
+ your idea, there is no need to over-describe it. Maintainers and future
+ users will be grateful for having to read less.
+
+- __One idea at a time__ – if you have multiple ideas that don't belong
+ together, please open separate change requests for each of those ideas.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you have a customization or another
+way to add the proposed change, you can help other users by sharing it here
+before we maintainers can add it to our code base.
+
+> __Why we need this__: To understand and evaluate your proposed change, we
+> need to have a clear understanding of your idea. By providing a detailed and
+> precise description, you can help save you and us time spent discussing
+> further clarification of your idea in the comments.
+
+ [Python Markdown]: https://python-markdown.github.io/extensions/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
+### Related links
+
+Please provide any relevant links to issues, discussions, or documentation
+sections related to your change request. If you (or someone else) already
+discussed this idea with our community on our discussion board, please include
+the link to the discussion as well.
+
+> __Why we need this__: Related links help us gain a comprehensive
+> understanding of your change request by providing additional context.
+> Additionally, linking to previous issues and discussions allows us
+> to quickly evaluate the feedback and input already provided by our community.
+
+### Use cases
+
+Explain how your change request would work from an author's and user's
+perspective – what's the expected impact, and why does it not only benefit you,
+but other users? How many of them? Furthermore, would it potentially break
+existing functionality?
+
+> __Why we need this__: Understanding the use cases and benefits of an idea is
+> crucial in evaluating its potential impact and usefulness for the project and
+> its users. This information helps us to understand the expected value of the
+> idea and how it aligns with the goals of the project.
+
+### Visuals optional { #visuals }
+
+We now have a clear and detailed description of your idea, including information
+on its potential use cases and relevant links for context. If you have any
+visuals, such as sketches, screenshots, mockups, or external assets, you may
+present them in this section.
+
+__You can drag and drop the files here or include links to external assets.__
+
+Additionally, if you have seen this change, feature, or improvement used in
+other static site generators or themes, please provide an example by showcasing
+it and describing how it was implemented and incorporated.
+
+> __Why this might be helpful__: Illustrations and visuals can help us
+> maintainers better understand and envision your idea. Screenshots, sketches,
+> or mockups can create an additional level of detail and clarity that text
+> alone may not be able to convey. Also, seeing how your idea has been
+> implemented in other projects can help us understand its potential impact and
+> feasibility in Material for MkDocs, which helps us maintainers evaluate and
+> triage change requests.
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality change request – you
+are almost done. The checklist ensures that you have read this guide and have
+worked to your best knowledge to provide us with every piece of information to
+review your idea for Material for MkDocs.
+
+__We'll take it from here.__
+
+---
+
+## Rejected requests
+
+__Your change request got rejected? We're sorry for that.__ We understand it can
+be frustrating when your ideas don't get accepted, but as the maintainers of a
+very popular project, we always need to consider the needs of our entire
+community, sometimes forcing us to make tough decisions.
+
+We always have to consider and balance many factors when evaluating change
+requests, and we explain the reasoning behind our decisions whenever we can.
+If you're unsure why your change request was rejected, please don't hesitate
+to ask for clarification.
+
+The following principles (in no particular order) form the basis for our
+decisions:
+
+- [ ] Alignment with vision and tone of the project
+- [ ] Compatibility with existing features and plugins
+- [ ] Compatibility with all screen sizes and browsers
+- [ ] Effort of implementation and maintenance
+- [ ] Usefulness to the majority of users
+- [ ] Simplicity and ease of use
+- [ ] Accessibility
+
+But that's not the end of your idea – you can always implement it on your own
+via [customization]. If you're unsure about how to do that or want to know if
+someone has already done it, feel free to get in touch with our community on
+the [discussion board].
+
+ [customization]: ../customization.md
diff --git a/mkdocs-material/docs/conventions.md b/mkdocs-material/docs/conventions.md
new file mode 100644
index 0000000..0363412
--- /dev/null
+++ b/mkdocs-material/docs/conventions.md
@@ -0,0 +1,93 @@
+# Conventions
+
+This section explains several conventions used in this documentation.
+
+## Symbols
+
+This documentation use some symbols for illustration purposes. Before you read
+on, please make sure you've made yourself familiar with the following list of
+conventions:
+
+### – Sponsors only { data-toc-label="Sponsors only" }
+
+The pumping heart symbol denotes that a specific feature or behavior is only
+available to sponsors via [Insiders]. Make sure that you have access to
+[Insiders] if you want to use the feature.
+
+### – Version { data-toc-label="Version" }
+
+The tag symbol in conjunction with a version number denotes when a specific
+feature or behavior was added. Make sure you're at least on this version
+if you want to use it.
+
+### – Version (Insiders) { data-toc-label="Version (Insiders)" }
+
+The tag symbol with a heart in conjunction with a version number denotes that a
+specific feature or behavior was added to the [Insiders] version of Material for
+MkDocs.
+
+### – Default value { #default data-toc-label="Default value" }
+
+Some properties in `mkdocs.yml` have default values for when the author does not
+explicitly define them. The default value of the property is always included.
+
+#### – Default value is computed { #default data-toc-label="is computed" }
+
+Some default values are not set to static values but computed from other values,
+like the site language, repository provider, or other settings.
+
+#### – Default value is empty { #default data-toc-label="is empty" }
+
+Some properties do not contain default values. This means that the functionality
+that is associated with them is not available unless explicitly enabled.
+
+### – Metadata property { #metadata data-toc-label="Metadata property" }
+
+This symbol denotes that the thing described is a metadata property, which can
+be used in Markdown documents as part of the front matter definition.
+
+### – Multiple instances { #multiple-instances data-toc-label="Multiple instances" }
+
+This symbol denotes that the plugin supports multiple instances, i.e, that it
+can be used multiple times in the `plugins` setting in `mkdocs.yml`.
+
+### – Optional feature { #feature data-toc-label="Optional feature" }
+
+Most of the features are hidden behind feature flags, which means they must
+be explicitly enabled via `mkdocs.yml`. This allows for the existence of
+potentially orthogonal features.
+
+### – Experimental { data-toc-label="Experimental" }
+
+Some newer features are still considered experimental, which means they might
+(although rarely) change at any time, including their complete removal (which
+hasn't happened yet).
+
+### – Plugin { data-toc-label="Plugin" }
+
+Several features are implemented through MkDocs excellent plugin architecture,
+some of which are built-in and distributed with Material for MkDocs, so no
+installation is required.
+
+### – Markdown extension { data-toc-label="Markdown extension" #extension }
+
+This symbol denotes that the thing described is a Markdown extension, which can
+be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
+parser.
+
+### – Required value { #required data-toc-label="Required value" }
+
+Some (very few in fact) properties or settings are required, which means the
+authors must explicitly define them.
+
+### – Customization { #customization data-toc-label="Customization" }
+
+This symbol denotes that the thing described is a customization that must be
+added by the author.
+
+### – Utility { data-toc-label="Utility" }
+
+Besides plugins, there are some utilities that build on top of MkDocs in order
+to provide extended functionality, like for example support for versioning.
+
+ [Insiders]: insiders/index.md
diff --git a/mkdocs-material/docs/creating-your-site.md b/mkdocs-material/docs/creating-your-site.md
new file mode 100644
index 0000000..cd0378e
--- /dev/null
+++ b/mkdocs-material/docs/creating-your-site.md
@@ -0,0 +1,269 @@
+# Creating your site
+
+After you've [installed] Material for MkDocs, you can bootstrap your project
+documentation using the `mkdocs` executable. Go to the directory where you want
+your project to be located and enter:
+
+```
+mkdocs new .
+```
+
+Alternatively, if you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
+ ```
+
+=== "Windows (cmd)"
+
+ ```
+ docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
+ ```
+
+This will create the following structure:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+ [installed]: getting-started.md
+
+## Configuration
+
+### Minimal configuration
+
+Simply set the `site_name` and add the following lines to `mkdocs.yml` to enable the theme:
+
+``` yaml hl_lines="2-5"
+site_name: My site
+site_url: https://mydomain.org/mysite
+theme:
+ name: material
+```
+
+The `site_url` setting is important for a number of reasons.
+By default, MkDocs will assume that your site is hosted at the root of
+your domain. This is not the case, for example, when [publishing to GitHub
+pages] - unless you use a custom domain. Another reason is that some of the
+plugins require the `site_url` to be set, so you should always do this.
+
+ [publishing to GitHub pages]: publishing-your-site.md#github-pages
+ [installation methods]: getting-started.md#installation
+
+???+ tip "Recommended: [configuration validation and auto-complete]"
+
+ In order to minimize friction and maximize productivity, Material for MkDocs
+ provides its own [schema.json][^1] for `mkdocs.yml`. If your editor supports
+ YAML schema validation, it's definitely recommended to set it up:
+
+ === "Visual Studio Code"
+
+ 1. Install [`vscode-yaml`][vscode-yaml] for YAML language support.
+ 2. Add the schema under the `yaml.schemas` key in your user or
+ workspace [`settings.json`][settings.json]:
+
+ ``` json
+ {
+ "yaml.schemas": {
+ "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+ },
+ "yaml.customTags": [ // (1)!
+ "!ENV scalar",
+ "!ENV sequence",
+ "!relative scalar",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
+ "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
+ ]
+ }
+ ```
+
+ 1. This setting is necessary if you plan to use [icons and emojis],
+ or Visual Studio Code will show errors on certain lines.
+
+ === "Other"
+
+ 1. Ensure your editor of choice has support for YAML schema validation.
+ 2. Add the following lines at the top of `mkdocs.yml`:
+
+ ``` yaml
+ # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+ ```
+
+ [^1]:
+ If you're a MkDocs plugin or Markdown extension author and your project
+ works with Material for MkDocs, you're very much invited to contribute a
+ schema for your [extension] or [plugin] as part of a pull request on GitHub.
+ If you already have a schema defined, or wish to self-host your schema to
+ reduce duplication, you can add it via [$ref].
+
+ [configuration validation and auto-complete]: https://x.com/squidfunk/status/1487746003692400642
+ [schema.json]: schema.json
+ [vscode-yaml]: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
+ [settings.json]: https://code.visualstudio.com/docs/getstarted/settings
+ [extension]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/extensions
+ [plugin]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/plugins
+ [$ref]: https://json-schema.org/understanding-json-schema/structuring.html#ref
+ [icons and emojis]: reference/icons-emojis.md
+
+### Advanced configuration
+
+Material for MkDocs comes with many configuration options. The setup section
+explains in great detail how to configure and customize colors, fonts, icons
+and much more:
+
+
+
+- [Changing the colors]
+- [Changing the fonts]
+- [Changing the language]
+- [Changing the logo and icons]
+- [Ensuring data privacy]
+- [Setting up navigation]
+- [Setting up site search]
+- [Setting up site analytics]
+- [Setting up social cards]
+- [Setting up a blog]
+- [Setting up tags]
+- [Setting up versioning]
+- [Setting up the header]
+- [Setting up the footer]
+- [Adding a git repository]
+- [Adding a comment system]
+- [Building an optimized site]
+- [Building for offline usage]
+
+
+
+Furthermore, see the list of supported [Markdown extensions] that are natively
+integrated with Material for MkDocs, delivering an unprecedented low-effort
+technical writing experience.
+
+ [Changing the colors]: setup/changing-the-colors.md
+ [Changing the fonts]: setup/changing-the-fonts.md
+ [Changing the language]: setup/changing-the-language.md
+ [Changing the logo and icons]: setup/changing-the-logo-and-icons.md
+ [Ensuring data privacy]: setup/ensuring-data-privacy.md
+ [Setting up navigation]: setup/setting-up-navigation.md
+ [Setting up site search]: setup/setting-up-site-search.md
+ [Setting up site analytics]: setup/setting-up-site-analytics.md
+ [Setting up social cards]: setup/setting-up-social-cards.md
+ [Setting up a blog]: setup/setting-up-a-blog.md
+ [Setting up tags]: setup/setting-up-tags.md
+ [Setting up versioning]: setup/setting-up-versioning.md
+ [Setting up the header]: setup/setting-up-the-header.md
+ [Setting up the footer]: setup/setting-up-the-footer.md
+ [Adding a git repository]: setup/adding-a-git-repository.md
+ [Adding a comment system]: setup/adding-a-comment-system.md
+ [Building for offline usage]: setup/building-for-offline-usage.md
+ [Building an optimized site]: setup/building-an-optimized-site.md
+ [Markdown extensions]: setup/extensions/index.md
+
+## Templates
+
+If you want to jump start a new project, you can use one of our growing
+collection of templates:
+
+
+
+- :octicons-repo-template-24: __[Blog][blog-template]__
+
+ ---
+
+ Create a blog
+
+- :octicons-repo-template-24: __[Social cards][social-cards-template]__
+
+ ---
+
+ Create documentation with social cards
+
+
+
+[blog-template]: https://github.com/mkdocs-material/create-blog
+[social-cards-template]: https://github.com/mkdocs-material/create-social-cards
+
+## Previewing as you write
+
+MkDocs includes a live preview server, so you can preview your changes as you
+write your documentation. The server will automatically rebuild the site upon
+saving. Start it with:
+
+``` sh
+mkdocs serve # (1)!
+```
+
+1. If you have a large documentation project, it might take minutes until
+ MkDocs has rebuilt all pages for you to preview. If you're only interested
+ in the current page, the [`--dirtyreload`][--dirtyreload] flag will make
+ rebuilds much faster:
+
+ ```
+ mkdocs serve --dirtyreload
+ ```
+
+If you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+ ```
+
+=== "Windows"
+
+ ```
+ docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
+ ```
+
+Point your browser to [localhost:8000][live preview] and you should see:
+
+[![Creating your site]][Creating your site]
+
+ [--dirtyreload]: https://www.mkdocs.org/about/release-notes/#support-for-dirty-builds-990
+ [live preview]: http://localhost:8000
+ [Creating your site]: assets/screenshots/creating-your-site.png
+
+## Building your site
+
+When you're finished editing, you can build a static site from your Markdown
+files with:
+
+```
+mkdocs build
+```
+
+If you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
+ ```
+
+=== "Windows"
+
+ ```
+ docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build
+ ```
+
+The contents of this directory make up your project documentation. There's no
+need for operating a database or server, as it is completely self-contained.
+The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
+or your private web space.
+
+ [GitHub Pages]: publishing-your-site.md#github-pages
+ [GitLab pages]: publishing-your-site.md#gitlab-pages
+
+If you intend to distribute your documentation as a set of files to be
+read from a local filesystem rather than a web server (such as in a
+`.zip` file), please read the notes about [building for offline
+usage].
+
+ [building for offline usage]: setup/building-for-offline-usage.md
diff --git a/mkdocs-material/docs/customization.md b/mkdocs-material/docs/customization.md
new file mode 100644
index 0000000..e7f7ac8
--- /dev/null
+++ b/mkdocs-material/docs/customization.md
@@ -0,0 +1,402 @@
+# Customization
+
+Project documentation is as diverse as the projects themselves and Material for
+MkDocs is a great starting point for making it look beautiful. However, as you
+write your documentation, you may reach a point where small adjustments are
+necessary to preserve your brand's style.
+
+## Adding assets
+
+[MkDocs] provides several ways to customize a theme. In order to make a few
+small tweaks to Material for MkDocs, you can just add CSS and JavaScript files to
+the `docs` directory.
+
+ [MkDocs]: https://www.mkdocs.org
+
+### Additional CSS
+
+If you want to tweak some colors or change the spacing of certain elements,
+you can do this in a separate style sheet. The easiest way is by creating a
+new style sheet file in the `docs` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ stylesheets/
+│ └─ extra.css
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra_css:
+ - stylesheets/extra.css
+```
+
+### Additional JavaScript
+
+If you want to integrate another syntax highlighter or add some custom logic to
+your theme, create a new JavaScript file in the `docs` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ javascripts/
+│ └─ extra.js
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra_javascript:
+ - javascripts/extra.js
+```
+
+??? tip "How to integrate with third-party JavaScript libraries"
+
+ It is likely that you will want to run your JavaScript code only
+ once the page has been fully loaded by the browser. This means
+ installing a callback function subscribing to events on the
+ `document$` observable exported by Material for MkDocs.
+ Using the `document$` observable is particularly important if you
+ are using [instant loading] since it will not result in a page
+ refresh in the browser - but subscribers on the observable will be
+ notified.
+
+ ``` javascript
+ document$.subscribe(function() {
+ console.log("Initialize third-party libraries here")
+ })
+ ```
+
+ `document$` is an [RxJS Observable] and you can call the `subscribe()`
+ method any number of times to attach different functionality.
+
+ [instant loading]: setup/setting-up-navigation.md/#instant-loading
+ [RxJS Observable]: https://rxjs.dev/api/index/class/Observable
+
+## Extending the theme
+
+If you want to alter the HTML source (e.g. add or remove some parts), you can
+extend the theme. MkDocs supports [theme extension], an easy way to override
+parts of Material for MkDocs without forking from git. This ensures that you
+can update to the latest version more easily.
+
+ [theme extension]: https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir
+
+### Setup and theme structure
+
+Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
+for `overrides` which you then reference using the [`custom_dir`][custom_dir]
+setting:
+
+``` yaml
+theme:
+ name: material
+ custom_dir: overrides
+```
+
+!!! warning "Theme extension prerequisites"
+
+ As the [`custom_dir`][custom_dir] setting is used for the theme extension
+ process, Material for MkDocs needs to be installed via `pip` and referenced
+ with the [`name`][name] setting in `mkdocs.yml`. It will not work when
+ cloning from `git`.
+
+The structure in the `overrides` directory must mirror the directory structure
+of the original theme, as any file in the `overrides` directory will replace the
+file with the same name which is part of the original theme. Besides, further
+assets may also be put in the `overrides` directory:
+
+``` { .sh .no-copy }
+.
+├─ .icons/ # Bundled icon sets
+├─ assets/
+│ ├─ images/ # Images and icons
+│ ├─ javascripts/ # JavaScript files
+│ └─ stylesheets/ # Style sheets
+├─ partials/
+│ ├─ integrations/ # Third-party integrations
+│ │ ├─ analytics/ # Analytics integrations
+│ │ └─ analytics.html # Analytics setup
+│ ├─ languages/ # Translation languages
+│ ├─ actions.html # Actions
+│ ├─ alternate.html # Site language selector
+│ ├─ comments.html # Comment system (empty by default)
+│ ├─ consent.html # Consent
+│ ├─ content.html # Page content
+│ ├─ copyright.html # Copyright and theme information
+│ ├─ feedback.html # Was this page helpful?
+│ ├─ footer.html # Footer bar
+│ ├─ header.html # Header bar
+│ ├─ icons.html # Custom icons
+│ ├─ language.html # Translation setup
+│ ├─ logo.html # Logo in header and sidebar
+│ ├─ nav.html # Main navigation
+│ ├─ nav-item.html # Main navigation item
+│ ├─ pagination.html # Pagination (used for blog)
+│ ├─ palette.html # Color palette toggle
+│ ├─ post.html # Blog post excerpt
+│ ├─ progress.html # Progress indicator
+│ ├─ search.html # Search interface
+│ ├─ social.html # Social links
+│ ├─ source.html # Repository information
+│ ├─ source-file.html # Source file information
+│ ├─ tabs.html # Tabs navigation
+│ ├─ tabs-item.html # Tabs navigation item
+│ ├─ tags.html # Tags
+│ ├─ toc.html # Table of contents
+│ ├─ toc-item.html # Table of contents item
+│ └─ top.html # Back-to-top button
+├─ 404.html # 404 error page
+├─ base.html # Base template
+├─ blog.html # Blog index page
+├─ blog-archive.html # Blog archive index page
+├─ blog-category.html # Blog category index page
+├─ blog-post.html # Blog post page
+└─ main.html # Default page
+```
+
+ [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+ [name]: https://www.mkdocs.org/user-guide/configuration/#name
+
+### Overriding partials
+
+In order to override a partial, we can replace it with a file of the same name
+and location in the `overrides` directory. For example, to replace the original
+`footer.html` partial, create a new `footer.html` partial in the `overrides`
+directory:
+
+``` { .sh .no-copy }
+.
+├─ overrides/
+│ └─ partials/
+│ └─ footer.html
+└─ mkdocs.yml
+```
+
+MkDocs will now use the new partial when rendering the theme. This can be done
+with any file.
+
+### Overriding blocks recommended { #overriding-blocks data-toc-label="Overriding blocks" }
+
+Besides overriding partials, it's also possible to override (and extend)
+template blocks, which are defined inside the templates and wrap specific
+features. In order to set up block overrides, create a `main.html` file inside
+the `overrides` directory:
+
+``` { .sh .no-copy }
+.
+├─ overrides/
+│ └─ main.html
+└─ mkdocs.yml
+```
+
+Then, e.g. to override the site title, add the following lines to `main.html`:
+
+``` html
+{% extends "base.html" %}
+
+{% block htmltitle %}
+ Lorem ipsum dolor sit amet
+{% endblock %}
+```
+
+If you intend to __add__ something to a block rather than to replace it
+altogether with new content, use `{{ super() }}` inside the block to include the
+original block content. This is particularly useful when adding third-party
+scripts to your docs, e.g.
+
+``` html
+{% extends "base.html" %}
+
+{% block scripts %}
+
+ {{ super() }}
+
+{% endblock %}
+```
+
+The following template blocks are provided by the theme:
+
+| Block name | Purpose |
+| :---------------- | :---------------------------------------------- |
+| `analytics` | Wraps the Google Analytics integration |
+| `announce` | Wraps the announcement bar |
+| `config` | Wraps the JavaScript application config |
+| `container` | Wraps the main content container |
+| `content` | Wraps the main content |
+| `extrahead` | Empty block to add custom meta tags |
+| `fonts` | Wraps the font definitions |
+| `footer` | Wraps the footer with navigation and copyright |
+| `header` | Wraps the fixed header bar |
+| `hero` | Wraps the hero teaser (if available) |
+| `htmltitle` | Wraps the `` tag |
+| `libs` | Wraps the JavaScript libraries (header) |
+| `outdated` | Wraps the version warning |
+| `scripts` | Wraps the JavaScript application (footer) |
+| `site_meta` | Wraps the meta tags in the document head |
+| `site_nav` | Wraps the site navigation and table of contents |
+| `styles` | Wraps the style sheets (also extra sources) |
+| `tabs` | Wraps the tabs navigation (if available) |
+
+## Theme development
+
+Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], and
+uses a lean, custom build process to put everything together.[^1] If you want
+to make more fundamental changes, it may be necessary to make the adjustments
+directly in the source of the theme and recompile it.
+
+ [^1]:
+ Prior to the build was based on Webpack, resulting
+ in occasional broken builds due to incompatibilities with loaders and
+ plugins. Therefore, we decided to swap Webpack for a leaner solution which
+ is now based on [RxJS] as the application itself. This allowed for the
+ pruning of more than 500 dependencies (~30% less).
+
+ [TypeScript]: https://www.typescriptlang.org/
+ [RxJS]: https://github.com/ReactiveX/rxjs
+ [SASS]: https://sass-lang.com
+
+### Environment setup
+
+First, clone the repository for the edition you want to work on. If
+you want to clone the Insiders repository, you need to become a
+sponsor first to gain access.
+
+ [Insiders]: insiders/index.md
+
+=== "Material for MkDocs"
+
+ ```
+ git clone https://github.com/squidfunk/mkdocs-material
+ cd mkdocs-material
+ ```
+
+=== "Insiders"
+
+ You will need to have a GitHub access token [as described in the
+ Insiders documentation] and make it available in the `$GH_TOKEN`
+ variable.
+
+ ``` sh
+ git clone https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git # (1)!
+ ```
+
+ 1. If you are using SSH keys for authenticating with GitHub, you can
+ clone Insiders with this command:
+
+ ```
+ git clone git@github.com:squidfunk/mkdocs-material-insiders.git
+ ```
+
+ [as described in the Insiders documentation]: insiders/getting-started.md#requirements
+
+Next, create a new [Python virtual environment][venv] and
+[activate][venv-activate] it:
+
+```
+python -m venv venv
+source venv/bin/activate
+```
+
+!!! note "Ensure pip always runs in a virtual environment"
+
+ If you set the environment variable `PIP_REQUIRE_VIRTUALENV` to
+ `true`, `pip` will refuse to install anything outside a virtual
+ environment. Forgetting to activate a `venv` can be very annoying
+ as it will install all sorts of things outside virtual
+ environments over time, possibly leading to further errors. So,
+ you may want to add this to your `.bashrc` or `.zshrc` and
+ re-start your shell:
+
+ ```
+ export PIP_REQUIRE_VIRTUALENV=true
+ ```
+
+ [venv]: https://docs.python.org/3/library/venv.html
+ [venv-activate]: https://docs.python.org/3/library/venv.html#how-venvs-work
+
+Then, install all Python dependencies:
+
+=== "Material for MkDocs"
+
+ ```
+ pip install -e ".[recommended]"
+ pip install nodeenv
+ ```
+
+=== "Insiders"
+
+ ```
+ pip install -e ".[recommended, imaging]"
+ pip install nodeenv
+ ```
+
+ In addition, you will need to install the `cairo` and `pngquant` libraries in your
+ system, as described in the [image processing] requirements guide.
+
+ [image processing]: plugins/requirements/image-processing.md
+
+
+Finally, install the [Node.js] LTS version into the Python virtual environment
+and install all Node.js dependencies:
+
+```
+nodeenv -p -n lts
+npm install
+```
+
+ [Node.js]: https://nodejs.org
+
+### Development mode
+
+Start the watcher with:
+
+```
+npm start
+```
+
+Then, in a second terminal window, start the MkDocs live preview server with:
+
+```
+mkdocs serve --watch-theme
+```
+
+Point your browser to [localhost:8000][live preview] and you should see this
+very documentation in front of you.
+
+!!! warning "Automatically generated files"
+
+ Never make any changes in the `material` directory, as the contents of this
+ directory are automatically generated from the `src` directory and will be
+ overwritten when the theme is built.
+
+ [live preview]: http://localhost:8000
+
+### Building the theme
+
+When you're finished making your changes, you can build the theme by invoking:
+
+``` sh
+npm run build # (1)!
+```
+
+1. While this command will build all theme files, it will skip the overrides
+ used in Material for MkDocs' own documentation which are not distributed
+ with the theme. If you forked the theme and want to build the overrides
+ as well, e.g. before submitting a PR with changes, use:
+
+ ```
+ npm run build:all
+ ```
+
+ This will take longer, as now the icon search index, schema files, as
+ well as additional style sheet and JavaScript files are built.
+
+This triggers the production-level compilation and minification of all style
+sheets and JavaScript files. After the command exits, the compiled files are
+located in the `material` directory. When running `mkdocs build`, you should
+now see your changes to the original theme.
diff --git a/mkdocs-material/docs/enterprise-support.md b/mkdocs-material/docs/enterprise-support.md
new file mode 100644
index 0000000..bd027ff
--- /dev/null
+++ b/mkdocs-material/docs/enterprise-support.md
@@ -0,0 +1,32 @@
+---
+status: new
+---
+
+# Enterprise Feedback
+
+We highly value the insights of our enterprise users, and we're eager to hear
+from you. Your feedback is immensely valuable to us. If you're utilizing
+Material for MkDocs in an enterprise context and would like to share your
+experiences with us, we'd love to connect and discuss:
+
+- What you are building with it
+- What aspects you like about it
+- What challenges you are facing
+- What could be improved
+
+## Let's Connect
+
+To schedule a convenient appointment, please reach out to us via email at
+contact@squidfunk.com and provide us with the following details:
+
+- Your company's name
+- How you are using Material for MkDocs
+- Any specific questions or topics you'd like to address
+
+Once we have this information, we'll promptly get in touch with you to arrange
+a 30-minute call. Please note that this call is exclusively intended for
+enterprise users and is not meant for technical support. Instead, it's an
+opportunity for us to engage in a casual conversation to better understand your
+unique needs.
+
+We look forward to our discussion!
diff --git a/mkdocs-material/docs/getting-started.md b/mkdocs-material/docs/getting-started.md
new file mode 100644
index 0000000..9706e7e
--- /dev/null
+++ b/mkdocs-material/docs/getting-started.md
@@ -0,0 +1,177 @@
+# Getting started
+
+Material for MkDocs is a powerful documentation framework on top of [MkDocs],
+a static site generator for project documentation.[^1] If you're familiar with
+Python, you can install Material for MkDocs with [`pip`][pip], the Python
+package manager. If not, we recommend using [`docker`][docker].
+
+ [^1]:
+ In 2016, Material for MkDocs started out as a simple theme for MkDocs, but
+ over the course of several years, it's now much more than that – with the
+ many built-in plugins, settings, and countless customization abilities,
+ Material for MkDocs is now one of the simplest and most powerful frameworks
+ for creating documentation for your project.
+
+ [MkDocs]: https://www.mkdocs.org
+ [pip]: #with-pip
+ [docker]: #with-docker
+
+## Installation
+
+### with pip recommended { #with-pip data-toc-label="with pip" }
+
+Material for MkDocs is published as a [Python package] and can be installed with
+`pip`, ideally by using a [virtual environment]. Open up a terminal and install
+Material for MkDocs with:
+
+=== "Latest"
+
+ ``` sh
+ pip install mkdocs-material
+ ```
+
+=== "9.x"
+
+ ``` sh
+ pip install mkdocs-material=="9.*" # (1)!
+ ```
+
+ 1. Material for MkDocs uses [semantic versioning][^2], which is why it's a
+ good idea to limit upgrades to the current major version.
+
+ This will make sure that you don't accidentally [upgrade to the next
+ major version], which may include breaking changes that silently corrupt
+ your site. Additionally, you can use `pip freeze` to create a lockfile,
+ so builds are reproducible at all times:
+
+ ```
+ pip freeze > requirements.txt
+ ```
+
+ Now, the lockfile can be used for installation:
+
+ ```
+ pip install -r requirements.txt
+ ```
+
+ [^2]:
+ Note that improvements of existing features are sometimes released as
+ patch releases, like for example improved rendering of content tabs, as
+ they're not considered to be new features.
+
+This will automatically install compatible versions of all dependencies:
+[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
+MkDocs always strives to support the latest versions, so there's no need to
+install those packages separately.
+
+---
+
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
+27m – Learn how to create and host a documentation site using Material for
+MkDocs on GitHub Pages in a step-by-step guide.
+
+ [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=xlABhbnNrfI
+
+---
+
+!!! tip
+
+ If you don't have prior experience with Python, we recommend reading
+ [Using Python's pip to Manage Your Projects' Dependencies], which is a
+ really good introduction on the mechanics of Python package management and
+ helps you troubleshoot if you run into errors.
+
+ [Python package]: https://pypi.org/project/mkdocs-material/
+ [virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
+ [semantic versioning]: https://semver.org/
+ [upgrade to the next major version]: upgrade.md
+ [Markdown]: https://python-markdown.github.io/
+ [Pygments]: https://pygments.org/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [Using Python's pip to Manage Your Projects' Dependencies]: https://realpython.com/what-is-pip/
+
+### with docker
+
+The official [Docker image] is a great way to get up and running in a few
+minutes, as it comes with all dependencies pre-installed. Open up a terminal
+and pull the image with:
+
+=== "Latest"
+
+ ```
+ docker pull squidfunk/mkdocs-material
+ ```
+
+=== "9.x"
+
+ ```
+ docker pull squidfunk/mkdocs-material:9
+ ```
+
+The `mkdocs` executable is provided as an entry point and `serve` is the
+default command. If you're not familiar with Docker don't worry, we have you
+covered in the following sections.
+
+The following plugins are bundled with the Docker image:
+
+- [mkdocs-minify-plugin]
+- [mkdocs-redirects]
+
+ [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+ [mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
+ [mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
+
+??? question "How to add plugins to the Docker image?"
+
+ Material for MkDocs only bundles selected plugins in order to keep the size
+ of the official image small. If the plugin you want to use is not included,
+ you can add them easily:
+
+ === "Material for MkDocs"
+
+ Create a `Dockerfile` and extend the official image:
+
+ ``` Dockerfile title="Dockerfile"
+ FROM squidfunk/mkdocs-material
+ RUN pip install mkdocs-macros-plugin
+ RUN pip install mkdocs-glightbox
+ ```
+
+ === "Insiders"
+
+ Clone or fork the Insiders repository, and create a file called
+ `user-requirements.txt` in the root of the repository. Then, add the
+ plugins that should be installed to the file, e.g.:
+
+ ``` txt title="user-requirements.txt"
+ mkdocs-macros-plugin
+ mkdocs-glightbox
+ ```
+
+ Next, build the image with the following command:
+
+ ```
+ docker build -t squidfunk/mkdocs-material .
+ ```
+
+ The new image will have additional packages installed and can be used
+ exactly like the official image.
+
+### with git
+
+Material for MkDocs can be directly used from [GitHub] by cloning the
+repository into a subfolder of your project root which might be useful if you
+want to use the very latest version:
+
+```
+git clone https://github.com/squidfunk/mkdocs-material.git
+```
+
+Next, install the theme and its dependencies with:
+
+```
+pip install -e mkdocs-material
+```
+
+ [GitHub]: https://github.com/squidfunk/mkdocs-material
diff --git a/mkdocs-material/docs/guides/creating-a-reproduction.md b/mkdocs-material/docs/guides/creating-a-reproduction.md
new file mode 100644
index 0000000..d7a4faa
--- /dev/null
+++ b/mkdocs-material/docs/guides/creating-a-reproduction.md
@@ -0,0 +1,124 @@
+# Creating a reproduction
+
+A reproduction is a simplified version of a bug that demonstrates the specific
+scenario in which the bug occurred. It includes all necessary minimal settings
+and instructions and should be as simple as possible while still demonstrating
+the issue.
+
+## Guide
+
+### Environment optional { #environment }
+
+We recommend using a [virtual environment], which is an isolated Python runtime.
+If you are in a virtual environment, any packages that you install or upgrade
+will be local to the environment. If you run into problems, you can
+just delete and recreate the environment. It's trivial to set up:
+
+- Create a new virtual environment with:
+
+ ```
+ python3 -m venv venv
+ ```
+
+- Activate the environment with:
+
+ === ":material-apple: macOS"
+
+ ``` sh
+ . venv/bin/activate
+ ```
+
+ === ":fontawesome-brands-windows: Windows"
+
+ ``` sh
+ . venv/Scripts/activate
+ ```
+
+ === ":material-linux: Linux"
+
+ ``` sh
+ . venv/bin/activate
+ ```
+
+
+ Your terminal should now print `(venv)` before the prompt, which is how you
+ know that you are inside the virtual environment that you just created.
+
+- Exit the environment with:
+
+ ```
+ deactivate
+ ```
+
+ [virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
+
+### Minimal reproduction
+
+Following the instructions below, you will set up a skeleton project to create
+a reproduction. As mentioned above, we recommend using a [virtual environment],
+so create a new folder in your working directory and a new virtual environment
+inside it. Next:
+
+1. As mentioned in our [bug reporting guide], ensure that you're running the
+ latest version of Material for MkDocs, which might already include a fix for
+ the bug:
+
+ ```
+ pip install --upgrade --force-reinstall mkdocs-material
+ ```
+
+2. Bootstrap a new documentation project using the `mkdocs` executable,
+ which you use as a basis for the reproduction. It's essential to create a
+ new, empty project for this:
+
+ ```
+ mkdocs new .
+ ```
+
+ Start by adding the [minimal configuration] in `mkdocs.yml`:
+
+ ``` yaml
+ theme:
+ name: material
+ ```
+
+3. Now, only add the necessary settings to `mkdocs.yml` to keep the
+ reproduction minimal. If you are creating a reproduction for a rendering
+ bug, create only the necessary amount of Markdown documents. __Repeat this
+ step until the bug you want to report can be observed.__
+
+4. As a last step, before packing everything into a `.zip` file, double-check
+ all settings and documents if they are essential to the reproduction, which
+ means that the bug does not occur when they are omitted. Remove all
+ non-essential lines and files.
+
+ [bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+ [minimal configuration]: ../creating-your-site.md#minimal-configuration
+
+### Creating a `.zip` file
+
+Material for MkDocs 9.0.0 includes a new plugin solely intended to create
+reproductions for bug reports. When the built-in info plugin is enabled, MkDocs
+will add all relevant files to a `.zip`, print a summary to the terminal and
+exit. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - info
+```
+
+Now, when running `mkdocs build`, a file called `example.zip` is automatically
+created, containing the minimal reproduction you can directly attach to your bug
+report.
+
+```
+INFO - Started archive creation for bug report
+INFO - Archive successfully created:
+
+ example/.dependencies.json 859.0 B
+ example/.versions.log 83.0 B
+ example/docs/index.md 282.0 B
+ example/mkdocs.yml 56.0 B
+
+ example.zip 1.8 kB
+```
diff --git a/mkdocs-material/docs/index.md b/mkdocs-material/docs/index.md
new file mode 100644
index 0000000..3aea9df
--- /dev/null
+++ b/mkdocs-material/docs/index.md
@@ -0,0 +1,9 @@
+---
+template: home.html
+title: Material for MkDocs
+social:
+ cards_layout_options:
+ title: Documentation that simply works
+---
+
+Welcome to Material for MkDocs.
diff --git a/mkdocs-material/docs/insiders/access-management.md b/mkdocs-material/docs/insiders/access-management.md
new file mode 100644
index 0000000..cd8d997
--- /dev/null
+++ b/mkdocs-material/docs/insiders/access-management.md
@@ -0,0 +1,204 @@
+# Access management
+
+The Material for MkDocs Insiders repository is a private repository hosted on
+GitHub and access is, therefore, managed through GitHub. This section covers
+everything you need to know in order to gain access to the private Material for
+MkDocs Insiders repository.
+
+## How to get access
+
+As the private Material for MkDocs Insiders repository is hosted on GitHub, you
+require a GitHub account to become a sponsor and to gain access. After
+sponsoring us on one of our [sponsoring tiers] starting at [$15 a month],
+you'll get access to the private Insiders repository.
+
+Please note that the process of gaining access is only partially automatable due
+to technical reasons. Depending on the type of account you've used to become a
+sponsor, we might need more information from you before we can grant access.
+
+ [$15 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+ [sponsoring tiers]: sponsoring-tiers.md
+
+### Individuals
+
+If you sponsor using a [personal account], you will receive an invitation link
+via email to the private Material for MkDocs Insiders repository immediately
+after initiating your sponsorship. This link is [valid for seven days]. Once you
+accept the invitation, you'll be ready to [get started].
+
+If the link expired, please contact us at sponsors@squidfunk.com and we'll
+send you a new one.
+
+ [personal account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
+ [valid for seven days]: #expired-invitations
+ [get started]: getting-started.md
+
+### Organizations
+
+When sponsoring using an [organization account], GitHub will not send an
+automated invitation via email to access the private Material for MkDocs Insiders
+repository. Due to [GitHub limitations], granting access to a private repository
+for an entire organization is not possible.
+
+Therefore, please contact us at sponsors@squidfunk.com with the name of a
+[personal account] or the name of a [bot account] that is publicly or privately
+listed as an owner of your GitHub organization after you received a confirmation
+that your sponsorship was initiated.
+
+We will add this designated account as a collaborator, and once the invitation
+is [accepted within seven days], your organization will be all set to [get
+started].
+
+ [organization account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
+ [GitHub limitations]: #collaborators
+ [bot account]: #bot-account
+ [accepted within seven days]: #expired-invitations
+
+### Enterprises
+
+If you would like to sponsor us using an [enterprise account], we recommend
+using a [personal account] or a [bot account] to initiate the sponsorship and
+access the private Material for MkDocs Insiders repository using this account.
+
+ [enterprise account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#enterprise-accounts
+
+## Restrictions
+
+GitHub sets limitations beyond our control, which is why we require further
+information regarding [collaborators] of private repositories and [matching] of
+GitHub accounts.
+
+ [collaborators]: #collaborators
+ [matching]: #matching
+
+### Collaborators
+
+GitHub policy limits access to [private repositories] to [personal accounts]
+only, which is why it is currently not possible for us to add [organization
+accounts] to the Material for MkDocs Insiders repository – a private
+repository.
+
+As much as we would love to give each member of your organization access, it's
+simply not feasible for us to add each member account, which is why every
+[sponsoring tier] is limited to one seat. However, you can use a [bot account]
+to work around this limitation.
+
+ [private repositories]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository
+ [personal accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
+ [organization accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
+ [sponsoring tier]: sponsoring-tiers.md
+ [team management]: #team-management
+
+### Matching
+
+Due to privacy reasons, GitHub does not allow email addresses to be matched with
+GitHub accounts. When requesting access via email at sponsors@squidfunk.com,
+it's necessary to provide us with the name of a [personal account].
+
+## Bot account
+
+Given that only personal accounts can be listed as collaborators on
+[private repositories], ensuring access for an entire organization requires
+coordination through individuals. Changes within the team could lead to losing
+access to the entire organization.
+
+To avoid this, you have the option to create a bot account, which is
+[a new personal account] that does not belong to a specific individual but is
+publicly or privately listed as the owner of the GitHub organization
+
+Using a bot account for access management and initiating your [public] or
+[private] sponsorship through it also allows for better attribution of
+sponsorship costs, allowing you to manage access and payment for all
+sponsorships through a single account, and is thus recommended.
+
+ [a new personal account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
+ [public]: privacy.md/#public-sponsors
+ [private]: privacy.md/#private-sponsors
+
+## Expired invitations
+
+The invitation to the private Material for MkDocs is valid for seven days, a
+limitation imposed by GitHub. If invitations are not accepted within this
+period, you'll need to contact us via mail at sponsors@squidfunk.com, and we
+will re-issue the invitation immediately.
+
+## Team management
+
+If you are using Material for MkDocs Insiders as an [individual] and don't
+collaborate with other users, [forking] the private repository is not necessary.
+However, when working with a team, it is not possible to simply share your
+collaborator status with other accounts. Therefore, in order to work in a team,
+the account with access to Insiders can [fork], [clone], or [mirror] the private
+Material for MkDocs Insiders repository to an organization, providing a pathway
+for team collaboration.
+
+ [fork]: #forking
+ [clone]: #cloning
+ [mirror]: #mirroring
+ [individual]: #individuals
+
+### Outside collaborators
+
+When working with outside collaborators, you should know that the Insiders
+edition is compatible with the community edition. All new features and
+configuration options are backward-compatible or implemented behind feature
+flags. Most Insiders features enhance the overall experience, e.g., by creating
+better social cards or instant previews. While these features add value for your
+site's users, they are most certainly not necessary for previewing your site.
+
+This means that outside collaborators can build the documentation locally with
+the community edition, and when they push their changes, your CI pipeline will
+build it with Insiders. When using [built-in plugins] exclusive to Insiders, we
+recommend using the [group] plugin.
+
+See the [getting started guide] for more information.
+ [getting started guide]: getting-started.md
+ [built-in plugins]: ../plugins/index.md
+ [group]: ../plugins/group.md
+
+### Forking
+
+[Forking] a repository creates a copy of the repository that allows for
+independent development while maintaining a link to the original repository
+for updates.
+
+ [forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+
+### Cloning
+
+[Cloning] a repository copies the repository to your local machine or codespace,
+facilitating offline work and content management. You can, of course, also
+[clone a private fork].
+
+ [cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+ [clone a private fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository
+
+### Mirroring
+
+[Mirroring] a repository creates an identical copy, ensuring you have the
+flexibility to host and work with the repository [in other environments] besides
+GitHub. This is a particularly useful strategy for organizations hosting their
+repositories in a private environment outside of GitHub.
+
+ [mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
+ [in other environments]: #github-alternatives
+
+## GitHub alternatives
+
+Material for MkDocs Insiders is designed to be compatible with various
+repository hosting platforms, including GitLab. The key requirement is still a
+GitHub account, as we use GitHub Sponsors for transactions and GitHub to manage access to the private Insiders repository.
+
+Once you've become a sponsor and secured access to the private Insiders
+repository via an individual GitHub account, you can [mirror the repository in
+another location]. This mirroring process not only allows for easy integration
+into your existing workflow but also ensures that your projects stay up-to-date
+with the latest features and improvements of Insiders.
+
+Our discussion board is a valuable resource for any questions about integrating
+Material for MkDocs Insiders into your projects. It offers a space to connect
+with others who may have similar requirements and setups, as well as to
+exchange tips and explore solutions together.
+
+ [mirror the repository in another location]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository-in-another-location
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/mkdocs-material/docs/insiders/benefits.md b/mkdocs-material/docs/insiders/benefits.md
new file mode 100644
index 0000000..f960160
--- /dev/null
+++ b/mkdocs-material/docs/insiders/benefits.md
@@ -0,0 +1,345 @@
+# What’s in it for you
+
+Material for MkDocs Insiders is packed with additional features that are
+exclusively available to our monthly sponsors – the moment you become a sponsor,
+you'll gain __immediate access__ to all the exclusive Insiders features, ready
+for you to __start using now__.
+
+## Features
+
+Our sponsors currently enjoy access to the following 26 additional features. New
+features are added regularly, so be sure to check back regularly to stay
+updated.
+
+
+
+## What's coming next
+
+> Too many ideas, too little time!
+
+Our backlog is filled with countless ideas that we came up with or that have
+been suggested by our community. We're also working to make our roadmap public.
+If you have something specific in mind, and wonder whether we've considered it,
+feel free to ask on our [discussion board].
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Frequent releases
+
+We’re committed to quickly addressing bugs, that come up and keeping our open
+issue count as low as possible. Both our community and Insiders editions are
+regularly updated, ensuring you have the latest features and fixes available at
+all times.
+
+## Additional benefits
+
+As a premium sponsors, you'll enjoy additional benefits that are not available
+to our individual sponsors. When sponsoring our work on one of our [commercial
+tiers] starting at [$125 a month], you'll get additional benefits that we offer
+for enterprises:
+
+- [Prioritized] bug reports to keep your projects running smoothly
+- Logo placement and backlink on our site for increased visibility
+- Private support via email for any questions to our maintainers
+
+ [commercial tiers]: sponsoring-tiers.md/#commercial-use
+ [$125 a month]: sponsoring-tiers.md/#the-organization
+ [list of premium sponsors]: https://github.com/squidfunk/mkdocs-material#user-content-premium-sponsors
+ [Prioritized]: ../support.md/#prioritized-support
+
+----
+
+Interested in supporting us? Together, let’s continue to make Material for
+MkDocs an even more powerful tool for everyone. We’re excited for what the
+future holds!
+
+[:octicons-heart-fill-24:{ .mdx-heart } Show your support ][sponsoring tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring tiers]: sponsoring-tiers.md#commercial-use
+
+
+
+## Funding
+
+### Goals
+
+The following section lists all funding goals. Each goal contains a list of
+features prefixed with a checkmark symbol, denoting whether a feature is
+:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or
+:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" }
+planned, but not yet implemented. This means that each funding goal unlocks new
+features for general availability in the community edition, after sponsors have
+used them for a while.
+
+#### $ 16,000 – Chipotle
+
+- [x] [Meta plugin]
+- [x] [Blog plugin: related links]
+- [x] [Blog plugin: custom index pages]
+- [x] [Tags plugin: configurable listings]
+- [x] [Tags plugin: allow list] + [custom sorting]
+- [x] [Navigation subtitles]
+
+ [Meta plugin]: ../plugins/meta.md
+ [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
+ [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
+ [Tags plugin: configurable listings]: ../setup/setting-up-tags.md#configurable-listings
+ [Tags plugin: allow list]: ../plugins/tags.md#config.tags_allowed
+ [custom sorting]: ../plugins/tags.md#config.tags_sort_by
+ [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
+
+#### $ 18,000 – Lemon Drop
+
+- [x] [Optimize plugin]
+- [x] [Navigation path] (Breadcrumbs)
+- [x] [Blog plugin: advanced settings]
+- [x] [Blog plugin: author profiles]
+- [x] [Blog plugin: pinned posts]
+- [x] [Instant prefetching]
+
+ [Optimize plugin]: ../plugins/optimize.md
+ [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
+ [Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings
+ [Blog plugin: author profiles]: ../setup/setting-up-a-blog.md#adding-author-profiles
+ [Blog plugin: pinned posts]: ../setup/setting-up-a-blog.md#pinning-a-post
+ [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
+
+#### $ 20,000 – Jalapeño
+
+- [x] [Typeset plugin]
+- [x] [Footnote tooltips]
+- [x] [Privacy plugin: advanced settings]
+- [x] [Privacy plugin: external links]
+- [ ] to be announced
+- [ ] to be announced
+
+ [Typeset plugin]: ../plugins/typeset.md
+ [Footnote tooltips]: ../reference/footnotes.md#footnote-tooltips
+ [Privacy plugin: external links]: ../plugins/privacy.md#external-links
+ [Privacy plugin: advanced settings]: ../setup/ensuring-data-privacy.md#advanced-settings
+
+#### $ 22,000 – Habanero Orange
+
+- [x] [Instant previews]
+- [x] [Social plugin: custom layouts]
+- [x] [Social plugin: background images]
+- [x] [Code range selection]
+- [x] [Code annotations: custom selectors]
+- [x] [Stay on page when switching languages]
+
+ [Instant previews]: ../setup/setting-up-navigation.md#instant-previews
+ [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
+ [Social plugin: background images]: ../plugins/social.md#option.background_image
+ [Code range selection]: ../reference/code-blocks.md#code-selection-button
+ [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
+ [Stay on page when switching languages]: ../setup/changing-the-language.md#stay-on-page
+
+#### $ 24,000 – Blockpaprika
+
+- [x] [Projects plugin]
+- [x] [Tags plugin: nested tags]
+- [x] [Tags plugin: shadow tags]
+- [x] [Tags plugin: advanced settings]
+- [ ] to be announced
+- [ ] to be announced
+
+ [Projects plugin]: ../plugins/projects.md
+ [Tags plugin: nested tags]: ../setup/setting-up-tags.md#nested-tags
+ [Tags plugin: shadow tags]: ../setup/setting-up-tags.md#shadow-tags
+ [Tags plugin: advanced settings]: ../setup/setting-up-tags.md#advanced-settings
+
+### Goals completed
+
+This section celebrates the milestones we’ve achieved thanks to our incredible
+sponsors. Those features were once part of Material for MkDocs Insiders, and
+therefore only available to our sponsors, and are now generally available to
+be used by all users.
+
+#### $ 14,000 – Goat's Horn
+
+- [x] [Privacy plugin]
+- [x] [Card grids]
+- [x] [Tooltips]
+- [x] [Content tabs: anchor links]
+- [x] [Automatic light / dark mode]
+- [x] [Document contributors]
+
+ [Privacy plugin]: ../setup/ensuring-data-privacy.md#built-in-privacy-plugin
+ [Card grids]: ../reference/grids.md
+ [Tooltips]: ../reference/tooltips.md
+ [Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links
+ [Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode
+ [Document contributors]: ../setup/adding-a-git-repository.md#document-contributors
+
+#### $ 12,000 – Piri Piri
+
+- [x] [Blog plugin]
+- [x] [Chinese search support]
+- [x] [Annotations]
+- [x] [Navigation icons]
+- [x] [Navigation pruning]
+- [x] [Navigation status]
+
+ [Blog plugin]: ../setup/setting-up-a-blog.md
+ [Chinese search support]: ../blog/posts/chinese-search-support.md
+ [Annotations]: ../reference/annotations.md
+ [Navigation icons]: ../reference/index.md#setting-the-page-icon
+ [Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning
+ [Navigation status]: ../reference/index.md#setting-the-page-status
+
+#### $ 10,000 – Carolina Reaper
+
+- [x] [Brand new search plugin]
+- [x] [Rich search previews]
+- [x] [Tokenizer with lookahead]
+- [x] [Advanced search highlighting]
+- [x] [Excluding content from search]
+- [x] [Offline plugin]
+
+ [Brand new search plugin]: ../blog/posts/search-better-faster-smaller.md
+ [Rich search previews]: ../blog/posts/search-better-faster-smaller.md#rich-search-previews
+ [Tokenizer with lookahead]: ../blog/posts/search-better-faster-smaller.md#tokenizer-lookahead
+ [Advanced search highlighting]: ../blog/posts/search-better-faster-smaller.md#accurate-highlighting
+ [Excluding content from search]: ../setup/setting-up-site-search.md#search-exclusion
+ [Offline plugin]: ../setup/building-for-offline-usage.md
+
+#### $ 8,000 – Scotch Bonnet
+
+- [x] [Social cards]
+- [x] Code annotations: anchor links
+- [x] [Code annotations: strip comments]
+- [x] [Tag icons]
+- [x] [Table of contents anchor following]
+- [x] Sidebars automatically scroll to active item
+
+ [Social cards]: ../setup/setting-up-social-cards.md
+ [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
+ [Tag icons]: ../setup/setting-up-tags.md#tag-icons-and-identifiers
+ [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
+
+#### $ 7,000 – Royal Gold
+
+- [x] [Cookie consent]
+- [x] [Was this page helpful?]
+- [x] [Dismissable announcement bar]
+
+ [Cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
+ [Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful
+ [Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read
+
+#### $ 6,000 – Trinidad Scorpion
+
+- [x] [Boosting pages in search]
+- [x] [Custom admonition icons]
+- [x] [Linking content tabs]
+
+ [Boosting pages in search]: ../setup/setting-up-site-search.md#search-boosting
+ [Custom admonition icons]: ../reference/admonitions.md#admonition-icons
+ [Linking content tabs]: ../reference/content-tabs.md#linked-content-tabs
+
+#### $ 5,000 – Aji Panca
+
+- [x] [Mermaid.js integration]
+- [x] Stay on page when switching versions
+- [x] [Tags with search integration]
+
+ [Mermaid.js integration]: ../reference/diagrams.md
+ [Tags with search integration]: ../setup/setting-up-tags.md
+
+#### $ 4,000 – Ghost Pepper
+
+- [x] [Anchor tracking]
+- [x] [Code annotations]
+- [x] [Version warning]
+
+ [Anchor tracking]: ../setup/setting-up-navigation.md#anchor-tracking
+ [Code annotations]: ../reference/code-blocks.md#adding-annotations
+ [Version warning]: ../setup/setting-up-versioning.md#version-warning
+
+#### $ 3,000 – Caribbean Red
+
+- [x] [Sticky navigation tabs]
+- [x] [Section index pages]
+- [x] [Remove generator notice]
+
+ [Sticky navigation tabs]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
+ [Section index pages]: ../setup/setting-up-navigation.md#section-index-pages
+ [Remove generator notice]: ../setup/setting-up-the-footer.md#generator-notice
+
+#### $ 2,500 – Biquinho Vermelho
+
+- [x] [Search suggestions]
+- [x] [Search highlighting]
+- [x] [Search sharing]
+
+ [Search suggestions]: ../setup/setting-up-site-search.md#search-suggestions
+ [Search highlighting]: ../setup/setting-up-site-search.md#search-highlighting
+ [Search sharing]: ../setup/setting-up-site-search.md#search-sharing
+
+#### $ 2,000 – Black Pearl
+
+- [x] Latest release tag
+- [x] [Color palette toggle]
+- [x] [Back-to-top button]
+
+ [Color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
+ [Back-to-top button]: ../setup/setting-up-navigation.md#back-to-top-button
+
+#### $ 1,500 – Bhut Jolokia
+
+- [x] [Admonition inline blocks]
+- [x] [Site language selection]
+- [x] [Versioning]
+
+ [Admonition inline blocks]: ../reference/admonitions.md#inline-blocks
+ [Site language selection]: ../setup/changing-the-language.md#site-language-selector
+ [Versioning]: ../setup/setting-up-versioning.md#versioning
+
+#### $ 1,000 – Prairie Fire
+
+- [x] [Navigation sections]
+- [x] [Navigation expansion]
+- [x] [Hiding the sidebars]
+- [x] [Table of contents in navigation]
+- [x] [Header hides on scroll]
+
+ [Navigation sections]: ../setup/setting-up-navigation.md#navigation-sections
+ [Navigation expansion]: ../setup/setting-up-navigation.md#navigation-expansion
+ [Hiding the sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
+ [Table of contents in navigation]: ../setup/setting-up-navigation.md#navigation-integration
+ [Header hides on scroll]: ../setup/setting-up-the-header.md#automatic-hiding
+
+#### $ 500 – Madame Jeanette
+
+- [x] Improved search result grouping
+- [x] Improved search result relevance and scoring
+- [x] Missing query terms in search results
diff --git a/mkdocs-material/docs/insiders/changelog/index.md b/mkdocs-material/docs/insiders/changelog/index.md
new file mode 100644
index 0000000..0e3aca7
--- /dev/null
+++ b/mkdocs-material/docs/insiders/changelog/index.md
@@ -0,0 +1,1115 @@
+# Changelog
+
+## Material for MkDocs Insiders
+
+### 4.53.14 September 29, 2024 { id="4.53.14" }
+
+- Fixed #7567: Empty headlines when using typeset plugin with anchorlinks
+
+### 4.53.13 September 14, 2024 { id="4.53.13" }
+
+- Fixed #7520: Social plugin errors for generated files (MkDocs 1.6+)
+
+### 4.53.12 August 2, 2024 { id="4.53.12" }
+
+- Fixed #7410: Instant previews jump on content tabs with anchor links
+- Fixed #7408: Instant previews jump on content tabs
+
+### 4.53.11 May 27, 2024 { id="4.53.11" }
+
+- Fixed projects plugin crashing when serving before building subprojects
+
+### 4.53.10 May 20, 2024 { id="4.53.10" }
+
+- Fixed projects plugin crashing in serve mode when disabled
+- Fixed projects plugin crashing when building nested projects
+
+### 4.53.9 May 20, 2024 { id="4.53.9" }
+
+- Fixed #7191: Tags listings not rendering when `toc_depth` is changed
+
+### 4.53.8 April 26, 2024 { id="4.53.8" }
+
+- Fixed #7052: Preview extension automatically including all pages
+- Fixed #7051: Instant previews mounting on footnote references
+- Fixed #5165: Improved tooltips not mounting in sidebar for typeset plugin
+
+### 4.53.7 April 25, 2024 { id="4.53.7" }
+
+- Fixed #7060: Incorrect resolution of translation when using static-i18n
+
+### 4.53.6 April 5, 2024 { id="4.53.6" }
+
+- Ensure working directory is set for projects when using projects plugin
+- Fixed #6970: Incorrect relative paths in git submodules with projects plugin
+
+### 4.53.5 April 2, 2024 { id="4.53.5" }
+
+- Fixed social plugin crashing when no colors are specified in palettes
+
+### 4.53.4 March 31, 2024 { id="4.53.4" }
+
+- Fixed #6973: Escaping issue in tags extra files deprecation helper
+
+### 4.53.3 March 23, 2024 { id="4.53.3" }
+
+- Added support for font variants in social plugin
+- Improved resilience of font resolution in social plugin
+- Fixed tag listing sometimes not being auto-populated
+- Fixed tag listing scope not being correctly resolved
+- Fixed #6941: Meta plugin adding duplicate entries
+- Fixed #6928: Social plugin crashes for some fonts
+
+### 4.53.2 March 18, 2024 { id="4.53.2" }
+
+- Fixed abort on first non-matching configuration in preview extension
+- Fixed #6914: Meta files take precedence over front matter
+
+### 4.53.1 March 6, 2024 { id="4.53.1" }
+
+- Fixed #6877: Projects plugin computes incorrect path to assets
+- Fixed #6869: Blog plugin should emit warning on invalid related link
+
+### 4.53.0 February 24, 2024 { id="4.53.0" }
+
+- Added support for automatic instant previews
+- Added support for pinned blog posts
+
+### 4.52.3 February 21, 2024 { id="4.52.3" }
+
+- Fixed resolution of URLs in instant previews
+- Fixed instant previews not mounting for same-page links
+
+### 4.52.2 February 7, 2024 { id="4.52.2" }
+
+- Fixed #6735: Instant previews misplaced when below tabs
+
+### 4.52.1 January 30, 2024 { id="4.52.1" }
+
+- Fixed #6705: Navigation path not being hidden when specified
+- Fixed #6703: New tags plugin crashes on Windows (2nd attempt)
+
+### 4.52.0 January 28, 2024 { id="4.52.0" }
+
+- Added support for instant previews
+- Fixed footnote tooltips positioning edge cases
+- Fixed #6703: New tags plugin crashes on Windows
+
+### 4.51.0 January 24, 2024 { id="4.51.0" }
+
+- Added support for footnote tooltips
+
+### 4.50.0 January 19, 2024 { id="4.50.0" }
+
+- Added configurable logging capabilities to privacy plugin
+
+### 4.49.2 January 9, 2024 { id="4.49.2" }
+
+- Fixed missing attribute lists extension for tags plugin
+- Fixed #6627: New tags plugin crashes on Python 3.8
+
+### 4.49.1 January 7, 2024 { id="4.49.1" }
+
+- Improved interop of new tags plugin with other plugins
+- Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
+- Fixed #6569: Social plugin crashes if in different file system location
+
+### 4.49.0 December 29, 2023 { id="4.49.0" }
+
+- Added support for exporting tags and mappings
+- Added support for disabling tags and/or listings or both
+- Fixed tag links from pages to listings on homepage
+
+### 4.48.0 December 23, 2023 { id="4.48.0" }
+
+- Rewrite of tags plugin, now much more powerful
+- Added support for nested tags (tag hierarchies, e.g. foo/bar)
+- Added support for shadow tags (by list, prefix or suffix)
+- Added support for custom tag layouts and templates
+- Added support for hiding tags in table of contents
+- Added support for configurable inline tag listings
+- Added support for automatically linking to closest tag listing
+- Added support for scoped listings (limit to subsection of site)
+- Added support for multiple instances of tags plugin
+- Added support for changing front matter property and template variable
+- Added support for tag slugification format strings
+- Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
+- Fixed projects plugin not notifying plugins about serve mode
+- Fixed projects plugin skipping projects on prefix match
+- Deprecated tags_file and tags_extra_files settings
+- Modernized tags plugin code base
+
+### 4.47.1 December 11, 2023 { id="4.47.1" }
+
+- Improved editing experience for projects plugin
+- Improved resilience of optimize and social plugin
+- Fixed race condition when writing manifest in optimize and social plugin
+- Fixed #6475: Logo not taking precedence over icon in social card
+- Fixed #6399: Projects plugin doesn't pick up added/removed projects
+- Fixed #6306: Projects plugin cache not correctly updated
+
+### 4.47.0 December 8, 2023 { id="4.47.0" }
+
+- Added support for staying on page when switching languages
+- Added configurable logging capabilities to projects plugin
+- Removed temporary warning on blog plugin authors file format change
+- Fixed projects plugin logging messages twice on Linux systems
+- Fixed projects plugin trying to hoist theme assets of divergent themes
+- Fixed compatibility of optimize plugin and projects plugin
+- Fixed compatibility of social plugin and projects plugin
+- Fixed #6448: Code line selection broken for code blocks with custom ids
+- Fixed #6437: Projects plugin crashing for certain site URL configurations
+- Fixed #6414: Projects plugin doesn't prefix messages coming from projects
+
+### 4.46.0 November 26, 2023 { id="4.46.0" }
+
+- Added support for author profiles in blog plugin
+- Fixed custom index pages yielding two navigation items (4.45.0 regression)
+
+### 4.45.0 November 24, 2023 { id="4.45.0" }
+
+- Added support for sorting blog categories by post count or custom function
+- Improved tags plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of multiple authors in blog plugin
+
+### 4.44.0 November 23, 2023 { id="4.44.0" }
+
+- Added pagination settings for archive pages in blog plugin
+- Added pagination settings for category pages in blog plugin
+
+### 4.43.1 November 19, 2023 { id="4.43.1" }
+
+- Added third-party theme support in projects plugin, improving editing
+- Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
+- Fixed #6306: Projects plugin not reloading nested project configuration
+
+### 4.43.0 November 5, 2023 { id="4.43.0" }
+
+- Added support for GitLab committers (document contributors)
+- Fixed #6264: Fixed compatibility with Python < 3.10
+- Fixed #6254: Meta plugin not applying meta files to blog posts
+
+### 4.42.3 October 27, 2023 { id="4.42.3" }
+
+- Fixed #6251: Cards in grids cut off on very small screens
+- Fixed #6241: Using social plugin + static-i18n plugin errors
+
+### 4.42.2 October 14, 2023 { id="4.42.2" }
+
+- Fixed #6186: Privacy plugin ignores hash fragments on images
+- Fixed #6180: Projects plugin crashing when adding or removing files
+
+### 4.42.1 October 5, 2023 { id="4.42.1" }
+
+- Fixed spacing of related links in blog posts on small screens
+
+### 4.42.0 September 19, 2023 { id="4.42.0" }
+
+- Added support for using git submodules in projects plugin
+- Added support for transforming project configurations
+- Improved resilience of optimize and blog plugin
+- Fixed optimize plugin crashing on `.jpeg` extension
+- Fixed project URLs not using site URLs in projects plugin
+
+### 4.41.0 September 11, 2023 { id="4.41.0" }
+
+- Improved multi-instance support for optimize plugin
+- Added inclusion and exclusion patterns for optimize plugin
+- Added transparent keyword for color handling in social plugin
+- Changed default quality of PNGs to 3 in optimize plugin
+- Fixed #5979: meta file not detected in root of docs directory
+
+### 4.40.4 September 4, 2023 { id="4.40.4" }
+
+- Fixed privacy plugin choking on boolean HTML5 attributes
+- Fixed wrapping of inline code blocks in typeset table of contents
+- Fixed blog plugin error when running under dirty reload
+
+### 4.40.3 September 2, 2023 { id="4.40.3" }
+
+- Fixed #5946: Docker image missing pngquant for optimize plugin
+
+### 4.40.2 August 31, 2023 { id="4.40.2" }
+
+- Added configurable error handling capabilities for social plugin
+- Fixed #5922: Blog plugin shows no posts when building a standalone blog
+- Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
+- Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
+
+### 4.40.1 August 27, 2023 { id="4.40.1" }
+
+- Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
+- Fixed empty category pages in blog plugin (4.40.0 regression)
+
+### 4.40.0 August 26, 2023 { id="4.40.0" }
+
+- Added logo, title and description options to social plugin default layouts
+- Fixed privacy plugin compatibility issue with Python < 3.10
+- Fixed #5896: Blog plugin errors when using custom index pages
+
+### 4.39.3 August 24, 2023 { id="4.39.3" }
+
+- Fixed lxml dependency missing in Docker container (4.39.2 regression)
+
+### 4.39.2 August 23, 2023 { id="4.39.2" }
+
+- Fixed color palette toggle being reversed (9.2.0 regression)
+
+### 4.39.1 August 21, 2023 { id="4.39.1" }
+
+- Fixed git diff in tags plugin after merging back 9.2.0 changes
+
+### 4.39.0 August 3, 2023 { id="4.39.0" }
+
+- Added support for hoisting theme media files when building projects
+- Added support for sorting pages on tags index for tags plugin
+- Added support for adding date of last update to blog posts
+- Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
+### 4.38.1 August 1, 2023 { id="4.38.1" }
+
+- Improved nested serve mode for projects plugin
+- Improved compat in privacy plugin with third-party plugins
+- Fixed #5790: Typeset plugin ignores data-toc-label attribute
+- Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+- Fixed #5773: Info plugin erroring when community edition is in beta
+
+### 4.38.0 July 29, 2023 { id="4.38.0" }
+
+- Added projects plugin for building nested projects
+- Updated privacy plugin to new MkDocs API
+
+### 4.37.1 July 28, 2023 { id="4.37.1" }
+
+- Updated MkDocs to 1.5.1
+- Fixed deprecation warning in social plugin due to MkDocs upgrade
+- Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+### 4.37.0 July 7, 2023 { id="4.37.0" }
+
+- Added support for overriding social cards settings per page
+- Added new social card `default/only/image` layout
+- Improved resilience of optimize and social plugin
+- Fixed rendering bugs for pruned navigation items
+- Fixed jumping of content tabs anchor links when instant loading is enabled
+- Fixed #5676: Optimize plugin doesn't check for `pngquant`
+
+### 4.36.1 June 23, 2023 { id="4.36.1" }
+
+- Fixed #5618: Date comparison breaking for drafts in blog plugin
+
+### 4.36.0 June 15, 2023 { id="4.36.0" }
+
+- Added support for instant prefetching to speed up slow connections
+- Improved stability of anchor link removal in built-in typeset plugin
+- Improved performance of regular expressions in typeset plugin
+- Removed unnecessary import test for `cairosvg` in optimize plugin
+- Fixed #5590: Regular expression for anchor link removal too greedy
+
+### 4.35.3 June 1, 2023 { id="4.35.3" }
+
+- Fixed #5579: Abbreviations in headlines filtered by typeset plugin
+
+### 4.35.2 May 29, 2023 { id="4.35.2" }
+
+- Fixed #5555: Blog plugin crashes when computing readtime for emojis
+
+### 4.35.1 May 20, 2023 { id="4.35.1" }
+
+- Fixed internal handling of errors in social plugin
+
+### 4.35.0 May 20, 2023 { id="4.35.0" }
+
+- Improve editing experience and stability of social plugin
+- Added support for custom layout syntax validation in social plugin
+- Added support for layer origin for easier placement in social plugin
+- Added support for in- and exclusion patterns in social plugin
+- Catch and print syntax errors in custom layouts
+
+### 4.34.1 May 16, 2023 { id="4.34.1" }
+
+- Disable social plugin debug mode by default on mkdocs build
+- Added warning in social plugin debug mode when font style couldn't be found
+- Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+- Fixed #5521: Social plugin triggers race condition when downloading fonts
+- Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+### 4.34.0 May 14, 2023 { id="4.34.0" }
+
+- Added support for new overflow mode to auto-fit text in social plugin
+- Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+- Improved print styles for (code) annotation lists
+- Improved performance of social plugin, now 3x as fast
+- Improved interop of typeset plugin with MkDocstrings
+- Fixed logo location for variants of default template in social plugin
+- Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+### 4.33.2 May 12, 2023 { id="4.33.2" }
+
+- Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+- Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+- Fixed #5505: Social plugin trying to resolve logo in wrong location
+- Fixed #5496: Annotations with nested lists incorrectly mounted
+- Fixed #5493: Social plugin crashes on Python 3.8
+
+### 4.33.1 May 9, 2023 { id="4.33.1" }
+
+- Added support for SVG background images in social plugin
+
+### 4.33.0 May 8, 2023 { id="4.33.0" }
+
+- Added support for custom layouts for social plugin
+- Added support for background images for social cards
+
+### 4.32.6 April 22, 2023 { id="4.32.6" }
+
+- Fixed #5336: Interplay of blog plugin with git-revision-date-localized
+
+### 4.32.5 April 7, 2023 { id="4.32.5" }
+
+- Fixed #5322: Navigation tabs hoist nested page icons
+
+### 4.32.4 March 24, 2023 { id="4.32.4" }
+
+- Fixed #5241: Built-in typeset plugin jams navigation for anchors in headings
+
+### 4.32.3 March 9, 2023 { id="4.32.3" }
+
+- Fixed Docker image release workflow (9.1.0 regression)
+- Fixed #5159: Missing underline for abbreviations (9.1.0 regression)
+
+### 4.32.2 February 23, 2023 { id="4.32.2" }
+
+- Fixed #5127: Privacy plugin not handling large number of occurrences
+- Fixed #5126: Privacy plugin breaks when replacing specific emojis
+
+### 4.32.1 February 23, 2023 { id="4.32.1" }
+
+- Fixed code block spans interfering with copying
+- Fixed #5077: Privacy plugin breaks image `alt` text encoding
+- Fixed #5079: Privacy plugin removing `rel=me` on external links
+
+### 4.32.0 February 19, 2023 { id="4.32.0" }
+
+- Added support for custom selectors for code annotations
+- Added support for code line range selection for better sharing
+
+### 4.31.0 February 18, 2023 { id="4.31.0" }
+
+- Added support for table of contents on blog index and archive pages
+- Fixed #4512: Allow custom search field boosts (experimental)
+
+### 4.30.2 February 13, 2023 { id="4.30.2" }
+
+- Fixed privacy plugin excludes not working (4.30.0 regression)
+
+### 4.30.1 February 12, 2023 { id="4.30.1" }
+
+- Fixed privacy plugin not handling static templates (e.g. `404.html`)
+
+### 4.30.0 February 6, 2023 { id="4.30.0" }
+
+- Rewrite of privacy plugin for concurrency, now twice as fast
+- Added support for explicit inclusion for privacy plugin
+- Added optimization support for privacy plugin (+ optimize plugin)
+
+### 4.29.0 January 21, 2023 { id="4.29.0" }
+
+- Added built-in optimize plugin for automatically compressing images
+- Switched reporting in built-in privacy plugin to `info` level
+
+### 4.28.1 January 17, 2023 { id="4.28.1" }
+
+- Fixed built-in info plugin erroring for Insiders on version check
+- Fixed #4865: Navigation paths render bug when there's no top-level section
+- Fixed #4875: Added support for hiding navigation paths
+- Improved navigation path to not render for a single item
+
+### 4.28.0 January 14, 2023 { id="4.28.0" }
+
+- Added support for navigation path (breadcrumbs)
+
+### 4.27.1 December 20, 2022 { id="4.27.1" }
+
+- Fixed rendering of succeeding navigation items in typeset plugin
+- Fixed #4795: Built-in typeset plugin changes MkDocs' title precedence
+- Fixed #4724: Blog plugin not rendering integrate table of contents
+
+### 4.27.0 December 20, 2022 { id="4.27.0" }
+
+- Added built-in typeset plugin to preserve formatting in sidebars
+- Added URL and table of contents support for blog categories
+
+### 4.26.6 November 28, 2022 { id="4.26.6" }
+
+- Fixed #4683: Tags plugin crashes when a tag is empty
+
+### 4.26.5 November 27, 2022 { id="4.26.5" }
+
+- Fixed #4632: Post excerpt title link doesn't point to top of the page
+
+### 4.26.4 November 27, 2022 { id="4.26.4" }
+
+- Fixed redundant file extension when using privacy plugin
+
+### 4.26.3 November 15, 2022 { id="4.26.3" }
+
+- Fixed #4637: Attachments w/o titles in related links error in blog plugin
+- Fixed #4631: Remote favicons not downloaded and inlined by privacy plugin
+
+### 4.26.2 November 3, 2022 { id="4.26.2" }
+
+- Updated MkDocs to 1.4.2
+- Added support for tag compare functions when sorting on index pages
+- Fixed footnotes being rendered in post excerpts without separators
+- Fixed error in blog plugin when `toc` extension is not enabled
+- Fixed issues with invalid asset paths and linked post titles
+- Fixed #4572: Privacy plugin fails when symlinks cannot be created
+- Fixed #4545: Blog plugin doesn't automatically link headline to post
+- Fixed #4542: Blog plugin doesn't allow for multiple instances
+- Fixed #4532: Blog plugin doesn't allow for mixed use of date and datetime
+
+### 4.26.1 October 22, 2022 { id="4.26.1" }
+
+- Improved reporting of configuration errors in tags plugin
+- Fixed #4515: Privacy plugin fails when site URL is not defined
+- Fixed #4514: Privacy plugin doesn't fetch Google fonts (4.26.0 regression)
+
+### 4.26.0 October 18, 2022 { id="4.26.0" }
+
+- Refactored privacy plugin to prepare for new features
+- Added support for `rel=noopener` links in privacy plugin
+- Resolve encoding issues with blog and privacy plugin
+
+### 4.25.5 October 16, 2022 { id="4.25.5" }
+
+- Updated MkDocs to 1.4.1
+- Added namespace prefix to built-in plugins
+- Updated `content` and `header` partial
+
+### 4.25.4 October 9, 2022 { id="4.25.4" }
+
+- Fixed other path issues for standalone blogs (4.24.2 regression)
+
+### 4.25.3 October 9, 2022 { id="4.25.3" }
+
+- Fixed #4457: Posts not collected for standalone blog (4.24.2 regression)
+
+### 4.25.2 October 4, 2022 { id="4.25.2" }
+
+- Fixed #4452: Blog and tags plugin crash when specifying slugify function
+
+### 4.25.1 October 3, 2022 { id="4.25.1" }
+
+- Updated `mkdocs-rss-plugin` in `Dockerfile` to fix MkDocs compat errors
+
+### 4.25.0 October 2, 2022 { id="4.25.0" }
+
+- Added support for navigation subtitles
+- Added support for defining an allow list for built-in tags plugin
+- Added support for custom slugify functions for built-in tags plugin
+- Improved stability of search plugin when using `--dirtyreload`
+
+### 4.24.2 October 1, 2022 { id="4.24.2" }
+
+- Updated MkDocs to 1.4
+- Fixed compatibility issues with MkDocs 1.4
+- Fixed incorrectly generated paths in privacy plugin
+- Fixed blog index page not showing navigation when using meta plugin
+
+### 4.24.1 September 30, 2022 { id="4.24.1" }
+
+- Fixed #4430: build error when enabling consent without repository URL
+
+### 4.24.0 September 27, 2022 { id="4.24.0" }
+
+- Added support for custom content on index pages (blog)
+- Added support for keeping content on paginated index pages (blog)
+- Added support for limiting categories in post excerpts (blog)
+- Added support for simple override of templates via front matter (blog)
+- Added icon in navigation for pages with encrypted content
+- Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+- Improved performance by building post excerpts once (blog)
+
+### 4.23.6 September 22, 2022 { id="4.23.6" }
+
+- Fixed #4389: Blog posts in first week of year in wrong archive
+- Fixed (= switched) footer previous and next links for blog posts
+
+### 4.23.5 September 18, 2022 { id="4.23.5" }
+
+- Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+- Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+### 4.23.4 September 14, 2022 { id="4.23.4" }
+
+- Fixed #4365: Recursion error in blog plugin due to `deepcopy`
+- Fixed path errors for blog plugin on Windows
+- Fixed publishing workflow in forked repositories
+
+### 4.23.3 September 13, 2022 { id="4.23.3" }
+
+- Fixed previous and next page links for drafts of blog posts
+
+### 4.23.2 September 13, 2022 { id="4.23.2" }
+
+- Fixed #4348: Blog plugin crashes on custom `nav` title
+- Fixed blog plugin crashing when category contained only drafts
+- Fixed rendering of content from blog index file
+
+### 4.23.1 September 12, 2022 { id="4.23.1" }
+
+- Fixed #4345: Blog plugin errors with default settings
+
+### 4.23.0 September 12, 2022 { id="4.23.0" }
+
+- Added blogging support via built-in blog plugin
+
+### 4.22.1 September 7, 2022 { id="4.22.1" }
+
+- Fixed #4217: Tooltips in data tables render in wrong position
+
+### 4.22.0 August 21, 2022 { id="4.22.0" }
+
+- Added support for navigation status
+
+### 4.21.1 August 13, 2022 { id="4.21.1" }
+
+- Fixed #4176: Broken image when avatar is served by Gravatar
+- Fixed #4212: Deferred search initialization for file:// locations
+
+### 4.21.0 July 17, 2022 { id="4.21.0" }
+
+- Added meta plugin: set front matter for all pages in a folder
+- Fixed #4114: Tags plugin fails if only `tags_extra_files` is set
+
+### 4.20.1 July 11, 2022 { id="4.20.1" }
+
+- Fixed #4105: Tags plugin fails if `tags_file` is not set (4.20.0 regression)
+
+### 4.20.0 July 7, 2022 { id="4.20.0" }
+
+- Added support for additional tags indexes
+- Fixed #4100: Tag icons not shown in tags index
+
+### 4.19.2 July 4, 2022 { id="4.19.2" }
+
+- Fixed #4051: Privacy plugin fails if symlinking isn't allowed on Windows
+
+### 4.19.1 June 25, 2022 { id="4.19.1" }
+
+- Added `mkdocs-git-committers-plugin` to Dockerfile
+- Added `mkdocs-git-revision-date-localized-plugin` to Dockerfile
+
+### 4.19.0 June 24, 2022 { id="4.19.0" }
+
+- Added support for document contributors
+- Updated French translations for cookie consent
+
+### 4.18.2 June 16, 2022 { id="4.18.2" }
+
+- Fixed #4026: Fixed tooltips not mounted for nested navigation links
+
+### 4.18.1 June 14, 2022 { id="4.18.1" }
+
+- Fixed #3990: Chinese search highlighting not working on non-boundaries
+
+### 4.18.0 June 11, 2022 { id="4.18.0" }
+
+- Added support for automatic dark/light mode
+- Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows
+
+### 4.17.2 June 5, 2022 { id="4.17.2" }
+
+- Added support for custom jieba dictionaries (Chinese search)
+
+### 4.17.1 June 5, 2022 { id="4.17.1" }
+
+- Added support for cookie consent reject button
+- Added support for cookie consent custom button ordering
+- Fixed #3988: Content tab not focused after alternating anchor links
+
+### 4.17.0 June 4, 2022 { id="4.17.0" }
+
+- Added support for content tabs anchor links (deep linking)
+- Fixed #3975: Detect composition events in search interface (Chinese)
+- Fixed #3980: Search plugin doesn't use title set via front matter
+
+### 4.16.2 May 29, 2022 { id="4.16.2" }
+
+- Fixed #3961: Nested sections triggered build error for navigation tabs
+
+### 4.16.1 May 28, 2022 { id="4.16.1" }
+
+- Switched feedback widget rating titles to tooltips
+- Improved contrast of link colors for light/dark color schemes
+- Fixed #3950: Sticky navigation tabs rendering broken (4.15.2 regression)
+- Fixed #3958: Links invisible when using `white` primary color
+
+### 4.16.0 May 25, 2022 { id="4.16.0" }
+
+- Added support for navigation pruning
+- Fixed search results for non-segmented characters (4.15.2 regression)
+
+### 4.15.2 May 22, 2022 { id="4.15.2" }
+
+- Removed workaround for `abbr` on touch devices (superseded by tooltips)
+- Fixed #3915: Improved Chinese search query segmentation
+- Fixed #3938: Fixed tooltips position for navigation titles with ellipsis
+
+### 4.15.1 May 14, 2022 { id="4.15.1" }
+
+- Improved performance of element focus observables
+- Fixed #3531: Added prev/next buttons to content tabs
+- Fixed tooltip positioning when host element is hidden
+
+### 4.15.0 May 8, 2022 { id="4.15.0" }
+
+- Added support for improved tooltips
+- Fixed #3785: Show tooltip on hover for overflowing navigation link
+
+### 4.14.0 May 5, 2022 { id="4.14.0" }
+
+- Added Chinese language support to built-in search plugin
+- Fixed all-numeric page titles raising error in social plugin
+
+### 4.13.2 April 30, 2022 { id="4.13.2" }
+
+- Improved caching of downloaded resources in privacy plugin
+- Fixed #3851: External images not downloaded by privacy plugin
+
+### 4.13.1 April 25, 2022 { id="4.13.1" }
+
+- Fixed #3839: Tags plugin breaks without icons (4.13.0 regression)
+
+### 4.13.0 April 24, 2022 { id="4.13.0" }
+
+- Added support for tag icons
+
+### 4.12.0 March 27, 2022 { id="4.12.0" }
+
+- Added support for card grids and grid layouts
+- Fixed #3685: Annotations sometimes broken when using instant loading
+- Fixed #3742: Automatically add Mermaid.js when building for offline usage
+
+### 4.11.0 March 6, 2022 { id="4.11.0" }
+
+- Added support for excluding external assets from privacy plugin
+
+### 4.10.1 March 2, 2022 { id="4.10.1" }
+
+- Added missing build dependencies to Dockerfile
+- Fixed encoding issues in privacy plugin, now forcing UTF-8 encoding
+- Fixed #3624: Scroll to active navigation item unreliable in Firefox
+- Fixed #3642: Privacy plugin errors when font setting was omitted
+
+### 4.10.0 February 27, 2022 { id="4.10.0" }
+
+- Added support for offline plugin (supersedes offline search support)
+- Improved built-in privacy plugin to download nested JavaScript assets
+- Refactored configuration of built-in privacy plugin
+
+### 4.9.1 February 21, 2022 { id="4.9.1" }
+
+- Fixed #3610: missing `lxml` dependency for privacy plugin
+- Fixed error when charset is missing in `content-type` header
+
+### 4.9.0 February 20, 2022 { id="4.9.0" }
+
+- Added privacy plugin: automatic downloading of external assets
+
+### 4.8.3 February 13, 2022 { id="4.8.3" }
+
+- Fixed #3560: Mermaid diagrams don't render for `file://` locations
+
+### 4.8.2 February 10, 2022 { id="4.8.2" }
+
+- Fixed #3559: Mermaid diagrams don't render inside closed `details`
+
+### 4.8.1 February 6, 2022 { id="4.8.1" }
+
+- Fixed jump back to top on mobile when using anchor following
+
+### 4.8.0 February 6, 2022 { id="4.8.0" }
+
+- Added support for anchor following table of contents (= auto scroll)
+
+### 4.7.2 February 2, 2022 { id="4.7.2" }
+
+- Fixed #3526: Transparent sidebar title due to Safari bug
+- Fixed #3528: Firefox sometimes clips text in flow chart diagrams
+
+### 4.7.1 January 30, 2022 { id="4.7.1" }
+
+- Fixed #3506: Tags index not respecting title set via front matter
+
+### 4.7.0 January 25, 2022 { id="4.7.0" }
+
+- Added native support for offline search
+
+### 4.6.1 January 16, 2022 { id="4.6.1" }
+
+- Fixed #3459: Section index pages picking up wrong title
+
+### 4.6.0 January 11, 2022 { id="4.6.0" }
+
+- Added support for annotations (outside of code blocks)
+
+### 4.5.2 January 8, 2022 { id="4.5.2" }
+
+- Fixed #3440: Content tab indicator not moving when using linking
+- Fixed #3445: Content tab switch flickers/jitters when using linking
+
+### 4.5.1 January 2, 2022 { id="4.5.1" }
+
+- Added support for setting initial state of cookie consent
+- Fixed #3396: Disappearing link in navigation due to Safari bug
+
+### 4.5.0 December 16, 2021 { id="4.5.0" }
+
+- Added support for navigation icons
+
+### 4.4.0 December 10, 2021 { id="4.4.0" }
+
+- Added support for code annotation anchor links (deep linking)
+- Added new code annotation syntax modifier to strip comment
+- Updated German translations for cookie consent
+
+### 4.3.0 December 5, 2021 { id="4.3.0" }
+
+- Added support for custom fonts in social cards
+- Fixed #3300: Announcement bar reappearing when using instant loading
+
+### 4.2.0 December 2, 2021 { id="4.2.0" }
+
+- Added support for dismissible announcement bar
+- Added support for named placeholders in feedback widget
+
+### 4.1.0 November 30, 2021 { id="4.1.0" }
+
+- Added support for passing page title to feedback forms
+
+### 4.0.0 November 28, 2021 { id="4.0.0" }
+
+- Removed deprecated content tabs legacy implementation
+- Removed deprecated `seealso` admonition type
+- Removed deprecated `site_keywords` setting (unsupported by MkDocs)
+- Removed deprecated prebuilt search index support
+- Removed deprecated web app manifest – use customization
+- Removed `extracopyright` variable – use new `copyright` partial
+- Removed Disqus integration – use customization
+- Switched to `:is()` selectors for simple selector lists
+- Switched autoprefixer from `last 4 years` to `last 2 years`
+- Improved CSS overall to match modern standards
+- Improved CSS variable semantics for fonts
+- Improved extensibility by restructuring partials
+- Improved handling of `details` when printing
+- Improved keyboard navigation for footnotes
+- Fixed #3214: Search highlighting breaks site when empty
+
+### 3.2.3 November 20, 2021 { id="3.2.3" }
+
+- Updated Swedish and French translations
+- Removed support for `.mermaid-experimental` class (now `.mermaid`)
+- Fixed #3202: Cookie consent not dismissable on `file://` locations
+- Fixed #3216: Cookie consent not dismissed when invoked via anchor
+- Fixed #3232: Mermaid.js sometimes runs twice (race condition)
+
+### 3.2.2 November 6, 2021 { id="3.2.2" }
+
+- Fixed always last feedback rating being sent
+- Fixed #3145: Code annotations eat whole comment lines
+- Fixed #3170: Feedback widget doesn't send data to GA4
+
+### 3.2.1 November 4, 2021 { id="3.2.1" }
+
+- Added support for custom Mermaid.js version via additional JavaScript
+- Fixed some configuration edge cases for tags plugin (3.1.5 regression)
+- Fixed feedback widget title not being centered in Firefox
+- Fixed #3179: Safari doesn't send request for feedback widget
+
+### 3.2.0 October 31, 2021 { id="3.2.0" }
+
+- Added support for feedback widget (Was this page helpful?)
+
+### 3.1.5 October 28, 2021 { id="3.1.5" }
+
+- Fixed #3144: Rogue link when using tags with auto-populated navigation
+- Fixed #3147: Code block line numbers appear in search results
+- Fixed #3158: Social cards do not strip HTML tags from title
+
+### 3.1.4 October 17, 2021 { id="3.1.4" }
+
+- Fixed #2974: Text cropped with other fonts than `Roboto` in social plugin
+- Fixed #3099: Encoding problems with non-latin character in social plugin
+- Fixed #3112: Japanese segmenter not executed as part of new tokenizer
+- Fixed tags (front matter) appearing in search with disabled tags plugin
+
+### 3.1.3 October 12, 2021 { id="3.1.3" }
+
+- Added warnings to search plugin for unsupported options and syntax
+- Fixed #3503: Search sometimes returns entire page
+- Fixed #3089: Single-line code annotations disappear when printing
+
+### 3.1.2 October 6, 2021 { id="3.1.2" }
+
+- Fixed incorrect path separators for social cards on Windows
+
+### 3.1.1 September 26, 2021 { id="3.1.1" }
+
+- Fixed ordering bug in search exclusion logic
+
+### 3.1.0 September 26, 2021 { id="3.1.0" }
+
+- Added support for excluding pages, sections, and elements from search
+- Fixed #2803: Code block annotations not visible when printing
+
+### 3.0.1 September 19, 2021 { id="3.0.1" }
+
+- Added support for using literal `h1-6` tags for search plugin
+- Fixed search plugin breaking on void elements without slashes
+- Fixed search plugin filtering link contents from headlines
+- Fixed search plugin handling of multiple `h1` headlines
+- Fixed search plugin handling of missing `h1` headlines
+
+### 3.0.0 September 13, 2021 { id="3.0.0" }
+
+- Rewrite of MkDocs' search plugin
+- Added support for rich search previews
+- Added support for tokenizer with lookahead
+- Improved search indexing performance (twice as fast)
+- Improved search highlighting
+
+### 2.13.3 September 1, 2021 { id="2.13.3" }
+
+- Added support for disabling social card generation
+
+### 2.13.2 August 25, 2021 { id="2.13.2" }
+
+- Fixed #2965: Social plugin error when primary color is not defined
+
+### 2.13.1 August 21, 2021 { id="2.13.1" }
+
+- Fixed #2948: Social cards are not cached
+- Fixed #2953: Mermaid.js diagrams can't be centered anymore
+
+### 2.13.0 August 7, 2021 { id="2.13.0" }
+
+- Added support for custom colors in social cards
+
+### 2.12.2 August 4, 2021 { id="2.12.2" }
+
+- Fixed #2891: Division by zero error in social plugin
+
+### 2.12.1 July 26, 2021 { id="2.12.1" }
+
+- Fixed error in social plugin when `site_description` was not set
+- Fixed error in social plugin for non-ASCII characters
+
+### 2.12.0 July 25, 2021 { id="2.12.0" }
+
+- Added support for social cards
+
+### 2.11.1 July 20, 2021 { id="2.11.1" }
+
+- Fixed order of tags index, now sorted alphabetically
+
+### 2.11.0 July 18, 2021 { id="2.11.0" }
+
+- Improved Mermaid.js integration, now stable
+- Added support for sequence diagrams
+- Added support for entity relationship diagrams
+- Added support for cookie consent configuration
+- Added feature flag to always enable annotations
+
+### 2.10.0 July 10, 2021 { id="2.10.0" }
+
+- Added support for cookie consent
+- Fixed #2807: Back-to-top button not hidden when using sticky tabs
+
+### 2.9.2 May 30, 2021 { id="2.9.2" }
+
+- Moved tags to partial for easier customization
+- Added support for hiding tags on any page
+
+### 2.9.1 May 24, 2021 { id="2.9.1" }
+
+- Added missing guard for linking of content tabs
+
+### 2.9.0 May 23, 2021 { id="2.9.0" }
+
+- Added support for linking of content tabs
+
+### 2.8.0 May 12, 2021 { id="2.8.0" }
+
+- Added support for boosting pages in search
+
+### 2.7.2 May 8, 2021 { id="2.7.2" }
+
+- Fixed #2638: Warnings shown when using `tags` plugin without directory URLs
+
+### 2.7.1 May 3, 2021 { id="2.7.1" }
+
+- Fixed `git-revision-date-localized` plugin integration (2.7.0 regression)
+
+### 2.7.0 May 1, 2021 { id="2.7.0" }
+
+- Added support for tags (with search integration)
+
+### 2.6.0 April 11, 2021 { id="2.6.0" }
+
+- Stay on page when switching versions
+
+### 2.5.0 March 28, 2021 { id="2.5.0" }
+
+- Added support for version warning
+
+### 2.4.0 March 20, 2021 { id="2.4.0" }
+
+- Added support for custom admonition icons
+- Fixed #2444: Code block annotations with extra comments have wrong index
+
+### 2.3.1 March 14, 2021 { id="2.3.1" }
+
+- Fixed anchor offset for permalinks when using sticky navigation tabs
+
+### 2.3.0 March 13, 2021 { id="2.3.0" }
+
+- Added support for back-to-top button
+
+### 2.2.1 March 4, 2021 { id="2.2.1" }
+
+- Fixed #2382: Repository stats failing when no release tag is present
+
+### 2.2.0 February 28, 2021 { id="2.2.0" }
+
+- Added support for code block annotations
+
+### 2.1.0 February 26, 2021 { id="2.1.0" }
+
+- Added support for anchor tracking
+
+### 2.0.0 February 24, 2021 { id="2.0.0" }
+
+- Migrated Insiders to the new architecture
+- Swapped color palette toggle configuration
+
+### 1.17.0 January 31, 2021 { id="1.17.0" }
+
+- Added support for section index pages
+
+### 1.16.1 January 26, 2021 { id="1.16.1" }
+
+- Fixed #2249: Instant loading + sticky tabs result in invalid links
+- Fixed #2248: Search highlighting URL parameter always added
+- Fixed #2235: Version selector doesn't select current version for aliases
+
+### 1.16.0 January 7, 2021 { id="1.16.0" }
+
+- Added latest release to repository info (GitHub)
+- Slight facelift of repository info (lighter fonts, spacing and icons)
+
+### 1.15.0 January 2, 2021 { id="1.15.0" }
+
+- Added support for native Mermaid.js integration
+
+### 1.14.0 December 30, 2020 { id="1.14.0" }
+
+- Added support for sharing searches
+
+### 1.13.2 December 22, 2020 { id="1.13.2" }
+
+- Fixed version selector + sticky tabs navigation rendering issues
+- Fixed version selector wrapping
+
+### 1.13.1 December 20, 2020 { id="1.13.1" }
+
+- Removed horizontal scrollbars on language and version selector
+- Fixed type conversion in JavaScript config
+
+### 1.13.0 December 13, 2020 { id="1.13.0" }
+
+- Refactored navigation tabs to simplify grouping behavior
+- Added support for sticky navigation tabs
+- Added support for arbitrary links in navigation tabs
+- Fixed #2098: Subsequent active subsection not highlighted correctly
+
+### 1.12.1 December 8, 2020 { id="1.12.1" }
+
+- Fixed empty language selector being shown
+
+### 1.12.0 December 6, 2020 { id="1.12.0" }
+
+- Added support for adding a language selector
+
+### 1.11.2 November 29, 2020 { id="1.11.2" }
+
+- Fixed #2068: Search highlight interprets code blocks as JavaScript
+
+### 1.11.1 November 29, 2020 { id="1.11.1" }
+
+- Refactored styling to be more stable and easier to adjust
+- Fixed some styling regressions from latest features
+
+### 1.11.0 November 22, 2020 { id="1.11.0" }
+
+- Added support for rendering admonitions as inline blocks
+
+### 1.10.0 November 15, 2020 { id="1.10.0" }
+
+- Added support for integrating table of contents into navigation
+
+### 1.9.0 November 7, 2020 { id="1.9.0" }
+
+- Added support for hiding navigation and table of contents on any page
+- Removed autohiding table of contents when empty
+
+### 1.8.0 November 1, 2020 { id="1.8.0" }
+
+- Added support for navigation sections
+- Fixed appearance of inactive search suggestions
+
+### 1.7.0 October 25, 2020 { id="1.7.0" }
+
+- Added support for deploying multiple versions
+- Fixed alignment of sidebar when content area is too small
+
+### 1.6.0 October 11, 2020 { id="1.6.0" }
+
+- Added support for search suggestions to save keystrokes
+- Added support for removing __Made with Material for MkDocs__ from footer
+- Fixed #1915: search should go to first result by pressing ++enter++
+
+### 1.5.1 September 21, 2020 { id="1.5.1" }
+
+- Fixed content area stretching to whole width for long code blocks
+
+### 1.5.0 September 19, 2020 { id="1.5.0" }
+
+- Added support for autohiding table of contents when empty
+
+### 1.4.1 September 6, 2020 { id="1.4.1" }
+
+- Improved typeahead and search result relevance and scoring
+
+### 1.4.0 August 30, 2020 { id="1.4.0" }
+
+- Added support for autohiding header on scroll
+
+### 1.3.0 August 26, 2020 { id="1.3.0" }
+
+- Added support for user-selectable color palettes
+
+### 1.2.0 August 11, 2020 { id="1.2.0" }
+
+- Added feature to expand navigation by default
+
+### 1.1.0 August 3, 2020 { id="1.1.0" }
+
+- Added highlighting of search results
+
+### 1.0.0 July 14, 2020 { id="1.0.0" }
+
+- Added grouping of search results
+- Added missing query terms to search result
+- Improved search result relevance and scoring
diff --git a/mkdocs-material/docs/insiders/community-experts-program/index.md b/mkdocs-material/docs/insiders/community-experts-program/index.md
new file mode 100644
index 0000000..54c6276
--- /dev/null
+++ b/mkdocs-material/docs/insiders/community-experts-program/index.md
@@ -0,0 +1,148 @@
+---
+title: Community Experts Program
+status: new
+---
+
+# Calling for Community Experts
+
+Interested in joining the Material for MkDocs team as a Community Expert?
+We're on the lookout for individuals who are passionate about supporting our
+awesome community. In return for your valuable contributions, time, and
+insights, __you'll gain free access to the Insiders edition__.
+
+## Why we need you
+
+As our project and community continue to grow, so do the questions and needs of
+our users on our discussion board. Our discussion board is a vital part of our
+project, serving as a hub for our community to connect and a valuable knowledge
+base to complement our documentation.
+
+We're eager to keeping it well-maintained, organized, easy to search and address
+all queries which is why we need extra hands to keep up with the demand.
+
+That's why we're building a team of Community Experts!
+
+## Your role
+
+As a Community Expert, your role primarily involves active participation on
+our [discussion board], where we'd expect you to be:
+
+- Answering discussions to help users with their questions
+- Providing guidance regarding implementations
+- Sharing insights into customizations and workarounds
+- Optimizing searchability by adjusting discussion titles with relevant keywords
+
+## Your benefits
+
+Here is a list of the benefits we offer to our Community Experts:
+
+- __Free access to Material for MkDocs Insiders__ – Exclusive Access to all of
+ our Material for MkDocs Insiders features for _non-commercial use_.[^1]
+
+- __Close communication with the team__ – Stay connected with us through various
+ channels, including calls and internal project management tools.
+
+- __GitHub profile boost__ – Enhance your GitHub profile's visibility and
+ credibility as your activity increases, earning you valuable badges that can
+ enhance your credibility.
+
+ [^1]:
+ Access to Insiders is granted to your primary account, i.e., the account
+ with which you're contributing to the project. It cannot be transferred to
+ another account. Additionally, it cannot be used for commercial purposes.
+
+## Your knowledge & skills
+
+To be a successful Community Expert, your skills should include the following:
+
+- __Material and MkDocs allrounder__ – You have an understanding of Material
+ for MkDocs and the MkDocs ecosystem, including many of its extensions and
+ plugins.
+
+- __Great communicator__ – You enjoy helping others in a productive,
+ constructive and friendly manner and use inclusive and welcoming language.
+
+- __Independent worker__ – You are self-motivated, stay up-to-date with
+ project developments, regularly check the discussion board, and respond to
+ notifications in reasonable time.
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+ [contribution guides]: ../contributing/index.md
+
+## Your time commitment
+
+We don't require a fixed number of hours each week; instead, we ask for a
+minimum of __five answered discussions per month[^2]__, which amounts to
+slightly more than one per week. Your active interaction within the community is
+highly valued.
+
+To do this effectively, it's best to regularly check the discussion board to see
+where you can offer help. The time you invest may vary depending on the
+complexity of the topics and questions.
+
+Upon joining, you'll receive access to the Insiders' edition for as long as you
+continue to assist us. Access will be renewed every three months, allowing you
+the flexibility to continue your contributions or take a break as needed.
+
+ [^2]:
+ An answered discussion is a collaborative interaction where knowledge and
+ expertise are shared, resulting in resolutions or clarifications that benefit
+ the user and our entire community. In essence, it embodies the spirit of
+ cooperation and support within our community, highlighting the power of
+ collective wisdom and the willingness to assist and uplift one another.
+
+## Ready to get started?
+
+Since we have a limited number of seats for these roles[^3], we would like to
+get to know you before you become one of our Community Experts. Here's how to
+get started:
+
+ [^3]:
+ Please note that we're currently limiting the number of seats on the
+ Community Experts program to three. We will update this page when we'll
+ expand the team, which is when we'll be accepting new applications.
+
+### Step 1: Get in touch
+
+Send us an email introducing yourself, sharing a bit about your background, and
+include a link to your GitHub profile. Additionally, provide links to three
+previous discussions you've answered on the discussion board, where you've
+assisted another community member.
+
+Please use the following email template to reach out to us at
+community@squidfunk.com:
+
+```
+Subject: Community Expert
+
+Intro: Tell us a bit about yourself.
+ - Name:
+ - Background:
+ - Profession:
+ - GitHub profile:
+
+Answered discussions
+ - Link 1:
+ - Link 2:
+ - Link 3:
+```
+
+### Step 2: Evaluation
+
+After receiving and reviewing your application, we will get in touch with you
+to discuss everything you need to know to get started. If you get selected, we
+will set you up as a collaborator and provide you immediate access to the
+Insiders edition for three months.
+
+### Step 3: Dive in
+
+Let's get started! You can actively begin participating in five discussions per
+month. We trust you to take the lead, and we won't do strict monitoring. Simply
+ensure that you are consistently listed on the _Most Helpful_ list, located on
+the discussion board's left side, under the categories.
+---
+
+__Ready to join us?__
+
+Sounds good? Let's give it a try!
diff --git a/mkdocs-material/docs/insiders/getting-started.md b/mkdocs-material/docs/insiders/getting-started.md
new file mode 100644
index 0000000..f0c7862
--- /dev/null
+++ b/mkdocs-material/docs/insiders/getting-started.md
@@ -0,0 +1,184 @@
+---
+title: Getting started with Insiders
+---
+
+# Getting started with Insiders
+
+Material for MkDocs Insiders is a compatible drop-in replacement for Material
+for MkDocs, and can be installed similarly using [`pip`][pip],
+[`docker`][docker] or [`git`][git]. Note that in order to access the Insiders
+repository, you need to [become an eligible sponsor] of @squidfunk on GitHub.
+
+ [pip]: #with-pip
+ [docker]: #with-docker
+ [git]: #with-git
+ [become an eligible sponsor]: how-to-sponsor.md
+
+## Requirements
+
+After you've been added to the list of collaborators and accepted the
+repository invitation, the next step is to create a [personal access token] for
+your GitHub account in order to access the Insiders repository programmatically
+(from the command line or GitHub Actions workflows):
+
+1. Go to https://github.com/settings/tokens
+2. Click on [Generate a new token]
+3. Enter a name and select the [`repo`][scopes] scope
+4. Generate the token and store it in a safe place
+
+ [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+ [Generate a new token]: https://github.com/settings/tokens/new
+ [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+
+Some of the instructions below require that the `GH_TOKEN` environment
+variable is set to the value of the personal access token you
+generated in the previous step. Note that the personal access token
+must be kept secret at all times, as it allows the owner to access
+your private repositories.
+
+## Installation
+
+### with pip
+
+Material for MkDocs Insiders can be installed with `pip`. You will
+normally want to install the latest release but can also install a
+specific older release or even the latest development version.
+Make sure you have the `GH_TOKEN` variable set as instructed above.
+
+=== "Specific release"
+
+ Pick the corresponding tag from the [list of tags] for the Insiders
+ repository. In the `pip` command below, replace the tag at the
+ end of the URL with the one you want.
+
+ ``` sh
+ pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+ ```
+
+=== "Latest"
+
+ ``` sh
+ pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ ```
+
+[list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
+
+### with docker
+
+In case you want to use Material for MkDocs Insiders from within Docker, some
+additional steps are necessary. While we cannot provide a hosted Docker image
+for Insiders[^2], [GitHub Container Registry] allows for simple and
+comfortable self-hosting:
+
+1. [Fork the Insiders repository]
+2. Enable [GitHub Actions] on your fork[^3]
+3. Create a new personal access token[^4]
+ 1. Go to https://github.com/settings/tokens
+ 2. Click on [Generate a new token]
+ 3. Enter a name and select the [`write:packages`][scopes] scope
+ 4. Generate the token and store it in a safe place
+4. Add a [GitHub Actions secret] on your fork
+ 1. Set the name to `GHCR_TOKEN`
+ 2. Set the value to the personal access token created in the previous step
+5. [Create a new release] to build and publish the Docker image
+6. Install [Pull App] on your fork to stay in-sync with upstream
+
+The [`publish`][publish] workflow[^5] is automatically run when a new tag
+(release) is created. When a new Insiders version is released on the upstream
+repository, the [Pull App] will create a pull request with the changes and
+pull in the new tag, which is picked up by the [`publish`][publish] workflow
+that builds and publishes the Docker image automatically to your private
+registry.
+
+Now, you should be able to pull the Docker image from your private registry:
+
+```
+docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
+docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
+```
+
+Should you wish to add additional plugins to the insiders container image, follow the steps
+outlined in the [Getting Started guide](../getting-started.md#with-docker).
+
+ [^2]:
+ Earlier, Insiders provided a dedicated Docker image which was available to
+ all sponsors. On March 21, 2021, the image was deprecated for the reasons
+ outlined and discussed in #2442. It was removed on June 1, 2021.
+
+ [^3]:
+ When forking a repository, GitHub will disable all workflows. While this
+ is a reasonable default setting, you need to enable GitHub Actions to be
+ able to automatically build and publish a Docker image on
+ [GitHub Container Registry].
+
+ [^4]:
+ While you could just add the `write:packages` scope to the personal access
+ token created to access the Insiders repository, it's safer to create a
+ dedicated token which you'll only use for publishing the Docker image.
+
+ [^5]:
+ The Insiders repository contains two GitHub Actions workflows:
+
+ - `build.yml` – Build and lint the project (disabled on forks)
+ - `publish.yml` – Build and publish the Docker image
+
+### with git
+
+Of course, you can use Material for MkDocs Insiders directly from `git`:
+
+```
+git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
+```
+
+The theme will reside in the folder `mkdocs-material/material`. When cloning
+from `git`, the theme must be installed, so MkDocs can find the built-in
+plugins:
+
+```
+pip install -e mkdocs-material
+```
+
+ [GitHub Container Registry]: https://docs.github.com/en/packages/guides/about-github-container-registry
+ [Fork the Insiders repository]: https://github.com/squidfunk/mkdocs-material-insiders/fork
+ [GitHub Actions]: https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
+ [packages scope]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+ [GitHub Actions secret]: https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
+ [Create a new release]: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
+ [Pull App]: https://github.com/apps/pull
+ [publish]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml
+
+## Built-in plugins
+
+When you're using built-in plugins that are solely available via Insiders,
+outside contributors won't be able to build your documentation project on their
+local machine. This is the reason why we developed the [built-in group plugin]
+that allows to conditionally load plugins:
+
+``` yaml
+plugins:
+ - search
+ - social
+
+ # CI=1 mkdocs build
+ - group:
+ enabled: !ENV CI
+ plugins:
+ - git-revision-date-localized
+ - git-committers
+
+ # INSIDERS=1 mkdocs build
+ - group:
+ enabled: !ENV INSIDERS
+ plugins:
+ - optimize
+ - privacy
+```
+
+Of course, you can also enable both groups with:
+
+```
+CI=1 INSIDERS=1 mkdocs build
+```
+
+ [built-in group plugin]: ../plugins/group.md
+ [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
diff --git a/mkdocs-material/docs/insiders/how-to-sponsor.md b/mkdocs-material/docs/insiders/how-to-sponsor.md
new file mode 100644
index 0000000..be170d4
--- /dev/null
+++ b/mkdocs-material/docs/insiders/how-to-sponsor.md
@@ -0,0 +1,114 @@
+# How to sponsor
+
+Becoming a sponsor for Material for MkDocs is a straightforward process through
+@squidfunk's [GitHub Sponsors profile]. By supporting
+the project with a monthly contribution of __$15 a month__ or more, you can sponsor
+either via an [individual] or [organizational] GitHub account.
+
+ [GitHub Sponsors profile]: https://github.com/sponsors/squidfunk
+ [individual]: access-management.md/#individuals
+ [organizational]: access-management.md/#organizations
+
+## Walkthrough
+
+Want to become a sponsor? We will guide you through the sponsoring process below
+If you have additional questions, you can find detailed information about
+[payment and billing], [access management], [runtime and cancellation],
+[privacy], [license] and [support] on dedicated pages.
+
+ [payment and billing]: payment-and-billing.md
+ [access management]: access-management.md
+ [runtime and cancellation]: runtime-and-cancellation.md
+ [privacy]: privacy.md
+ [license]: license.md
+ [support]: ../support.md
+
+### Sponsoring tier
+
+First, it's a good idea to explore [our sponsoring tiers], as each sponsoring
+tier is designed to accommodate different levels of sponsors and includes
+dedicated benefits.
+
+After reviewing the sponsoring tiers, it's time to choose one. Consider what you
+want to achieve and keep your requirements in mind, e.g. the number of projects
+you want to build or how many accounts you need. [Switching tiers] is possible
+at any time.
+
+Choosing a tier will take you to GitHub's sponsorship confirmation page.
+
+ [our sponsoring tiers]: sponsoring-tiers.md
+ [Switching tiers]: sponsoring-tiers.md/#switching-tiers
+
+### Sponsorship summary
+
+#### Payment and billing
+
+Next, GitHub will ask you to provide your billing information, which is required
+to process your sponsorship payment. On this page, the _Sponsorship summary_
+section displays the (possibly prorated) amount due to initiate your sponsorship.
+This amount is determined by your account's [billing cycle], which can be set to
+a monthly or yearly interval.
+
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+
+Proceed to input your [payment information], specifically your credit card
+details. Please make sure that the used credit card is valid and will remain
+so for an extended period to help avoid any interruptions in your sponsorship.
+
+ [payment information]: payment-and-billing.md
+
+#### Privacy
+
+On this page, you can also set the visibility of your sponsorship. You have the
+option to keep your [sponsorship private or to make it public], which includes
+listing your name or organization on the list of [our sponsors] and, for
+organizations, the opportunity for [logo placement].
+
+ [sponsorship private or to make it public]: privacy.md
+ [our sponsors]: our-sponsors.md
+ [logo placement]: our-sponsors.md/#premium-sponsors
+
+#### News and updates
+
+Note that we rarely send out emails, and when we do, it's usually to inform you
+about significant updates or changes to the project, so it's best to keep this
+option enabled. To stay updated on the latest developments, you can check out
+our [changelog].
+
+ [changelog]: ../changelog/index.md
+
+#### Tax information
+
+If you're sponsoring as an organization, it's essential to provide your country,
+region and VAT number, so we can correctly attribute your sponsorship. This is
+due to the fact that VAT is handled differently for individuals than for
+organizations.
+
+#### Confirmation
+
+Before finalizing your sponsorship, take a moment to review all the details of
+your sponsorship, including the selected tier, billing information, and payment
+details.
+
+Then proceed to confirm your sponsorship by clicking the _Sponsor_ button.
+
+### Access management
+
+After completing the sponsorship process and your payment is successfully
+processed, you will be all set to [gain access] to the private Material for
+MkDocs Insiders repository.
+
+ [gain access]: access-management.md
+
+---
+
+__Ready to become a sponsor?__
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
+
+If you still find yourself with more questions, feel free to [reach out to Kathi]
+via mail at sponsors@squidfunk.com for additional support.
+
+ [reach out to Kathi]: ../support.md/#sponsoring-support
diff --git a/mkdocs-material/docs/insiders/index.md b/mkdocs-material/docs/insiders/index.md
new file mode 100644
index 0000000..ee6af1f
--- /dev/null
+++ b/mkdocs-material/docs/insiders/index.md
@@ -0,0 +1,229 @@
+# Insiders
+
+Material for MkDocs Insiders offers an enhanced experience with early access to
+exclusive features that aren't available in the community edition. Become a
+sponsor and make use of these features directly!
+
+You’ve already seen the benefits of using Material for MkDocs;
+imagine what more you can achieve with Insiders. Your sponsorship helps us
+continue to innovate and improve, ensuring Material for MkDocs remains a
+cutting-edge tool. Discover how your contributions make a difference.
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
+
+## Additional information
+
+Explore the following section to learn more about Material for MkDocs, why
+you should sponsor us, what's in it for you, and who is sponsoring us.
+
+
+
+- :fontawesome-solid-circle-question:
+ __Why sponsor us__
+
+ ---
+
+ Learn how to support our goal of becoming the leading tool in documentation
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Why sponsor us]
+
+- :material-gift:
+ __What's in it for you__
+
+ ---
+
+ Discover exclusive benefits and features available only to our monthly sponsors
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][What's in it for you]
+
+- :fontawesome-solid-people-group:
+ __Who is sponsoring__
+
+ ---
+
+ Get to know our awesome sponsors, financially backing Material for MkDocs
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Who is sponsoring]
+
+
+
+### Sponsoring guide
+
+Learn how to become a sponsor of Material for MkDocs Insiders and start your
+sponsorship journey by choosing the right tier for you:
+
+
+
+
+- :material-animation-outline:
+ __Sponsoring tiers__
+
+ ---
+
+ Find the perfect monthly sponsoring tier that fits your needs and
+ requirements
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Sponsoring tiers]
+
+- :octicons-heart-fill-24:{ .mdx-heart }
+ __How to sponsor__
+
+ ---
+
+ Follow our step-by-step guide on how to become a sponsor to get you started
+
+ ---
+
+ [:octicons-arrow-right-24: More information][How to sponsor]
+
+
+
+### Additional information
+
+If you require additional and detailed information about payment, billing,
+access management, and more, here is everything you need to know:
+
+
+
+- :material-hand-coin:
+ __Payment and billing__
+
+ ---
+
+ All the information you need about payment methods and billing cycles
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Payment and billing]
+
+- :material-key-variant:
+ __Access management__
+
+ ---
+
+ Learn about access management to Insiders – for individuals and
+ organizations
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Access management]
+
+- :material-clock-time-three:
+ __Runtime and cancellation__
+
+ ---
+
+ Receive information on the duration of your sponsorship and the cancellation
+ process
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Runtime and cancellation]
+
+- :material-lock-open:
+ __Privacy__
+
+ ---
+
+ Our commitment to your privacy – learn assurances on valuing your privacy
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Privacy]
+
+- :material-briefcase:
+ __License__
+
+ ---
+
+ Get details on the licensing of Material for MkDocs Insiders and its requirements
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][License]
+
+- :material-email:
+ __Support__
+
+ ---
+
+ Overview of our support options available, ensuring you get the information
+ you need
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Support]
+
+
+
+### Using Insiders
+
+Once you have become a sponsor, you can start using Material for MkDocs Insiders,
+get all the information you need to get started:
+
+
+
+- :material-download:
+ __Getting started__
+
+ ---
+
+ Step-by-step instructions on how to install Material for MkDocs Insiders
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Getting started]
+
+- :octicons-versions-16:
+ __Changelog__
+
+ ---
+
+ Review the latest changes and additions to Material for MkDocs Insiders
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Changelog]
+
+- :material-update:
+ __Upgrade__
+
+ ---
+
+ Stay updated with the latest changes and improvements in the Insiders
+ edition
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][Upgrade]
+
+
+
+ [Why sponsor us]: why-sponsor-us.md
+ [What's in it for you]: benefits.md
+ [Who is sponsoring]: our-sponsors.md
+ [Sponsoring tiers]: sponsoring-tiers.md
+ [How to sponsor]: how-to-sponsor.md
+ [Payment and billing]: payment-and-billing.md
+ [Access management]: access-management.md
+ [Runtime and cancellation]: runtime-and-cancellation.md
+ [Privacy]: privacy.md
+ [License]: license.md
+ [Support]: ../support.md
+ [Getting started]: getting-started.md
+ [Changelog]: ../changelog/index.md
+ [Upgrade]: upgrade.md
+
+----
+
+__We're looking forward to welcoming you as a sponsor!__
diff --git a/mkdocs-material/docs/insiders/license.md b/mkdocs-material/docs/insiders/license.md
new file mode 100644
index 0000000..268aa5e
--- /dev/null
+++ b/mkdocs-material/docs/insiders/license.md
@@ -0,0 +1,67 @@
+# License
+
+Material for MkDocs Insiders is licensed under the [MIT license], the exact
+same license used for the community edition. The MIT license is a permissive
+license that allows commercial use, redistribution, and everything else as
+long as the original authors are credited in source files.
+
+The MIT license is the [most popular license] among all Open Source projects.
+
+ [MIT license]: https://opensource.org/license/mit
+ [most popular license]: https://opensource.org/blog/the-most-popular-licenses-for-each-language-2023
+
+## MIT License
+
+The MIT License gives you the freedom to work with the code with minimal
+restrictions. When using Material for MkDocs Insiders or the community edition,
+make sure to __include the copyright notice__ and avoid future liability claims.
+Its appeal lies in its simplicity and clear terms, making it a go-to for
+projects of any scale. Its popularity stems from its simplicity, clarity,
+and development-friendly terms, making it suitable for all types of projects.
+The MIT License ensures that anyone – individual or organization – can use
+Material for MkDocs Insiders under the same conditions as the community edition.
+
+### Advantages of MIT
+
+The MIT License is favored for its balance between freedom and protection,
+appealing to those who find GNU/GPL licenses too restrictive or advocate for
+privatized software. Its broad wording supports both open community development
+and the use of components in proprietary software.
+
+### MIT in open source
+
+Material for MkDocs stands out for being open source, developed by a small,
+user-oriented team committed to delivering high-quality tools for the community.
+Here’s what this means for you:
+
+- __Independence from investors:__ Our focus is purely on developing the
+project and guiding it without external pressures. This freedom means we’re all
+about what’s best for the community and the project's future.
+- __Freedom from vendor lock-in:__ Thanks to Open Source principles, you can use
+Material for MkDocs without any strings attached. Customize or integrate it
+into your projects without worrying about restrictions. Your docs belong to you,
+and you are free to change the software at any time.
+- __Ecosystem Development:__ Material for MkDocs is more than a tool; it's a
+community-driven effort to build an ecosystem, which it already is. Through open
+collaboration, we’re constantly adding new extensions, plugins, and integrations
+to give you more tools at your disposal.
+
+## Fair use policy
+
+Our fair use policy is here to ensure the project continues to thrive, which is
+why we request that our sponsors respect the following:
+
+- __Source Code Distribution:__ Keeping our sponsorware model intact means we
+count on you not to distribute the Insiders source code. While you're encouraged
+to privately [fork], or [mirror] the private Insiders repository for your needs,
+__keeping the source private__ is key. If this guideline is violated,
+everybody loses, as it will reduce the time of us maintainers we could otherwise
+set aside to push this project forward.
+- __Sponsorship tiers:__ We base our sponsorship tiers on non-commercial or
+commercial use and ask our sponsors to respect these requirements when
+initiating a sponsorship. Additionally, we base our sponsoring tiers on the number
+of sites you intend to build. Please upgrade your sponsorship accordingly to
+support the project’s growth and ensure its continued development.
+
+ [fork]: access-management.md/#forking
+ [mirror]: access-management.md/#mirroring
diff --git a/mkdocs-material/docs/insiders/our-sponsors.md b/mkdocs-material/docs/insiders/our-sponsors.md
new file mode 100644
index 0000000..d096dce
--- /dev/null
+++ b/mkdocs-material/docs/insiders/our-sponsors.md
@@ -0,0 +1,131 @@
+# Our sponsors
+
+Starting in 2020, we have managed to build a community of a few hundred sponsors
+that support us every month, for which we are immensely grateful. Without their
+financial support, Material for MkDocs wouldn't be anywhere near where it is
+today.
+
+
+
+
+ If you sponsor publicly, you're automatically added here with a link to
+ your profile and avatar to show your support for Material for MkDocs.
+ Alternatively, if you wish to keep your sponsorship private, you'll be a
+ silent +1. You can select visibility during checkout and change it
+ afterwards.
+
+
diff --git a/mkdocs-material/docs/insiders/payment-and-billing.md b/mkdocs-material/docs/insiders/payment-and-billing.md
new file mode 100644
index 0000000..957551c
--- /dev/null
+++ b/mkdocs-material/docs/insiders/payment-and-billing.md
@@ -0,0 +1,94 @@
+# Payment and billing
+
+Since we host our repositories on GitHub, including both the Material for MkDocs
+community edition and the private Insiders edition, [GitHub Sponsors] is a
+natural fit for handling all financial transactions, as well as for access
+management to the Insiders repository.
+
+Therefore, to become a sponsor of Material for MkDocs, a [GitHub account] is mandatory.
+
+ [GitHub Sponsors]: https://github.com/sponsors
+ [GitHub account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
+
+## Payment
+
+GitHub Sponsors currently only accepts payments via credit card, as they
+[removed support for PayPal] at the beginning of 2023. When
+entering your credit card details, ensure that the card remains [valid over an
+extended period] to prevent any disruptions to your sponsorship.
+
+ [valid over an extended period]: runtime-and-cancellation.md#automatic-cancellation
+ [removed support for PayPal]: https://github.blog/changelog/2023-01-23-github-sponsors-will-stop-supporting-paypal/
+
+## Invoices
+
+GitHub Sponsors automatically issues and send a payment receipt via email after
+each billing cycle. These receipts serve as confirmation of payment rather than
+formal invoices. As all transactions are managed by [GitHub Sponsors], GitHub is
+your primary point of contact for payment and billing matters, not us.
+
+If you need an official invoice from us for your records, please get in touch
+with us at sponsors@squidfunk.com before initiating your sponsorship.
+
+## Refunds
+
+Our team does not have insights or access to details related to sponsorship
+transactions of our sponsors, as GitHub does not provide us with this
+information. For questions regarding payment issues or for more detailed
+information about your sponsorship, please get in touch with the [GitHub
+support] team.
+
+ [GitHub support]: https://support.github.com/
+
+## Discounts
+
+Unfortunately, we can't offer discounts. To ensure that everyone in our
+community can afford to become a sponsor, we keep the barrier low and set
+prices as low as possible, starting at [\$15 a month][15] for
+[non-commercial use] and at [\$125 a month][125] for [commercial use].
+
+ [15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+ [125]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210643
+ [non-commercial use]: sponsoring-tiers.md/#non-commercial-use
+ [commercial use]: sponsoring-tiers.md/#commercial-use
+
+## Free access
+
+Free access to the Insiders edition is only granted exclusively to our [Community
+Experts] and to selected members of the MkDocs ecosystem. Our Community Experts
+program is designed to recognize and reward users who significantly contribute
+to the community by sharing their expertise on our [discussion board].
+
+Our discussion board facilitates the exchange of insights on workarounds, setups,
+and features and addresses queries from users at all levels of experience. All
+communication is public and visible for the entire community, benefitting
+everyone.
+
+Community experts not only enrich our project but also enable our team to focus
+on continuous improvement and the development of new features. Therefore, we are
+happy to provide them with free access to the private Insiders repository and
+encourage you to [join the team] as well!
+
+ [community experts]: community-experts-program/index.md
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [join the team]: community-experts-program/index.md/#ready-to-get-started
+
+## Billing cycle
+
+The [billing cycle] is an account-level setting on GitHub and is set to monthly
+or yearly. It can be changed at any time, so you might want to check the setting
+before sponsoring and change it either to monthly or yearly according to your
+own or your organization's preferences.
+
+If, for whatever reason, you cannot change your billing cycle, a practical
+solution is to create a dedicated [GitHub bot account] where you set the billing
+cycle accordingly and use it specifically for your sponsorship contributions.
+This is a strategy many of our organizational sponsors have successfully
+implemented.
+
+If you experience any difficulties or have further questions before sponsoring,
+please don't hesitate to contact us at sponsors@squidfunk.com for additional
+support.
+
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+ [GitHub bot account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
diff --git a/mkdocs-material/docs/insiders/privacy.md b/mkdocs-material/docs/insiders/privacy.md
new file mode 100644
index 0000000..f4b1f13
--- /dev/null
+++ b/mkdocs-material/docs/insiders/privacy.md
@@ -0,0 +1,79 @@
+# Privacy
+
+Transparency is at the heart of our sponsorware model, which includes our
+funding goals, the features we're working towards, and, importantly, the
+acknowledgment of our sponsors. As a sponsor, you can support our project
+either [publicly] or [privately], according to your preference.
+
+ [publicly]: #public-sponsors
+ [privately]: #private-sponsors
+
+## Public sponsors
+
+By default, GitHub lists all sponsorships publicly. To sponsor privately, you
+must explicitly select this option. When sponsoring publicly, your GitHub
+account will be listed as part of [our sponsors], @squidfunk's [sponsoring page],
+and within the "sponsoring" section of your GitHub account.
+
+ [our sponsors]: our-sponsors.md
+ [sponsoring page]: https://github.com/sponsors/squidfunk?metadata_origin=docs
+
+## Private sponsors
+
+For those preferring discretion, [setting your sponsorship to private] during
+the sponsorship initiation process ensures your sponsorship remains unlisted,
+keeping your affiliation with Material for MkDocs confidential.
+
+This setting can be adjusted at any time through your GitHub account's
+sponsorship settings.
+
+For companies concerned about being visible as sponsors of any project due to
+their privacy restrictions, creating a [bot account] on GitHub that is solely
+used for sponsoring is advised. This account, set to sponsor privately, won't be
+linked to any individual within your organization and provides an extra layer of anonymity.
+
+ [setting your sponsorship to private]: https://docs.github.com/en/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-the-privacy-setting-for-your-sponsorship
+ [bot account]: access-management.md/#bot-account
+
+## Administrative requests
+
+To focus on the development of our projects, we aim to reduce administrative
+tasks as much as possible for our small team, utilizing GitHub Sponsors for
+efficient sponsor management.
+
+### Vendor agreements
+
+Since GitHub Sponsors facilitates our sponsor transactions, they act as your
+vendor. For vendor agreements or related queries, especially for organizations
+with GitHub enterprise accounts, reaching out to [GitHub Support] is recommended.
+
+ [GitHub Support]: https://github.com/sponsors
+
+### Non-disclosure agreements
+
+Given our limited resources as a small team, we are unable to review and sign
+NDAs. We advise those requiring such agreements to consult [our promise] for
+reassurance. Additionally, please contact us if you have any questions at
+sponsors@squidfunk.com
+
+ [our promise]: #our-promise
+
+## Our promise
+
+We recognize the importance of privacy for our organizational sponsors,
+especially in the absence of formal agreements like [NDAs]. "Our Promise" is our
+assurance of commitment to your confidentiality and discretion.
+
+- __Confidential sponsorship:__ Your choice between public or private
+sponsorship is respected to the fullest. For private sponsors, we guarantee your
+relation with us remains confidential at all times, ensuring no public disclosure
+of your sponsorship.
+- __Logo usage and brand representation:__ Logo display and any form of public
+acknowledgment are completely under your control and will only proceed with your
+explicit consent. This ensures your brand is represented on your terms.
+- __Marketing and communication:__ We commit not to use the details of your
+sponsorship for marketing or promotional purposes without your approval.
+Your sponsorship details are guarded with the highest level of confidentiality,
+with no unauthorized use or disclosure.
+
+ [NDAs]: #non-disclosure-agreements
diff --git a/mkdocs-material/docs/insiders/runtime-and-cancellation.md b/mkdocs-material/docs/insiders/runtime-and-cancellation.md
new file mode 100644
index 0000000..0b74f0c
--- /dev/null
+++ b/mkdocs-material/docs/insiders/runtime-and-cancellation.md
@@ -0,0 +1,58 @@
+# Runtime and cancellation
+
+The sponsorship model for Material for MkDocs is facilitated through GitHub
+Sponsors and, therefore, adheres to GitHub's policies. If you're curious about
+the duration of your sponsorship and the cancellation process, you will find
+everything you need to know below.
+
+## Runtime
+
+Sponsorships remain valid as long as monthly or yearly subscriptions are
+active and only expire when you cancel the sponsorship or when your [payment
+method expires].
+
+ [payment method expires]: #automatic-cancellation
+
+## Cancellation process
+
+Canceling your sponsorship initiates a cancellation request through GitHub,
+which is scheduled to take effect at the end of your current billing cycle. This
+means you'll retain access to Insiders until the cancellation officially becomes
+effective.
+
+All transactions are processed by GitHub and as we don't receive any information
+regarding your payment, we can't provide details about when your cancellation
+will be in place.
+
+### How to cancel
+
+To downgrade or cancel your sponsorship, please follow the [step-by-step guide
+from GitHub]. If you have sponsored using an organizational account, ensure that
+you cancel the sponsorship under that specific account, as the
+[collaborator and sponsor accounts may differ].
+
+ [step-by-step guide from GitHub]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship#canceling-a-sponsorship
+ [collaborator and sponsor accounts may differ]: access-management.md/#collaborators
+
+### Effects of cancellation
+
+Upon the effective date of your cancellation, GitHub will automatically remove
+you as a collaborator from the private Material for MkDocs Insiders repository.
+You will no longer receive updates. However, you are welcome to continue using
+the latest version available to you at the time of cancellation for as long as
+you like.
+
+!!! warning "GitHub deletes private forks"
+
+ Please note that once you lose your collaborator status, [GitHub will
+ automatically delete your private fork] of the Insiders repository, so you
+ may want to take steps to ensure that you have a local backup.
+
+ [GitHub will automatically delete your private fork]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository#deleting-forks-of-private-repositories
+
+### Automatic cancellation
+
+If your credit card expires, GitHub will automatically cancel your sponsorship
+and remove you as a collaborator. Regularly checking your payment method is
+recommended to avoid unintended cancellations. If it happens, you can
+reinstate your sponsorship with a new credit card.
diff --git a/mkdocs-material/docs/insiders/sponsoring-tiers.md b/mkdocs-material/docs/insiders/sponsoring-tiers.md
new file mode 100644
index 0000000..742e352
--- /dev/null
+++ b/mkdocs-material/docs/insiders/sponsoring-tiers.md
@@ -0,0 +1,229 @@
+# Sponsoring tiers
+
+We offer a range of sponsoring tiers tailored to the diverse needs of our
+community. Whether you're an individual user, or rooted in academia, or work in
+an organization using our software commercially, there's a sponsoring tier
+that suits your needs.
+
+## Choosing a tier
+
+Choosing the right sponsoring tier depends on your needs and how you intend to
+use Material for MkDocs Insiders. Our tiers are categorized into [non-commercial]
+and [commercial] use:
+
+ - __Non-commercial tiers__: Intended for individuals, Open Source projects,
+ and academic use
+ - __Commercial tiers__: Designed for organizations and enterprises of any size
+
+Each [monthly sponsoring tier] offers a range of benefits tailored to your needs.
+Benefits include access to our private Material for MkDocs Insiders repository,
+priority handling of bug reports, and more, which vary by the number of
+projects[^1] that you intend to build with it and collaborators required.
+Remember, you can always [upgrade or downgrade] your
+sponsorship level at any time.
+
+ [^1]:
+ A project is defined as a folder with a `mkdocs.yml` configuration file
+ that is built with Material for MkDocs Insiders. This is the only limitation
+ to follow – the number of documentation pages or the size of your project
+ is up to you.
+
+ [monthly sponsoring tier]: #monthly-sponsoring
+ [non-commercial]: #non-commercial-use
+ [commercial]: #commercial-use
+ [upgrade or downgrade]: #switching-tiers
+
+## Monthly sponsoring
+
+Monthly sponsoring tiers provide you with access to our private Material for
+MkDocs Insiders repository. Your financial contribution supports the ongoing
+development of both the Insiders and the community edition.
+
+### Non-commercial use
+
+Non-commercial use essentially means "personal use". This includes individuals
+using the Insiders edition for personal or purely non-commercial Open Source
+projects. We offer two different tiers for non-commercial use.
+
+---
+
+#### The Individual
+
+You love Material for MkDocs and use it for your Open Source project or personal
+blog. You read about all the awesome features in Insiders, which are first
+exclusively released to sponsors, and don't want to miss out.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-charity: Non-commercial use for __1-2 projects__
+
+[ Sponsor with __$15 a month__ ][15 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [15 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+
+---
+
+#### The Dedicated Individual
+
+You use Material for MkDocs for several of your Open Source projects or personal
+sites, and just love that you can build beautiful documentation without having
+to worry about the constantly breaking JavaScript ecosystem – this is now
+[@squidfunk's] job.
+
+ [@squidfunk's]: https://github.com/squidfunk
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-charity: Non-commercial use for __3+ projects__
+
+[ Sponsor with __$35 a month__ ][35 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [35 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210641
+
+---
+
+### Commercial use
+
+Commercial use refers to any use of our software for a business or for-profit
+purpose. This includes any use by a corporation or other organization, whether
+or not they generate revenue directly from the software. We offer different
+pricing tiers for commercial use, each tailored to the needs of different
+businesses. It's important to note that internal use of the software within your
+organization is also considered commercial use, as with all commercial software.
+
+---
+
+#### The Organization :star:
+
+Your organization uses Material for MkDocs for its documentation or internal
+knowledge base and wants to make sure that it is well-maintained and safe to use
+for the years to come. You agree that $125 a month (less than 1 hour of a
+skilled developer) is a clever investment into a solution, solving tons of
+problems you don't want to fight yourself.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __1-9 projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __small logo__
+
+[ Sponsor with __$125 a month__ ][125 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [125 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210643
+
+---
+
+#### The Global Organization :star::star:
+
+Your organization runs many internal and public-facing sites that are built with
+Material for MkDocs, helping you to share and manage knowledge efficiently.
+You've evaluated several commercial alternatives which will cost you 3-4x more,
+some of which with a smaller feature set. You agree that $250 a month (less than
+2 hours of a skilled developer) is a very good deal for the value you're getting
+out of it.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __10-49 projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __logo__
+
+[ Sponsor with __$250 a month__ ][250 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [250 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=181282
+
+---
+
+#### The Holistic Organization :star::star::star:
+
+Your organization's day-to-day operations critically depend on Material for
+MkDocs, and you need to make sure that bugs are fixed quickly to keep your
+customers happy. You see your work as part of a larger ecosystem, realizing that
+giving back is essential to keeping everything you fight for alive.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __50+ projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __large logo__
+ - :material-face-agent: Private __email support__
+
+[ Sponsor with __$1,000 a month__ ][1000 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [1000 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=334388
+
+---
+
+## One-time sponsoring
+
+For those who wish to contribute one-time without an ongoing subscription and
+without receiving access to the exclusive Insiders features, we offer the
+following one-time sponsoring tiers.
+
+---
+
+### Just a Tip! :money_with_wings:
+
+You asked a question or needed some help on a problem, and we've helped you
+quickly. You want no perks, just good karma and a warm feeling of giving
+something back.
+
+[ Sponsor __$20 one-time__ ][20 one-time]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [20 one-time]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=222886
+
+---
+
+### The Mentoring
+
+A 1-hour video call with [@squidfunk], the creator and core maintainer of the
+project. He is happy to share his experiences with you and help you with
+anything related to his work.
+
+__Popular topics are:__
+
+ - How to tailor Material for MkDocs to your needs
+ - How to start earning a living in Open Source
+ - How to make your Open Source project sustainable
+
+ [@squidfunk]: https://github.com/squidfunk
+
+[ Sponsor __$350 one-time__ ][350 one-time]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [350 one-time]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210891
+
+---
+
+## Custom amount
+
+You're invited to contribute custom sponsorship amounts via GitHub Sponsors,
+enabling you to support Material for MkDocs according to your preferences.
+Please be aware that individuals need to pledge a minimum of $15 a month to
+access Insiders, whereas organizations are encouraged to sponsor $125 a month or
+more, based on their requirements.
+
+Contributions exceeding these thresholds are highly appreciated. Please note
+that one-time donations, regardless of their size, won't be granted access to
+Insiders due to technical constraints.
+
+## Switching tiers
+
+You can easily switch between different sponsorship tiers — [upgrade] or
+[downgrade] — at any time. Simply visit the @squidfunk's
+[GitHub Sponsors profile] and adjust your sponsorship tier selection. Once
+you've made the change, you'll immediately sponsor at the new tier.
+
+If you exceed the number of projects within your current sponsorship limit, we
+kindly request that you upgrade your sponsorship to a higher tier to retain
+access to Material for MkDocs Insiders. The change takes effect immediately,
+and the amount is prorated based on your [billing cycle].
+
+ [upgrade]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship
+ [downgrade]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+ [GitHub Sponsors profile]: https://github.com/sponsors/squidfunk
diff --git a/mkdocs-material/docs/insiders/upgrade.md b/mkdocs-material/docs/insiders/upgrade.md
new file mode 100644
index 0000000..ec86ad9
--- /dev/null
+++ b/mkdocs-material/docs/insiders/upgrade.md
@@ -0,0 +1,79 @@
+# How to upgrade
+
+When upgrading Insiders, you should always check the version of Material for
+MkDocs which makes up the first part of the version qualifier, e.g., Insiders
+`4.x.x` is currently based on `9.x.x`:
+
+```
+9.x.x-insiders-4.x.x
+```
+
+If the major version increased, it's a good idea to consult the [upgrade
+guide] and go through the steps to ensure your configuration is up to date and
+all necessary changes have been made.
+
+ [upgrade guide]: ../upgrade.md
+ [list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
+
+Depending on how you installed and what you want to upgrade to you
+need to run different commands:
+
+=== "pip upgrade to release"
+
+ If you installed Insiders via `pip` and you want to upgrade to a
+ specific release, pick the tag from the [list of tags] and replace
+ the tag at the end of the URL of the command given below:
+
+ ```
+ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+ ```
+
+=== "pip upgrade to latest development"
+
+ If you installed Insiders via `pip` and want to upgrade to the
+ latest development version, run:
+
+ ```
+ pip install --upgrade --force-reinstall git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ ```
+
+ The `--force-reinstall` option serves to make sure `pip` does, in fact,
+ install the latest development version, instead of deciding that nothing
+ is to be done based on the version numbers.
+ ```
+
+=== "git upgrade"
+
+ If you installed Insiders via `git`, you will first need to check
+ out the version you want to install into your workspace. After
+ this is done, you can run `pip` to install that version.
+
+ First, make sure that your local clone is up-to-date with the
+ upstream repository by running `git pull`.
+
+ You can look up the tags using `git tag --sort -refname` or you
+ can consult the [list of tags]. Then, checkout the tag you want to
+ use by replacing the one given in the command below (twice)and running
+ it from your workspace[^detached]:
+
+ [^detached]:
+ The `--detach` argument serves to tell `git` that you are ok to
+ have your workspace in the [detached head] state, which is
+ perfectly fine to have here.
+
+ [detached head]: https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit/
+
+ ```
+ cd mkdocs-material
+ git checkout --detach tags/9.4.2-insiders-4.42.0
+ ```
+
+ Now, change back to the parent directory in which your Git
+ repository lives and run `pip`:
+
+ ```
+ cd ..
+ pip install -e mkdocs-material
+ ```
+
+
diff --git a/mkdocs-material/docs/insiders/why-sponsor-us.md b/mkdocs-material/docs/insiders/why-sponsor-us.md
new file mode 100644
index 0000000..5b153cc
--- /dev/null
+++ b/mkdocs-material/docs/insiders/why-sponsor-us.md
@@ -0,0 +1,121 @@
+# Why sponsor us
+
+Material for MkDocs is an Open Source project that is developed and maintained
+by a small team of individuals who want to devote as much time as possible to
+make it better every day. We need to rely on the financial support of
+[our awesome sponsors], who buy us the time to work on it.
+
+ [become a monthly sponsor]: sponsoring-tier.md
+ [our awesome sponsors]: our-sponsors.md
+ [squidfunk's sponsor profile]: https://github.com/sponsors/squidfunk/
+
+## Who we are
+
+While [the project was started] by @squidfunk as a personal side project, the
+[Sponsorware] model that the project adopted in 2020 allowed him to build a
+small team of amazing individuals around him, [who are now helping him] to
+maintain the project, as well as the growing list of sponsors.
+
+ [the project was started]: #how-it-started
+ [sponsorware]: #sponsorware
+ [who are now helping him]: #where-we-are-today
+
+### How it started
+
+In 2015, albeit 10 years in the industry, @squidfunk was still quite new to
+Open Source. Having just finished his latest Open Source project, he realized
+that the project was too complex to be explained in a plain README on GitHub.
+He needed a good documentation tool for this project.
+
+After evaluating static site generators in general and Hugo, Sphinx and MkDocs
+in particular, he quickly decided that MkDocs seemed a good choice, as it was
+specifically aimed at technical project documentation and easy to use.
+Unfortunately, all of the available themes looked dated, and since @squidfunk
+is a very visual person, he just couldn't convince himself to call it a day.
+
+He needed to build a theme.
+
+Months later, in February 2016, [the first version] of Material for MkDocs was
+released. Over the next years, @squidfunk being the sole maintainer, countless
+feature requests were implemented and bugs were fixed, allowing the project to
+gain popularity and reach almost 3,000 stars on GitHub by the end of 2019. It
+is still his most popular project to date.
+
+As the project grew, @squidfunk started to implement feature requests that made
+sense from a general perspective, but not for his personal use. This was the
+point where the project started to shift from a personal project to a
+community-driven one, and began to feel like a secondary job. Having a primary
+job, many maintainers burn out when their side projects become successful, which
+is why @squidfunk decided to give the [Sponsorware] model a try and make
+Material for MkDocs his primary job. This turned out to be an incredible success.
+
+ [the first version]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+
+### Sponsorware
+
+The Sponsorware model is simple – as a sponsor, you get early access to the
+latest and greatest features of Material for MkDocs as part of [Insiders] before
+everyone else gets to enjoy them, as you are the one making them possible with
+your financial contributions.
+
+Every new feature that lands in [Insiders] is linked to a funding goal with a
+specific amount. Once this amount is reached, all of the features that are part
+of this funding goal are merged into the community edition, making them
+available to everyone. It is that simple.
+
+This brand-new and still experimental approach not only helps keep the project
+vibrant and cutting-edge but also ensures it can continue to meet and exceed
+your expectations.
+
+ [Insiders]: index.md
+
+### Where we are today
+
+Fast forward to today, Material for MkDocs is a thriving community-supported
+and well-funded project, with over 500 sponsors and a small but growing team,
+used by international companies and organizations. The project has outgrown
+its original purpose by far, as it has become so much more than just a theme –
+a powerful documentation framework built on top of MkDocs.
+
+Starting in 2020 with the advent of the [Sponsorware] model, the frequency of
+releases has more than doubled, with a new release seeing the light of day on
+average every 1-2 weeks. Moreover, our team responds to issues as fast as
+possible, keeping the number of open issues low.
+
+## Our pledge
+
+We're working hard to make Material for MkDocs one of the best documentation
+tools out there, ridiculously powerful, a pleasure to use and most importantly –
+free and Open Source. It is the financial contributions of our awesome sponsors,
+that allow us to do our best work.
+
+It's a simple equation: as long as this project is funded, we can continue to
+improve it, fix bugs, and add new features. We will continue to provide the
+best possible support to our users and make sure that Material for MkDocs
+remains a tool that you love to use.
+
+If you sponsor us, your contribution helps us to pay for:
+
+1. __Taxes__: Since we provide a service to our sponsors, we're of course
+ legally obligated and happy to pay sales tax. This requirement applies to
+ all sponsorship contributions, aligning us with standard business practices,
+ as for the rest of the world.
+
+2. __Sponsorships__: A significant portion of our funding is redirected to
+ upstream projects. This cultivates collaboration and supports the broader
+ Open Source ecosystem. We regard those projects and their maintainers as
+ essential for the persistence of Material for MkDocs.
+
+3. __Team__: Our team is growing! With more funds available, we can pay more
+ individuals to help us make Material for MkDocs even better. Note that this
+ covers various aspects of the project, like the creation of new features,
+ bug resolution, support, and sponsor relations.
+
+We are bootstrapped – no investors to please! If you decide to support us, you
+help us stay independent and free from outside influence. This means we can
+focus on building a solution that you love to use and keep ownership of your
+documentation project without vendor lock-in.
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
diff --git a/mkdocs-material/docs/license.md b/mkdocs-material/docs/license.md
new file mode 100644
index 0000000..83fba87
--- /dev/null
+++ b/mkdocs-material/docs/license.md
@@ -0,0 +1,23 @@
+# License
+
+**MIT License**
+
+Copyright (c) 2016-2024 Martin Donath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/mkdocs-material/docs/philosophy.md b/mkdocs-material/docs/philosophy.md
new file mode 100644
index 0000000..11b4d99
--- /dev/null
+++ b/mkdocs-material/docs/philosophy.md
@@ -0,0 +1,35 @@
+# Philosophy
+
+Before settling for Material for MkDocs, it's a good idea to understand the
+philosophy behind the project, in order to make sure it aligns with your goals.
+This page explains the design principles anchored in Material for MkDocs, and
+discusses the [conventions] used in this documentation.
+
+ [conventions]: conventions.md
+
+## Design principles
+
+- __It's just Markdown__: Focus on the content of your documentation and create
+ a professional static site in minutes. No need to know HTML,CSS or JavaScript
+ – let Material for MkDocs do the heavy lifting for you.
+
+- __Works on all devices__: Serve your documentation with confidence – the
+ underlying layout automatically adapts to perfectly fit the available screen
+ estate, no matter the type or size of the viewing device.
+
+- __Made to measure__: Change the colors, fonts, language, icons, logo and much
+ more with a few lines of configuration. Material for MkDocs can be easily
+ extended and provides tons of options to alter appearance and behavior.
+
+- __Fast and lightweight__: Don't let your users wait – get incredible value
+ with a small footprint, by using one of the fastest themes around with
+ excellent performance, yielding great search engine rankings and happy
+ users that return.
+
+- __Accessible__: Make accessibility a priority – users can navigate your
+ documentation with touch devices, keyboard, and screen readers. Semantic
+ markup ensures that your documentation works for everyone.
+
+- __Open Source__: Trust 45,000+ users – choose a mature and well-funded
+ solution built with state-of-the-art Open Source technologies. Keep ownership
+ of your content without fear of vendor lock-in. Licensed under MIT.
diff --git a/mkdocs-material/docs/plugins/blog.md b/mkdocs-material/docs/plugins/blog.md
new file mode 100644
index 0000000..e1e4127
--- /dev/null
+++ b/mkdocs-material/docs/plugins/blog.md
@@ -0,0 +1,1729 @@
+---
+title: Built-in blog plugin
+icon: material/newspaper-variant-outline
+---
+
+# Built-in blog plugin
+
+The blog plugin makes it very easy to build a blog, either as a sidecar to
+your documentation or as the main thing. Focus on your content while the plugin
+does all the heavy lifting, generating a view of all latest posts, [archive] and
+[category] pages, configurable [pagination] and much more.
+
+ [archive]: #archive
+ [category]: #categories
+ [pagination]: #pagination
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`posts` directory][config.post_dir] for
+`.md` files from which paginated views[^1] are automatically generated. If not
+configured otherwise, the plugin expects that your project has the following
+directory layout, and will create any missing directories or files for you:
+
+ [^1]:
+ Views are pages that are automatically generated, i.e., the entry point to
+ your blog listing all latest posts, as well as [archive] and [category]
+ pages that list all posts associated with them through [metadata] in
+ chronological order.
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+The `index.md` file in the [`blog` directory][config.blog_dir] is the entry
+point to your blog – a paginated view listing all posts in reverse chronological
+order. Besides that, the plugin supports automatically creating [archive] and
+[category] pages that list a subset of posts for a time interval or category.
+
+[Post URLs][config.post_url_format] are completely configurable, no matter if
+you want your URLs to include the post's date or not. Rendered dates always
+display in the locale of the [site language] of your project. Like in other
+static blog frameworks, posts can be annotated with a variety of [metadata],
+allowing for easy integration with other [built-in plugins], e.g., the
+[social] and [tags] plugin.
+
+Posts can be organized in nested folders with a directory layout that suits your
+specific needs, and can make use of all components and syntax that Material for
+MkDocs offers, including [admonitions], [annotations], [code blocks],
+[content tabs], [diagrams], [icons], [math], and more.
+
+ [metadata]: #metadata
+ [built-in plugins]: index.md
+ [social]: social.md
+ [tags]: tags.md
+ [admonitions]: ../reference/admonitions.md
+ [annotations]: ../reference/annotations.md
+ [code blocks]: ../reference/code-blocks.md
+ [content tabs]: ../reference/content-tabs.md
+ [diagrams]: ../reference/diagrams.md
+ [icons]: ../reference/icons-emojis.md
+ [math]: ../reference/math.md
+
+### When to use it
+
+If you want to add a blog to your project, or migrate from another blog
+framework to Material for MkDocs because of its excellent technical writing
+capabilities, this plugin is a great choice, as it integrates perfectly with
+many other built-in plugins:
+
+
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to apply [metadata] to a subset of posts,
+ including authors, tags, categories, draft status, as well as social card
+ layouts.
+
+ ---
+
+ __Simpler organization, categorization and management of post metadata__
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each post and page, showing as previews on social media.
+
+ ---
+
+ __Links to your blog render beautiful social cards when shared on social
+ media__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your blog loads faster as smaller images are served to your users__
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The tags plugin allows to categorize posts alongside with pages in your
+ project, to improve their discoverability and connect posts to your
+ documentation.
+
+ ---
+
+ __Your documentation's tag system integrates with your blog__
+
+
+
+ [meta]: meta.md
+ [social]: social.md
+ [optimize]: optimize.md
+ [tags]: tags.md
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the blog plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and you can
+start writing your first post:
+
+``` yaml
+plugins:
+ - blog
+```
+
+The blog plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [blog]: blog.md
+ [built-in plugins]: index.md
+
+### Navigation
+
+If you do not have site navigation configured in your `mkdocs.yml` then there is
+nothing more to do. The blog [archive] and [category] pages will automatically
+appear underneath the automatically generated navigation.
+
+If you do have a navigation structure defined then you will need to specify
+where the blog should appear in this. Create a [navigation section with an index
+page] for the blog:
+
+```yaml
+theme:
+ name: material
+ features:
+ - navigation.indexes
+nav:
+ - ...
+ - Blog:
+ - blog/index.md
+```
+
+The [archive] and [category] pages will appear within that section as
+subsections beneath pages in the blog section. In this case, they would appear
+after `index.md`. The path to the `index.md` file must match
+[blog_dir][config.blog_dir]. This means that you can name the blog navigation
+entry anything you like: 'Blog' or 'News' or perhaps 'Tips'.
+
+[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - blog:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+Use this setting to change the path where your blog is located in the
+[`docs` directory][mkdocs.docs_dir]. The path is included in the generated
+URLs as a prefix for all posts and views. You can change it with:
+
+=== "Documentation + Blog"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: blog
+ ```
+
+=== "Blog only"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: .
+ ```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+Use this setting to leverage the table of contents to display post titles in
+views. This might be useful, if your post excerpts are rather long. If you want
+to enable it, use:
+
+``` yaml
+plugins:
+ - blog:
+ blog_toc: true
+```
+
+### Posts
+
+The following settings are available for posts:
+
+---
+
+####
+
+
+
+
+Use this setting to change the folder where your posts are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+ - blog:
+ post_dir: "{blog}/articles"
+```
+
+Note that the [`posts` directory][config.post_dir] is solely used for post
+organization – it is not included in post URLs, since they are automatically
+and comfortably generated by this plugin.
+
+The following placeholders are available:
+
+- `blog` – [`blog` directory][config.blog_dir]
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+Use this setting to change the date format of posts. This plugin uses [babel]
+to render dates in the configured [site language]. You can use [babel]'s
+[pattern syntax] or the following shortcodes:
+
+=== "Monday, January 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: full
+ ```
+
+=== "January 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: long
+ ```
+
+=== "Jan 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: medium
+ ```
+
+=== "1/31/24"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: short
+ ```
+
+Note that depending on the [site language], results might look different for
+other languages.
+
+ [babel]: https://pypi.org/project/Babel/
+ [site language]: ../setup/changing-the-language.md#site-language
+ [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax
+
+---
+
+####
+
+
+
+
+Use this setting to change the date format used in post URLs. The format string
+must adhere to [babel]'s [pattern syntax] and should not contain whitespace.
+Some popular choices:
+
+=== ":material-link: blog/2024/01/31/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy/MM/dd
+ ```
+
+=== ":material-link: blog/2024/01/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy/MM
+ ```
+
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy
+ ```
+
+If you want to remove the date from post URLs, e.g., when your blog features
+mostly evergreen content, you can remove the `date` placeholder from the
+[`post_url_format`][config.post_url_format] format string.
+
+---
+
+####
+
+
+
+
+Use this setting to change the format string that is used when generating post
+URLs. You can freely combine placeholders, and join them with slashes or other
+characters:
+
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{date}/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `categories` – Post categories, slugified with [`categories_slugify`][config.categories_slugify]
+- `date` – Post date, formatted with [`post_url_date_format`][config.post_url_date_format]
+- `slug` – Post title, slugified with [`post_slugify`][config.post_slugify], or explicitly set via [`slug`][meta.slug] metadata property
+- `file` – Post filename without `.md` file extension
+
+If you remove the `date` placeholder, make sure that post URLs don't collide
+with URLs of other pages hosted under the [`blog` directory][config.blog_dir],
+as this leads to undefined behavior.
+
+---
+
+####
+
+
+
+
+Use this setting to set an upper bound for the number of categories included in
+post URLs if the `categories` placeholder is part of [`post_url_format`]
+[config.post_url_format] and the post defines categories:
+
+``` yaml
+plugins:
+ - blog:
+ post_url_format: "{categories}/{slug}"
+ post_url_max_categories: 2
+```
+
+If more than one category is given, they are joined with `/` after slugifying.
+
+---
+
+####
+
+
+
+
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - blog:
+ post_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+####
+
+
+
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`post_slugify`][config.post_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - blog:
+ post_slugify_separator: _
+```
+
+---
+
+####
+
+
+
+
+By default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)
+optional. When a post doesn't define an excerpt, views include the entire post.
+This setting can be used to make post excerpts required:
+
+=== "Optional"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: optional
+ ```
+
+=== "Required"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: required
+ ```
+
+When post excerpts are required, posts without excerpt separators raise an
+error. Thus, this setting is useful when you want to make sure that all posts
+have excerpts defined.
+
+---
+
+####
+
+
+
+
+Use this setting to set an upper bound for the number of authors rendered in
+post excerpts. While each post may be written by multiple authors, this setting
+allows to limit the display to just a few or even a single author, or disable
+authors in post excerpts:
+
+=== "Render up to 2 authors"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_authors: 2
+ ```
+
+=== "Disable authors"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_authors: 0
+ ```
+
+This only applies to post excerpts in views. Posts always render all authors.
+
+---
+
+####
+
+
+
+
+Use this setting to set an upper bound for the number of categories rendered in
+post excerpts. While each post may be assigned to multiple categories, this
+setting allows to limit the display to just a few or even a single category, or
+disable categories in post excerpts:
+
+=== "Render up to 2 categories"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_categories: 2
+ ```
+
+=== "Disable categories"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_categories: 0
+ ```
+
+This only applies to post excerpts in views. Posts always render all categories.
+
+---
+
+####
+
+
+
+
+Use this setting to set the separator the plugin will look for in a post's
+content when generating post excerpts. All content __before__ the separator is
+considered to be part of the excerpt:
+
+``` yaml
+plugins:
+ - blog:
+ post_excerpt_separator:
+```
+
+It is common practice to use an HTML comment as a separator.
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should automatically compute the
+reading time of a post, which is then rendered in post excerpts, as well as in
+posts themselves:
+
+``` yaml
+plugins:
+ - blog:
+ post_readtime: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the number of words that a reader is expected to read
+per minute when computing the reading time of a post. If you want to fine-tune
+it, use:
+
+``` yaml
+plugins:
+ - blog:
+ post_readtime_words_per_minute: 300
+```
+
+A reading time of 265 words per minute is considered to be the
+[average reading time of an adult].
+
+ [average reading time of an adult]: https://help.medium.com/hc/en-us/articles/214991667-Read-time
+
+### Archive
+
+The following settings are available for archive pages:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable archive pages. An archive page shows all
+posts for a specific interval (e.g. year, month, etc.) in reverse order. If you
+want to disable archive pages, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the title of the archive section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_name: Archive
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the date format used for archive page titles. The
+format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
+
+=== "2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: yyyy
+ ```
+
+=== "January 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: MMMM yyyy
+ ```
+
+Note that depending on the [site language], results might look different for
+other languages.
+
+---
+
+####
+
+
+
+
+Use this setting to change the date format used for archive page URLs. The
+format string must adhere to [babel]'s [pattern syntax] and should not contain
+whitespace. Some popular choices:
+
+=== ":material-link: blog/archive/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: yyyy
+ ```
+
+=== ":material-link: blog/archive/2024/01/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: yyyy/MM
+ ```
+
+---
+
+####
+
+
+
+
+Use this setting to change the format string that is used when generating
+archive page URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/archive/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "archive/{date}"
+ ```
+
+=== ":material-link: blog/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "{date}"
+ ```
+
+The following placeholders are available:
+
+- `date` – Archive date, formatted with [`archive_url_date_format`][config.archive_url_date_format]
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for archive pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination_per_page: 5
+```
+
+---
+
+####
+
+
+
+
+Use this setting to leverage the table of contents to display post titles on all
+archive pages. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use
+
+``` yaml
+plugins:
+ - blog:
+ archive_toc: true
+```
+
+### Categories
+
+The following settings are available for category pages:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable category pages. A category page shows all
+posts for a specific category in reverse chronological order. If you want to
+disable category pages, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the title of the category section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_name: Categories
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the format string that is used when generating
+category page URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/category/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "category/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `slug` – Category, slugified with [`categories_slugify`][config.categories_slugify]
+
+---
+
+####
+
+
+
+
+Use this setting to change the function for generating URL-compatible slugs
+from categories. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - blog:
+ categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+---
+
+####
+
+
+
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`categories_slugify`][config.categories_slugify]. While
+the default is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - blog:
+ categories_slugify_separator: _
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for sorting categories. For
+example, if you want to sort categories by the number of posts they contain,
+use the following configuration:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_by: !!python/name:material.plugins.blog.view_post_count
+```
+
+Don't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].
+You can define your own comparison function, which must return something
+that can be compared while sorting, i.e., a string or number.
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which categories are sorted. By
+default, categories are sorted in ascending order, but you can reverse ordering
+as follows:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_reverse: true
+```
+
+---
+
+####
+
+
+
+
+The plugin allows to check categories against a predefined list, in order to
+catch typos or make sure that categories are not arbitrarily added. Specify the
+categories you want to allow with:
+
+``` yaml
+plugins:
+ - blog:
+ categories_allowed:
+ - Search
+ - Performance
+```
+
+The plugin stops the build if a post references a category that is not part of
+this list. Posts can be assigned to categories by using the [`categories`]
+[meta.categories] metadata property.
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for category pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per category page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination_per_page: 5
+```
+
+---
+
+####
+
+
+
+
+Use this setting to leverage the table of contents to display post titles on all
+category pages. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_toc: true
+```
+
+### Authors
+
+The following settings are available for authors:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable post authors. If this setting is enabled,
+the plugin will look for a file named [`.authors.yml`][config.authors_file] and
+render authors in posts and views. Disable this behavior with:
+
+``` yaml
+plugins:
+ - blog:
+ authors: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the path of the file where the author information for
+your posts resides. It's normally not necessary to change this setting, but if
+you need to, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_file: "{blog}/.authors.yml"
+```
+
+The following placeholders are available:
+
+- `blog` – [`blog` directory][config.blog_dir]
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+!!! info "Format of author information"
+
+ The `.authors.yml` file must adhere to the following format:
+
+ ``` yaml title=".authors.yml"
+ authors:
+ :
+ name: string # Author name
+ description: string # Author description
+ avatar: url # Author avatar
+ slug: url # Author profile slug
+ url: url # Author website URL
+ ```
+
+ Note that `` must be set to an identifier for associating authors
+ with posts, e.g., a GitHub username like `squidfunk`. This identifier can
+ then be used in the [`authors`][meta.authors] metadata property of
+ a post. Multiple authors are supported. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable automatically generated author profiles.
+An author profile shows all posts by an author in reverse chronological order.
+You can enable author profiles with:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the title of the authors section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_name: Authors
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the format string that is used when generating
+author profile URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/author/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "author/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]
+- `name` – Author name from [`authors_file`][config.authors_file]
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for author profiles. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination_per_page: 5
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to leverage the table of contents to display post titles on all
+author profiles. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_toc: true
+```
+
+### Pagination
+
+The following settings are available for pagination:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable pagination in views – generated pages
+that show posts or subsets of posts in reverse chronological order. If you want
+to disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the number of posts rendered per page. If you have
+rather long post excerpts, it can be a good idea to reduce the number of posts
+per page:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_per_page: 5
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the format string that is used when generating
+paginated view URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/page/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "page/{page}"
+ ```
+
+=== ":material-link: blog/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "{page}"
+ ```
+
+The following placeholders are available:
+
+- `page` – Page number
+
+---
+
+####
+
+
+
+
+The plugin uses the [paginate] module to generate the pagination markup using a
+special syntax. Use this setting to customize how pagination is constructed.
+Some popular choices:
+
+=== "1 2 3 .. n"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "~2~"
+ ```
+
+=== "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
+ ```
+
+=== "1 :material-chevron-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "$link_previous $page $link_next"
+ ```
+
+The following placeholders are supported by [paginate]:
+
+- `#!css $first_page` – Number of first reachable page
+- `#!css $last_page` – Number of last reachable page
+- `#!css $page` – Number of currently selected page
+- `#!css $page_count` – Number of reachable pages
+- `#!css $items_per_page` – Maximal number of items per page
+- `#!css $first_item` – Index of first item on the current page
+- `#!css $last_item` – Index of last item on the current page
+- `#!css $item_count` – Total number of items
+- `#!css $link_first` – Link to first page (unless on first page)
+- `#!css $link_last` – Link to last page (unless on last page)
+- `#!css $link_previous` – Link to previous page (unless on first page)
+- `#!css $link_next` – Link to next page (unless on last page)
+
+ [paginate]: https://pypi.org/project/paginate/
+
+---
+
+####
+
+
+
+
+Use this setting to control whether pagination should be automatically disabled
+when the view only consists of a single page. If you want to always render
+pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_if_single_page: true
+```
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable persistence of content, i.e., if paginated
+views should also display the content of their containing view. If you want to
+enable this behavior, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_keep_content: true
+```
+
+### Drafts
+
+The following settings are available for drafts:
+
+---
+
+####
+
+
+
+
+Rendering [draft posts][meta.draft] can be useful in deploy previews. Use this
+setting to specify whether the plugin should include posts marked as drafts when
+[building your project]:
+
+=== "Render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: true
+ ```
+
+=== "Don't render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: false
+ ```
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should include posts marked as
+drafts when [previewing your site]. If you don't wish to include draft posts
+when previewing, use:
+
+``` yaml
+plugins:
+ - blog:
+ draft_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+####
+
+
+
+
+The plugin can automatically mark posts with future dates as drafts. When the
+date is past today, the post is automatically included when
+[building your project], unless explicitly marked as draft:
+
+``` yaml
+plugins:
+ - blog:
+ draft_if_future_date: true
+```
+
+## Usage
+
+### Metadata
+
+Posts can define a handful of metadata properties that specify how the plugin
+renders them, in which views they are integrated, and how they are linked to
+each other. The metadata of each post is validated against a schema to allow for
+a quicker discovery of syntax errors.
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a post with [authors] by providing a list of
+identifiers as defined in the [`authors_file`][config.authors_file]. If an
+author can't be resolved, the plugin will terminate with an error:
+
+``` yaml
+---
+authors:
+ - squidfunk # (1)!
+---
+
+# Post title
+...
+```
+
+1. Authors are linked by using their identifiers. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [authors]: #authors
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a post with one or more [categories][category],
+making the post a part of the generated category page. Categories are defined
+as a list of strings (whitespaces are allowed):
+
+``` yaml
+---
+categories:
+ - Search
+ - Performance
+---
+
+# Post title
+...
+```
+
+If you want to prevent accidental typos assigning categories to posts, you
+can set a predefined list of allowed categories in `mkdocs.yml` by using
+the [`categories_allowed`][config.categories_allowed] setting.
+
+---
+
+####
+
+
+
+
+
+Use this property to specify a post's date. Note that this property is required,
+which means the build fails when it's not set. Additional dates can be set by
+using a slightly different syntax:
+
+=== "Date"
+
+ ``` yaml
+ ---
+ date: 2024-01-31
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Update date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2024-01-31 # (1)!
+ updated: 2024-02-01
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. Each post must have a creation date set.
+
+=== "Custom date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2024-01-31
+ my_custom_date: 2024-02-01 # (1)!
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. The blog plugin validates all dates and allows to format them with
+ [babel]'s [pattern syntax] in templates. When using theme extension,
+ authors can add custom dates to templates.
+
+ This was first requested in #5733.
+
+The following date formats are supported:
+
+- `2024-01-31`
+- `2024-01-31T12:00:00`
+
+---
+
+####
+
+
+
+
+
+Use this property to mark a post as draft. The plugin allows to include or
+exclude posts marked as drafts when [building your project] using the
+[`draft`][config.draft] setting. Mark a post as draft with:
+
+``` yaml
+---
+draft: true
+---
+
+# Post title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+
+Use this property to pin a post to the top of a view. In case multiple posts are
+pinned, the pinned posts are sorted by descending order and appear before all
+other posts. Pin a post with:
+
+``` yaml
+---
+pin: true
+---
+
+# Post title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+
+Use this property to define a list of links that are rendered in the sidebar of
+a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
+`mkdocs.yml`, supporting sections and even anchors:
+
+=== "Links"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - insiders/index.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with sections"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - Insiders:
+ - insiders/index.md
+ - insiders/getting-started.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with anchors"
+
+ ``` yaml
+ ---
+ links:
+ - plugins/search.md # (1)!
+ - Insiders:
+ - insiders/how-to-sponsor.md
+ - insiders/getting-started.md#requirements
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. If a link defines an anchor, the plugin resolves the anchor from the
+ linked page and sets the anchor title as a [subtitle].
+
+All relative links are resolved from the [`docs` directory][mkdocs.docs_dir].
+
+ [subtitle]: ../reference/index.md#setting-the-page-subtitle
+
+---
+
+####
+
+
+
+
+
+Use this property to explicitly set the reading time of a post in minutes. When
+[`post_readtime`][config.post_readtime] is enabled, the plugin computes the
+reading time of a post, which can be overridden with:
+
+``` yaml
+---
+readtime: 15
+---
+
+# Post title
+...
+```
+
+---
+
+####
+
+
+
+
+
+Use this property to explicitly set the slug of a post. By default, the slug of
+a post is automatically computed by the [`post_slugify`][config.post_slugify]
+function from the post's title, which can be overridden with:
+
+``` yaml
+---
+slug: help-im-trapped-in-a-universe-factory
+---
+
+# Post title
+...
+```
+
+Slugs are passed to [`post_url_format`][config.post_url_format].
+
+---
+
+!!! question "Missing something?"
+
+ When setting up your blog or migrating from another blog framework, you
+ might discover that you're missing specific functionality – we're happy to
+ consider adding it to the plugin! You can [open a discussion] to
+ ask a question, or create a [change request] on our [issue tracker], so we
+ can find out if it might be a good fit for the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/mkdocs-material/docs/plugins/group.md b/mkdocs-material/docs/plugins/group.md
new file mode 100644
index 0000000..6e17c4c
--- /dev/null
+++ b/mkdocs-material/docs/plugins/group.md
@@ -0,0 +1,121 @@
+---
+title: Built-in group plugin
+icon: material/format-list-group
+---
+
+# Built-in group plugin
+
+The group plugin allows to group plugins into logical units to conditionally
+enable or disable them for specific environments with the use of
+[environment variables][mkdocs.env], e.g., to only enable a subset of
+plugins when [building your project] during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin conditionally and lazily loads all plugins that are part of a group
+if and only if the group is enabled, which means that the plugin doesn't add any
+overhead when the group is disabled. It also means that the grouped plugins
+only need to be installed when the group is enabled.
+
+The plugins that are part of the group are executed in the same order as if
+they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
+Thus, order is preserved and deterministic.
+
+### When to use it
+
+Whenever you're using multiple plugins that are only required in specific
+environments, e.g., when building your project during continuous integration
+(CI), the plugin is the perfect utility for making configuration simpler, as it
+removes the need for splitting configuration into multiple files.
+
+It can be used with any built-in or third-party plugin.
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the group plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+splitting plugins into logical units:
+
+``` yaml
+plugins:
+ - group
+```
+
+The group plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [group]: group.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+The plugin behaves differently than all other built-in plugins – __it is
+disabled by default__. To enable a group, use:
+
+``` yaml
+plugins:
+ - group:
+ enabled: !ENV CI # (1)!
+```
+
+1. If you only want to use the group plugin for better organization and
+ always want to enable the plugins that are part of it, use:
+
+ ``` yaml
+ plugins:
+ - group:
+ enabled: true
+ ```
+
+The decision to disable the plugin by default was made to simplify the usage
+of environment variables, as it removes the need to provide a default value for
+an environment variable.
+
+Now, when [building your project], you can enable a group by setting the
+[environment variable][mkdocs.env]:
+
+``` sh
+CI=true mkdocs build
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+Use this setting to list the plugins that are part of the group. The syntax is
+exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
+simply copy the list of plugins that you want to group, e.g:
+
+``` yaml
+plugins:
+ - group:
+ plugins:
+ - optimize
+ - minify
+```
+
+The plugins mentioned here are just used for illustration purposes.
diff --git a/mkdocs-material/docs/plugins/index.md b/mkdocs-material/docs/plugins/index.md
new file mode 100644
index 0000000..8bf6a8a
--- /dev/null
+++ b/mkdocs-material/docs/plugins/index.md
@@ -0,0 +1,246 @@
+# Built-in plugins
+
+Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
+evolved into a full-fledged framework for building and maintaining documentation.
+The theme is still the core of the project, but it's now accompanied by a
+growing number of complementary built-in plugins.
+
+We strive to make those plugins as modular and generic as possible, so that they
+can be used in a wide variety of projects and use cases. By providing useful
+default settings, we also try to make them as easy to use as possible, so that
+you can get started quickly, tweaking their settings later on. When
+developing built-in plugins, we always adhere to the following design principles:
+
+- **Modularity:** Built-in plugins are designed to be modular, so that they can
+ be easily combined to implement sophisticated pipelines. For example, the
+ [offline], [optimize] and [privacy] plugins can be used together to build
+ truly [offline-capable documentation].
+
+- **Interoperability:** Built-in plugins are designed to be as compatible as
+ possible, so they can be used in combination with other plugins, including
+ third-party plugins. We strive to make it simple to integrate with the vast
+ ecosystem that has evolved around [MkDocs][mkdocs].
+
+- **Performance:** Built-in plugins are designed to be as fast and
+ memory-efficient as possible, so that they don't unnecessarily slow down
+ builds. This is particularly important for large documentation projects with
+ thousands of pages.
+
+ [mkdocs]: https://www.mkdocs.org/
+ [design principles]: ../design-principles.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Categories
+
+### Management
+
+The following plugins greatly improve the authoring experience when working on
+documentation projects by providing better management capabilities, from the
+management of plugins, multiple projects, and metadata, to the creation of
+minimal reproductions for bug reports:
+
+
+
+- :material-format-list-group: __[Built-in group plugin][group]__
+
+ ---
+
+ The group plugin allows to group plugins into logical units to conditionally
+ enable or disable them for specific environments with the use of
+ [environment variables][mkdocs.env].
+
+ ---
+
+ __Optimal management of plugins when building in different environments__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to manage metadata (front matter) for all
+ pages in a folder, so a certain subset of pages uses specific tags or a
+ custom template.
+
+ ---
+
+ __Simpler organization, categorization and management of metadata__
+
+- :material-folder-open: __[Built-in projects plugin][projects]__
+
+ ---
+
+ The projects plugin allows to split your main project into multiple distinct
+ projects, build them concurrently and preview them together as one.
+
+ ---
+
+ __Connect multiple projects together, and build them separately or as one__
+
+- :material-information: __[Built-in info plugin][info]__
+
+ ---
+
+ The info plugin is a small and useful utility that helps to create
+ self-contained minimal reproductions, so we maintainers can fix reported
+ bugs more quickly.
+
+ ---
+
+ __Your bug reports are of the highest quality, so we can fix them as fast as
+ possible__
+
+
+
+
+ [group]: group.md
+ [info]: info.md
+ [meta]: meta.md
+ [projects]: projects.md
+
+### Optimization
+
+The following plugins are designed to help you build optimized documentation,
+making it more accessible to your users through faster loading times, better
+search engine rankings, beautiful preview images on social media, and GDPR
+compliance with a few lines of configuration:
+
+
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each page of your documentation, showing as previews on
+ social media.
+
+ ---
+
+ __Links to your site render beautiful social cards when shared on social
+ media__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your site loads faster as smaller images are served to your users__
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin downloads external assets automatically for easy
+ self-hosting, allowing for GDPR compliance with a single line of
+ configuration.
+
+ ---
+
+ __Your documentation can be made GDPR compliant with minimal effort__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building [offline-capable documentation],
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+
+
+ [offline]: offline.md
+ [optimize]: optimize.md
+ [privacy]: privacy.md
+ [social]: social.md
+
+### Content
+
+The following plugins are designed to help you set up a blog, provide search
+functionality to your users, add tags to pages and posts, and use the same
+typesetting capabilities in specific parts of the documentation exactly as in
+the main content:
+
+
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The blog plugin adds first-class support for blogging to Material for
+ MkDocs, either as a sidecar to your documentation or as a standalone
+ installation.
+
+ ---
+
+ __Your blog is built with the same powerful engine as your documentation__
+
+- :material-magnify: __[Built-in search plugin][search]__
+
+ ---
+
+ The search plugin adds a search bar to the header, allowing users to search
+ the entire documentation, so it's easier for them to find what they're
+ looking for.
+
+ ---
+
+ __Your documentation is searchable without any external services, even
+ offline__
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The tags plugin adds first-class support for categorizing pages with tags,
+ adding the ability to group related pages to improve the discovery of
+ related content.
+
+ ---
+
+ __Your pages are categorized with tags, yielding additional context__
+
+- :material-format-title: __[Built-in typeset plugin][typeset]__
+
+ ---
+
+ The typeset plugin allows to preserve the enriched presentation of titles
+ and headlines within the navigation and table of contents.
+
+ ---
+
+ __Sidebars preserve the same formatting as section titles in pages__
+
+
+
+ [blog]: blog.md
+ [search]: search.md
+ [tags]: tags.md
+ [typeset]: typeset.md
+
+## Architecture
+
+### Multiple instances
+
+Several built-in plugins have support for multiple instances, which means that
+they can be used multiple times in the same configuration file, allowing to
+fine-tune behavior for separate sections of your project. Currently, the
+following plugins have support for multiple instances:
+
+
+
+- [Built-in blog plugin][blog]
+- [Built-in group plugin][group]
+- [Built-in optimize plugin][optimize]
+- [Built-in privacy plugin][privacy]
+- [Built-in social plugin][social]
+
+
diff --git a/mkdocs-material/docs/plugins/info.md b/mkdocs-material/docs/plugins/info.md
new file mode 100644
index 0000000..b422daa
--- /dev/null
+++ b/mkdocs-material/docs/plugins/info.md
@@ -0,0 +1,155 @@
+---
+title: Built-in info plugin
+icon: material/information
+---
+
+# Built-in info plugin
+
+The info plugin is a utility that is solely intended to create self-contained
+[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
+[change requests], making communication between us maintainers and you much
+easier, as we have a common ground to work on.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
+ [reporting bugs]: ../contributing/reporting-a-bug.md
+ [change requests]: ../contributing/requesting-a-change.md
+
+## Objective
+
+### How it works
+
+The plugin helps you to prepare a minimal reproduction by collecting the
+necessary information about the environment and configuration of your project.
+This makes it easier for us to fix bugs, as it requires that you
+[upgrade to the latest version] and [remove your customizations].
+
+When following these principles, you can be confident that you don't report a
+bug that has already been fixed in a subsequent release, or which is caused by
+one of your customizations. Even more importantly, you actively help
+us to fix the bug as quickly as possible.
+
+The output of the plugin is a `.zip` file that you can share with us maintainers.
+
+ [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+ [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
+
+
+### When to use it
+
+Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
+like a question or [change request][change requests], you should attach
+a small, self-contained minimal reproduction. Runnable examples help to make
+communication much more efficient, giving us maintainers more time to benefit
+more users by pushing the project forward. Minimal reproductions are mandatory
+for bug reports.
+
+## Configuration
+
+
+
+
+In order to get started with the built-in info plugin, just add the following
+lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
+with us maintainers:
+
+``` yaml
+plugins:
+ - info
+```
+
+The info plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [info]: info.md
+ [create a minimal reproduction]: ../guides/creating-a-reproduction.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should be enabled when
+[previewing your site]. It's normally not necessary to specify this setting,
+but if you want to change this behavior, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled_on_serve: true
+```
+
+This setting streamlines the process of creating and inspecting minimal
+reproductions, as it allows to quickly iterate on the reproduction without
+having to disable the plugin first.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+### Archive
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should create a `.zip` file
+from the project or exit after the version check. This setting is solely
+intended for debugging the plugin itself:
+
+``` yaml
+plugins:
+ - info:
+ archive: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should stop creating the `.zip`
+file when one of the [requirements] is not satisfied. This setting must only be
+used when [reporting a bug][reporting bugs] that is related to a customization
+[explicitly mentioned in our documentation]. You can change it with:
+
+``` yaml
+plugins:
+ - info:
+ archive_stop_on_violation: false
+```
+
+If you're using this setting when [reporting a bug][reporting bugs], please
+explain why you think it is necessary to include customizations. If you're
+unsure, please ask us first by [creating a discussion].
+
+ [requirements]: #how-it-works
+ [explicitly mentioned in our documentation]: ?q=%22extends+base%22
+ [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/mkdocs-material/docs/plugins/meta.md b/mkdocs-material/docs/plugins/meta.md
new file mode 100644
index 0000000..5ab8496
--- /dev/null
+++ b/mkdocs-material/docs/plugins/meta.md
@@ -0,0 +1,202 @@
+---
+title: Built-in meta plugin
+icon: material/file-tree
+---
+
+# Built-in meta plugin
+
+The meta plugin solves the problem of setting metadata (front matter) for all
+pages in a folder, i.e., a subsection of your project, which is particularly
+useful to ensure that a certain subset of pages features specific tags, uses a
+custom template, or is attributed to an author.
+
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
+and recursively merges the contents of those files with the metadata (front
+matter) of all pages that are contained in the same folder and all subfolders.
+For example, if you want to add the tag Example to
+multiple pages, use:
+
+``` yaml title=".meta.yml"
+tags:
+ - Example
+```
+
+Now, given the following directory layout, if you store the file in the folder
+named `example`, all pages in that folder receive the tag, while all pages
+outside of the folder remain unaffected:
+
+``` { .sh .no-copy hl_lines="4-8" }
+.
+├─ docs/
+│ ├─ ...
+│ ├─ example/
+│ │ ├─ .meta.yml
+│ │ ├─ a.md
+│ │ ├─ ...
+│ │ └─ z.md
+│ └─ ...
+└─ mkdocs.yml
+```
+
+When combining metadata, lists and dictionaries are recursively merged, which
+means you can append values to a list and add or set specific properties in a
+dictionary on arbitrary levels.
+
+### When to use it
+
+While the plugin itself doesn't offer much functionality beyond adding and
+merging metadata, it is a perfect companion for many of the other built-in
+plugins that Material for MkDocs offers. Some of the most powerful combinations
+of the meta plugin and other built-in plugins are:
+
+
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The meta plugin can be used to [change the layout] for social cards or
+ [change specific layout options] like [background] or [color]
+ for a subset of pages.
+
+ ``` yaml title=".meta.yml"
+ social:
+ cards_layout: default/variant
+ ```
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The meta plugin allows to automatically associate blog posts with specific
+ [authors] and [categories], ensuring that blog posts are always correctly
+ annotated.
+
+ ``` yaml title=".meta.yml"
+ authors:
+ - squidfunk
+ ```
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags], so they can't be forgotten when
+ adding pages.
+
+ ``` yaml title=".meta.yml"
+ tags:
+ - Example
+ ```
+
+- :material-magnify: __[Built-in search plugin][search]__
+
+ ---
+
+ The meta plugin makes it easy to [boost] specific sections in search results
+ or to [exclude] them entirely from being indexed, giving more granular
+ control over search.
+
+ ``` yaml title=".meta.yml"
+ search:
+ exclude: true
+ ```
+
+
+
+ [social]: social.md
+ [change the layout]: social.md#meta.social.cards_layout
+ [change specific layout options]: social.md#meta.social.cards_layout_options
+ [background]: social.md#option.background_color
+ [color]: social.md#option.color
+ [blog]: blog.md
+ [authors]: blog.md#meta.authors
+ [categories]: blog.md#meta.categories
+ [tags]: tags.md
+ [specific tags]: tags.md#meta.tags
+ [search]: search.md
+ [exclude]: search.md#meta.search.exclude
+ [boost]: search.md#meta.search.boost
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the meta plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+applying metadata for multiple pages at once:
+
+``` yaml
+plugins:
+ - meta
+```
+
+The meta plugin is included with Material for MkDocs and doesn't need to be
+installed.
+
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - meta:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Meta file
+
+The following settings are available for meta files:
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the meta file name the plugin will look for when
+scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
+change this setting, but if you want to change it, use:
+
+``` yaml
+plugins:
+ - meta:
+ meta_file: .meta.yml
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
+recursively.
diff --git a/mkdocs-material/docs/plugins/offline.md b/mkdocs-material/docs/plugins/offline.md
new file mode 100644
index 0000000..760c01b
--- /dev/null
+++ b/mkdocs-material/docs/plugins/offline.md
@@ -0,0 +1,153 @@
+---
+title: Built-in offline plugin
+icon: material/connection
+---
+
+
+# Built-in offline plugin
+
+[MkDocs][mkdocs] is one of the few frameworks that allow to build offline-capable
+documentation that can be directly viewed by the user – no server needed. With
+the offline plugin, you can distribute the [`site` directory][mkdocs.site_dir]
+as a downloadable `.zip` file while retaining most interactive functionality.
+
+## Objective
+
+### How it works
+
+After [building your project], switch to the [`site` directory][mkdocs.site_dir]
+and open `index.html` in your browser – you're now viewing your documentation
+from your local file system! Most browsers will denote this by showing `file://`
+in the address bar. However, you'll realize that the site search is gone.
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the local file system due to the restrictions of modern browsers. More
+specifically and technically, all calls to the [Fetch API] will error with a
+message like:
+
+```
+Cross origin requests are only supported for protocol schemes: http, [...]
+```
+
+While browsers impose those restriction for security reasons, it reduces the
+interactivity of your project. The offline plugin makes sure that site search
+keeps working by moving the search index to a JavaScript file, and leveraging
+@squidfunk's [iframe-worker] shim.
+
+Additionally, the plugin automatically disables the [`use_directory_urls`]
+[mkdocs.use_directory_urls] setting, ensuring that users can open your
+documentation directly from the local file system.
+
+There are some [limitations].
+
+ [building your project]: ../creating-your-site.md#building-your-site
+ [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ [iframe-worker]: https://github.com/squidfunk/iframe-worker
+ [limitations]: #limitations
+
+### When to use it
+
+As the name already indicates, the plugin should only be used when you're
+[building your project] for offline distribution. It's also good to know, that
+the offline plugin plays nicely with the following other plugins, helping to
+create even better offline-capable documentation:
+
+
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use external assets when building for
+ offline usage, as it automatically downloads them for distribution with
+ your documentation.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet[^1]__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your documentation can be distributed as a smaller `.zip` download__
+
+
+
+ [^1]:
+ You might wonder why the [privacy plugin][privacy] is necessary to build
+ truly offline-capable documentation with the offline plugin. While it's
+ certainly possible to also add support for downloading external assets to
+ the offline plugin, this functionality is already fully implemented in the
+ privacy plugin and is its very raison d'être.
+
+ Material for MkDocs follows a modular approach for its plugin system – many
+ of the plugins work perfectly together and enhance each others
+ functionalities, allowing to solve complex problems with a few lines
+ of configuration.
+
+ [privacy]: privacy.md
+ [optimize]: optimize.md
+
+## Configuration
+
+
+
+
+As with all [built-in plugins], getting started with the offline plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+building offline-capable documentation:
+
+``` yaml
+plugins:
+ - offline
+```
+
+The offline plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [offline]: offline.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to build online- as well as offline-capable documentation, it's a
+good idea to use an [environment variable][mkdocs.env]:
+
+``` yaml
+plugins:
+ - offline:
+ enabled: !ENV [OFFLINE, false]
+```
+
+## Limitations
+
+When enabling the offline plugin, make sure to disable the following settings,
+as they make use of the [Fetch API] which will error when invoked from the local
+file system:
+
+- [Instant loading]
+- [Site analytics]
+- [Versioning]
+- [Comment systems]
+
+ [Instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Site analytics]: ../setup/setting-up-site-analytics.md
+ [Versioning]: ../setup/setting-up-versioning.md
+ [Comment systems]: ../setup/adding-a-comment-system.md
diff --git a/mkdocs-material/docs/plugins/optimize.md b/mkdocs-material/docs/plugins/optimize.md
new file mode 100644
index 0000000..231c31e
--- /dev/null
+++ b/mkdocs-material/docs/plugins/optimize.md
@@ -0,0 +1,449 @@
+---
+title: Built-in optimize plugin
+icon: material/rabbit
+---
+
+# Built-in optimize plugin
+
+The optimize plugin automatically identifies and optimizes all media files when
+[building your project] by using common compression and conversion techniques.
+As a result, your site loads significantly faster and yields better rankings in
+search engines.
+
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [building your project]: ../creating-your-site.md#building-your-site
+ [our awesome sponsors]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
+assets, optimizing them automatically in order to reduce the final size of the
+[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
+ship less bytes to your users, as well as a smaller download for
+[offline-capable documentation].
+
+Optimized images are [intelligently cached][intelligent caching], which is why
+the plugin will only optimize media files that changed since the last build.
+This makes it possible to swap out or update images, without having to worry
+about optimizing them, or even worse, forgetting to do so.
+
+In order to optimize media files, a few [dependencies] need to be available on
+your system.
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [dependencies]: #configuration
+
+### When to use it
+
+It's generally recommended to use the plugin, as media files are optimized
+automatically without the need for intervention, ensuring that your site loads
+as fast as possible. Optimized media files are one of the key components for a
+high and consistent ranking in search engines.
+
+Additionally, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated
+build pipelines tailored to your project:
+
+
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use unoptimized external assets, passing
+ them to the optimize plugin before copying them to the [`site` directory]
+ [mkdocs.site_dir].
+
+ ---
+
+ __External media files can be automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building offline-capable documentation,
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can be distributed as a smaller `.zip` download__
+
+
+
+ [privacy]: privacy.md
+ [offline]: offline.md
+
+## Configuration
+
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the optimize plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe how
+media files are optimized automatically:
+
+``` yaml
+plugins:
+ - optimize
+```
+
+The optimize plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to optimize all media files, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [optimize]: optimize.md
+ [built-in plugins]: index.md
+ [image processing]: requirements/image-processing.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - optimize:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete media file optimization faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - optimize:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a media
+file or asset is only passed through the optimization pipeline when its contents
+change. If you swap out or update an image, the plugin detects it and updates
+the optimized version of the media file.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-optimize all media files, even though the cache may not be stale. It's
+normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - optimize:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where media files are cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - optimize:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Optimization
+
+Documentation often makes use of screenshots or diagrams for better
+visualization of things, both of which are prime candidates for optimization.
+The plugin automatically optimizes images using [pngquant] for `.png` files,
+and [Pillow] for `.jpg` files.
+
+The following settings are available for optimization:
+
+ [pngquant]: https://pngquant.org/
+ [Pillow]: https://pillow.readthedocs.io/
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable media file optimization. Currently,
+the plugin's sole purpose is to optimize media files, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the near future, other features
+might be added. If you want to disable optimization, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the optimization of `.png` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.png` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the speed/quality tradeoff that [pngquant] applies
+when optimizing `.png` files. The lower the number, the more aggressively
+[pngquant] will try to optimize:
+
+=== "Slower smaller"
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 1
+ ```
+
+=== "Faster larger"
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 10
+ ```
+
+A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether [pngquant] should strip optional metadata
+from `.png` files that are not required to display the image, e.g., [EXIF].
+If you want to preserve metadata, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png_strip: false
+```
+
+ [EXIF]: https://en.wikipedia.org/wiki/Exif
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the optimization of `.jpg` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.jpg` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the image quality that [Pillow] applies when
+optimizing `.jpg` files. If the images look blurry, it's a good idea to
+fine-tune and change this setting:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_quality: 75
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether [Pillow] should use progressive encoding
+when optimizing `.jpg` files, rendering faster on slow connections. If you want
+to disable progressive encoding, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_progressive: false
+```
+
+ [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_include:
+ - screenshots/*
+```
+
+This configuration enables optimization for all media files that are contained
+in the `screenshots` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - social:
+ optimize_exclude:
+ - vendor/*
+```
+
+This configuration disables optimization for all media files that are contained
+in the `vendor` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+### Reporting
+
+The following settings are available for reporting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should print the number of bytes
+gained after optimizing each file. If you want to disable this behavior, use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should print the total number of
+bytes gained after optimizing all files. If you want to disable this behavior,
+use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain_summary: false
+```
diff --git a/mkdocs-material/docs/plugins/privacy.md b/mkdocs-material/docs/plugins/privacy.md
new file mode 100644
index 0000000..47052a1
--- /dev/null
+++ b/mkdocs-material/docs/plugins/privacy.md
@@ -0,0 +1,504 @@
+---
+title: Built-in privacy plugin
+icon: material/shield-account
+---
+
+
+# Built-in privacy plugin
+
+The privacy plugin offers a streamlined solution for automatically self-hosting
+external assets. With just a single line of configuration, the plugin can
+automatically identify and download external assets, making GDPR compliance
+as effortless as it can possibly be.
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML for external assets, i.e., scripts, style
+sheets, images, and web fonts, downloads them, stores them in the
+[`site` directory][mkdocs.site_dir] and replaces all references with links to
+the downloaded copies for effortless self-hosting. For example:
+
+``` html
+
+```
+
+This external script is downloaded, and the link is replaced with:
+
+``` html
+
+```
+
+Of course, scripts and style sheets can reference further external assets,
+which is why this process is repeated recursively until no further external
+assets are detected:
+
+- Scripts are scanned for further scripts, style sheets and JSON files
+- Style sheets are scanned for images and web fonts
+
+Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
+requesting external assets, are removed from the output, as they're not
+necessary when self-hosting. After the plugin has done it's work, your project
+will be free of requests to external services.
+
+There are some [limitations].
+
+ [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin was developed to make compliance with the 2018 European
+__General Data Protection Regulation__ (GDPR) as simple as possible, while
+retaining the flexibility and power that Material for MkDocs offers, like for
+example its tight integration with [Google Fonts].
+
+But, that's only the start. For example, if your project includes a lot of
+images, enabling the plugin allows to move them outside of your repository, as
+the plugin will automatically download and store them in the [`site` directory]
+[mkdocs.site_dir] when [building your project].
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin allows to optimize all downloaded external assets
+ detected by the privacy plugin by using compression and conversion
+ techniques.
+
+ ---
+
+ __External media files are automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building [offline-capable documentation],
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+
+
+ [Google Fonts]: ../setup/changing-the-fonts.md
+ [building your project]: ../creating-your-site.md#building-your-site
+ [optimize]: optimize.md
+ [offline]: offline.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the privacy plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+effortlessly self-hosting external assets:
+
+``` yaml
+plugins:
+ - privacy
+```
+
+The privacy plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [privacy]: privacy.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - privacy:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+####
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete handling of external assets faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - privacy:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that external
+assets are only downloaded when they're not already contained in the cache.
+While the initial build might take some time, it's a good idea to use caching,
+as it will speed up consecutive builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-schedule downloads for all external assets, even though the cache may not be
+stale. It's normally not necessary to specify this setting, except for when
+debugging the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - privacy:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where downloaded copies are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should display log messages when
+building your site. While not being recommended, you can disable logging with:
+
+``` yaml
+plugins:
+ - privacy:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot
+ be created due to a lack of permissions on Windows systems (#6550).
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported, including which
+ assets were successfully downloaded by the plugin.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages, if and only if MkDocs
+ was started with the `--verbose` flag. Note that this will print a lot of
+ messages and is only useful for debugging.
+
+### External assets
+
+The following settings are available for external assets:
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should download external
+assets. If you only want the plugin to process [external links], you can disable
+handling of external assets with:
+
+``` yaml
+plugins:
+ - privacy:
+ assets: false
+```
+
+ [external links]: #external-links
+
+---
+
+####
+
+
+
+
+Use this setting to control whether the plugin should downloads or only report
+external assets when they're encountered. If you already self-host all external
+assets, this setting can be used as a safety net to detect links to external
+assets placed by the author in pages:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch: true
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+external assets are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch_dir: my/custom/dir
+```
+
+This configuration stores the downloaded copies at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_include:
+ - unsplash.com/*
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_exclude: # (1)!
+ - unpkg.com/mathjax@3/*
+ - giscus.app/*
+```
+
+1. [MathJax] loads web fonts for typesetting of mathematical content
+ through relative URLs, and thus cannot be automatically bundled by the
+ privacy plugin. [MathJax can be self-hosted].
+
+ [Giscus], which we recommend to use as a [comment system], uses a technique
+ called code-splitting to load only the code that is necessary, which
+ is implemented via relative URLs. [Giscus can be self-hosted] as well.
+
+ [MathJax]: ../reference/math.md
+ [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
+ [Giscus]: https://giscus.app/
+ [comment system]: ../setup/adding-a-comment-system.md
+ [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
+
+---
+
+### External links
+
+The following settings are available for external links:
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to parse and process external links to
+annotate them for [improved security], or to automatically add additional
+attributes to external links. If you want to disable processing of external
+links, use:
+
+``` yaml
+plugins:
+ - privacy:
+ links: false
+```
+
+ [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify additional attributes that should be added to
+external links, for example, to add `target="_blank"` to all external links
+so they open in a new tab:
+
+``` yaml
+plugins:
+ - privacy:
+ links_attr_map:
+ target: _blank
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not recommended to change this setting, as it will automatically
+annotate external links that open in a new window with `rel="noopener"` for
+[improved security]:
+
+``` yaml
+plugins:
+ - privacy:
+ links_noopener: true
+```
+
+## Limitations
+
+### Dynamic URLs
+
+Dynamically created URLs as part of scripts are not detected, and thus cannot be
+downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
+
+``` js
+const host = "https://example.com"
+const path = `${host}/script.js`
+```
+
+Instead, always use fully qualified URLs:
+
+``` js
+const url ="https://example.com/script.js"
+```
+
+### Embedded HTML
+
+By default, embedded HTML files (e.g. in iframes) are not scanned for external
+assets. This is a limitation of MkDocs, as it considers `.html` files to be
+templates, which must be explicitly listed under
+[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets
+of an embedded HTML file:
+
+``` yaml
+extra_templates:
+ - iframe.html
+```
+
+Note that the path to `iframe.html` is relative to the
+[`docs_dir`][mkdocs.docs_dir] directory.
diff --git a/mkdocs-material/docs/plugins/projects.md b/mkdocs-material/docs/plugins/projects.md
new file mode 100644
index 0000000..c7327ab
--- /dev/null
+++ b/mkdocs-material/docs/plugins/projects.md
@@ -0,0 +1,447 @@
+---
+title: Built-in projects plugin
+icon: material/folder-open
+---
+
+# Built-in projects plugin
+
+The projects plugin adds the ability to split your main project into multiple
+distinct projects, build them concurrently and preview them together as one.
+This is particularly useful when creating a multi-language project, but can also
+be used to split very large projects into smaller parts.
+
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`projects` directory][config.projects_dir] for
+`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
+If not configured otherwise, the plugin expects that your project has
+the following directory layout, e.g. for a multi-language project:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+├─ projects/
+│ ├─ en/
+│ │ ├─ docs/
+│ │ └─ mkdocs.yml
+│ └─ de/
+│ ├─ docs/
+│ └─ mkdocs.yml
+└─ mkdocs.yml
+```
+
+One of the most useful and interesting features of the plugin is that it allows
+[previewing your site] from the main project, while still being able to preview
+and build each project individually. This is especially useful for
+multi-language projects.
+
+If, when [previewing your site], you change a file in one of the projects, the
+plugin only rebuilds this project and makes sure that MkDocs will also reload
+the associated files. This also creates the opportunity for splitting your
+main project into several projects for a better editing experience.
+
+There are some [limitations], but we're working hard to remove them.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin came into existence because we needed a convenient and scalable
+method to build our [examples] repository, which features many self-contained
+and runnable projects that users can download and use as a basis when
+bootstrapping a new project or [creating a reproduction].
+
+When you want to create a multi-language project, or have a very large existing
+project, you might consider using the plugin, as it makes managing, editing
+and building more comfortable.
+
+ [examples]: https://github.com/mkdocs-material/examples
+ [creating a reproduction]: ../guides/creating-a-reproduction.md
+
+## Configuration
+
+
+
+
+
+
+In order to get started with the projects plugin, just add the following lines
+to `mkdocs.yml`, and split your main project into several distinct projects that
+can be built concurrently:
+
+``` yaml
+plugins:
+ - projects
+```
+
+The projects plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [projects]: projects.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+build projects faster. If you want to disable concurrent processing completely,
+use:
+
+``` yaml
+plugins:
+ - projects:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a
+project is only rebuilt when its contents change. While the initial build might
+take some time, it's a good idea to use caching, as it will speed up consecutive
+builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+rebuild all projects, even though the cache may not be stale. It's normally not
+necessary to specify this setting, except for when debugging the plugin itself.
+Caching can be disabled with:
+
+``` yaml
+plugins:
+ - projects:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where the metadata is cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - projects:
+ cache_dir: my/custom/dir
+```
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should display log messages from
+projects when building your site. While not being recommended, you can disable
+logging with:
+
+``` yaml
+plugins:
+ - projects:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages.
+
+### Projects
+
+The following settings are available for projects:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable building of projects. Currently, the
+plugin's sole purpose is to build projects, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable building of projects, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the folder where your projects are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects_dir: projects
+```
+
+Note that the [`projects` directory][config.projects_dir] is solely used for
+project organization – it is not included in project URLs, since projects are
+automatically hoisted by the plugin.
+
+The provided path is resolved from the root directory.
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the location or name of configuration files the
+plugin will look for when scanning the [`projects` directory]
+[config.projects_dir]. Adjusting this setting can be necessary when the
+configuration files are located in subdirectories of projects, e.g.
+`docs/mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_files: "**/mkdocs.yml" # (1)!
+```
+
+1. If all projects share the same location for their configuration files, e.g.,
+ `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
+ to resolve than a `**` glob pattern.
+
+ ``` yaml
+ plugins:
+ - projects:
+ projects_config_files: "*/docs/mkdocs.yml"
+ ```
+
+ This configuration fits the following directory structure, which is quite
+ common for projects using git submodules:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ ├─ projects/
+ │ ├─ git-submodule-a/
+ │ │ └─ docs/
+ │ │ └─ mkdocs.yml
+ │ └─ git-submodule-b/
+ │ └─ docs/
+ │ └─ mkdocs.yml
+ └─ mkdocs.yml
+ ```
+
+The provided path is resolved from the [`projects` directory]
+[config.projects_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to transform the configuration of each project as read from
+`mkdocs.yml` before it is built, which allows for adjusting the configuration
+of each project when building them together, but leave them untouched when
+building them individually:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_transform: !!python/name:projects.transform
+```
+
+The provided module and function name are looked up in Python's [module search
+path]. You need to add your root directory to the search path when building
+your site, so Python can resolve it. The easiest way is to add the working
+directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
+
+``` .sh
+export PYTHONPATH=.
+```
+
+!!! tip "How to define a configuration transformation function"
+
+ The [`python/name`][python-name] tag is provided by [PyYAML] and must point
+ to a valid module and function name within Python's [module search path].
+ The plugin passes the `project` and top-level `config` objects to the
+ function.
+
+ As an example, we can inherit the [`use_directory_urls`]
+ [mkdocs.use_directory_urls] setting for all projects from the top-level
+ configuration:
+
+ ``` py title="projects/__init__.py"
+ from mkdocs.config.defaults import MkDocsConfig
+
+ # Transform project configuration
+ def transform(project: MkDocsConfig, config: MkDocsConfig):
+ project.use_directory_urls = config.use_directory_urls
+ ```
+
+ [module search path]: https://docs.python.org/3/library/sys_path_init.html
+ [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+ [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
+ [PyYAML]: https://pyyaml.org/
+
+### Hoisting
+
+The following settings are available for hoisting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable hoisting of themes files to the main
+project. If you disable this setting, each project receives a copy of the
+theme's files, which can be considered redundant:
+
+``` yaml
+plugins:
+ - projects:
+ hoisting: false
+```
+
+It's generally advisable to enable hoisting, as it yields faster deployments
+and faster loading of your project's sites, because the files are the same for
+all projects and can be deduplicated.
+
+### Limitations
+
+The plugin is one of the latest additions to Material for MkDocs, which means it
+is rather young and has some limitations. We're working hard to remove them, and
+we're happy to receive feedback and learn about your requirements in ?5800.
+Current limitations are:
+
+- __Basic multi-language support only__: we'll be investigating how to provide
+ better support for multi-language projects, allowing to easier interlink
+ projects and switch between them.
+
+- __Separate search indexes and sitemaps__: currently, the projects are entirely
+ separate, which means they will have separate search indexes and sitemaps.
diff --git a/mkdocs-material/docs/plugins/requirements/caching.md b/mkdocs-material/docs/plugins/requirements/caching.md
new file mode 100644
index 0000000..63b3f4a
--- /dev/null
+++ b/mkdocs-material/docs/plugins/requirements/caching.md
@@ -0,0 +1,35 @@
+---
+icon: material/database-outline
+---
+
+# Caching
+
+Some of the [built-in plugins] implement intelligent caching mechanisms, which
+massively speed up consecutive builds by reducing the amount of work that needs
+to be done. This guide explains how to configure caching in different
+environments.
+
+## Prerequisites
+
+Caching is entirely optional but enabled by default. It can be disabled per
+plugin. If not configured otherwise, plugins will cache their data in the
+`.cache` folder in the root of your project. For this reason it's recommended
+to create a `.gitignore` file in the root of your project:
+
+``` title=".gitignore"
+.cache
+```
+
+This ensures that cached files are not added to your git repository – something
+that is generally not recommended to do unless absolutely necessary. In some
+cases, you might need to check in cached files, e.g. when you need to
+pre-generate [social cards] locally, e.g., when you're not be able to install
+the image processing dependencies in your continuous integration (CI)
+environment.
+
+In this case, we recommend changing the `cache_dir` setting – something that all
+plugins that implement caching share – to a folder which you add to your git
+repository.
+
+ [built-in plugins]: ../index.md
+ [social cards]: ../../setup/setting-up-social-cards.md
diff --git a/mkdocs-material/docs/plugins/requirements/image-processing.md b/mkdocs-material/docs/plugins/requirements/image-processing.md
new file mode 100644
index 0000000..c309315
--- /dev/null
+++ b/mkdocs-material/docs/plugins/requirements/image-processing.md
@@ -0,0 +1,272 @@
+---
+icon: material/image-sync-outline
+---
+
+# Image processing
+
+Some of the [built-in plugins] depend on external libraries for efficient image
+processing, most notably the [social] plugin to generate [social cards], and the
+[optimize] plugin for applying [image optimization]. This guide explains how to
+install those libraries in different environments.
+
+ [built-in plugins]: ../index.md
+ [social]: ../social.md
+ [social cards]: ../../setup/setting-up-social-cards.md
+ [optimize]: ../optimize.md
+ [image optimization]: ../../setup/building-an-optimized-site.md
+
+## Dependencies
+
+The libraries for image processing are entirely optional, and only need to be
+installed if you want to use the [social] plugin or the [optimize] plugin. The
+libraries are listed under the `imaging` extra:
+
+```
+pip install "mkdocs-material[imaging]"
+```
+
+This will install compatible versions of the following packages:
+
+- [Pillow]
+- [CairoSVG]
+
+ [Pillow]: https://pillow.readthedocs.io/
+ [CairoSVG]: https://cairosvg.org/
+
+### Cairo Graphics
+
+[Cairo Graphics] is a graphics library and dependency of [Pillow], which
+Material for MkDocs makes use of for generating [social cards] and performing
+[image optimization]. See the following section which explains how to install
+[Cairo Graphics] and its dependencies on your system:
+
+=== ":material-apple: macOS"
+
+ Make sure [Homebrew] is installed, which is a modern package manager for
+ macOS. Next, use the following command to install all necessary
+ dependencies:
+
+ ```
+ brew install cairo freetype libffi libjpeg libpng zlib
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ The easiest way to get up and running with the [Cairo Graphics] library is
+ by installing it via [MSYS2], which is a software distribution and building
+ platform for Windows. Run the following command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-cairo
+ ```
+
+ MSYS2 provides the Cairo Graphics library in several different environments.
+ The above command uses the [UCRT64] environment, as recommended by the MSYS2
+ developers.
+
+=== ":material-linux: Linux"
+
+ There are several package managers for Linux with varying availability per
+ distribution. The [installation guide] explains how to install the [Cairo
+ Graphics] library for your distribution:
+
+ === ":material-ubuntu: Ubuntu"
+
+ ```
+ apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+ ```
+
+ === ":material-fedora: Fedora"
+
+ ```
+ yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+ ```
+
+ === ":fontawesome-brands-suse: openSUSE"
+
+ ```
+ zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+ ```
+
+The following environments come with a preinstalled version of [Cairo Graphics]:
+
+- [x] No installation needed in [Docker image]
+- [x] No installation needed in [GitHub Actions] (Ubuntu)
+
+ [Cairo Graphics]: https://www.cairographics.org/
+ [Homebrew]: https://brew.sh/
+ [installation guide]: https://www.cairographics.org/download/
+ [MSYS2]: https://www.msys2.org/
+ [UCRT64]: https://www.msys2.org/docs/environments/
+ [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+ [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+
+### pngquant
+
+[pngquant] is an excellent library for lossy PNG compression, and a direct
+dependency of the [built-in optimize plugin]. See the following section which
+explains how to install [pngquant] system:
+
+=== ":material-apple: macOS"
+
+ Make sure [Homebrew] is installed, which is a modern package manager for
+ macOS. Next, use the following command to install all necessary
+ dependencies:
+
+ ```
+ brew install pngquant
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ The easiest way to get [pngquant] is by installing it via [MSYS2], which is
+ a software distribution and building platform for Windows. Run the following
+ command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-pngquant
+ ```
+
+=== ":material-linux: Linux"
+
+ All popular Linux distributions, regardless of package manager, should
+ allow to install [pngquant] with the bundled package manager. For example,
+ on Ubuntu, [pngquant] can be installed with:
+
+ ```
+ apt-get install pngquant
+ ```
+
+ The same is true for `yum` and `zypper`.
+
+The following environments come with a preinstalled version of [pngquant]:
+
+- [x] No installation needed in [Docker image]
+
+ [pngquant]: https://pngquant.org/
+ [built-in optimize plugin]: ../../plugins/optimize.md
+ [pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild
+
+## Troubleshooting
+
+### Cairo library was not found
+
+After following the installation guide above it may happen that you still get
+the following error:
+
+```bash
+no library called "cairo-2" was found
+no library called "cairo" was found
+no library called "libcairo-2" was found
+cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
+cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
+cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
+```
+
+This means that the [`cairosvg`][PyPi CairoSVG] package was installed, but the
+underlying [`cairocffi`][PyPi CairoCFFI] dependency couldn't [find][cffi-dopen]
+the installed library. Depending on the operating system the library lookup
+process is different:
+
+!!! tip
+ Before proceeding remember to fully restart any open Terminal windows, and
+ their parent hosts like IDEs to reload any environmental variables, which
+ were altered during the installation process. This might be the quick fix.
+
+=== ":material-apple: macOS"
+
+ On macOS the library lookup checks inside paths defined in [dyld][osx-dyld].
+ Additionally each library `name` is checked in [three variants][find-library-macOS]
+ with the `libname.dylib`, `name.dylib` and `name.framework/name` format.
+
+ [Homebrew] should set every needed variable to point at the installed
+ library directory, but if that didn't happen, you can use the debug script
+ below to see what paths are looked up.
+
+ A [known workaround][cffi-issue] is to add the Homebrew lib path directly
+ before running MkDocs:
+
+ ```bash
+ export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
+ ```
+
+ View source code of [cairo-lookup-macos.py]
+
+ ```bash title="Python Debug macOS Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py" | python -
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ On Windows the library lookup checks inside the paths defined in the
+ environmental `PATH` variable. Additionally each library `name` is checked
+ in [two variants][find-library-Windows] with the `name` and `name.dll` format.
+
+ The default binary and shared library path for the [UCRT64] environment of
+ [MSYS2], in which the packages were installed using the above commands, is:
+
+ ```powershell
+ C:\msys64\ucrt64\bin
+ ```
+
+ Use the debug script below to check if the path is included. If it isn't then:
+
+ 1. Press ++windows+r++.
+ 2. Run the `SystemPropertiesAdvanced` applet.
+ 3. Select "Environmental Variables" at the bottom.
+ 4. Add the whole path to the above directory to your `Path` variable.
+ 5. Click OK on all open windows to apply changes.
+ 6. Fully restart any open Terminal windows and their parent hosts like IDEs.
+
+ ```powershell title="You can also list paths using PowerShell"
+ $env:Path -split ';'
+ ```
+
+ View source code of [cairo-lookup-windows.py]
+
+ ```powershell title="PowerShell - Python Debug Windows Script"
+ (Invoke-WebRequest "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py").Content | python -
+ ```
+
+=== ":material-linux: Linux"
+
+ On Linux the library lookup can [differ greatly][find-library-Linux] and is
+ dependent from the installed distribution. For tested Ubuntu and Manjaro
+ systems Python runs shell commands to check which libraries are available in
+ [`ldconfig`][ubuntu-ldconfig], in the [`gcc`][ubuntu-gcc]/`cc` compiler, and
+ in [`ld`][ubuntu-ld].
+
+ You can extend the `LD_LIBRARY_PATH` environmental variable with an absolute
+ path to a library directory containing `libcairo.so` etc. Run this directly
+ before MkDocs:
+
+ ```bash
+ export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH
+ ```
+
+ You can also modify the `/etc/ld.so.conf` file.
+
+ The Python script below shows, which function is being run to find installed
+ libraries. You can check the source to find out what specific commands are
+ executed on your system during library lookup.
+
+ View source code of [cairo-lookup-linux.py]
+
+ ```bash title="Python Debug Linux Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
+ ```
+
+ [PyPi CairoSVG]: https://pypi.org/project/CairoSVG
+ [PyPi CairoCFFI]: https://pypi.org/project/CairoCFFI
+ [osx-dyld]: https://www.unix.com/man-page/osx/1/dyld/
+ [ubuntu-ldconfig]: https://manpages.ubuntu.com/manpages/focal/en/man8/ldconfig.8.html
+ [ubuntu-ld]: https://manpages.ubuntu.com/manpages/xenial/man1/ld.1.html
+ [ubuntu-gcc]: https://manpages.ubuntu.com/manpages/trusty/man1/gcc.1.html
+ [cffi-issue]: https://github.com/squidfunk/mkdocs-material/issues/5121
+ [cffi-dopen]: https://github.com/Kozea/cairocffi/blob/f1984d644bbc462ef0ec33b97782cf05733d7b53/cairocffi/__init__.py#L24-L49
+ [find-library-macOS]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L70-L81
+ [find-library-Windows]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L59-L67
+ [find-library-Linux]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L92
+ [cairo-lookup-macos.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py
+ [cairo-lookup-windows.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py
+ [cairo-lookup-linux.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py
diff --git a/mkdocs-material/docs/plugins/search.md b/mkdocs-material/docs/plugins/search.md
new file mode 100644
index 0000000..603501c
--- /dev/null
+++ b/mkdocs-material/docs/plugins/search.md
@@ -0,0 +1,427 @@
+---
+title: Built-in search plugin
+icon: material/magnify
+---
+
+# Built-in search plugin
+
+The search plugin adds a search bar to the header, allowing users to search your
+documentation. It's powered by [lunr.js], a lightweight full-text search engine
+for the browser, elimininating the need for external services, and even works
+when building [offline-capable documentation].
+
+ [lunr.js]: https://lunrjs.com/
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML and builds a search index from all pages and
+sections by extracting the section titles and contents. It preserves some inline
+formatting like code blocks and lists, but removes all other formatting, so the
+search index is as small as possible.
+
+When a user visits your site, the search index is shipped to the browser,
+indexed with [lunr.js] and made available for fast and simple querying – no
+server needed. This ensures that the search index is always up to date with
+your documentation, yielding accurate results.
+
+### When to use it
+
+It's generally recommended to use the plugin, as interactive search functionality
+is a vital part of every good documentation. Additionally, the plugin integrates
+perfectly with several of the other [built-in plugins] that Material for MkDocs
+offers:
+
+
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building offline-capable documentation,
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to [boost][meta.search.boost] specific
+ sections in search results or to [exclude][meta.search.exclude] them
+ entirely from being indexed, giving more granular control over search.
+
+ ---
+
+ __Simpler organization and management of search in different subsections__
+
+
+
+ [offline]: offline.md
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+
+
+
+As with all [built-in plugins], getting started with the search plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and your users
+will be able to search your documentation:
+
+``` yaml
+plugins:
+ - search
+```
+
+The search plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [search]: search.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - search:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Search
+
+The following settings are available for search:
+
+---
+
+####
+
+
+
+
+Use this setting to specify the language of the search index, enabling [stemming]
+support for other languages than English. The default value is automatically
+computed from the [site language], but can be explicitly set to another language
+or even multiple languages with:
+
+=== "Set language"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: en
+ ```
+
+=== "Add further languages"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: # (1)!
+ - en
+ - de
+ ```
+
+ 1. Be aware that including support for further languages increases the
+ base JavaScript payload by around 20kb and by another 15-30kb per
+ language, all before `gzip`.
+
+ [stemming]: https://en.wikipedia.org/wiki/Stemming
+ [site language]: ../setup/changing-the-language.md#site-language
+ [lunr languages]: https://github.com/MihaiValentin/lunr-languages
+
+Language support is provided by [lunr languages], a collection of
+language-specific stemmers and stop words for [lunr.js] maintained by the
+Open Source community.
+
+---
+
+The following languages are currently supported by [lunr languages]:
+
+
+
+- `ar` – Arabic
+- `da` – Danish
+- `de` – German
+- `du` – Dutch
+- `en` – English
+- `es` – Spanish
+- `fi` – Finnish
+- `fr` – French
+- `hi` – Hindi
+- `hu` – Hungarian
+- `hy` – Armenian
+- `it` – Italian
+- `ja` – Japanese
+- `kn` - Kannada
+- `ko` – Korean
+- `no` – Norwegian
+- `pt` – Portuguese
+- `ro` – Romanian
+- `ru` – Russian
+- `sa` – Sanskrit
+- `sv` – Swedish
+- `ta` – Tamil
+- `te` – Telugu
+- `th` – Thai
+- `tr` – Turkish
+- `vi` – Vietnamese
+- `zh` – Chinese
+
+
+
+If [lunr languages] doesn't provide support for the selected [site language],
+the plugin falls back to another language that yields the best stemming results.
+If you discover that the search results are not satisfactory, you can contribute
+to [lunr languages] by adding support for your language.
+
+---
+
+####
+
+
+
+
+Use this setting to specify the separator used to split words when building the
+search index on the client side. The default value is automatically computed
+from the [site language], but can also be explicitly set to another value with:
+
+``` yaml
+plugins:
+ - search:
+ separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+```
+
+Separators support [positive and negative lookahead assertions], which allows
+for rather complex expressions that yield precise control over how words are
+split when building the search index.
+
+Broken into its parts, this separator induces the following behavior:
+
+=== "Special characters"
+
+ ```
+ [\s\-,:!=\[\]()"/]+
+ ```
+
+ The first part of the expression inserts token boundaries for each
+ document before and after whitespace, hyphens, commas, brackets and
+ other special characters. If several of those special characters are
+ adjacent, they are treated as one.
+
+=== "Case changes"
+
+ ```
+ (?!\b)(?=[A-Z][a-z])
+ ```
+
+ Many programming languages have naming conventions like `PascalCase` or
+ `camelCase`. By adding this subexpression to the separator,
+ [words are split at case changes], tokenizing the word `PascalCase`
+ into `Pascal` and `Case`.
+
+=== "Version strings"
+
+ ```
+ \.(?!\d)
+ ```
+
+ When adding `.` to the separator, version strings like `1.2.3` are split
+ into `1`, `2` and `3`, which makes them undiscoverable via search. When
+ using this subexpression, a small lookahead is introduced which will
+ [preserve version strings] and keep them discoverable.
+
+=== "HTML/XML tags"
+
+ ```
+ &[lg]t;
+ ```
+
+ If your documentation includes HTML/XML code examples, you may want to allow
+ users to find [specific tag names]. Unfortunately, the `<` and `>` control
+ characters are encoded in code blocks as `<` and `>`. Adding this
+ subexpression to the separator allows for just that.
+
+ [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
+ [words are split at case changes]: ?q=searchHighlight
+ [preserve version strings]: ?q=9.0.0
+ [specific tag names]: ?q=script
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the [pipeline functions] that are used to filter and
+expand tokens after tokenizing them with the [`separator`][config.separator] and
+before adding them to the search index. The default value is automatically
+computed from the [site language], but can also be explicitly set with:
+
+``` yaml
+plugins:
+ - search:
+ pipeline:
+ - stemmer
+ - stopWordFilter
+ - trimmer
+```
+
+The following pipeline functions can be used:
+
+- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
+- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
+- `trimmer` – Trim whitespace from tokens
+
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+
+### Segmentation
+
+The plugin supports text segmentation of Chinese via [jieba], a popular
+Chinese text segmentation library. Other languages like Japanese and Korean are
+currently segmented on the client side, but we're considering to move this
+functionality into the plugin in the future.
+
+The following settings are available for segmentation:
+
+ [jieba]: https://pypi.org/project/jieba/
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a [custom dictionary] to be used by [jieba] for
+segmenting text, replacing the default dictionary. [jieba] comes with
+several dictionaries, which can be used with:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict: dict.txt
+```
+
+The following dictionaries are provided by [jieba]:
+
+- [dict.txt.small] – 占用内存较小的词典文件
+- [dict.txt.big] – 支持繁体分词更好的词典文件
+
+The provided path is resolved from the root directory.
+
+ [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
+ [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
+ [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify an additional [user dictionary] to be used by
+[jieba] for segmenting text, augmenting the default dictionary. User
+dictionaries are ideal for tuning the segmenter:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict_user: user_dict.txt
+```
+
+The provided path is resolved from the root directory.
+
+ [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to increase or decrease the relevance of a page in the search
+results, giving more weight to them. Use values above `1` to rank up and values
+below `1` to rank down:
+
+=== ":material-arrow-up-circle: Rank up"
+
+ ``` yaml
+ ---
+ search:
+ boost: 2 # (1)!
+ ---
+
+ # Page title
+ ...
+ ```
+
+ 1. When boosting pages, always start with low values.
+
+=== ":material-arrow-down-circle: Rank down"
+
+ ``` yaml
+ ---
+ search:
+ boost: 0.5
+ ---
+
+ # Page title
+ ...
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this property to exclude a page from the search results. Note that this will
+not only remove the page, but also all subsections of the page from the search
+results:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
diff --git a/mkdocs-material/docs/plugins/social.md b/mkdocs-material/docs/plugins/social.md
new file mode 100644
index 0000000..7ad60ad
--- /dev/null
+++ b/mkdocs-material/docs/plugins/social.md
@@ -0,0 +1,1082 @@
+---
+title: Built-in social plugin
+icon: material/share-circle
+---
+
+# Built-in social plugin
+
+The social plugin automatically and intelligently generates beautiful and highly
+customizable social cards in different [layouts][default layouts] for each page
+of your project, rendering as preview images whenever you or somebody else share
+a link to your project on social media.
+
+## Objective
+
+### How it works
+
+The plugin automatically generates a customizable social card for each page
+of your project, which appears as a preview image when sharing a link to your
+project on social media, without the use of external services and just
+[a single line of configuration][configuration].
+
+With the use of an efficient [image processing] library, the plugin allows to
+define [custom layouts] for social cards, which can be adapted to match your
+project's style and branding. While it would technically be much simpler to
+generate social cards by using a web browser and an automation framework like
+[Puppeteer][^1], it would add further liabilities to your toolchain, with the
+potential to make build pipelines more complex, much more resource intense,
+and significantly slower.
+
+ [^1]:
+ [GitHub wrote in their blog] that they use [Puppeteer] to generate social
+ card images for repositories, issues, commits, discussions, and basically
+ everything else that appear as preview images when shared on social media.
+
+The generated social cards are [cached] and stored in the
+[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your
+project doesn't depend on external services. In order to generate social cards
+images, a few [dependencies] need to be available on your system.
+
+ [configuration]: #configuration
+ [image processing]: requirements/image-processing.md
+ [custom layouts]: ../setup/setting-up-social-cards.md#customization
+ [Puppeteer]: https://github.com/puppeteer/puppeteer
+ [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/
+ [cached]: #caching
+ [dependencies]: #configuration
+
+### When to use it
+
+There's one particular case when we don't recommend to use the plugin: when you
+build [offline-capable documentation] to offer it as a download. Otherwise, it
+always makes sense to enable the plugin, as links to your documentation shared
+on social media will appear much more appealing.
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each post and page, showing as previews on social media.
+
+ ---
+
+ __Links to your blog render beautiful social cards when shared on social media__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin can be used to [change the layout][meta.social.cards_layout]
+ for social cards or [change specific layout options]
+ [meta.social.cards_layout_options] like [background][option.background_color]
+ or [color][option.color] for a subset of pages.
+
+ ---
+
+ __Your documentation can use completely different social cards per section__
+
+
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [blog]: blog.md
+ [meta]: meta.md
+
+## Configuration
+
+
+
+
+
+
+In order to get started with the social plugin, just add the following lines to
+`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social
+cards for you:
+
+``` yaml
+plugins:
+ - social
+```
+
+The social plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to generate social card images, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [social]: social.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - social:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+####
+
+
+
+
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete social card generation faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - social:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that social
+cards are only regenerated when their contents change or they're not already
+contained in the cache. If any of the variables used in a layout changes, the
+plugin detects it and regenerates the social card.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+####
+
+
+
+
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-generate social cards for all pages, even though the cache may not be stale.
+It's normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - social:
+ cache: false
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where social card images are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should only log errors when
+generating social cards without terminating the build, e.g., invalid references
+to icons. To terminate the build, use:
+
+``` yaml
+plugins:
+ - social:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: warn
+ ```
+
+ Errors are reported as warnings, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: info
+ ```
+
+ Errors are only reported as informational messages.
+
+=== "`ignore`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: ignore
+ ```
+
+ Errors are only reported when using the `--verbose` flag.
+
+### Social cards
+
+The following settings are available for social card generation:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable social card generation. Currently, the
+plugin's sole purpose is to generate social cards, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable social card generation, use:
+
+``` yaml
+plugins:
+ - social:
+ cards: false
+```
+
+---
+
+####
+
+
+
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+social cards are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_dir: my/custom/dir
+```
+
+This configuration stores the generated images at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+If you want to build a [custom social card layout][custom layouts], use this
+setting to change the folder where you store your custom layouts, the default
+being a folder called `layouts` in your root directory:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_dir: layouts
+```
+
+The provided path is resolved from the root directory.
+
+!!! tip "Where to store custom layouts"
+
+ Our recommendation is to locate the folder outside of the
+ [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]
+ are not copied to the [`site` directory][mkdocs.site_dir] when
+ [building your project], e.g., by adhering to the following directory
+ layout:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ *.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+####
+
+
+
+
+
+The plugin ships a growing list of [`default` layouts][default layouts] for
+social cards. If you've created a [custom social card layout][custom layouts],
+you can instruct the plugin to use it exactly as one of the included layouts:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout: my-custom-layout
+```
+
+The provided path is resolved from the[
+`layouts` directory][config.cards_layout_dir].
+
+!!! tip "How custom layouts are resolved"
+
+ By default, the plugin will load your [custom layouts] from a folder named
+ `layouts` in your root directory. If your layout is called
+ `my-custom-layout`, the directory layout must adhere to:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ my-custom-layout.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+####
+
+
+
+
+Use this setting to set options for the layout specified via [`cards_layout`]
+[config.cards_layout] (if the layout supports it), which allows for making
+layouts easily and entirely configurable:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+
:
+```
+
+When creating a [custom layout][custom layouts], you are completely free in
+defining which parts of your layout can be parametrized. The [`default` layouts]
+[default layouts] included with the plugin support the following options:
+
+
+
+
+ [default layouts]: #layouts
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_include:
+ - blog/*
+```
+
+This configuration enables social card generation for all pages that are
+contained in the `blog` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+####
+
+
+
+
+
+Use this setting to disable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_exclude:
+ - changelog/*
+```
+
+This configuration disables social card generation for all pages that are
+contained in the `changelog` folder and its subfolders inside the
+[`docs` directory][mkdocs.docs_dir].
+
+### Debugging
+
+The plugin includes a special mode for debugging layouts, which is very useful
+when creating [custom layouts], as it allows for quicker iteration and better
+understanding of composition.
+
+The following settings are available for debugging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable a special mode for debugging your layout, which
+renders each layer with a colored outline and its `x` and `y` offsets, and
+overlays a dot grid for alignment, so it's easier to understand how the
+distinct layers of your layout are composed together:
+
+``` yaml
+plugins:
+ - social:
+ debug: true
+```
+
+---
+
+####
+
+
+
+
+
+By default, the plugin automatically disables [`debug`][config.debug] mode when
+[building your project], so you can be sure that debug overlays are never
+deployed to production. If you want to change that, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_on_build: true
+```
+
+It's normally not necessary to change this setting, as it's just intended to
+be a safety net.
+
+---
+
+####
+
+
+
+
+
+When [`debug`][config.debug] mode is enabled, this setting specifies whether a
+dot grid is rendered on top of all layers, to allow for better alignment. If you
+want to switch the grid off, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the step size of the dot grid in pixels, if enabled,
+which can be useful to create perfectly aligned layers for ideal composition.
+It you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid_step: 64
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify the color of the outlines that are added to each
+layer and the dot grid that is rendered on top of all layers. If you need to
+change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_color: yellow
+```
+
+In rare cases, it might be necessary to change this setting if the dot grid or
+the outlines are hard to distinguish, as the plugin will automatically adjust
+the color if not explicitly set.
+
+## Usage
+
+### Metadata
+
+The plugin allows to override a subset of settings through metadata (front
+matter) in order to customize social card generation, e.g., to set [options for
+the included `default` layouts][default layouts] for a single page, or even
+[for an entire subsection] of your project by leveraging the [meta] plugin.
+
+The following properties are available:
+
+ [for an entire subsection]: meta.md#how-it-works
+ [meta]: meta.md
+
+---
+
+####
+
+
+
+
+
+
+Use this property to override the [`cards`][config.cards] setting for the given
+page:
+
+``` yaml
+---
+social:
+ cards: false
+---
+
+# Page title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+
+Use this property to override the [`cards_layout`][config.cards_layout] setting
+for the given page:
+
+``` yaml
+---
+social:
+ cards_layout: my-custom-layout
+---
+
+# Page title
+...
+```
+
+---
+
+####
+
+
+
+
+
+
+Use this property to override the [`cards_layout_options`]
+[config.cards_layout_options] setting for the given page:
+
+``` yaml
+---
+social:
+ cards_layout_options:
+ background_color: blue # Change background color
+ background_image: null # Remove background image
+---
+
+# Page title
+...
+```
+
+Setting an option to `#!yaml null` resets the option.
+
+### Layouts
+
+While it is possible and simple to build [custom layouts], the plugin ships
+several predefined layouts, all of which are prefixed with `default`. The
+following layouts are included:
+
+=== "`default`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default
+ ```
+
+
+
+ ![Layout default]
+
+ This layout sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ –
+
+ - [`font_family`][option.font_family]
+ –
+
+
+
+ This layout only shows the given background image and scales it to cover.
+
+
+
+The [`default` layouts][default layouts] are very flexible and comfortable to
+use, as they replicate the original behavior of the plugin, sourcing default
+values for all options from other `theme` settings.
+
+The following options are available:
+
+ [Layout default]: ../assets/screenshots/social-cards.png
+ [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+ [Layout default accent]: ../assets/screenshots/social-cards-accent.png
+ [Layout default invert]: ../assets/screenshots/social-cards-invert.png
+
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [page icon]: ../reference/index.md#setting-the-page-icon
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [font]: ../setup/changing-the-fonts.md#regular-font
+
+---
+
+####
+
+
+
+
+Use this option to change the background color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: "#ff1493" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: rgb(255, 20, 147) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: deeppink # (1)!
+ ```
+
+ 1. See the [``][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+If this options is used together with [`background_image`]
+[option.background_image], the color is rendered on top of the image which
+allows for tinting images. If you want to remove the background color, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ background_color: transparent
+```
+
+ [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names
+ [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+
+---
+
+####
+
+
+
+
+
+Use this option to define a background image for the generated social card. Note
+that the image is tinted with the [`background_color`][option.background_color],
+which can also be set to `transparent`:
+
+=== "Image"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: transparent
+ ```
+
+=== "Image with tint"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: "#ff149366"
+ ```
+
+The provided path is resolved from the root directory.
+
+---
+
+####
+
+
+
+
+Use this option to change the foreground color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: "#ffffff" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: rgb(255, 255, 255) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: white # (1)!
+ ```
+
+ 1. See the [``][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+---
+
+####
+
+
+
+
+Use this option to change the font family of the generated social card. The
+plugin automatically downloads the font from [Google Fonts], so the font must
+point to an existing Google Font:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_family: Ubuntu
+```
+
+When you've found a font that you like on [Google Fonts], you can just copy the
+name from the font's specimen page and use it as the value for this option –
+no further configuration needed.
+
+ [Google Fonts]: https://fonts.google.com/
+
+---
+
+####
+
+
+
+
+
+Use this option to change the font variant used to generate the social card.
+If the downloaded font has variants like `Condensed` or `Expanded`, you can set
+them with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_variant: Condensed
+```
+
+The variant is combined with the style as used in the custom layout, so the
+plugin is instructed to use combinations like `Condensed Regular` or
+`Expanded Bold`.
+
+---
+
+####
+
+
+
+
+
+Use this option to change the logo that is used in the generated social card.
+By default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]
+[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ logo: layouts/logo.png
+```
+
+The provided path is resolved from the root directory.
+
+ [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image
+ [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled
+
+---
+
+####
+
+
+
+
+
+Use this option to change the title of the generated social card. This overrides
+the computed page title as assigned by MkDocs, as well as the [`title`]
+[meta.title] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ title: My custom title
+```
+
+ [meta.title]: ../reference/index.md#setting-the-page-title
+
+---
+
+####
+
+
+
+
+
+Use this option to change the description of the generated social card. This
+overrides the set [`site_description`][mkdocs.site_description], if defined, as
+well as the [`description`][meta.description] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ description: My custom description
+```
+
+ [meta.description]: ../reference/index.md#setting-the-page-description
+
+---
+
+!!! question "Missing something?"
+
+ When setting up social cards, you might discover that you're missing
+ specific functionality – we're happy to consider adding it to the plugin!
+ You can [open a discussion] to ask a question, or create a [change request]
+ on our [issue tracker], so we can find out if it might be a good fit for
+ the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/mkdocs-material/docs/plugins/tags.md b/mkdocs-material/docs/plugins/tags.md
new file mode 100644
index 0000000..87a2689
--- /dev/null
+++ b/mkdocs-material/docs/plugins/tags.md
@@ -0,0 +1,952 @@
+---
+title: Built-in tags plugin
+icon: material/tag-text
+---
+
+# Built-in tags plugin
+
+The tags plugin adds first-class support for categorizing pages with the use
+of tags, adding the possibility to group related pages and make them
+discoverable via search and dedicated tags indexes. If your documentation is
+large, tags can help to discover relevant information faster.
+
+## Objective
+
+### How it works
+
+The plugin scans all pages for the [`tags`][meta.tags] metadata property and
+generates a tags index, which is an inverted list of tags and the pages they
+appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
+allowing for maximum flexibility when adding tags to your project.
+
+### When to use it
+
+If you want to add one or multiple tags indexes to your project, the tags
+plugin is a perfect choice as it makes this process ridiculously simple.
+Additionally, it integrates perfectly with several of the other
+[built-in plugins] that Material for MkDocs offers:
+
+
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags][meta.tags], so they can't be
+ forgotten when adding pages.
+
+ ---
+
+ __Simpler organization and management of tags in different subsections__
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The tags plugin allows to categorize posts alongside with pages in your
+ project, to improve their discoverability and connect posts to your
+ documentation.
+
+ ---
+
+ __Your documentation's tag system integrates with your blog__
+
+
+
+ [meta]: meta.md
+ [blog]: blog.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+
+
+
+
+As with all [built-in plugins], getting started with the tags plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start using
+[tags][meta.tags] to categorize your pages:
+
+``` yaml
+plugins:
+ - tags
+```
+
+The tags plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [tags]: tags.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - tags:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Tags
+
+The following settings are available for tags:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable rendering of tags. The plugin still
+extracts tags from all pages, e.g., for [exporting tags] without rendering them.
+Rendering can be disabled with:
+
+``` yaml
+plugins:
+ - tags:
+ tags: false
+```
+
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
+---
+
+####
+
+
+
+
+!!! info "This setting is not needed in [Insiders]"
+
+ Insiders ships a __ground up rewrite of the tags plugin__ which is infinitely
+ more powerful than the current version in the community edition. It allows
+ for an arbitrary number of tags indexes (listings), [scoped listings],
+ [shadow tags], [nested tags], and much more.
+
+Use this setting to specify the location of the tags index, which is the page
+used to render a list of all tags and their associated pages. If this setting is
+specified, tags become clickable, pointing to the corresponding section in the
+tags index:
+
+``` yaml
+plugins:
+ - tags:
+ tags_file: tags.md
+```
+
+The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
+section of `mkdocs.yml`. This setting is not required – you should only use it
+if you want to have a tags index.
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+ [Insiders]: ../insiders/index.md
+ [scoped listings]: ../setup/setting-up-tags.md#scoped-listings
+ [shadow tags]: ../setup/setting-up-tags.md#shadow-tags
+ [nested tags]: ../setup/setting-up-tags.md#nested-tags
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`tags_slugify`][config.tags_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_separator: _
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the format string that is used when generating tag
+slugs. It is a good idea to prefix tag slugs with a string that makes them
+unique, the default being:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_format: "tag:{slug}"
+```
+
+The following placeholders are available:
+
+- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]
+
+---
+
+####
+
+
+
+
+
+
+Use this setting to enable support for tag hierarchies (nested tags, e.g.,
+`foo/bar`). If you intend to create hierarchical listings of tags, you can
+enable this setting in `mkdocs.yml` with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy: true
+```
+
+---
+
+####
+
+
+
+
+
+
+Use this setting to change the separator that is used when creating tag
+hierarchies. By default, tags are separated by a forward slash `/`, but you
+can change this to any string, e.g., `.`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy_separator: .
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing tags. By default,
+tag comparison is case-sensitive, but you can use `tag_name_casefold` for
+case-insensitive comparison:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
+```
+
+You can also define your own comparison function, which must return a string
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the name of the front matter property that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_property: tags
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the name of the template variable that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_variable: tags
+```
+
+---
+
+####
+
+
+
+
+
+The plugin allows to check tags against a predefined list, in order to catch
+typos or make sure that tags are not arbitrarily added. Specify the tags you
+want to allow with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_allowed:
+ - HTML5
+ - JavaScript
+ - CSS
+```
+
+The plugin stops the build if a page references a tag that is not part of
+this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
+metadata property.
+
+### Listings
+
+The following settings are available for listings:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable listings. It is normally not necessary to
+change this setting, as listings are created entirely by inline comments, but
+you can disable them if necessary with:
+
+``` yaml
+plugins:
+ - tags:
+ listings: false
+```
+
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
+---
+
+####
+
+
+
+
+
+Use this define listing configurations that you can then reference in listings
+with a custom identifier. Sharing configurations is a good idea, especially
+when you have many tag listings:
+
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: true
+ exclude: Internal
+```
+
+Then, just reference the listing identifier:
+
+``` html
+
+```
+
+See the [listings section] for a list of all available settings.
+
+ [listings section]: #listing-configuration
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing listing items. By
+default, items are ordered by their titles, but you can change the sorting
+criterion with the following configuration:
+
+=== "Sort by item title"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_sort_by: !!python/name:material.plugins.tags.item_title
+ ```
+
+=== "Sort by item URL"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_sort_by: !!python/name:material.plugins.tags.item_url
+ ```
+
+You can also define your own comparison function, which must return a string
+or number representing the item, that is used for sorting, and reference it in
+[`listings_sort_by`][config.listings_sort_by].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which items are sorted when comparing
+them. By default, items are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ listings_sort_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing tags in listings. By
+default, tag comparison is case-sensitive, but you can use `tag_name_casefold`
+for case-insensitivity:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
+```
+
+You can also define your own comparison function, which must return a string
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the name of the directive the plugin will look for
+when processing pages. If you want to use a shorter directive than
+`material/tags`, you could use:
+
+``` yaml
+plugins:
+ - tags:
+ listings_directive: $tags
+```
+
+Using this setting, listings must now be referenced as such:
+
+``` html
+
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable tags showing up in the table of contents.
+If you don't want tags to show up in the table of contents, you can disable this
+behavior with:
+
+``` yaml
+plugins:
+ - tags:
+ listings_toc: false
+```
+
+### Shadow tags
+
+The following settings are available for shadow tags:
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether the plugin should include shadow tags on
+pages and in listings when [building your project], which might be useful for
+deploy previews:
+
+=== "Show shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: true
+ ```
+
+=== "Hide shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: false
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should include shadow tags on
+pages and in listings when [previewing your site]. If you don't wish to include
+them when previewing, use:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+####
+
+
+
+
+
+The plugin allows to specify a predefined list of shadow tags which can be
+included and excluded from builds by using the [`shadow`][config.shadow]
+setting. Shadow tags must be specified as a list:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags:
+ - Draft
+ - Internal
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a string that is checked as a prefix for each tag.
+If the tag starts with this string, the tag is marked as a shadow tag. A common
+practice is to use `_` as a prefix:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_prefix: _
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a string that is checked as a suffix for each tag.
+If the tag ends with this string, the tag is marked as a shadow tag. One option
+can be to use `Internal` as a suffix:
+
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_suffix: Internal
+```
+
+### Export
+
+The following settings are available for exporting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin creates a `tags.json` file
+inside your [`site` directory][mkdocs.site_dir], which can then be consumed by
+other plugins and projects:
+
+``` yaml
+plugins:
+ - tags:
+ export: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the path of the file where the exported tags are
+stored. It's normally not necessary to change this setting, but if you need to,
+use:
+
+``` yaml
+plugins:
+ - tags:
+ export_file: tags.json
+```
+
+The provided path is resolved from the [`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+This setting is solely provided for convenience to disable the rendering of tags
+and listings with a single setting (e.g. by using an environment variable),
+while keeping the export functionality:
+
+``` yaml
+plugins:
+ - tags:
+ export_only: true
+```
+
+This will automatically disable the [`tags`][config.tags] and
+[`listings`][config.listings] settings.
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+####
+
+
+
+
+
+Use this property to associate a page with one or more tags, making the page
+appear in the generated tags index. Tags are defined as a list of strings
+(whitespaces are allowed):
+
+``` yaml
+---
+tags:
+ - HTML5
+ - JavaScript
+ - CSS
+---
+
+# Page title
+...
+```
+
+If you want to prevent accidental typos when assigning tags to pages, you can
+set a predefined list of allowed tags in `mkdocs.yml` by using the
+[`tags_allowed`][config.tags_allowed] setting.
+
+### Listing configuration
+
+The listings configuration controls which tags are included in or excluded from
+a listing and whether a listing only includes pages in the current scope.
+Furthermore, listings can override some values from the global configuration.
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should only consider pages that are
+within the current subsection of the documentation of the page the listing is
+embedded in:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: false
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should include shadow tags, which
+allows to override the global [`shadow`][config.shadow] setting on a per-listing
+basis:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ shadow: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should render tags inside the table
+of contents, allowing to override the global [`listings_toc`][config.listings_toc]
+setting on a per-listing basis:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ toc: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify which tags should be included in the listing. Each
+page that features a tag that is part of this setting, is listed under the
+respective tag:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ include:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+If this setting is left empty, all tags and pages are included.
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify which tags should be excluded from the listing. Each
+page that features a tag that is part of this setting, is excluded from the
+listing entirely:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ exclude:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+If this setting is left empty, no tags or pages are excluded.
diff --git a/mkdocs-material/docs/plugins/typeset.md b/mkdocs-material/docs/plugins/typeset.md
new file mode 100644
index 0000000..3216ca6
--- /dev/null
+++ b/mkdocs-material/docs/plugins/typeset.md
@@ -0,0 +1,89 @@
+---
+title: Built-in typeset plugin
+icon: material/format-title
+---
+
+# Built-in typeset plugin
+
+The typeset plugin allows to preserve the enriched presentation of titles and
+headlines within the navigation and table of contents. This means that code
+blocks, icons, emojis and any other inline formatting can be rendered exactly
+as defined in the page's content.
+
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+When [building your project], MkDocs extracts the plain text from headlines and
+drops the original formatting. This is generally useful and a good idea, since
+this information is made available to other plugins that might have problems
+when being passed HTML instead of plain text.
+
+However, it also means that the entire formatting is lost.
+
+The plugin hooks into the rendering process, extracts the original headlines,
+and makes them available to be used in templates and plugins. The templates of
+Material for MkDocs use this information to render an enriched version of the
+navigation and table of contents.
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### When to use it
+
+It's generally recommended to use the plugin, because it is a drop-in solution
+that doesn't require any configuration and is designed to work out of the box.
+Since it doesn't overwrite but only adds information, it's not expected to
+interfere with other plugins.
+
+## Configuration
+
+
+
+
+
+
+As with all [built-in plugins], getting started with the typeset plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe the
+enriched navigation and table of contents:
+
+``` yaml
+plugins:
+ - typeset
+```
+
+The typeset plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [typeset]: typeset.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - typeset:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
diff --git a/mkdocs-material/docs/publishing-your-site.md b/mkdocs-material/docs/publishing-your-site.md
new file mode 100644
index 0000000..4019a3f
--- /dev/null
+++ b/mkdocs-material/docs/publishing-your-site.md
@@ -0,0 +1,241 @@
+# Publishing your site
+
+The great thing about hosting project documentation in a `git` repository is
+the ability to deploy it automatically when new changes are pushed. MkDocs
+makes this ridiculously simple.
+
+## GitHub Pages
+
+If you're already hosting your code on GitHub, [GitHub Pages] is certainly
+the most convenient way to publish your project documentation. It's free of
+charge and pretty easy to set up.
+
+ [GitHub Pages]: https://pages.github.com/
+
+### with GitHub Actions
+
+Using [GitHub Actions] you can automate the deployment of your project
+documentation. At the root of your repository, create a new GitHub Actions
+workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
+contents:
+
+=== "Material for MkDocs"
+
+ ``` yaml
+ name: ci # (1)!
+ on:
+ push:
+ branches:
+ - master # (2)!
+ - main
+ permissions:
+ contents: write
+ jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+ - uses: actions/cache@v4
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install mkdocs-material # (4)!
+ - run: mkdocs gh-deploy --force
+ ```
+
+ 1. You can change the name to your liking.
+
+ 2. At some point, GitHub renamed `master` to `main`. If your default branch
+ is named `master`, you can safely remove `main`, vice versa.
+
+ 3. Store the `cache_id` environmental variable to access it later during cache
+ `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+ - The `--utc` option makes sure that each workflow runner uses the same time zone.
+ - The `%V` format assures a cache update once a week.
+ - You can change the format to `%F` to have daily cache updates.
+
+ You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+ 4. This is the place to install further [MkDocs plugins] or Markdown
+ extensions with `pip` to be used during the build:
+
+ ``` sh
+ pip install \
+ mkdocs-material \
+ mkdocs-awesome-pages-plugin \
+ ...
+ ```
+
+=== "Insiders"
+
+ ``` yaml
+ name: ci
+ on:
+ push:
+ branches:
+ - master
+ - main
+ permissions:
+ contents: write
+ jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ if: github.event.repository.fork == false
+ steps:
+ - uses: actions/checkout@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+ - uses: actions/cache@v4
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - run: apt-get install pngquant # (1)!
+ - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ - run: mkdocs gh-deploy --force
+ env:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)!
+ ```
+
+ 1. This step is only necessary if you want to use the
+ [built-in optimize plugin] to automatically compress images.
+
+ 2. Remember to set the `GH_TOKEN` repository secret to the value of your
+ [personal access token] when deploying [Insiders], which can be done
+ using [GitHub secrets].
+
+Now, when a new commit is pushed to either the `master` or `main` branches,
+the static site is automatically built and deployed. Push your changes to see
+the workflow in action.
+
+If the GitHub Page doesn't show up after a few minutes, go to the settings of
+your repository and ensure that the [publishing source branch] for your GitHub
+Page is set to `gh-pages`.
+
+Your documentation should shortly appear at `.github.io/`.
+
+ [GitHub Actions]: https://github.com/features/actions
+ [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+ [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+ [Insiders]: insiders/index.md
+ [built-in optimize plugin]: plugins/optimize.md
+ [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
+ [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+ [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
+
+### with MkDocs
+
+If you prefer to deploy your project documentation manually, you can just invoke
+the following command from the directory containing the `mkdocs.yml` file:
+
+```
+mkdocs gh-deploy --force
+```
+
+This will build your documentation and deploy it to a branch
+`gh-pages` in your repository. See [this overview in the MkDocs
+documentation] for more information. For a description of the
+arguments, see [the documentation for the command].
+
+ [this overview in the MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages
+ [the documentation for the command]: https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
+
+## GitLab Pages
+
+If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
+by using the [GitLab CI] task runner. At the root of your repository, create a
+task definition named `.gitlab-ci.yml` and copy and paste the following
+contents:
+
+=== "Material for MkDocs"
+
+ ``` yaml
+ pages:
+ stage: deploy
+ image: python:latest
+ script:
+ - pip install mkdocs-material
+ - mkdocs build --site-dir public
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+ ```
+
+=== "Insiders"
+
+ ``` yaml
+ pages:
+ stage: deploy
+ image: python:latest
+ script: # (1)!
+ - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ - mkdocs build --site-dir public
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+ ```
+
+ 1. Remember to set the `GH_TOKEN` repository secret to the value of your
+ [personal access token] when deploying [Insiders], which can be done
+ using [masked custom variables].
+
+Now, when a new commit is pushed to the [default branch] (typically `master` or
+`main`), the static site is automatically built and deployed. Commit and push
+the file to your repository to see the workflow in action.
+
+Your documentation should shortly appear at `.gitlab.io/`.
+
+## Other
+
+Since we can't cover all possible platforms, we rely on community contributed
+guides that explain how to deploy websites built with Material for MkDocs to
+other providers:
+
+
+
+ [GitLab Pages]: https://gitlab.com/pages
+ [GitLab CI]: https://docs.gitlab.com/ee/ci/
+ [masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
+ [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html
+ [Azure]: https://bawmedical.co.uk/t/publishing-a-material-for-mkdocs-site-to-azure-with-automatic-branch-pr-preview-deployments/763
+ [Cloudflare Pages]: https://deborahwrites.com/guides/deploy-mkdocs-material-cloudflare/
+ [DigitalOcean]: https://deborahwrites.com/guides/deploy-mkdocs-material-digitalocean-app-platform/
+ [Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
+ [Netlify]: https://deborahwrites.com/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
+ [Vercel]: https://deborahwrites.com/guides/deploy-mkdocs-material-vercel/
+ [Codeberg Pages]: https://andre601.ch/blog/2023/11-05-using-codeberg-pages/
+ [Scaleway]: https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/
+
diff --git a/mkdocs-material/docs/reference/admonitions.md b/mkdocs-material/docs/reference/admonitions.md
new file mode 100644
index 0000000..02f9fe2
--- /dev/null
+++ b/mkdocs-material/docs/reference/admonitions.md
@@ -0,0 +1,505 @@
+---
+icon: material/alert-outline
+---
+
+# Admonitions
+
+Admonitions, also known as _call-outs_, are an excellent choice for including
+side content without significantly interrupting the document flow. Material for
+MkDocs provides several different types of admonitions and allows for the
+inclusion and nesting of arbitrary content.
+
+## Configuration
+
+This configuration enables admonitions, allows to make them collapsible and to
+nest arbitrary content inside admonitions. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - admonition
+ - pymdownx.details
+ - pymdownx.superfences
+```
+
+See additional configuration options:
+
+- [Admonition]
+- [Details]
+- [SuperFences]
+
+ [Admonition]: ../setup/extensions/python-markdown.md#admonition
+ [Details]: ../setup/extensions/python-markdown-extensions.md#details
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+
+### Admonition icons
+
+
+
+Each of the supported admonition types has a distinct icon, which can be changed
+to any icon bundled with the theme, or even a [custom icon]. Add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ admonition:
+ : # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+??? example "Expand to show alternate icon sets"
+
+ === ":octicons-mark-github-16: Octicons"
+
+ ``` yaml
+ theme:
+ icon:
+ admonition:
+ note: octicons/tag-16
+ abstract: octicons/checklist-16
+ info: octicons/info-16
+ tip: octicons/squirrel-16
+ success: octicons/check-16
+ question: octicons/question-16
+ warning: octicons/alert-16
+ failure: octicons/x-circle-16
+ danger: octicons/zap-16
+ bug: octicons/bug-16
+ example: octicons/beaker-16
+ quote: octicons/quote-16
+ ```
+
+
+ === ":fontawesome-brands-font-awesome: FontAwesome"
+
+ ``` yaml
+ theme:
+ icon:
+ admonition:
+ note: fontawesome/solid/note-sticky
+ abstract: fontawesome/solid/book
+ info: fontawesome/solid/circle-info
+ tip: fontawesome/solid/bullhorn
+ success: fontawesome/solid/check
+ question: fontawesome/solid/circle-question
+ warning: fontawesome/solid/triangle-exclamation
+ failure: fontawesome/solid/bomb
+ danger: fontawesome/solid/skull
+ bug: fontawesome/solid/robot
+ example: fontawesome/solid/flask
+ quote: fontawesome/solid/quote-left
+ ```
+
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [supported types]: #supported-types
+ [icon search]: icons-emojis.md#search
+
+## Usage
+
+Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
+single keyword used as a [type qualifier]. The content of the block follows on
+the next line, indented by four spaces:
+
+``` markdown title="Admonition"
+!!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+!!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+ [type qualifier]: #supported-types
+
+### Changing the title
+
+By default, the title will equal the type qualifier in titlecase. However, it
+can be changed by adding a quoted string containing valid Markdown (including
+links, formatting, ...) after the type qualifier:
+
+``` markdown title="Admonition with custom title"
+!!! note "Phasellus posuere in sem ut cursus"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+!!! note "Phasellus posuere in sem ut cursus"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+### Removing the title
+
+Similar to [changing the title], the icon and title can be omitted entirely by
+adding an empty string directly after the type qualifier. Note that this will
+not work for [collapsible blocks]:
+
+``` markdown title="Admonition without title"
+!!! note ""
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+!!! note ""
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+ [changing the title]: #changing-the-title
+ [collapsible blocks]: #collapsible-blocks
+
+### Collapsible blocks
+
+When [Details] is enabled and an admonition block is started with `???` instead
+of `!!!`, the admonition is rendered as a collapsible block with a small toggle
+on the right side:
+
+``` markdown title="Admonition, collapsible"
+??? note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+??? note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+Adding a `+` after the `???` token renders the block expanded:
+
+``` markdown title="Admonition, collapsible and initially expanded"
+???+ note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+???+ note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+### Inline blocks
+
+Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing
+them to the right using the `inline` + `end` modifiers, or to the left using
+only the `inline` modifier:
+
+=== ":octicons-arrow-right-16: inline end"
+
+ !!! info inline end "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+ ``` markdown
+ !!! info inline end "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Nulla et euismod nulla.
+ Curabitur feugiat, tortor non consequat
+ finibus, justo purus auctor massa, nec
+ semper lorem quam in massa.
+ ```
+
+ Use `inline end` to align to the right (left for rtl languages).
+
+=== ":octicons-arrow-left-16: inline"
+
+ !!! info inline "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+ ``` markdown
+ !!! info inline "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Nulla et euismod nulla.
+ Curabitur feugiat, tortor non consequat
+ finibus, justo purus auctor massa, nec
+ semper lorem quam in massa.
+ ```
+
+ Use `inline` to align to the left (right for rtl languages).
+
+__Important__: admonitions that use the `inline` modifiers _must_ be declared
+prior to the content block you want to place them beside. If there's
+insufficient space to render the admonition next to the block, the admonition
+will stretch to the full width of the viewport, e.g., on mobile viewports.
+
+### Supported types
+
+Following is a list of type qualifiers provided by Material for MkDocs, whereas
+the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
+
+ [^1]:
+ Previously, some of the supported types defined more than one qualifier.
+ For example, authors could use `summary` or `tldr` as alternative qualifiers
+ to render an [`abstract`](#+type:abstract) admonition. As this increased the
+ size of the CSS that is shipped with Material for MkDocs, the additional
+ type qualifiers are now all deprecated and will be removed in the next major
+ version. This will also be mentioned in the upgrade guide.
+
+
+
+: !!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! abstract
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! info
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! tip
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! success
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! question
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! warning
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! failure
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! danger
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! bug
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! example
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+
+
+: !!! quote
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+## Customization
+
+### Classic admonitions
+
+Prior to version , admonitions had a slightly
+different appearance:
+
+!!! classic "Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+If you want to restore this appearance, add the following CSS to an
+[additional style sheet]:
+
+
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .md-typeset .admonition,
+ .md-typeset details {
+ border-width: 0;
+ border-left-width: 4px;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+### Custom admonitions
+
+If you want to add a custom admonition type, all you need is a color and an
+`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
+and add the following CSS to an [additional style sheet]:
+
+
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root {
+ --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,')
+ }
+ .md-typeset .admonition.pied-piper,
+ .md-typeset details.pied-piper {
+ border-color: rgb(43, 155, 70);
+ }
+ .md-typeset .pied-piper > .admonition-title,
+ .md-typeset .pied-piper > summary {
+ background-color: rgba(43, 155, 70, 0.1);
+ }
+ .md-typeset .pied-piper > .admonition-title::before,
+ .md-typeset .pied-piper > summary::before {
+ background-color: rgb(43, 155, 70);
+ -webkit-mask-image: var(--md-admonition-icon--pied-piper);
+ mask-image: var(--md-admonition-icon--pied-piper);
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, you can use the custom admonition type:
+
+``` markdown title="Admonition with custom type"
+!!! pied-piper "Pied Piper"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+```
+
+
+
+!!! pied-piper "Pied Piper"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/mkdocs-material/docs/reference/annotations.md b/mkdocs-material/docs/reference/annotations.md
new file mode 100644
index 0000000..2ee13c1
--- /dev/null
+++ b/mkdocs-material/docs/reference/annotations.md
@@ -0,0 +1,246 @@
+---
+icon: material/plus-circle
+---
+
+# Annotations
+
+One of the flagship features of Material for MkDocs is the ability to inject
+annotations – little markers that can be added almost anywhere in a document
+and expand a tooltip containing arbitrary Markdown on click or keyboard focus.
+
+## Configuration
+
+This configuration allows to add annotations to all inline- and block-level
+elements, as well as code blocks, and nest annotations inside each other. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - md_in_html
+ - pymdownx.superfences
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+- [SuperFences]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+
+### Annotation icons
+
+
+
+The annotation icon can be changed to any icon bundled with the theme, or even
+a [custom icon], e.g. to material/arrow-right-circle:. Simply add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ annotation: material/arrow-right-circle # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+Some popular choices:
+
+- :material-plus-circle: - `material/plus-circle`
+- :material-circle-medium: - `material/circle-medium`
+- :material-record-circle: - `material/record-circle`
+- :material-arrow-right-circle: - `material/arrow-right-circle`
+- :material-arrow-right-circle-outline: - `material/arrow-right-circle-outline`
+- :material-chevron-right-circle: - `material/chevron-right-circle`
+- :material-star-four-points-circle: - `material/star-four-points-circle`
+- :material-plus-circle-outline: - `material/plus-circle-outline`
+
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [icon search]: icons-emojis.md#search
+
+## Usage
+
+### Using annotations
+
+
+
+
+Annotations consist of two parts: a marker, which can be placed anywhere in
+a block marked with the `annotate` class, and content located in a list below
+the block containing the marker:
+
+``` markdown title="Text with annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be expressed in Markdown.
+```
+
+
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+
+
+Note that the `annotate` class must only be added to the outermost block. All
+nested elements can use the same list to define annotations, except when
+annotations are nested themselves.
+
+#### in annotations
+
+When [SuperFences] is enabled, annotations can be nested inside annotations by
+adding the `annotate` class to the list item hosting the annotation content,
+repeating the process:
+
+``` markdown title="Text with nested annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+```
+
+
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! (1)
+ { .annotate style="margin-bottom: 0" }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+
+
+
+#### in admonitions
+
+The titles and bodies of [admonitions] can also host annotations by adding the
+`annotate` modifier after the type qualifier, which is similar to how
+[inline blocks] work:
+
+``` markdown title="Admonition with annotations"
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+ Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+1. :man_raising_hand: I'm an annotation!
+2. :woman_raising_hand: I'm an annotation as well!
+```
+
+
+
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+ Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+1. :man_raising_hand: I'm an annotation!
+2. :woman_raising_hand: I'm an annotation as well!
+
+
+
+ [admonitions]: admonitions.md
+ [inline blocks]: admonitions.md#inline-blocks
+
+#### in content tabs
+
+Content tabs can host annotations by adding the `annotate` class to the block
+of a dedicated content tab (and not to the container, which is not supported):
+
+``` markdown title="Content tabs with annotations"
+=== "Tab 1"
+
+ Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+ { .annotate }
+
+ 1. :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+ Phasellus posuere in sem ut cursus (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+```
+
+
+
+=== "Tab 1"
+
+ Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+ { .annotate }
+
+ 1. :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+ Phasellus posuere in sem ut cursus (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+
+
+
+#### in everything else
+
+The [Attribute Lists] extension is the key ingredient for adding annotations to
+most elements, but it has some [limitations]. However, it's always possible to
+leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
+`div` with the `annotate` class:
+
+```` html title="HTML with annotations"
+
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+
+
+1. :man_raising_hand: I'm an annotation!
+````
+
+
+
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+
+
+1. :man_raising_hand: I'm an annotation!
+
+
+
+With this trick, annotations can also be added to blockquotes, lists, and many
+other elements that are not supported by the [Attribute Lists] extension.
+Furthermore, note that [code blocks follow different semantics].
+
+!!! warning "Known limitations"
+
+ Please note that annotations currently don't work in [data tables] as
+ reported in #3453, as data tables are scrollable elements and positioning
+ is very tricky to get right. This might be fixed in the future.
+
+ [limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+ [code blocks follow different semantics]: code-blocks.md#adding-annotations
+ [data tables]: data-tables.md
diff --git a/mkdocs-material/docs/reference/buttons.md b/mkdocs-material/docs/reference/buttons.md
new file mode 100644
index 0000000..03dcb6d
--- /dev/null
+++ b/mkdocs-material/docs/reference/buttons.md
@@ -0,0 +1,84 @@
+---
+icon: material/button-cursor
+---
+
+# Buttons
+
+Material for MkDocs provides dedicated styles for primary and secondary buttons
+that can be added to any link, `label` or `button` element. This is especially
+useful for documents or landing pages with dedicated _call-to-actions_.
+
+## Configuration
+
+This configuration allows to add attributes to all inline- and block-level
+elements with a simple syntax, turning any link into a button. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+
+## Usage
+
+### Adding buttons
+
+In order to render a link as a button, suffix it with curly braces and add the
+`.md-button` class selector to it. The button will receive the selected
+[primary color] and [accent color] if active.
+
+``` markdown title="Button"
+[Subscribe to our newsletter](#){ .md-button }
+```
+
+
+
+[Subscribe to our newsletter][Demo]{ .md-button }
+
+
+
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [Demo]: javascript:alert$.next("Demo")
+
+### Adding primary buttons
+
+If you want to display a filled, primary button (like on the [landing page]
+of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
+CSS class selectors.
+
+``` markdown title="Button, primary"
+[Subscribe to our newsletter](#){ .md-button .md-button--primary }
+```
+
+
+
+[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
+
+
+
+ [landing page]: ../index.md
+
+### Adding icon buttons
+
+Of course, icons can be added to all types of buttons by using the [icon syntax]
+together with any valid icon shortcode, which can be easily found with a few keystrokes through our [icon search].
+
+``` markdown title="Button with icon"
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
+```
+
+
+
+ [icon syntax]: icons-emojis.md#using-icons
+ [icon search]: icons-emojis.md#search
diff --git a/mkdocs-material/docs/reference/code-blocks.md b/mkdocs-material/docs/reference/code-blocks.md
new file mode 100644
index 0000000..414057a
--- /dev/null
+++ b/mkdocs-material/docs/reference/code-blocks.md
@@ -0,0 +1,548 @@
+---
+icon: material/code-json
+---
+
+# Code blocks
+
+Code blocks and examples are an essential part of technical project
+documentation. Material for MkDocs provides different ways to set up syntax
+highlighting for code blocks, either during build time using [Pygments] or
+during runtime using a JavaScript syntax highlighter.
+
+ [Pygments]: https://pygments.org
+
+## Configuration
+
+This configuration enables syntax highlighting on code blocks and inline code
+blocks, and allows to include source code directly from other files. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets
+ - pymdownx.superfences
+```
+
+The following sections discuss how to use different syntax highlighting features
+with [Pygments], the recommended highlighter, so they don't apply when using a
+JavaScript syntax highlighter.
+
+See additional configuration options:
+
+- [Highlight]
+- [InlineHilite]
+- [SuperFences]
+- [Snippets]
+
+ [Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight
+ [InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+ [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Code copy button
+
+
+
+
+Code blocks can automatically render a button on the right side to allow the
+user to copy a code block's contents to the clipboard. Add the following to
+`mkdocs.yml` to enable them globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.copy
+```
+
+??? info "Enabling or disabling code copy buttons for a specific code block"
+
+ If you don't want to enable code copy buttons globally, you can enable them
+ for a specific code block by using a slightly different syntax based on the
+ [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .copy }
+ # Code block content
+ ```
+ ````
+
+ Note that there must be a language shortcode, which has to come first and
+ must also be prefixed by a `.`. Similarly, the copy button can also be
+ disabled for a specific code block:
+
+ ```` { .yaml .no-copy }
+ ``` { .yaml .no-copy }
+ # Code block content
+ ```
+ ````
+
+ To enable or disable the copy button without syntax highlighting, you can
+ use the `.text` language shortcode, which doesn't highlight anything.
+
+### Code selection button
+
+
+
+
+
+Code blocks can include a button to allow for the selection of line ranges by
+the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
+to `mkdocs.yml` to enable it globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.select
+```
+
+??? info "Enabling or disabling code selection buttons for a specific code block"
+
+ If you don't want to enable code selection buttons globally, you can enable
+ them for a specific code block by using a slightly different syntax based on
+ the [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .select }
+ # Code block content
+ ```
+ ````
+
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`. Similarly, the selection button can also be disabled for
+ a specific code block:
+
+ ```` { .yaml .no-select }
+ ``` { .yaml .no-select }
+ # Code block content
+ ```
+ ````
+
+ [line highlighting]: #highlighting-specific-lines
+
+### Code annotations
+
+
+
+
+Code annotations offer a comfortable and friendly way to attach arbitrary
+content to specific sections of code blocks by adding numeric markers in block
+and inline comments in the language of the code block. Add the following to
+`mkdocs.yml` to enable them globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)!
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+??? info "Enabling code annotations for a specific code block"
+
+ If you don't want to enable code annotations globally, because you don't
+ like the automatic inlining behavior, you can enable them for a specific
+ code block by using a slightly different syntax based on the
+ [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .annotate }
+ # Code block content
+ ```
+ ````
+
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`.
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+
+#### Custom selectors
+
+
+
+
+
+Normally, code annotations can only be [placed in comments], as comments can be
+considered safe for placement. However, sometimes it might be necessary to place
+annotations in parts of the code block where comments are not allowed, e.g. in
+strings.
+
+Additional selectors can be set per-language:
+
+``` yaml
+extra:
+ annotate:
+ json: [.s2] # (1)!
+```
+
+1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for double-quoted
+ strings. If you want to use a code annotation in another lexeme than a
+ comment, inspect the code block and determine which lexeme needs to be added
+ to the list of additional selectors.
+
+ __Important__: Code annotations cannot be split between lexemes.
+
+Now, code annotations can be used from within strings in JSON:
+
+``` json
+{
+ "key": "value (1)"
+}
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+ [placed in comments]: #adding-annotations
+ [s2]: https://github.com/squidfunk/mkdocs-material/blob/87d5ca487b9d9ab95c41ee72813149d214048693/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss#L45
+
+## Usage
+
+Code blocks must be enclosed with two separate lines containing three backticks.
+To add syntax highlighting to those blocks, add the language shortcode directly
+after the opening block. See the [list of available lexers] to find the
+shortcode for a given language:
+
+```` markdown title="Code block"
+``` py
+import tensorflow as tf
+```
+````
+
+
+
+``` py
+import tensorflow as tf
+```
+
+
+
+ [list of available lexers]: https://pygments.org/docs/lexers/
+
+### Adding a title
+
+In order to provide additional context, a custom title can be added to a code
+block by using the `title=""` option directly after the shortcode,
+e.g. to display the name of a file:
+
+```` markdown title="Code block with title"
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
+
+
+
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+
+
+
+### Adding annotations
+
+Code annotations can be placed anywhere in a code block where a comment for the
+language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
+`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]:
+
+ [^1]:
+ Code annotations require syntax highlighting with [Pygments] – they're
+ currently not compatible with JavaScript syntax highlighters, or languages
+ that do not have comments in their grammar. However, we're actively working
+ on supporting alternate ways of defining code annotations, allowing to
+ always place code annotations at the end of lines.
+
+```` markdown title="Code block with annotation"
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+````
+
+
+
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+
+
+#### Stripping comments
+
+
+
+
+If you wish to strip the comment characters surrounding a code annotation,
+simply add an `!` after the closing parenthesis of the code annotation:
+
+```` markdown title="Code block with annotation, stripped"
+``` yaml
+# (1)!
+```
+
+1. Look ma, less line noise!
+````
+
+
+
+``` yaml
+# (1)!
+```
+
+1. Look ma, less line noise!
+
+
+
+Note that this only allows for a single code annotation to be rendered per
+comment. If you want to add multiple code annotations, comments cannot be
+stripped for technical reasons.
+
+### Adding line numbers
+
+Line numbers can be added to a code block by using the `linenums=""`
+option directly after the shortcode, whereas `` represents the starting
+line number. A code block can start from a line number other than `1`, which
+allows to split large code blocks for readability:
+
+```` markdown title="Code block with line numbers"
+``` py linenums="1"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
+
+
+
+``` py linenums="1"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+
+
+
+### Highlighting specific lines
+
+Specific lines can be highlighted by passing the line numbers to the `hl_lines`
+argument placed right after the language shortcode. Note that line counts start
+at `1`, regardless of the starting line number specified as part of
+[`linenums`][Adding line numbers]:
+
+=== "Lines"
+
+ ```` markdown title="Code block with highlighted lines"
+ ``` py hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+ ````
+
+
+
+ ``` py linenums="1" hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+
+
+=== "Line ranges"
+
+ ```` markdown title="Code block with highlighted line range"
+ ``` py hl_lines="3-5"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+ ````
+
+
+
+ ``` py linenums="1" hl_lines="3-5"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+
+
+ [Adding line numbers]: #adding-line-numbers
+
+### Highlighting inline code blocks
+
+When [InlineHilite] is enabled, syntax highlighting can be applied to inline
+code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
+the corresponding [language shortcode][list of available lexers].
+
+``` markdown title="Inline code block"
+The `#!python range()` function is used to generate a sequence of numbers.
+```
+
+
+
+The `#!python range()` function is used to generate a sequence of numbers.
+
+
+
+### Embedding external files
+
+When [Snippets] is enabled, content from other files (including source files)
+can be embedded by using the [`--8<--` notation][Snippets notation] directly
+from within a code block:
+
+```` markdown title="Code block with external content"
+``` title=".browserslistrc"
+;--8<-- ".browserslistrc"
+```
+````
+
+
+
+``` title=".browserslistrc"
+last 4 years
+```
+
+
+
+ [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
+
+## Customization
+
+### Custom syntax theme
+
+If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
+[colors], which are built with a custom and well-balanced palette that works
+equally well for both [color schemes]:
+
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
+
+Code block foreground, background and line highlight colors are defined via:
+
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
+
+Let's say you want to change the color of `#!js "strings"`. While there are
+several [types of string tokens], they use the same color. You can assign
+a new color by using an [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root > * {
+ --md-code-hl-string-color: #0FF1CE;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
+can lookup the specific CSS class name in the [syntax theme definition], and
+override it as part of your [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .highlight .sb {
+ color: #0FF1CE;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+ [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [types of string tokens]: https://pygments.org/docs/tokens/#literals
+ [additional style sheet]: ../customization.md#additional-css
+ [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+
+### Annotation tooltip width
+
+If you have a lot of content hosted inside your code annotations, it can be a
+good idea to increase the width of the tooltip by adding the following as part
+of an [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root {
+ --md-tooltip-width: 600px;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+This will render annotations with a larger width:
+
+
+
+``` yaml
+# (1)!
+```
+
+1. Muuuuuuuuuuuuuuuch more space for content
+
+
diff --git a/mkdocs-material/docs/reference/content-tabs.md b/mkdocs-material/docs/reference/content-tabs.md
new file mode 100644
index 0000000..ded76be
--- /dev/null
+++ b/mkdocs-material/docs/reference/content-tabs.md
@@ -0,0 +1,247 @@
+---
+icon: material/tab
+---
+
+# Content tabs
+
+Sometimes, it's desirable to group alternative content under different tabs,
+e.g. when describing how to access an API from different languages or
+environments. Material for MkDocs allows for beautiful and functional tabs,
+grouping code blocks and other content.
+
+## Configuration
+
+This configuration enables content tabs, and allows to nest arbitrary content
+inside content tabs, including code blocks and ... more content tabs! Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
+```
+
+See additional configuration options:
+
+- [SuperFences]
+- [Tabbed]
+
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+ [Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
+
+### Anchor links
+
+
+
+
+In order to link to content tabs and share them more easily, an anchor link is
+automatically added to each content tab, which you can copy via right click or
+open in a new tab:
+
+=== "Open me in a new tab ..."
+
+=== "... or me ..."
+
+=== "... or even me"
+
+You can copy the link of the tab and create a link on the same or any other
+page. For example, you can [jump to the third tab above this paragraph][tab_1]
+or to the [publishing guide for Insiders][tab_2].
+
+!!! tip "Readable anchor links"
+
+ [Python Markdown Extensions] 9.6 adds support for [slugification] of
+ content tabs, which produces nicer looking and more readable anchor links.
+ Enable the slugify function with the following lines:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ Fore more information, please [see the extension guide][slugification].
+
+ [tab_1]: #anchor-links--or-even-me
+ [tab_2]: ../publishing-your-site.md#with-github-actions-insiders
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [slugification]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.tabbed.slugify
+
+### Linked content tabs
+
+
+
+
+When enabled, all content tabs across the whole documentation site will be
+linked and switch to the same label when the user clicks on a tab. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.tabs.link
+```
+
+Content tabs are linked based on their label, not offset. This means that all
+tabs with the same label will be activated when a user clicks a content tab
+regardless of order inside a container. Furthermore, this feature is fully
+integrated with [instant loading] and persisted across page loads.
+
+=== "Feature enabled"
+
+ [![Linked content tabs enabled]][Linked content tabs enabled]
+
+=== "Feature disabled"
+
+ [![Linked content tabs disabled]][Linked content tabs disabled]
+
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
+ [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
+
+## Usage
+
+### Grouping code blocks
+
+Code blocks are one of the primary targets to be grouped, and can be considered
+a special case of content tabs, as tabs with a single code block are always
+rendered without horizontal spacing:
+
+``` title="Content tabs with code blocks"
+=== "C"
+
+ ``` c
+ #include
+
+ int main(void) {
+ printf("Hello world!\n");
+ return 0;
+ }
+ ```
+
+=== "C++"
+
+ ``` c++
+ #include
+
+ int main(void) {
+ std::cout << "Hello world!" << std::endl;
+ return 0;
+ }
+ ```
+```
+
+
+
+### Grouping other content
+
+When a content tab contains more than one code block, it is rendered with
+horizontal spacing. Vertical spacing is never added, but can be achieved
+by nesting tabs in other blocks:
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+
+
+### Embedded content
+
+When [SuperFences] is enabled, content tabs can contain arbitrary nested
+content, including further content tabs, and can be nested in other blocks like
+[admonitions] or blockquotes:
+
+``` title="Content tabs in admonition"
+!!! example
+
+ === "Unordered List"
+
+ ``` markdown
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+ ```
+
+ === "Ordered List"
+
+ ``` markdown
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+ ```
+```
+
+
+
+!!! example
+
+ === "Unordered List"
+
+ ``` markdown
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+ ```
+
+ === "Ordered List"
+
+ ``` markdown
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+ ```
+
+
+
+ [admonitions]: admonitions.md
diff --git a/mkdocs-material/docs/reference/data-tables.md b/mkdocs-material/docs/reference/data-tables.md
new file mode 100644
index 0000000..fd2db1b
--- /dev/null
+++ b/mkdocs-material/docs/reference/data-tables.md
@@ -0,0 +1,191 @@
+---
+icon: material/table-edit
+---
+
+# Data tables
+
+Material for MkDocs defines default styles for data tables – an excellent way
+of rendering tabular data in project documentation. Furthermore, customizations
+like [sortable tables] can be achieved with a third-party library and some
+[additional JavaScript].
+
+ [sortable tables]: #sortable-tables
+ [additional JavaScript]: ../customization.md#additional-javascript
+
+## Configuration
+
+This configuration enables Markdown table support, which should normally be
+enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - tables
+```
+
+See additional configuration options:
+
+- [Tables]
+
+ [Tables]: ../setup/extensions/python-markdown.md#tables
+
+## Usage
+
+Data tables can be used at any position in your project documentation and can
+contain arbitrary Markdown, including inline code blocks, as well as [icons and
+emojis]:
+
+``` markdown title="Data table"
+| Method | Description |
+| ----------- | ------------------------------------ |
+| `GET` | :material-check: Fetch resource |
+| `PUT` | :material-check-all: Update resource |
+| `DELETE` | :material-close: Delete resource |
+```
+
+
+
+Note that [tablesort] provides alternative comparison implementations like
+numbers, filesizes, dates and month names. See the [tablesort documentation]
+[tablesort] for more information.
+
+
+
+
+ [tablesort]: http://tristen.ca/tablesort/demo/
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+### Import table from file
+
+The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
+import data from a CSV or Excel file.
+
+ [table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
diff --git a/mkdocs-material/docs/reference/diagrams.md b/mkdocs-material/docs/reference/diagrams.md
new file mode 100644
index 0000000..9125af3
--- /dev/null
+++ b/mkdocs-material/docs/reference/diagrams.md
@@ -0,0 +1,285 @@
+---
+icon: material/graph-outline
+---
+
+# Diagrams
+
+Diagrams help to communicate complex relationships and interconnections between
+different technical components, and are a great addition to project
+documentation. Material for MkDocs integrates with [Mermaid.js], a very
+popular and flexible solution for drawing diagrams.
+
+ [Mermaid.js]: https://mermaid.js.org/
+
+## Configuration
+
+
+
+This configuration enables native support for [Mermaid.js] diagrams. Material
+for MkDocs will automatically initialize the JavaScript runtime when a page
+includes a `mermaid` code block:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+```
+
+No further configuration is necessary. Advantages over a custom integration:
+
+- [x] Works with [instant loading] without any additional effort
+- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
+- [x] Fonts and colors can be customized with [additional style sheets]
+- [x] Support for both, light and dark color schemes – _try it on this page!_
+
+ [^1]:
+ While all [Mermaid.js] features should work out-of-the-box, Material for
+ MkDocs will currently only adjust the fonts and colors for flowcharts,
+ sequence diagrams, class diagrams, state diagrams and entity relationship
+ diagrams. See the section on [other diagrams] for more information why this
+ is currently not implemented for all diagrams.
+
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [additional style sheets]: ../customization.md#additional-css
+ [other diagrams]: #other-diagram-types
+
+## Usage
+
+### Using flowcharts
+
+[Flowcharts] are diagrams that represent workflows or processes. The steps
+are rendered as nodes of various kinds and are connected by edges, describing
+the necessary order of steps:
+
+```` markdown title="Flow chart"
+``` mermaid
+graph LR
+ A[Start] --> B{Error?};
+ B -->|Yes| C[Hmm...];
+ C --> D[Debug];
+ D --> B;
+ B ---->|No| E[Yay!];
+```
+````
+
+
+
+``` mermaid
+graph LR
+ A[Start] --> B{Error?};
+ B -->|Yes| C[Hmm...];
+ C --> D[Debug];
+ D --> B;
+ B ---->|No| E[Yay!];
+```
+
+
+
+ [Flowcharts]: https://mermaid.js.org/syntax/flowchart.html
+
+### Using sequence diagrams
+
+[Sequence diagrams] describe a specific scenario as sequential interactions
+between multiple objects or actors, including the messages that are exchanged
+between those actors:
+
+```` markdown title="Sequence diagram"
+``` mermaid
+sequenceDiagram
+ autonumber
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+````
+
+
+
+``` mermaid
+sequenceDiagram
+ autonumber
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+
+
+
+ [Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html
+
+### Using state diagrams
+
+[State diagrams] are a great tool to describe the behavior of a system,
+decomposing it into a finite number of states, and transitions between those
+states:
+
+```` markdown title="State diagram"
+``` mermaid
+stateDiagram-v2
+ state fork_state <>
+ [*] --> fork_state
+ fork_state --> State2
+ fork_state --> State3
+
+ state join_state <>
+ State2 --> join_state
+ State3 --> join_state
+ join_state --> State4
+ State4 --> [*]
+```
+````
+
+
+
+ [State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html
+
+### Using class diagrams
+
+[Class diagrams] are central to object oriented programming, describing the
+structure of a system by modelling entities as classes and relationships between
+them:
+
+```` markdown title="Class diagram"
+``` mermaid
+classDiagram
+ Person <|-- Student
+ Person <|-- Professor
+ Person : +String name
+ Person : +String phoneNumber
+ Person : +String emailAddress
+ Person: +purchaseParkingPass()
+ Address "1" <-- "0..1" Person:lives at
+ class Student{
+ +int studentNumber
+ +int averageMark
+ +isEligibleToEnrol()
+ +getSeminarsTaken()
+ }
+ class Professor{
+ +int salary
+ }
+ class Address{
+ +String street
+ +String city
+ +String state
+ +int postalCode
+ +String country
+ -validate()
+ +outputAsLabel()
+ }
+```
+````
+
+
+
+``` mermaid
+classDiagram
+ Person <|-- Student
+ Person <|-- Professor
+ Person : +String name
+ Person : +String phoneNumber
+ Person : +String emailAddress
+ Person: +purchaseParkingPass()
+ Address "1" <-- "0..1" Person:lives at
+ class Student{
+ +int studentNumber
+ +int averageMark
+ +isEligibleToEnrol()
+ +getSeminarsTaken()
+ }
+ class Professor{
+ +int salary
+ }
+ class Address{
+ +String street
+ +String city
+ +String state
+ +int postalCode
+ +String country
+ -validate()
+ +outputAsLabel()
+ }
+```
+
+
+
+ [Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html
+
+### Using entity-relationship diagrams
+
+An [entity-relationship diagram] is composed of entity types and specifies
+relationships that exist between entities. It describes inter-related things in
+a specific domain of knowledge:
+
+```` markdown title="Entity-relationship diagram"
+``` mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ ORDER ||--|{ LINE-ITEM : contains
+ LINE-ITEM {
+ string name
+ int pricePerUnit
+ }
+ CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+````
+
+
+
+``` mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ ORDER ||--|{ LINE-ITEM : contains
+ LINE-ITEM {
+ string name
+ int pricePerUnit
+ }
+ CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+
+
+ [entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+
+### Other diagram types
+
+Besides the diagram types listed above, [Mermaid.js] provides support for
+[pie charts], [gantt charts], [user journeys], [git graphs] and
+[requirement diagrams], all of which are not officially supported by Material
+for MkDocs. Those diagrams should still work as advertised by [Mermaid.js], but
+we don't consider them a good choice, mostly as they don't work well on mobile.
+
+ [pie charts]: https://mermaid.js.org/syntax/pie.html
+ [gantt charts]: https://mermaid.js.org/syntax/gantt.html
+ [user journeys]: https://mermaid.js.org/syntax/userJourney.html
+ [git graphs]: https://mermaid.js.org/syntax/gitgraph.html
+ [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html
diff --git a/mkdocs-material/docs/reference/footnotes.md b/mkdocs-material/docs/reference/footnotes.md
new file mode 100644
index 0000000..1a2ec5c
--- /dev/null
+++ b/mkdocs-material/docs/reference/footnotes.md
@@ -0,0 +1,112 @@
+---
+icon: material/format-align-bottom
+---
+
+# Footnotes
+
+Footnotes are a great way to add supplemental or additional information to a
+specific word, phrase or sentence without interrupting the flow of a document.
+Material for MkDocs provides the ability to define, reference and render
+footnotes.
+
+## Configuration
+
+This configuration adds the ability to define inline footnotes, which are then
+rendered below all Markdown content of a document. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - footnotes
+```
+
+See additional configuration options:
+
+- [Footnotes]
+
+ [Footnotes]: ../setup/extensions/python-markdown.md#footnotes
+
+### Footnote tooltips :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2024" }
+
+
+
+
+
+[Insiders] allows to render footnotes as inline tooltips, so the user can read
+the footnote without leaving the context of the document. Footnote tooltips can
+be enabled in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - content.footnote.tooltips
+```
+
+__Footnote tooltips are enabled on our documentation__, so to try it out, you
+can just hover or focus any footnote on this page or any other page of our
+documentation.
+
+ [Insiders]: ../insiders/index.md
+
+## Usage
+
+### Adding footnote references
+
+A footnote reference must be enclosed in square brackets and must start with a
+caret `^`, directly followed by an arbitrary identifier, which is similar to
+the standard Markdown link syntax.
+
+``` title="Text with footnote references"
+Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
+```
+
+
+
+### Adding footnote content
+
+The footnote content must be declared with the same identifier as the reference.
+It can be inserted at an arbitrary position in the document and is always
+rendered at the bottom of the page. Furthermore, a backlink to the footnote
+reference is automatically added.
+
+#### on a single line
+
+Short footnotes can be written on the same line:
+
+``` title="Footnote"
+[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+```
+
+
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:1)
+
+
+
+ [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+#### on multiple lines
+
+Paragraphs can be written on the next line and must be indented by four spaces:
+
+``` title="Footnote"
+[^2]:
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:2)
+
+
+
+[^2]:
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+ auctor massa, nec semper lorem quam in massa.
diff --git a/mkdocs-material/docs/reference/formatting.md b/mkdocs-material/docs/reference/formatting.md
new file mode 100644
index 0000000..e8148ce
--- /dev/null
+++ b/mkdocs-material/docs/reference/formatting.md
@@ -0,0 +1,140 @@
+---
+icon: material/format-font
+---
+
+# Formatting
+
+Material for MkDocs provides support for several HTML elements that can be used
+to highlight sections of a document or apply specific formatting. Additionally,
+[Critic Markup] is supported, adding the ability to display suggested changes
+for a document.
+
+ [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
+
+## Configuration
+
+This configuration enables support for keyboard keys, tracking changes in
+documents, defining sub- and superscript and highlighting text. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.critic
+ - pymdownx.caret
+ - pymdownx.keys
+ - pymdownx.mark
+ - pymdownx.tilde
+```
+
+See additional configuration options:
+
+- [Critic]
+- [Caret, Mark & Tilde]
+- [Keys]
+
+ [Critic]: ../setup/extensions/python-markdown-extensions.md#critic
+ [Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
+ [Keys]: ../setup/extensions/python-markdown-extensions.md#keys
+
+## Usage
+
+### Highlighting changes
+
+When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
+highlight suggested changes, as well as add inline comments to a document:
+
+``` title="Text with suggested changes"
+Text can be {--deleted--} and replacement text {++added++}. This can also be
+combined into {~~one~>a single~~} operation. {==Highlighting==} is also
+possible {>>and comments can be added inline<<}.
+
+{==
+
+Formatting can also be applied to blocks by putting the opening and closing
+tags on separate lines and adding new lines between the tags and the content.
+
+==}
+```
+
+
+
+Text can be deleted and replacement text
+added. This can also be combined into
+onea single operation.
+Highlighting is also possible
+and comments can be added inline.
+
+
+
+
+ Formatting can also be applied to blocks by putting the opening and
+ closing tags on separate lines and adding new lines between the tags and
+ the content.
+
+
+
+
+
+
+### Highlighting text
+
+When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
+syntax, which is more convenient that directly using the corresponding
+[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags:
+
+``` title="Text with highlighting"
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
+```
+
+
+
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
+
+
+
+ [mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+ [ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+ [del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
+
+### Sub- and superscripts
+
+When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
+superscripted with a simple syntax, which is more convenient than directly
+using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
+
+``` markdown title="Text with sub- and superscripts"
+- H~2~O
+- A^T^A
+```
+
+
+
+- H~2~O
+- A^T^A
+
+
+
+ [sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+ [sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
+
+### Adding keyboard keys
+
+When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
+Consult the [Python Markdown Extensions] documentation to learn about all
+available shortcodes:
+
+``` markdown title="Keyboard keys"
+++ctrl+alt+del++
+```
+
+
+
+++ctrl+alt+del++
+
+
+
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index
diff --git a/mkdocs-material/docs/reference/grids.md b/mkdocs-material/docs/reference/grids.md
new file mode 100644
index 0000000..10af8d5
--- /dev/null
+++ b/mkdocs-material/docs/reference/grids.md
@@ -0,0 +1,301 @@
+---
+icon: material/view-grid-plus
+---
+
+# Grids
+
+Material for MkDocs makes it easy to arrange sections into grids, grouping
+blocks that convey similar meaning or are of equal importance. Grids are just
+perfect for building index pages that show a brief overview of a large section
+of your documentation.
+
+## Configuration
+
+This configuration enables the use of grids, allowing to bring blocks of
+identical or different types into a rectangular shape. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions: # (1)!
+ - attr_list
+ - md_in_html
+```
+
+1. Note that some of the examples listed below use [icons and emojis], which
+ have to be [configured separately].
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+
+ [icons and emojis]: icons-emojis.md
+ [configured separately]: icons-emojis.md#configuration
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+
+## Usage
+
+Grids come in two flavors: [card grids], which wrap each element in a card that
+levitates on hover, and [generic grids], which allow to arrange arbitrary block
+elements in a rectangular shape.
+
+ [card grids]: #using-card-grids
+ [generic grids]: #using-generic-grids
+
+### Using card grids
+
+
+
+
+Card grids wrap each grid item with a beautiful hover card that levitates on
+hover. They come in two slightly different syntaxes: [list] and [block syntax],
+adding support for distinct use cases.
+
+ [list]: #list-syntax
+ [block syntax]: #block-syntax
+
+#### List syntax
+
+The list syntax is essentially a shortcut for [card grids], and consists of an
+unordered (or ordered) list wrapped by a `div` with both, the `grid` and `cards`
+classes:
+
+``` html title="Card grid"
+
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+
+```
+
+
+
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+
+
+
+List elements can contain arbitrary Markdown, as long as the surrounding `div`
+defines the `markdown` attribute. Following is a more complex example, which
+includes icons and links:
+
+``` html title="Card grid, complex example"
+
+
+- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+ ---
+
+ Install [`mkdocs-material`](#) with [`pip`](#) and get up
+ and running in minutes
+
+ [:octicons-arrow-right-24: Getting started](#)
+
+- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+ ---
+
+ Focus on your content and generate a responsive and searchable static site
+
+ [:octicons-arrow-right-24: Reference](#)
+
+- :material-format-font:{ .lg .middle } __Made to measure__
+
+ ---
+
+ Change the colors, fonts, language, icons, logo and more with a few lines
+
+ [:octicons-arrow-right-24: Customization](#)
+
+- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+ ---
+
+ Material for MkDocs is licensed under MIT and available on [GitHub]
+
+ [:octicons-arrow-right-24: License](#)
+
+
+```
+
+
+
+
+- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+ ---
+
+ Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
+ and running in minutes
+
+ [:octicons-arrow-right-24: Getting started][getting started]
+
+- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+ ---
+
+ Focus on your content and generate a responsive and searchable static site
+
+ [:octicons-arrow-right-24: Reference][reference]
+
+- :material-format-font:{ .lg .middle } __Made to measure__
+
+ ---
+
+ Change the colors, fonts, language, icons, logo and more with a few lines
+
+ [:octicons-arrow-right-24: Customization][customization]
+
+- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+ ---
+
+ Material for MkDocs is licensed under MIT and available on [GitHub]
+
+ [:octicons-arrow-right-24: License][license]
+
+
+
+
+If there's insufficient space to render grid items next to each other, the items
+will stretch to the full width of the viewport, e.g. on mobile viewports. If
+there's more space available, grids will render in items of 3 and more, e.g.
+when [hiding both sidebars].
+
+ [mkdocs-material]: https://pypistats.org/packages/mkdocs-material
+ [pip]: ../getting-started.md#with-pip
+ [getting started]: ../getting-started.md
+ [reference]: ../reference/index.md
+ [customization]: ../customization.md
+ [license]: ../license.md
+ [GitHub]: https://github.com/squidfunk/mkdocs-material
+ [hiding both sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
+
+#### Block syntax
+
+The block syntax allows for arranging cards in grids __together with other
+elements__, as explained in the section on [generic grids]. Just add the `card`
+class to any block element inside a `grid`:
+
+``` html title="Card grid, blocks"
+
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+
+```
+
+
+
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+
+
+
+While this syntax may seem unnecessarily verbose at first, the previous example
+shows how card grids can now be mixed with other elements that will also stretch
+to the grid.
+
+### Using generic grids
+
+
+
+
+Generic grids allow for arranging arbitrary block elements in a grid, including
+[admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks
+by using a `div` with the `grid` class:
+
+```` html title="Generic grid"
+
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+
+````
+
+
+
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+
+
+
+ [admonitions]: admonitions.md
+ [code blocks]: code-blocks.md
+ [content tabs]: content-tabs.md
diff --git a/mkdocs-material/docs/reference/icons-emojis.md b/mkdocs-material/docs/reference/icons-emojis.md
new file mode 100644
index 0000000..e9f5d6c
--- /dev/null
+++ b/mkdocs-material/docs/reference/icons-emojis.md
@@ -0,0 +1,239 @@
+---
+icon: material/emoticon-happy-outline
+---
+
+# Icons, Emojis
+
+One of the best features of Material for MkDocs is the possibility to use [more
+than 10,000 icons][icon search] and thousands of emojis in your project
+documentation with practically zero additional effort. Moreover, [custom icons
+can be added] and used in `mkdocs.yml`, documents and templates.
+
+ [icon search]: #search
+ [custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
+
+## Search
+
+
+
+
+
+
+
+
+
+
+ :octicons-light-bulb-16:
+ **Tip:** Enter some keywords to find icons and emojis and click on the
+ shortcode to copy it to your clipboard.
+
+
+## Configuration
+
+This configuration enables the use of icons and emojis by using simple
+shortcodes which can be discovered through the [icon search]. Add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+```
+
+The following icon sets are bundled with Material for MkDocs:
+
+- :material-material-design: – [Material Design]
+- :fontawesome-brands-font-awesome: – [FontAwesome]
+- :octicons-mark-github-16: – [Octicons]
+- :simple-simpleicons: – [Simple Icons]
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Emoji]
+- [Emoji with custom icons]
+
+ [Material Design]: https://materialdesignicons.com/
+ [FontAwesome]: https://fontawesome.com/search?m=free
+ [Octicons]: https://octicons.github.com/
+ [Simple Icons]: https://simpleicons.org/
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
+ [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.emoji.options.custom_icons
+
+## Usage
+
+### Using emojis
+
+Emojis can be integrated in Markdown by putting the shortcode of the emoji
+between two colons. If you're using [Twemoji] (recommended), you can look up
+the shortcodes at [Emojipedia]:
+
+``` title="Emoji"
+:smile:
+```
+
+
+
+:smile:
+
+
+ [Twemoji]: https://github.com/twitter/twemoji
+ [Emojipedia]: https://emojipedia.org/twitter/
+
+### Using icons
+
+When [Emoji] is enabled, icons can be used similar to emojis, by referencing
+a valid path to any icon bundled with the theme, which are located in the
+[`.icons`][custom icons] directory, and replacing `/` with `-`:
+
+``` title="Icon"
+:fontawesome-regular-face-laugh-wink:
+```
+
+
+
+:fontawesome-regular-face-laugh-wink:
+
+
+
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+
+#### with colors
+
+When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
+suffixing the icon with a special syntax. While HTML allows to use [inline
+styles], it's always recommended to add an [additional style sheet] and move
+declarations into dedicated CSS classes:
+
+
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .youtube {
+ color: #EE0F0F;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, add the CSS class to the icon shortcode:
+
+``` markdown title="Icon with color"
+:fontawesome-brands-youtube:{ .youtube }
+```
+
+
+
+:fontawesome-brands-youtube:{ .youtube }
+
+
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
+ [additional style sheet]: ../customization.md#additional-css
+
+#### with animations
+
+Similar to adding [colors], it's just as easy to add [animations] to icons by
+using an [additional style sheet], defining a `@keyframes` rule and adding a
+dedicated CSS class to the icon:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ @keyframes heart {
+ 0%, 40%, 80%, 100% {
+ transform: scale(1);
+ }
+ 20%, 60% {
+ transform: scale(1.15);
+ }
+ }
+ .heart {
+ animation: heart 1000ms infinite;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, add the CSS class to the icon shortcode:
+
+``` markdown title="Icon with animation"
+:octicons-heart-fill-24:{ .heart }
+```
+
+
+
+:octicons-heart-fill-24:{ .mdx-heart }
+
+
+
+ [colors]: #with-colors
+ [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
+
+### Icons, emojis in sidebars :smile:
+
+With the help of the [built-in typeset plugin], you can use icons and emojis
+in headings, which will then be rendered in the sidebars. The plugin preserves
+Markdown and HTML formatting.
+
+ [built-in typeset plugin]: ../plugins/typeset.md
+
+## Customization
+
+### Using icons in templates
+
+When you're [extending the theme] with partials or blocks, you can simply
+reference any icon that's [bundled with the theme][icon search] with Jinja's
+[`include`][include] function and wrap it with the `.twemoji` CSS class:
+
+``` html
+
+ {% include ".icons/fontawesome/brands/youtube.svg" %}
+
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+This is exactly what Material for MkDocs does in its templates.
+
+ [extending the theme]: ../customization.md#extending-the-theme
+ [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
diff --git a/mkdocs-material/docs/reference/images.md b/mkdocs-material/docs/reference/images.md
new file mode 100644
index 0000000..336bd4c
--- /dev/null
+++ b/mkdocs-material/docs/reference/images.md
@@ -0,0 +1,219 @@
+---
+icon: material/image-frame
+---
+
+# Images
+
+While images are first-class citizens of Markdown and part of the core syntax,
+it can be difficult to work with them. Material for MkDocs makes working with
+images more comfortable, providing styles for image alignment and image
+captions.
+
+## Configuration
+
+This configuration adds the ability to align images, add captions to images
+(rendering them as figures), and mark large images for lazy-loading. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - md_in_html
+ - pymdownx.blocks.caption
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+- [Caption]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+ [Caption]: ../setup/extensions/python-markdown-extensions.md#caption
+
+### Lightbox
+
+
+
+
+If you want to add image zoom functionality to your documentation, the
+[glightbox] plugin is an excellent choice, as it integrates perfectly
+with Material for MkDocs. Install it with `pip`:
+
+```
+pip install mkdocs-glightbox
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - glightbox
+```
+
+We recommend checking out the available
+[configuration options][glightbox options].
+
+ [glightbox]: https://github.com/blueswen/mkdocs-glightbox
+ [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
+
+## Usage
+
+### Image alignment
+
+When [Attribute Lists] is enabled, images can be aligned by adding the
+respective alignment directions via the `align` attribute, i.e. `align=left` or
+`align=right`:
+
+=== "Left"
+
+ ``` markdown title="Image, aligned to left"
+ { align=left }
+ ```
+
+
+
+ { align=left width=300 }
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+ { align=right width=300 }
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+
+
+If there's insufficient space to render the text next to the image, the image
+will stretch to the full width of the viewport, e.g. on mobile viewports.
+
+??? question "Why is there no centered alignment?"
+
+ The [`align`][align] attribute doesn't allow for centered alignment, which
+ is why this option is not supported by Material for MkDocs.[^1] Instead,
+ the [image captions] syntax can be used, as captions are optional.
+
+ [^1]:
+ You might also realize that the [`align`][align] attribute has been
+ deprecated as of HTML5, so why use it anyways? The main reason is
+ portability – it's still supported by all browsers and clients, and is very
+ unlikely to be completely removed, as many older websites still use it. This
+ ensures a consistent appearance when a Markdown file with these attributes
+ is viewed outside of a website generated by Material for MkDocs.
+
+ [align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
+ [image captions]: #image-captions
+
+### Image captions
+
+Sadly, the Markdown syntax doesn't provide native support for image captions,
+but it's always possible to use the [Markdown in HTML] extension with literal
+`figure` and `figcaption` tags:
+
+``` html title="Image with caption"
+
+ { width="300" }
+ Image caption
+
+```
+
+
+
+
+ Image caption
+
+
+
+However, [Caption] provides an alternative syntax to add captions
+to any Markdown block element, including images:
+
+``` markdown title="Image with caption"
+{ width="300" }
+/// caption
+Image caption
+///
+```
+
+### Image lazy-loading
+
+Modern browsers provide [native support for lazy-loading images][lazy-loading]
+through the `loading=lazy` directive, which degrades to eager-loading in
+browsers without support:
+
+``` markdown title="Image, lazy-loaded"
+{ loading=lazy }
+```
+
+
+
+
+
+ [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
+
+### Light and dark mode
+
+
+
+If you added a [color palette toggle] and want to show different images for
+light and dark color schemes, you can append a `#only-light` or `#only-dark`
+hash fragment to the image URL:
+
+``` markdown title="Image, different for light and dark mode"
+
+
+```
+
+
+
+!!! warning "Requirements when using [custom color schemes]"
+
+ The built-in [color schemes] define the aforementioned hash fragments, but
+ if you're using [custom color schemes], you'll also have to add the
+ following selectors to your scheme, depending on whether it's a light or
+ dark scheme:
+
+ === "Custom light scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-light"] img[src$="#only-dark"],
+ [data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
+ display: none; /* Hide dark images in light mode */
+ }
+ ```
+
+ === "Custom dark scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-dark"] img[src$="#only-light"],
+ [data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
+ display: none; /* Hide light images in dark mode */
+ }
+ ```
+
+ Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
+ name of your scheme.
+
+ [color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
+ [Zelda light world]: ../assets/images/zelda-light-world.png#only-light
+ [Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [custom color schemes]: ../setup/changing-the-colors.md#custom-color-schemes
diff --git a/mkdocs-material/docs/reference/index.md b/mkdocs-material/docs/reference/index.md
new file mode 100644
index 0000000..741511c
--- /dev/null
+++ b/mkdocs-material/docs/reference/index.md
@@ -0,0 +1,235 @@
+# Reference
+
+Material for MkDocs is packed with many great features that make technical
+writing a joyful activity. This section of the documentation explains how to set up
+a page, and showcases all available specimen that can be used directly from
+within Markdown files.
+
+## Configuration
+
+## Usage
+
+### Setting the page `title`
+
+Each page has a designated title, which is used in the navigation sidebar, for
+[social cards] and in other places. While MkDocs attempts to automatically
+determine the title of a page in a [four step process], the title can also be
+explicitly set with the front matter `title` property:
+
+``` yaml
+---
+title: Lorem ipsum dolor sit amet # (1)!
+---
+
+# Page title
+...
+```
+
+1. This line sets the [`title`][title] inside the HTML document's
+ [`head`][head] for the generated page to the given value. Note that the
+ site title, which is set via [`site_name`][site_name], is appended with a
+ dash.
+
+ [social cards]: ../setup/setting-up-social-cards.md
+ [four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
+ [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
+ [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
+ [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
+
+### Setting the page `description`
+
+A Markdown file can include a description that is added to the `meta` tags of
+a page, and is also used for [social cards]. It's a good idea to set a
+[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
+the author does not explicitly define a description for a Markdown file:
+
+``` yaml
+---
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
+---
+
+# Page title
+...
+```
+
+1. This line sets the `meta` tag containing the description inside the
+ document `head` for the current page to the provided value.
+
+ [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+
+### Setting the page `icon`
+
+
+
+
+An icon can be assigned to each page, which is then rendered as part of the
+navigation sidebar, as well as [navigation tabs], if enabled. Use the front
+matter `icon` property to reference an icon, adding the following lines at the
+top of a Markdown file:
+
+``` yaml
+---
+icon: material/emoticon-happy # (1)!
+---
+
+# Page title
+...
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+ [Insiders]: ../insiders/index.md
+ [icon search]: icons-emojis.md#search
+ [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
+
+### Setting the page `status`
+
+
+
+
+
+A status can be assigned to each page, which is then displayed as part of the
+navigation sidebar. First, associate a status identifier with a description by
+adding the following to `mkdocs.yml`:
+
+``` yaml
+extra:
+ status:
+ : # (1)!
+```
+
+1. The identifier can only include alphanumeric characters, as well as dashes
+ and underscores. For example, if you have a status `Recently added`, you can
+ set `new` as an identifier:
+
+ ``` yaml
+ extra:
+ status:
+ new: Recently added
+ ```
+
+The page status can now be set with the front matter `status` property. For
+example, you can mark a page as `new` with the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+status: new
+---
+
+# Page title
+...
+```
+
+The following status identifiers are already defined:
+
+- :material-alert-decagram: – `new`
+- :material-trash-can: – `deprecated`
+
+You can define a custom page status this way but if you want it to
+have an icon other than the default one you need to also configure
+that in your `extra.css`. We have an [example for a custom
+page status] to get you started.
+
+[example for a custom page status]: https://mkdocs-material.github.io/examples/page-status/
+
+### Setting the page `subtitle`
+
+
+
+
+
+Each page can define a subtitle, which is then rendered below the title as part
+of the navigation sidebar by using the front matter `subtitle` property, and
+adding the following lines:
+
+``` yaml
+---
+subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
+---
+
+# Page title
+...
+```
+
+### Setting the page `template`
+
+If you're using [theme extension] and created a new page template in the
+`overrides` directory, you can enable it for a specific page. Add the following
+lines at the top of a Markdown file:
+
+``` yaml
+---
+template: custom.html
+---
+
+# Page title
+...
+```
+
+??? question "How to set a page template for an entire folder?"
+
+ With the help of the [built-in meta plugin], you can set a custom template
+ for an entire section and all nested pages, by creating a `.meta.yml` file
+ in the corresponding folder with the following content:
+
+ ``` yaml
+ template: custom.html
+ ```
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [built-in meta plugin]: ../plugins/meta.md
+
+## Customization
+
+### Using metadata in templates
+
+#### :material-check-all: on all pages
+
+In order to add custom `meta` tags to your document, you can [extend the theme
+][theme extension] and [override the `extrahead` block][overriding blocks],
+e.g. to add indexing policies for search engines via the `robots` property:
+
+``` html
+{% extends "base.html" %}
+
+{% block extrahead %}
+
+{% endblock %}
+```
+
+ [overriding blocks]: ../customization.md#overriding-blocks
+
+#### :material-check: on a single page
+
+If you want to set a `meta` tag on a single page, or want to set different
+values for different pages, you can use the `page.meta` object inside your
+template override, e.g.:
+
+``` html
+{% extends "base.html" %}
+
+{% block extrahead %}
+ {% if page and page.meta and page.meta.robots %}
+
+ {% else %}
+
+ {% endif %}
+{% endblock %}
+```
+
+You can now use `robots` exactly like [`title`][title] and
+[`description`][description] to set values. Note that in this case, the
+template defines an `else` branch, which would set a default if none was given.
+
+ [title]: #setting-the-page-title
+ [description]: #setting-the-page-description
diff --git a/mkdocs-material/docs/reference/lists.md b/mkdocs-material/docs/reference/lists.md
new file mode 100644
index 0000000..1de7e7b
--- /dev/null
+++ b/mkdocs-material/docs/reference/lists.md
@@ -0,0 +1,168 @@
+---
+icon: material/format-list-bulleted
+---
+
+# Lists
+
+Material for MkDocs supports several flavors of lists that cater to different
+use cases, including _unordered lists_ and _ordered lists_, which are supported
+through standard Markdown, as well as _definition lists_ and _task lists_, which
+are supported through extensions.
+
+## Configuration
+
+This configuration enables the use of definition lists and tasks lists, which
+are both not part of the standard Markdown syntax. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - def_list
+ - pymdownx.tasklist:
+ custom_checkbox: true
+```
+
+See additional configuration options:
+
+- [Definition Lists]
+- [Tasklist]
+
+ [Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
+ [Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
+
+## Usage
+
+### Using unordered lists
+
+Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
+marker, all of which can be used interchangeably. Furthermore, all flavors
+of lists can be nested inside each other:
+
+``` markdown title="List, unordered"
+- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+ accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+ lacinia sed. Aenean in finibus diam.
+
+ * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ * Nam vulputate tincidunt fringilla.
+ * Nullam dignissim ultrices urna non auctor.
+```
+
+
+
+- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+ accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+ lacinia sed. Aenean in finibus diam.
+
+ * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ * Nam vulputate tincidunt fringilla.
+ * Nullam dignissim ultrices urna non auctor.
+
+
+
+### Using ordered lists
+
+Ordered lists must start with a number immediately followed by a dot. The
+numbers do not need to be consecutive and can be all set to `1.`, as they will
+be re-numbered when rendered:
+
+``` markdown title="List, ordered"
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+ sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+ nulla. Vivamus a pharetra leo.
+
+ 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+ quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+ ultricies libero efficitur sed.
+
+ 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+ rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+ 1. Mauris dictum mi lacus
+ 2. Ut sit amet placerat ante
+ 3. Suspendisse ac eros arcu
+```
+
+
+
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+ sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+ nulla. Vivamus a pharetra leo.
+
+ 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+ quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+ ultricies libero efficitur sed.
+
+ 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+ rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+ 1. Mauris dictum mi lacus
+ 2. Ut sit amet placerat ante
+ 3. Suspendisse ac eros arcu
+
+
+
+### Using definition lists
+
+When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
+parameters of functions or modules, can be enumerated with a simple syntax:
+
+``` markdown title="Definition list"
+`Lorem ipsum dolor sit amet`
+
+: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+ tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+
+: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+ ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+ Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ Nam vulputate tincidunt fringilla.
+ Nullam dignissim ultrices urna non auctor.
+```
+
+
+
+`Lorem ipsum dolor sit amet`
+
+: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+ tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+
+: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+ ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+ Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ Nam vulputate tincidunt fringilla.
+ Nullam dignissim ultrices urna non auctor.
+
+
+
+### Using task lists
+
+When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
+render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
+for the definition of task lists:
+
+``` markdown title="Task list"
+- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+- [ ] Vestibulum convallis sit amet nisi a tincidunt
+ * [x] In hac habitasse platea dictumst
+ * [x] In scelerisque nibh non dolor mollis congue sed et metus
+ * [ ] Praesent sed risus massa
+- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+```
+
+
+
+- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+- [ ] Vestibulum convallis sit amet nisi a tincidunt
+ * [x] In hac habitasse platea dictumst
+ * [x] In scelerisque nibh non dolor mollis congue sed et metus
+ * [ ] Praesent sed risus massa
+- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+
+
diff --git a/mkdocs-material/docs/reference/math.md b/mkdocs-material/docs/reference/math.md
new file mode 100644
index 0000000..83cc8df
--- /dev/null
+++ b/mkdocs-material/docs/reference/math.md
@@ -0,0 +1,198 @@
+---
+icon: material/alphabet-greek
+---
+
+# Math
+
+[MathJax] and [KaTeX] are two popular libraries for displaying
+mathematical content in browsers. Although both libraries offer similar
+functionality, they use different syntaxes and have different configuration
+options. This documentation site provides information on how to integrate them
+with Material for MkDocs easily.
+
+ [MathJax]: https://www.mathjax.org/
+ [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
+ [MathML]: https://en.wikipedia.org/wiki/MathML
+ [AsciiMath]: http://asciimath.org/
+ [KaTeX]: https://katex.org/
+
+
+## Configuration
+
+The following configuration enables support for rendering block and
+inline block equations using [MathJax] and [KaTeX].
+
+### MathJax
+
+[MathJax] is a powerful and flexible library that supports multiple input formats,
+such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
+HTML, SVG, MathML. To use MathJax within your project, add the following lines
+to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
+
+ ``` js
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => { // (1)!
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
+ MathJax.typesetPromise()
+ })
+ ```
+
+ 1. This integrates MathJax with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
+ extra_javascript:
+ - javascripts/mathjax.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+ ```
+
+See additional configuration options:
+
+- [Arithmatex]
+
+ [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+
+
+
+### KaTeX
+
+[KaTeX] is a lightweight library that focuses on speed and simplicity. It
+supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
+[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
+
+ ``` js
+ document$.subscribe(({ body }) => { // (1)!
+ renderMathInElement(body, {
+ delimiters: [
+ { left: "$$", right: "$$", display: true },
+ { left: "$", right: "$", display: false },
+ { left: "\\(", right: "\\)", display: false },
+ { left: "\\[", right: "\\]", display: true }
+ ],
+ })
+ })
+ ```
+
+ 1. This integrates KaTeX with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
+ extra_javascript:
+ - javascripts/katex.js
+ - https://unpkg.com/katex@0/dist/katex.min.js
+ - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
+
+ extra_css:
+ - https://unpkg.com/katex@0/dist/katex.min.css
+ ```
+
+## Usage
+
+### Using block syntax
+
+Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
+lines:
+
+``` latex title="block syntax"
+$$
+\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
+$$
+```
+
+
+
+### Using inline block syntax
+
+Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
+
+``` latex title="inline syntax"
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+```
+
+
+
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+
+
+
+## Comparing MathJax and KaTeX
+
+When deciding between MathJax and KaTeX, there are several key factors to
+consider:
+
+- __Speed__: KaTeX is generally faster than MathJax. If your site requires
+ rendering large quantities of complex equations quickly, KaTeX may be the
+ better choice.
+
+- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
+ process a variety of mathematical markup languages (like AsciiMath and MathML).
+ If you need advanced LaTeX features, MathJax may be more suitable.
+
+- __Output Format__: Both libraries support HTML and SVG outputs. However,
+ MathJax also offers MathML output, which can be essential for accessibility,
+ as it is readable by screen readers.
+
+- __Configurability__: MathJax provides a range of configuration options,
+ allowing for more precise control over its behavior. If you have specific
+ rendering requirements, MathJax might be a more flexible choice.
+
+- __Browser Support__: While both libraries work well in modern browsers,
+ MathJax has broader compatibility with older browsers. If your audience uses a
+ variety of browsers, including older ones, MathJax might be a safer option.
+
+In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
+more features and better compatibility at the expense of speed. The choice
+between the two will largely depend on your specific needs and constraints.
diff --git a/mkdocs-material/docs/reference/tooltips.md b/mkdocs-material/docs/reference/tooltips.md
new file mode 100644
index 0000000..55e8538
--- /dev/null
+++ b/mkdocs-material/docs/reference/tooltips.md
@@ -0,0 +1,167 @@
+---
+icon: material/tooltip-plus
+---
+
+# Tooltips
+
+Technical documentation often incurs the usage of many acronyms, which may
+need additional explanation, especially for new user of your project. For these
+matters, Material for MkDocs uses a combination of Markdown extensions to
+enable site-wide glossaries.
+
+## Configuration
+
+This configuration enables abbreviations and allows to build a simple
+project-wide glossary, sourcing definitions from a central location. Add the
+following line to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - abbr
+ - attr_list
+ - pymdownx.snippets
+```
+
+See additional configuration options:
+
+- [Abbreviations]
+- [Attribute Lists]
+- [Snippets]
+
+ [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Improved tooltips
+
+
+
+
+When improved tooltips are enabled, Material for MkDocs replaces the browser's
+rendering logic for `title` attribute with beautiful little tooltips.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.tooltips
+```
+
+Now, tooltips will be rendered for the following elements:
+
+- __Content__ – elements with a `title`, permalinks and code copy button
+- __Header__ – home button, header title, color palette switch and repository link
+- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
+
+## Usage
+
+### Adding tooltips
+
+The [Markdown syntax] allows to specify a `title` for each link, which will
+render as a beautiful tooltip when [improved tooltips] are enabled. Add a
+tooltip to a link with the following lines:
+
+``` markdown title="Link with tooltip, inline syntax"
+[Hover me](https://example.com "I'm a tooltip!")
+```
+
+
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+
+
+Tooltips can also be added to link references:
+
+``` markdown title="Link with tooltip, reference syntax"
+[Hover me][example]
+
+ [example]: https://example.com "I'm a tooltip!"
+```
+
+
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+
+
+For all other elements, a `title` can be added by using the [Attribute Lists]
+extension:
+
+``` markdown title="Icon with tooltip"
+:material-information-outline:{ title="Important information" }
+```
+
+
+
+ [Markdown syntax]: https://daringfireball.net/projects/markdown/syntax#link
+ [improved tooltips]: #improved-tooltips
+
+### Adding abbreviations
+
+Abbreviations can be defined by using a special syntax similar to URLs and
+[footnotes], starting with a `*` and immediately followed by the term or
+acronym to be associated in square brackets:
+
+``` markdown title="Text with abbreviations"
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+
+
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+
+
+
+
+
+
+{% endif %}
+```
+
+1. This code block ensures that [Giscus] renders with a dark theme when the
+ palette is set to `slate`. Note that multiple dark themes are available,
+ so you can change it to your liking.
+
+Replace the highlighted line with the snippet you generated with the [Giscus]
+configuration tool in the previous step. If you copied the snippet from above,
+you can enable comments on a page by setting the `comments` front matter
+property to `true`:
+
+``` yaml
+---
+comments: true
+---
+
+# Page title
+...
+```
+
+If you wish to enable comments for an entire folder, you can use the
+[built-in meta plugin].
+
+ [Giscus GitHub App]: https://github.com/apps/giscus
+ [theme extension]: ../customization.md#extending-the-theme
+ [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
+ [overriding partials]: ../customization.md#overriding-partials
+ [built-in meta plugin]: ../plugins/meta.md
diff --git a/mkdocs-material/docs/setup/adding-a-git-repository.md b/mkdocs-material/docs/setup/adding-a-git-repository.md
new file mode 100644
index 0000000..6ddbc0f
--- /dev/null
+++ b/mkdocs-material/docs/setup/adding-a-git-repository.md
@@ -0,0 +1,355 @@
+# Adding a git repository
+
+If your documentation is related to source code, Material for MkDocs provides
+the ability to display information to the project's repository as part of the
+static site, including stars and forks. Furthermore, the
+[date of last update and creation], as well as [contributors] can be shown.
+
+## Configuration
+
+### Repository
+
+
+
+
+In order to display a link to the repository of your project as part of your
+documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
+your repository, e.g.:
+
+``` yaml
+repo_url: https://github.com/squidfunk/mkdocs-material
+```
+
+The link to the repository will be rendered next to the search bar on big
+screens and as part of the main navigation drawer on smaller screen sizes.
+
+Additionally, for public repositories hosted on [GitHub] or [GitLab], the
+latest release tag[^1], as well as the number of stars and forks, are
+automatically requested and rendered.
+
+ [^1]:
+ Unfortunately, GitHub only provides an API endpoint to obtain the [latest
+ release] - not the latest tag. Thus, make sure to [create a release] (not
+ pre-release) for the latest tag you want to display next to the number of
+ stars and forks. For GitLab, although it is possible to get a [list of tags
+ sorted by update time], the [equivalent API endpoint] is used. So, make sure
+ you also [create a release for GitLab repositories].
+
+ [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
+ [latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
+ [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
+ [list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags
+ [equivalent API endpoint]: https://docs.gitlab.com/ee/api/releases/#get-the-latest-release
+ [create a release for GitLab repositories]: https://docs.gitlab.com/ee/user/project/releases/#create-a-release
+
+#### Repository name
+
+
+
+
+MkDocs will infer the source provider by examining the URL and try to set the
+_repository name_ automatically. If you wish to customize the name, set
+[`repo_name`][repo_name] in `mkdocs.yml`:
+
+``` yaml
+repo_name: squidfunk/mkdocs-material
+```
+
+ [repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
+
+#### Repository icon
+
+
+
+
+While the default repository icon is a generic git icon, it can be set to
+any icon bundled with the theme by referencing a valid icon path in
+`mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ repo: fontawesome/brands/git-alt # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+Some popular choices:
+
+- :fontawesome-brands-git: – `fontawesome/brands/git`
+- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
+- :fontawesome-brands-github: – `fontawesome/brands/github`
+- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
+- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
+- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
+- :fontawesome-solid-trash: – `fontawesome/solid/trash`
+
+ [icon search]: ../reference/icons-emojis.md#search
+
+#### Code actions
+
+
+
+
+If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
+repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
+resolves to the subfolder where your documentation is hosted.
+
+If your default branch is called `main`, change the setting to:
+
+``` yaml
+edit_uri: edit/main/docs/
+```
+
+After making sure that `edit_uri` is correctly configured, buttons for code
+actions can be added. Two types of code actions are supported: `edit` and `view`
+(GitHub only):
+
+=== ":material-file-edit-outline: Edit this page"
+
+ ``` yaml
+ theme:
+ features:
+ - content.action.edit
+ ```
+
+=== ":material-file-eye-outline: View source of this page"
+
+ ``` yaml
+ theme:
+ features:
+ - content.action.view
+ ```
+
+The icon of the edit and view buttons can be changed with the following lines:
+
+``` yaml
+theme:
+ icon:
+ edit: material/pencil # (1)!
+ view: material/eye
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+ [repository URL]: #repository
+ [GitHub]: https://github.com/
+ [GitLab]: https://about.gitlab.com/
+ [Bitbucket]: https://bitbucket.org/
+ [MkDocs]: https://www.mkdocs.org
+ [edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
+
+### Revisioning
+
+The following plugins are fully integrated with Material for MkDocs, allowing
+for showing the [date of last update and creation] of a document, as well as
+links to all [contributors] or [authors] involved.
+
+ [date of last update and creation]: #document-dates
+ [contributors]: #document-contributors
+ [authors]: #document-authors
+
+#### Document dates
+
+
+
+
+The [git-revision-date-localized] plugin adds support for adding the date of
+last update and creation of a document at the bottom of each page. Install it
+with `pip`:
+
+```
+pip install mkdocs-git-revision-date-localized-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-revision-date-localized:
+ enable_creation_date: true
+```
+
+The following configuration options are supported:
+
+
+
+: This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, e.g. for local builds, use an [environment variable]:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ enabled: !ENV [CI, false]
+ ```
+
+
+
+: The format of the date to be
+ displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
+ and `timeago`:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ type: date
+ ```
+
+
+
+: Enables the display of the
+ creation date of the file associated with the page next to the last updated
+ date at the bottom of the page:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ enable_creation_date: true
+ ```
+
+ !!! note "When using build environments"
+
+ If you are deploying through a CI system, you might need to adjust your
+ CI settings when fetching the code. For more information, see
+ [git-revision-date-localized].
+
+
+
+: Enables falling back to
+ the time when `mkdocs build` was executed. Can be used as a fallback when
+ the build is performed outside of a git repository:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ fallback_to_build_date: true
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+
+#### Document contributors
+
+
+
+
+
+The [git-committers][^2] plugin renders the GitHub avatars of all contributors,
+linking to their GitHub profiles at the bottom of each page. As always, it can
+be installed with `pip`:
+
+ [^2]:
+ We currently recommend using a fork of the [git-committers] plugin, as it
+ contains many improvements that have not yet been merged back into the
+ original plugin. See byrnereese/mkdocs-git-committers-plugin#12 for more
+ information.
+
+```
+pip install mkdocs-git-committers-plugin-2
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-committers:
+ repository: squidfunk/mkdocs-material
+ branch: main
+```
+
+The following configuration options are supported:
+
+
+
+: This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, e.g. for local builds, use an [environment variable]:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ enabled: !ENV [CI, false]
+ ```
+
+
+
+:
+ This property must be set to the slug of the repository that contains your
+ documentation. The slug must follow the pattern `/`:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ repository: squidfunk/mkdocs-material
+ ```
+
+
+
+: This property should be set to
+ the branch of the repository from which to retrieve the contributors. To use the `main` branch:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ branch: main
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [Insiders]: ../insiders/index.md
+ [git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
+ [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+ [rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
+
+#### Document authors
+
+
+
+
+
+The [git-authors] plugin is a lightweight alternative to the
+[git-committers] plugin and extracts the authors of a document from git to display
+them at the bottom of each page.
+
+Material for MkDocs offers deep integration for [git-authors]. This means the
+[customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme)
+are not necessary, and additional styling (such as nice icons) are added.
+Simply install it with `pip`:
+
+```
+pip install mkdocs-git-authors-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-authors
+```
+
+ [git-authors]: https://github.com/timvink/mkdocs-git-authors-plugin/
diff --git a/mkdocs-material/docs/setup/building-an-optimized-site.md b/mkdocs-material/docs/setup/building-an-optimized-site.md
new file mode 100644
index 0000000..ac356ea
--- /dev/null
+++ b/mkdocs-material/docs/setup/building-an-optimized-site.md
@@ -0,0 +1,108 @@
+# Building an optimized site
+
+Material for MkDocs, by default, allows to build optimized sites that rank great
+on search engines, load fast (even on slow networks), and work perfectly without
+JavaScript. Additionally, the [built-in optimize plugin] adds support for
+further useful automatic optimization techniques.
+
+ [built-in optimize plugin]: #built-in-optimize-plugin
+
+## Configuration
+
+### Built-in projects plugin
+
+
+
+
+
+
+The built-in projects plugin allows to split your documentation into multiple
+distinct MkDocs projects, __build them concurrently__ and
+__serve them together__. Add the following to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [projects]: ../plugins/projects.md
+ [plugin documentation]: ../plugins/projects.md
+
+??? info "Use cases for the projects plugin"
+
+ Ideal use cases for the projects plugin are:
+
+ - Building a multi-language site
+ - Building a blog alongside your documentation
+ - Splitting large code bases for better performance
+
+ Note that the plugin is currently experimental. We're releasing it early,
+ so that we can improve it together with our users and make it even more
+ powerful as we discover new use cases.
+
+#### Scope
+
+
+
+
+There might be a use case, where you want to share user-level settings like
+the selected [color palette], or [cookie consent] across all projects. To do
+so, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra:
+ scope: /
+```
+
+!!! example "How it works"
+
+ Suppose you have this site structure:
+ ```
+ .
+ └── /
+ ├── subsite-a/
+ ├── subsite-b/
+ └── subsite-c/
+ ```
+ By default, each site will have its own scope (`/subsite-a/`, `/subsite-b/`,
+ `/subsite-c/`). To modify this behaviour, add the following lines to
+ `mkdocs.yml`:
+
+ ``` yaml
+ extra:
+ scope: /
+ ```
+
+ By setting it to `/`, it should allow you to share the following preferences
+ across the main site and all subsites:
+
+ - [Cookie consent][cookie consent]
+ - [Linking of content tabs, i.e. active tab]
+ - [Color palette][color palette]
+
+ [Scope support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
+ [cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
+ [Linking of content tabs, i.e. active tab]: ../reference/content-tabs.md
+ [color palette]: ../setup/changing-the-colors.md#color-palette
+
+### Built-in optimize plugin
+
+
+
+
+
+
+The built-in optimize plugin automatically identifies and optimizes all media
+files as part of the build using compression and conversion techniques. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - optimize
+```
+
+For a list of all settings, please consult the [plugin documentation][optimize].
+
+ [optimize]: ../plugins/optimize.md
diff --git a/mkdocs-material/docs/setup/building-for-offline-usage.md b/mkdocs-material/docs/setup/building-for-offline-usage.md
new file mode 100644
index 0000000..5c13b57
--- /dev/null
+++ b/mkdocs-material/docs/setup/building-for-offline-usage.md
@@ -0,0 +1,55 @@
+# Building for offline usage
+
+If you want to ship your documentation together with your product, MkDocs has
+you covered – with support from themes, [MkDocs] allows for building
+offline-capable documentation. Notably, Material for MkDocs offers offline
+support for many of its features.
+
+ [MkDocs]: https://www.mkdocs.org
+
+## Configuration
+
+### Built-in offline plugin
+
+
+
+
+The built-in offline plugin makes sure that the [site search] works when you
+distribute the contents of your [site directory] as a download. Simply add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - offline
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [offline]: ../plugins/offline.md
+ [plugin documentation]: ../plugins/offline.md
+
+!!! tip "Automatically bundle all external assets"
+
+ The [built-in privacy plugin] makes it easy to use external assets
+ while building documentation for offline usage, as it will automatically
+ download all external assets to distribute them with your documentation.
+
+ [site search]: setting-up-site-search.md
+ [site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+ [built-in privacy plugin]:../plugins/privacy.md
+
+#### Limitations
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the file system due to the restrictions of modern browsers: all
+features that use the `fetch` API will error.
+
+Thus, when building for offline usage, make sure to disable the following
+configuration settings: [instant loading], [site analytics], [git repository],
+[versioning] and [comment systems].
+
+ [Instant loading]: setting-up-navigation.md#instant-loading
+ [Site analytics]: setting-up-site-analytics.md
+ [Versioning]: setting-up-versioning.md
+ [Git repository]: adding-a-git-repository.md
+ [Comment systems]: adding-a-comment-system.md
diff --git a/mkdocs-material/docs/setup/changing-the-colors.md b/mkdocs-material/docs/setup/changing-the-colors.md
new file mode 100644
index 0000000..25d93ce
--- /dev/null
+++ b/mkdocs-material/docs/setup/changing-the-colors.md
@@ -0,0 +1,403 @@
+# Changing the colors
+
+As any proper Material Design implementation, Material for MkDocs supports
+Google's original [color palette], which can be easily configured through
+`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
+fit your brand's identity by using [CSS variables][custom colors].
+
+ [color palette]: http://www.materialui.co/colors
+ [custom colors]: #custom-colors
+
+## Configuration
+
+### Color palette
+
+#### Color scheme
+
+
+
+
+Material for MkDocs supports two color schemes: a __light mode__, which is just
+called `default`, and a __dark mode__, which is called `slate`. The color scheme
+can be set via `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+ scheme: default
+```
+
+Click on a tile to change the color scheme:
+
+
+
+
+
+
+
+
+#### Primary color
+
+
+
+
+The primary color is used for the header, the sidebar, text links and several
+other components. In order to change the primary color, set the following value
+in `mkdocs.yml` to a valid color name:
+
+``` yaml
+theme:
+ palette:
+ primary: indigo
+```
+
+Click on a tile to change the primary color:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+See our guide below to learn how to set [custom colors].
+
+#### Accent color
+
+
+
+
+The accent color is used to denote elements that can be interacted with, e.g.
+hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
+choosing a valid color name:
+
+``` yaml
+theme:
+ palette:
+ accent: indigo
+```
+
+Click on a tile to change the accent color:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+See our guide below to learn how to set [custom colors].
+
+### Color palette toggle
+
+
+
+
+
+Offering a light _and_ dark color palette makes your documentation pleasant to
+read at different times of the day, so the user can choose accordingly. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette: # (1)!
+
+ # Palette toggle for light mode
+ - scheme: default
+ toggle:
+ icon: material/brightness-7 # (2)!
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+```
+
+1. Note that the `theme.palette` setting is now defined as a list.
+
+2. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+This configuration will render a color palette toggle next to the search bar.
+Note that you can also define separate settings for [`primary`][palette.primary]
+and [`accent`][palette.accent] per color palette.
+
+The following properties must be set for each toggle:
+
+
+
+:
+ This property must point to a valid icon path referencing any icon bundled
+ with the theme, or the build will not succeed. Some popular combinations:
+
+ * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4`
+ * :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline`
+ * :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny`
+ * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
+ * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
+
+
+
+:
+ This property is used as the toggle's `title` attribute and should be set to
+ a discernable name to improve accessibility. It's rendered as a [tooltip].
+
+ [palette.scheme]: #color-scheme
+ [palette.primary]: #primary-color
+ [palette.accent]: #accent-color
+ [icon search]: ../reference/icons-emojis.md#search
+ [tooltip]: ../reference/tooltips.md
+
+### System preference
+
+
+
+
+
+Each color palette can be linked to the user's system preference for light and
+dark appearance by using a media query. Simply add a `media` property next to
+the `scheme` definition in `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+```
+
+When the user first visits your site, the media queries are evaluated in the
+order of their definition. The first media query that matches selects the
+default color palette.
+
+#### Automatic light / dark mode
+
+
+
+
+
+Newer operating systems allow to automatically switch between light and dark
+appearance during day and night times. Material for MkDocs adds support for
+automatic light / dark mode, delegating color palette selection to the user's
+operating system. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+
+ # Palette toggle for automatic mode
+ - media: "(prefers-color-scheme)"
+ toggle:
+ icon: material/brightness-auto
+ name: Switch to light mode
+
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default # (1)!
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to system preference
+```
+
+1. You can also define separate settings for [`primary`][palette.primary] and
+ [`accent`][palette.accent] per color palette, i.e. different colors for
+ light and dark mode.
+
+Material for MkDocs will now change the color palette each time the operating
+system switches between light and dark appearance, even when the user doesn't
+reload the site.
+
+ [Insiders]: ../insiders/index.md
+
+## Customization
+
+### Custom colors
+
+
+
+
+Material for MkDocs implements colors using [CSS variables] (custom
+properties). If you want to customize the colors beyond the palette (e.g. to
+use your brand-specific colors), you can add an [additional style sheet] and
+tweak the values of the CSS variables.
+
+First, set the [`primary`][palette.primary] or [`accent`][palette.accent] values
+in `mkdocs.yml` to `custom`, to signal to the theme that you want to define
+custom colors, e.g., when you want to override the `primary` color:
+
+``` yaml
+theme:
+ palette:
+ primary: custom
+```
+
+Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__YouTube__, and want to set the primary color to your brand's palette. Just
+add:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root {
+ --md-primary-fg-color: #EE0F0F;
+ --md-primary-fg-color--light: #ECB7B7;
+ --md-primary-fg-color--dark: #90030C;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+See the file containing the [color definitions] for a list of all CSS variables.
+
+ [CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+ [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
+ [additional style sheet]: ../customization.md#additional-css
+
+
+### Custom color schemes
+
+Besides overriding specific colors, you can create your own, named color scheme
+by wrapping the definitions in a `[data-md-color-scheme="..."]`
+[attribute selector], which you can then set via `mkdocs.yml` as described
+in the [color schemes][palette.scheme] section:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ [data-md-color-scheme="youtube"] {
+ --md-primary-fg-color: #EE0F0F;
+ --md-primary-fg-color--light: #ECB7B7;
+ --md-primary-fg-color--dark: #90030C;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ theme:
+ palette:
+ scheme: youtube
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+Additionally, the `slate` color scheme defines all of it's colors via `hsla`
+color functions and deduces its colors from the `--md-hue` CSS variable. You
+can tune the `slate` theme with:
+
+``` css
+[data-md-color-scheme="slate"] {
+ --md-hue: 210; /* (1)! */
+}
+```
+
+1. The `hue` value must be in the range of `[0, 360]`
+
+ [attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors
diff --git a/mkdocs-material/docs/setup/changing-the-fonts.md b/mkdocs-material/docs/setup/changing-the-fonts.md
new file mode 100644
index 0000000..cb7da21
--- /dev/null
+++ b/mkdocs-material/docs/setup/changing-the-fonts.md
@@ -0,0 +1,119 @@
+# Changing the fonts
+
+Material for MkDocs makes it easy to change the typeface of your project
+documentation, as it directly integrates with [Google Fonts]. Alternatively,
+fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
+or another destination should be used.
+
+ [Google Fonts]: https://fonts.google.com
+
+## Configuration
+
+### Regular font
+
+
+
+
+The regular font is used for all body copy, headlines, and essentially
+everything that does not need to be monospaced. It can be set to any
+valid [Google Font][Google Fonts] via `mkdocs.yml`:
+
+``` yaml
+theme:
+ font:
+ text: Roboto
+```
+
+The typeface will be loaded in 300, 400, _400i_ and __700__.
+
+ [Roboto]: https://fonts.google.com/specimen/Roboto
+
+### Monospaced font
+
+
+
+
+The _monospaced font_ is used for code blocks and can be configured separately.
+Just like the regular font, it can be set to any valid [Google Font]
+[Google Fonts] via `mkdocs.yml`:
+
+``` yaml
+theme:
+ font:
+ code: Roboto Mono
+```
+
+The typeface will be loaded in 400.
+
+ [Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
+
+### Autoloading
+
+
+
+
+If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
+to adhere to [data privacy] regulations, and fall back to system fonts, add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ font: false
+```
+
+!!! tip "Automatically bundle Google Fonts"
+
+ The [built-in privacy plugin] makes it easy to use Google Fonts
+ while complying with the __General Data Protection Regulation__ (GDPR),
+ by automatically downloading and self-hosting the web font files.
+
+ [data privacy]: https://developers.google.com/fonts/faq/privacy
+ [built-in privacy plugin]:../plugins/privacy.md
+
+## Customization
+
+### Additional fonts
+
+If you want to load an (additional) font from another destination or override
+the system font, you can use an [additional style sheet] to add the
+corresponding `@font-face` definition:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ @font-face {
+ font-family: "";
+ src: "...";
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+The font can then be applied to specific elements, e.g. only headlines, or
+globally to be used as the site-wide regular or monospaced font:
+
+=== "Regular font"
+
+ ``` css
+ :root {
+ --md-text-font: ""; /* (1)! */
+ }
+ ```
+
+ 1. Always define fonts through CSS variables and not `font-family`, as
+ this would disable the system font fallback.
+
+=== "Monospaced font"
+
+ ``` css
+ :root {
+ --md-code-font: "";
+ }
+ ```
+
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/mkdocs-material/docs/setup/changing-the-language.md b/mkdocs-material/docs/setup/changing-the-language.md
new file mode 100644
index 0000000..054ef83
--- /dev/null
+++ b/mkdocs-material/docs/setup/changing-the-language.md
@@ -0,0 +1,208 @@
+# Changing the language
+
+Material for MkDocs supports internationalization (i18n) and provides
+translations for template variables and labels in 60+ languages. Additionally,
+the site search can be configured to use a language-specific stemmer, if
+available.
+
+## Configuration
+
+### Site language
+
+
+
+
+You can set the site language in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ language: en # (1)!
+```
+
+1. HTML5 only allows to set a [single language per document], which is why
+ Material for MkDocs only supports setting a canonical language for the
+ entire project, i.e. one per `mkdocs.yml`.
+
+ The easiest way to build a multi-language documentation is to create one
+ project in a subfolder per language, and then use the [language selector]
+ to interlink those projects.
+
+The following languages are supported:
+
+
+
+Note that some languages will produce unreadable anchor links due to the way
+the default slug function works. Consider using a [Unicode-aware slug function].
+
+!!! tip "Translations missing? Help us out, it takes only 5 minutes"
+
+ Material for MkDocs relies on outside contributions for adding and updating
+ translations for the more than 60 languages it supports. If your language
+ shows that some translations are missing, click on the link to add them. If
+ your language is not in the list, click here to [add a new language].
+
+ [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
+ [language selector]: #site-language-selector
+ [Unicode-aware slug function]: extensions/python-markdown.md#+toc.slugify
+ [add a new language]: https://github.com/squidfunk/mkdocs-material/issues/new?template=04-add-a-translation.yml&title=Add+translations+for+...
+
+### Site language selector
+
+
+
+
+If your documentation is available in multiple languages, a language selector
+pointing to those languages can be added to the header. Alternate languages
+can be defined via `mkdocs.yml`.
+
+``` yaml
+extra:
+ alternate:
+ - name: English
+ link: /en/ # (1)!
+ lang: en
+ - name: Deutsch
+ link: /de/
+ lang: de
+```
+
+1. Note that this must be an absolute link. If it includes a domain part, it's
+ used as defined. Otherwise the domain part of the [`site_url`][site_url] as
+ set in `mkdocs.yml` is prepended to the link.
+
+The following properties are available for each alternate language:
+
+
+
+:
+ This value of this property is used inside the language selector as the
+ name of the language and must be set to a non-empty string.
+
+
+
+:
+ This property must be set to an absolute link, which might also point to
+ another domain or subdomain not necessarily generated with MkDocs.
+
+
+
+:
+ This property must contain an [ISO 639-1 language code] and is used for
+ the `hreflang` attribute of the link, improving discoverability via search
+ engines.
+
+[![Language selector preview]][Language selector preview]
+
+ [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+ [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+ [Language selector preview]: ../assets/screenshots/language-selection.png
+
+#### Stay on page
+
+
+
+
+
+[Insiders] improves the user experience when switching between languages, e.g.,
+if language `en` and `de` contain a page with the same path name, the user will
+stay on the current page:
+
+=== "Insiders"
+
+ ```
+ docs.example.com/en/ -> docs.example.com/de/
+ docs.example.com/en/foo/ -> docs.example.com/de/foo/
+ docs.example.com/en/bar/ -> docs.example.com/de/bar/
+ ```
+
+=== "Material for MkDocs"
+
+ ```
+ docs.example.com/en/ -> docs.example.com/de/
+ docs.example.com/en/foo/ -> docs.example.com/de/
+ docs.example.com/en/bar/ -> docs.example.com/de/
+ ```
+
+No configuration is necessary. We're working hard on improving multi-language
+support in 2024, including making switching between languages even more seamless
+in the future.
+
+ [Insiders]: ../insiders/index.md
+
+### Directionality
+
+
+
+
+While many languages are read `ltr` (left-to-right), Material for MkDocs also
+supports `rtl` (right-to-left) directionality which is deduced from the
+selected language, but can also be set with:
+
+``` yaml
+theme:
+ direction: ltr
+```
+
+Click on a tile to change the directionality:
+
+
+
+
+
+
+
+
+## Customization
+
+### Custom translations
+
+If you want to customize some of the translations for a language, just follow
+the guide on [theme extension] and create a new partial in the `overrides`
+folder. Then, import the [translations] of the language as a fallback and only
+adjust the ones you want to override:
+
+=== ":octicons-file-code-16: `overrides/partials/languages/custom.html`"
+
+ ``` html
+
+ {% import "partials/languages/de.html" as language %}
+ {% import "partials/languages/en.html" as fallback %}
+
+
+ {% macro override(key) %}{{ {
+ "source.file.date.created": "Erstellt am",
+ "source.file.date.updated": "Aktualisiert am"
+ }[key] }}{% endmacro %}
+
+
+ {% macro t(key) %}{{
+ override(key) or language.t(key) or fallback.t(key)
+ }}{% endmacro %}
+ ```
+
+ 1. Note that `en` must always be used as a fallback language, as it's the
+ default theme language.
+
+ 2. Check the [list of available languages], pick the translation you want
+ to override for your language and add them here.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ theme:
+ language: custom
+ ```
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
+ [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
diff --git a/mkdocs-material/docs/setup/changing-the-logo-and-icons.md b/mkdocs-material/docs/setup/changing-the-logo-and-icons.md
new file mode 100644
index 0000000..c8cdd05
--- /dev/null
+++ b/mkdocs-material/docs/setup/changing-the-logo-and-icons.md
@@ -0,0 +1,166 @@
+# Changing the logo and icons
+
+When installing Material for MkDocs, you immediately get access to _over 8,000
+icons_ ready to be used for customization of specific parts of the theme and/or
+when writing your documentation in Markdown. Not enough? You can also add
+[additional icons] with minimal effort.
+
+ [additional icons]: #additional-icons
+
+## Configuration
+
+### Logo
+
+
+
+
+The logo can be changed to a user-provided image (any type, incl. `*.png` and
+`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
+Add the following lines to `mkdocs.yml`:
+
+=== ":octicons-image-16: Image"
+
+ ``` yaml
+ theme:
+ logo: assets/logo.png
+ ```
+
+=== ":octicons-package-16: Icon, bundled"
+
+ ``` yaml
+ theme:
+ icon:
+ logo: material/library # (1)!
+ ```
+
+ 1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+ [Abbreviations]: python-markdown.md#abbreviations
+ [Admonition]: python-markdown.md#admonition
+ [Arithmatex]: python-markdown-extensions.md#arithmatex
+ [Attribute Lists]: python-markdown.md#attribute-lists
+ [BetterEm]: python-markdown-extensions.md#betterem
+ [Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
+ [Critic]: python-markdown-extensions.md#critic
+ [Definition Lists]: python-markdown.md#definition-lists
+ [Details]: python-markdown-extensions.md#details
+ [Emoji]: python-markdown-extensions.md#emoji
+ [Footnotes]: python-markdown.md#footnotes
+ [Highlight]: python-markdown-extensions.md#highlight
+ [Keys]: python-markdown-extensions.md#keys
+ [Markdown in HTML]: python-markdown.md#markdown-in-html
+ [SmartSymbols]: python-markdown-extensions.md#smartsymbols
+ [Snippets]: python-markdown-extensions.md#snippets
+ [SuperFences]: python-markdown-extensions.md#superfences
+ [Tabbed]: python-markdown-extensions.md#tabbed
+ [Table of Contents]: python-markdown.md#table-of-contents
+ [Tables]: python-markdown.md#tables
+ [Tasklist]: python-markdown-extensions.md#tasklist
+
+## Configuration
+
+Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
+file. The following sections contain two example configurations to bootstrap
+your documentation project.
+
+ [overview]: #advanced-configuration
+
+### Minimal configuration
+
+This configuration is a good starting point for when you're using Material for
+MkDocs for the first time. The best idea is to explore the [reference], and
+gradually add what you want to use:
+
+``` yaml
+markdown_extensions:
+
+ # Python Markdown
+ - toc:
+ permalink: true
+
+ # Python Markdown Extensions
+ - pymdownx.highlight
+ - pymdownx.superfences
+```
+
+ [reference]: ../../reference/index.md
+
+### Recommended configuration
+
+This configuration enables all Markdown-related features of Material for MkDocs
+and is great for experienced users bootstrapping a new documentation project:
+
+``` yaml
+markdown_extensions:
+
+ # Python Markdown
+ - abbr
+ - admonition
+ - attr_list
+ - def_list
+ - footnotes
+ - md_in_html
+ - toc:
+ permalink: true
+
+ # Python Markdown Extensions
+ - pymdownx.arithmatex:
+ generic: true
+ - pymdownx.betterem:
+ smart_enable: all
+ - pymdownx.caret
+ - pymdownx.details
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ - pymdownx.highlight
+ - pymdownx.inlinehilite
+ - pymdownx.keys
+ - pymdownx.mark
+ - pymdownx.smartsymbols
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ - pymdownx.tilde
+```
diff --git a/mkdocs-material/docs/setup/extensions/python-markdown-extensions.md b/mkdocs-material/docs/setup/extensions/python-markdown-extensions.md
new file mode 100644
index 0000000..97aa098
--- /dev/null
+++ b/mkdocs-material/docs/setup/extensions/python-markdown-extensions.md
@@ -0,0 +1,801 @@
+# Python Markdown Extensions
+
+The [Python Markdown Extensions] package is an excellent collection of
+additional extensions perfectly suited for advanced technical writing. Material
+for MkDocs lists this package as an explicit dependency, so it's automatically
+installed with a supported version.
+
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
+## Supported extensions
+
+In general, all extensions that are part of [Python Markdown Extensions] should
+work with Material for MkDocs. The following list includes all extensions that
+are natively supported, meaning they work without any further adjustments.
+
+### Arithmatex
+
+
+
+
+The [Arithmatex] extension allows for rendering of block and inline block
+equations and integrates seamlessly with [MathJax][^1] – a library for
+mathematical typesetting. Enable it via `mkdocs.yml`:
+
+ [^1]:
+ Other libraries like [KaTeX] are also supported and can be integrated with
+ some additional effort. See the [Arithmatex documentation on KaTeX] for
+ further guidance, as this is beyond the scope of Material for MkDocs.
+
+``` yaml
+markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+```
+
+Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
+the JavaScript runtime need to be included, which can be done with a few lines
+of [additional JavaScript]:
+
+=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
+
+ ``` js
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => { // (1)!
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
+ MathJax.typesetPromise()
+ })
+ ```
+
+ 1. This integrates MathJax with [instant loading]
+
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/mathjax.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using block syntax]
+- [Using inline block syntax]
+
+ [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+ [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
+ [MathJax]: https://www.mathjax.org/
+ [KaTeX]: https://github.com/Khan/KaTeX
+ [additional JavaScript]: ../../customization.md#additional-javascript
+ [instant loading]: ../setting-up-navigation.md#instant-loading
+ [Using block syntax]: ../../reference/math.md#using-block-syntax
+ [Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
+
+### BetterEm
+
+
+
+
+The [BetterEm] extension improves the detection of Markup to emphasize text
+in Markdown using special characters, i.e. for `**bold**` and `_italic_`
+formatting. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.betterem
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
+documentation][BetterEm] for more information.
+
+ [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+
+### Caption
+
+
+
+
+The [Caption] extension adds the ability to add captions to any Markdown block,
+including images, tables, and code blocks. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.blocks.caption
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caption
+documentation][Caption] for more information.
+
+ [Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/
+
+### Caret, Mark & Tilde
+
+
+
+
+The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
+and define sub- and superscript using a simple syntax. Enable them together
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.caret
+ - pymdownx.mark
+ - pymdownx.tilde
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
+and [Tilde documentation][Tilde] for guidance.
+
+See reference for usage:
+
+- [Highlighting text]
+- [Sub- and superscripts]
+
+ [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
+ [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
+ [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
+ [Highlighting text]: ../../reference/formatting.md#highlighting-text
+ [Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
+
+### Critic
+
+
+
+
+The [Critic] extension allows for the usage of [Critic Markup] to highlight
+added, deleted or updated sections in a document, i.e. for tracking changes in
+Markdown syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.critic
+```
+
+The following configuration options are supported:
+
+
+
+: This option defines how the markup
+ should be parsed, i.e. whether to just `view` all suggested changes, or
+ alternatively `accept` or `reject` them:
+
+ === "View changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: view
+ ```
+
+ === "Accept changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: accept
+ ```
+
+ === "Reject changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: reject
+ ```
+
+See reference for usage:
+
+- [Highlighting changes]
+
+ [Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
+ [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
+ [Highlighting changes]: ../../reference/formatting.md#highlighting-changes
+
+### Details
+
+
+
+
+The [Details] extension supercharges the [Admonition] extension, making the
+resulting _call-outs_ collapsible, allowing them to be opened and closed by the
+user. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.details
+```
+
+No configuration options are available. See reference for usage:
+
+- [Collapsible blocks]
+
+ [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+ [Admonition]: python-markdown.md#admonition
+ [Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
+
+### Emoji
+
+
+
+
+The [Emoji] extension automatically inlines bundled and custom icons and emojis
+in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+```
+
+1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
+ support the inlining of icons, the `materialx` namespace must be used, as it
+ extends the functionality of `pymdownx`.
+
+The following configuration options are supported:
+
+
+
+: This option defines which set
+ of emojis is used for rendering. Note that the use of `emojione` is not
+ recommended due to [restrictions in licensing][Emoji index]:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ ```
+
+
+
+: This option defines how the
+ resolved emoji or icon shortcode is render. Note that icons can only be
+ used together with the `to_svg` configuration:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ ```
+
+
+
+: This option allows to list folders
+ with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
+ explained in more detail in the [icon customization guide]:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ options:
+ custom_icons:
+ - overrides/.icons
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using emojis]
+- [Using icons]
+- [Using icons in templates]
+
+ [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
+ [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
+ [icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
+ [Using emojis]: ../../reference/icons-emojis.md#using-emojis
+ [Using icons]: ../../reference/icons-emojis.md#using-icons
+ [Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
+
+### Highlight
+
+
+
+
+The [Highlight] extension adds support for syntax highlighting of code blocks
+(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
+(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.superfences # (1)!
+```
+
+1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
+ perform syntax highlighting on code blocks, not the other way round, which
+ is why this extension also needs to be enabled.
+
+The following configuration options are supported:
+
+
+
+: This option allows to control
+ whether highlighting should be carried out during build time using
+ [Pygments] or in the browser with a JavaScript syntax highlighter:
+
+ === "Pygments"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ use_pygments: true
+ - pymdownx.superfences
+ ```
+
+ === "JavaScript"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ use_pygments: false
+ ```
+
+ As an example, [Highlight.js], a JavaScript syntax highlighter, can be
+ integrated with some [additional JavaScript] and an [additional style
+ sheet] in `mkdocs.yml`:
+
+ === ":octicons-file-code-16: `docs/javascripts/highlight.js`"
+
+ ``` js
+ document$.subscribe(() => {
+ hljs.highlightAll()
+ })
+ ```
+
+ === ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
+ - javascripts/highlight.js
+ extra_css:
+ - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
+ ```
+
+ Note that [Highlight.js] has no affiliation with the
+ [Highlight][pymdownx.highlight] extension.
+
+ All following configuration options are only compatible with build-time
+ syntax highlighting using [Pygments], so they don't apply if `use_pygments`
+ is set to `false`.
+
+
+
+: This option instructs [Pygments]
+ to add a CSS class to identify the language of the code block, which is
+ essential for custom annotation markers to function:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ pygments_lang_class: true
+```
+
+
+
+: This option will automatically
+ add a [title] to all code blocks that shows the name of the language being
+ used, e.g. `Python` is printed for a `py` block:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ auto_title: true
+ ```
+
+
+
+: This option will add line numbers
+ to _all_ code blocks. If you wish to add line numbers to _some_, but not all
+ code blocks, consult the section on [adding line numbers][Adding line
+ numbers] in the code block reference, which also contains some tips on
+ working with line numbers:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ linenums: true
+ ```
+
+
+
+: The [Highlight] extension
+ provides three ways to add line numbers, two of which are supported by
+ Material for MkDocs. While `table` wraps a code block in a `
`
+ element, `pymdownx-inline` renders line numbers as part of the line itself:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ linenums_style: pymdownx-inline
+ ```
+
+ Note that `inline` will put line numbers next to the actual code, which
+ means that they will be included when selecting text with the cursor or
+ copying a code block to the clipboard. Thus, the usage of either `table`
+ or `pymdownx-inline` is recommended.
+
+
+
+: :octicons-milestone-24:
+ Default: `false` – If a code blocks contains line numbers, enabling this
+ setting will wrap them with anchor links, so they can be hyperlinked and
+ shared more easily:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ ```
+
+
+
+: When this option is set, each
+ line of a code block is wrapped in a `span`, which is essential for features
+ like line highlighting to work correctly:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ line_spans: __span
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using code blocks]
+- [Adding a title]
+- [Adding line numbers]
+- [Highlighting specific lines]
+- [Custom syntax theme]
+
+ [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+ [CodeHilite]: python-markdown.md#codehilite
+ [pymdownx.superfences]: #superfences
+ [pymdownx.inlinehilite]: #inlinehilite
+ [Pygments]: https://pygments.org
+ [additional style sheet]: ../../customization.md#additional-css
+ [Highlight.js]: https://highlightjs.org/
+ [title]: ../../reference/code-blocks.md#adding-a-title
+ [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
+ [Using code blocks]: ../../reference/code-blocks.md#usage
+ [Adding a title]: ../../reference/code-blocks.md#adding-a-title
+ [Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
+ [Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
+
+### InlineHilite
+
+
+
+
+The [InlineHilite] extension add support for syntax highlighting of inline code
+blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
+which it sources its configuration. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight
+ - pymdownx.inlinehilite
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`css_class`][InlineHilite options] option, which must not be changed. See the
+[InlineHilite documentation][InlineHilite] for guidance.
+
+See reference for usage:
+
+- [Highlighting inline code blocks]
+
+ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
+ [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
+ [pymdownx.highlight]: #highlight
+ [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
+
+### Keys
+
+
+
+
+The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
+keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.keys
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`class`][Keys options] option, which must not be changed. See the
+[Keys documentation][Keys] for more information.
+
+See reference for usage:
+
+- [Adding keyboard keys]
+
+ [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+ [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
+ [Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
+
+### SmartSymbols
+
+
+
+
+The [SmartSymbols] extension converts some sequences of characters into their
+corresponding symbols, e.g. copyright symbols or fractions. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.smartsymbols
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
+documentation][SmartSymbols] for guidance.
+
+ [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+
+### Snippets
+
+
+
+
+The [Snippets] extension adds the ability to embed content from arbitrary files
+into a document, including other documents or source files, by using a simple
+syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.snippets
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
+documentation][Snippets] for more information.
+
+See reference for usage:
+
+- [Adding a glossary]
+- [Embedding external files]
+
+ [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+ [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
+ [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
+
+### SuperFences
+
+
+
+
+The [SuperFences] extension allows for arbitrary nesting of code and content
+blocks inside each other, including admonitions, tabs, lists and all other
+elements. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences
+```
+
+The following configuration options are supported:
+
+
+
+: This option allows to define a
+ handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
+ diagrams to be interpreted in the browser:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ ```
+
+ Note that this will primarily prevent syntax highlighting from being
+ applied. See the reference on [diagrams] to learn how Mermaid.js is
+ integrated with Material for MkDocs.
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using annotations]
+- [Using code blocks]
+- [Using content tabs]
+- [Using flowcharts]
+- [Using sequence diagrams]
+- [Using state diagrams]
+- [Using class diagrams]
+- [Using entity-relationship diagrams]
+
+ [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+ [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
+ [Mermaid.js]: https://mermaid-js.github.io/mermaid/
+ [diagrams]: ../../reference/diagrams.md
+ [Using annotations]: ../../reference/annotations.md#usage
+ [Using content tabs]: ../../reference/content-tabs.md#usage
+ [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
+ [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
+ [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
+ [Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
+ [Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
+
+### Tabbed
+
+
+
+
+The [Tabbed] extension allows the usage of content tabs, a simple way to group
+related content and code blocks under accessible tabs. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.tabbed:
+ alternate_style: true
+```
+
+The following configuration options are supported:
+
+
+
+:
+ This option enables the content tabs
+ [alternate style], which has [better behavior on mobile viewports], and is
+ the only supported style:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ alternate_style: true
+ ```
+
+
+
+: This option enables the content tabs'
+ [`combine_header_slug` style] flag, which prepends the id of the header to
+ the id of the tab:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ combine_header_slug: true
+ ```
+
+
+
+: This option allows for
+ customization of the slug function. For some languages, the default may not
+ produce good and readable identifiers – consider using another slug function
+ like for example those from [Python Markdown Extensions][Slugs]:
+
+ === "Unicode"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify {}
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Grouping code blocks]
+- [Grouping other content]
+- [Embedded content]
+
+ [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+ [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
+ [combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
+ [better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214
+ [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
+ [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
+ [Embedded content]: ../../reference/content-tabs.md#embedded-content
+ [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+### Tasklist
+
+
+
+
+The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
+inspired [task lists][Tasklist specification], following the same syntactical
+conventions. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.tasklist:
+ custom_checkbox: true
+```
+
+The following configuration options are supported:
+
+
+
+: This option toggles the rendering
+ style of checkboxes, replacing native checkbox styles with beautiful icons,
+ and is therefore recommended:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ ```
+
+
+
+: This option toggles whether
+ checkboxes are clickable. As the state is not persisted, the use of this
+ option is _rather discouraged_ from a user experience perspective:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tasklist:
+ clickable_checkbox: true
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using task lists]
+
+ [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
+ [GitHub Flavored Markdown]: https://github.github.com/gfm/
+ [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
+ [Using task lists]: ../../reference/lists.md#using-task-lists
diff --git a/mkdocs-material/docs/setup/extensions/python-markdown.md b/mkdocs-material/docs/setup/extensions/python-markdown.md
new file mode 100644
index 0000000..a724e2f
--- /dev/null
+++ b/mkdocs-material/docs/setup/extensions/python-markdown.md
@@ -0,0 +1,347 @@
+# Python Markdown
+
+Material for MkDocs supports a large number of [Python Markdown] extensions,
+which is part of what makes it so attractive for technical writing. Following
+is a list of all supported extensions, linking to the relevant sections of the
+reference for which features they need to be enabled.
+
+ [Python Markdown]: https://python-markdown.github.io/
+
+## Supported extensions
+
+### Abbreviations
+
+
+
+
+The [Abbreviations] extension adds the ability to add a small tooltip to an
+element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
+supported. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - abbr
+```
+
+No configuration options are available. See reference for usage:
+
+- [Adding abbreviations]
+- [Adding a glossary]
+
+ [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
+ [Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
+ [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
+
+### Admonition
+
+
+
+
+The [Admonition] extension adds support for admonitions, more commonly known as
+_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
+it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - admonition
+```
+
+No configuration options are available. See reference for usage:
+
+- [Adding admonitions]
+- [Changing the title]
+- [Removing the title]
+- [Supported types]
+
+ [Admonition]: https://python-markdown.github.io/extensions/admonition/
+ [Adding admonitions]: ../../reference/admonitions.md#usage
+ [Changing the title]: ../../reference/admonitions.md#changing-the-title
+ [Removing the title]: ../../reference/admonitions.md#removing-the-title
+ [Supported types]: ../../reference/admonitions.md#supported-types
+
+### Attribute Lists
+
+
+
+
+The [Attribute Lists] extension allows to add HTML attributes and CSS classes
+to [almost every][Attribute Lists limitations] Markdown inline- and block-level
+element with a special syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using annotations]
+- [Using grids]
+- [Adding buttons]
+- [Adding tooltips]
+- [Using icons with colors]
+- [Using icons with animations]
+- [Image alignment]
+- [Image lazy-loading]
+
+ [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
+ [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+ [Using grids]: ../../reference/grids.md#using-grids
+ [Adding buttons]: ../../reference/buttons.md#adding-buttons
+ [Adding tooltips]: ../../reference/tooltips.md#adding-tooltips
+ [Using icons with colors]: ../../reference/icons-emojis.md#with-colors
+ [Using icons with animations]: ../../reference/icons-emojis.md#with-animations
+ [Image alignment]: ../../reference/images.md#image-alignment
+ [Image lazy-loading]: ../../reference/images.md#image-lazy-loading
+
+### Definition Lists
+
+
+
+
+The [Definition Lists] extension adds the ability to add definition lists (more
+commonly known as [description lists] – `dl` in HTML) via Markdown to a
+document. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - def_list
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using definition lists]
+
+ [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
+ [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
+ [Using definition lists]: ../../reference/lists.md#using-definition-lists
+
+### Footnotes
+
+
+
+
+The [Footnotes] extension allows to define inline footnotes, which are then
+rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - footnotes
+```
+
+No configuration options are supported. See reference for usage:
+
+- [Adding footnote references]
+- [Adding footnote content]
+
+ [Footnotes]: https://python-markdown.github.io/extensions/footnotes/
+ [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
+ [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
+
+### Markdown in HTML
+
+
+
+
+The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
+which is useful for wrapping Markdown content with custom elements. Enable it
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - md_in_html
+```
+
+> By default, Markdown ignores any content within a raw HTML block-level
+> element. With the `md_in_html` extension enabled, the content of a raw HTML
+> block-level element can be parsed as Markdown by including a `markdown`
+> attribute on the opening tag. The `markdown` attribute will be stripped from
+> the output, while all other attributes will be preserved.
+
+No configuration options are available. See reference for usage:
+
+- [Using annotations]
+- [Using grids]
+- [Image captions]
+
+ [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
+ [Using annotations]: ../../reference/annotations.md#usage
+ [Using grids]: ../../reference/grids.md#usage
+ [Image captions]: ../../reference/images.md#image-captions
+
+### Table of Contents
+
+
+
+
+The [Table of Contents] extension automatically generates a table of contents
+from a document, which Material for MkDocs will render as part of the resulting
+page. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - toc:
+ permalink: true
+```
+
+The following configuration options are supported:
+
+
+
+: –
+ This option sets the title of the table of contents in the right navigation
+ sidebar, which is normally automatically sourced from the translations for
+ the [site language] as set in `mkdocs.yml`:
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ title: On this page
+ ```
+
+
+
+: This option adds an anchor link
+ containing the paragraph symbol `¶` or another custom symbol at the end of
+ each headline, exactly like on the page you're currently viewing, which
+ Material for MkDocs will make appear on hover:
+
+ === "¶"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink: true
+ ```
+
+ === "⚓︎"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink: ⚓︎
+ ```
+
+
+
+: This option sets the
+ title of the anchor link which is shown on hover and read by screen readers.
+ For accessibility reasons, it might be beneficial to change it to a more
+ discernable name, stating that the anchor links to the section itself:
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink_title: Anchor link to this section for reference
+ ```
+
+
+
+: This option allows for
+ customization of the slug function. For some languages, the default may not
+ produce good and readable identifiers – consider using another slug function
+ like for example those from [Python Markdown Extensions][Slugs]:
+
+ === "Unicode"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify {}
+ ```
+
+
+
+: Define the range of levels to be
+ included in the table of contents. This may be useful for project
+ documentation with deeply structured headings to decrease the length of the
+ table of contents, or to remove the table of contents altogether:
+
+ === "Hide levels 4-6"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ toc_depth: 3
+ ```
+
+ === "Hide table of contents"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ toc_depth: 0
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [Table of Contents]: https://python-markdown.github.io/extensions/toc/
+ [site language]: ../changing-the-language.md#site-language
+ [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+### Tables
+
+
+
+
+The [Tables] extension adds the ability to create tables in Markdown by using a
+simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
+default):
+
+``` yaml
+markdown_extensions:
+ - tables
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using data tables]
+- [Column alignment]
+
+ [Tables]: https://python-markdown.github.io/extensions/tables/
+ [Using data tables]: ../../reference/data-tables.md#usage
+ [Column alignment]: ../../reference/data-tables.md#column-alignment
+
+## Superseded extensions
+
+The following [Python Markdown] extensions are not (or might not be) supported
+anymore, and are therefore not recommended for use. Instead, the alternatives
+should be considered.
+
+### Fenced Code Blocks
+
+
+
+
+Superseded by [SuperFences]. This extension might still work, but the
+[SuperFences] extension is superior in many ways, as it allows for arbitrary
+nesting, and is therefore recommended.
+
+ [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
+ [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
+### CodeHilite
+
+
+
+
+Superseded by [Highlight]. Support for CodeHilite was dropped in
+, as [Highlight] has a better integration with other
+essential extensions like [SuperFences] and [InlineHilite].
+
+ [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
+ [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+ [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
diff --git a/mkdocs-material/docs/setup/index.md b/mkdocs-material/docs/setup/index.md
new file mode 100644
index 0000000..c470698
--- /dev/null
+++ b/mkdocs-material/docs/setup/index.md
@@ -0,0 +1,90 @@
+# Setup
+
+Material for MkDocs offers a wide range of options for customizing your
+documentation. In this section, we will explain how you can create a meaningful
+structure for your site, change the look and feel, add a blog and comment system,
+and build a highly optimized site.
+
+## Site structure
+
+Set up and customize the structure of your documentation by configuring the
+header and footer to your taste, choosing among many modes of navigation,
+setting up site search, and more.
+
+
+
+- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
+- :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
+- :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
+- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
+- :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
+- :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages
+
+
+
+ [Language]: changing-the-language.md
+ [Navigation]: setting-up-navigation.md
+ [Header]: setting-up-the-header.md
+ [Footer]: setting-up-the-footer.md
+ [Search]: setting-up-site-search.md
+ [Tags]: setting-up-tags.md
+
+
+## Appearance
+
+Match your brand's colors, fonts, icons, logo, and more with a few lines of
+configuration – Material for MkDocs makes it easy to extend the basic
+configuration or alter the appearance.
+
+
+
+- :material-brush-variant: __[Colors]__ – Change colors with an existing color palette or customize with CSS
+- :material-format-font: __[Fonts]__ – Choose among 1,000 Google Fonts or load self-hosted fonts
+- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the 8,000+ icons, or add new ones
+- :material-cards-variant: __[Social Cards]__ – Automatically create social media previews when sharing links
+
+
+
+ [Colors]: changing-the-colors.md
+ [Fonts]: changing-the-fonts.md
+ [Logo & Icons]: changing-the-logo-and-icons.md
+ [Social Cards]: setting-up-social-cards.md
+
+## Content
+
+Create a blog, integrate a comment system, connect a git repository, and set up
+versioned documentation that matches your project's versioning methodology.
+
+
+
+- :material-book-open-outline: __[Blog]__ – Set up a standalone blog or host it alongside your documentation
+- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer
+- :octicons-versions-16: __[Versioning]__ – Deploy multiple versions by integrating with external utilities
+- :octicons-repo-16: __[Repository]__ – Connect your documentation to your git repository
+
+
+
+ [Blog]: setting-up-a-blog.md
+ [Comment System]: adding-a-comment-system.md
+ [Versioning]: setting-up-versioning.md
+ [Repository]: adding-a-git-repository.md
+
+## Optimization
+
+Add site analytics and build an optimized site by adding automatic image
+compression, complying with GDPR data privacy regulations, and making it
+offline-capable.
+
+
+
+- :material-google-analytics: __[Site analytics]__ – Learn how your users experience your documentation
+- :material-screwdriver: __[Optimized site]__ – Create optimized sites that rank great on search engines
+- :octicons-lock-16: __[Data Privacy]__ – Ensure compliance with data privacy regulations
+- :octicons-cloud-offline-16: __[Offline usage]__ – Build an online and offline-capable documentation
+
+
+
+ [Site analytics]: setting-up-site-analytics.md
+ [Optimized site]: building-an-optimized-site.md
+ [Data Privacy]: ensuring-data-privacy.md
+ [Offline usage]: building-for-offline-usage.md
diff --git a/mkdocs-material/docs/setup/setting-up-a-blog.md b/mkdocs-material/docs/setup/setting-up-a-blog.md
new file mode 100644
index 0000000..35dd9d6
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-a-blog.md
@@ -0,0 +1,707 @@
+# Setting up a blog
+
+Material for MkDocs makes it very easy to build a blog, either as a sidecar to
+your documentation or standalone. Focus on your content while the engine does
+all the heavy lifting, automatically generating [archive] and [category]
+indexes, [post slugs], configurable [pagination] and more.
+
+---
+
+__Check out our [blog], which is created with the new [built-in blog plugin]!__
+
+ [archive]: ../plugins/blog.md#archive
+ [category]: ../plugins/blog.md#categories
+ [post slugs]: ../plugins/blog.md#config.post_url_format
+ [pagination]: ../plugins/blog.md#pagination
+ [blog]: ../blog/index.md
+
+## Configuration
+
+### Built-in blog plugin
+
+
+
+
+
+The built-in blog plugin adds support for building a blog from a folder of
+posts, which are annotated with dates and other structured data. First, add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog
+```
+
+If you do not have a navigation (`nav`) definition in your `mkdocs.yml` then
+there is nothing else to do there as the blog plugin will add navigation
+automatically. If you do have a navigation defined then you need to add *the
+blog index page only* to it. You need not and should not add the individual
+blog posts. For example:
+
+```yaml
+nav:
+ - index.md
+ - Blog:
+ - blog/index.md
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/blog.md
+
+#### Advanced settings
+
+
+
+
+The following advanced settings are currently reserved to our [sponsors]
+[Insiders]. They are entirely optional, and don't affect the functionality of
+the blog, but can be helpful for customizations:
+
+- [`archive_pagination`][config.archive_pagination]
+- [`archive_pagination_per_page`][config.archive_pagination_per_page]
+- [`categories_sort_by`][config.categories_sort_by]
+- [`categories_sort_reverse`][config.categories_sort_reverse]
+- [`categories_pagination`][config.categories_pagination]
+- [`categories_pagination_per_page`][config.categories_pagination_per_page]
+- [`authors_profiles_pagination`][config.authors_profiles_pagination]
+- [`authors_profiles_pagination_per_page`][config.authors_profiles_pagination_per_page]
+
+We'll add more settings here, as we discover new use cases.
+
+ [Insiders]: ../insiders/index.md
+ [built-in blog plugin]: ../plugins/blog.md
+ [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
+ [start writing your first post]: #writing-your-first-post
+
+ [config.archive_pagination]: ../plugins/blog.md#config.archive_pagination
+ [config.archive_pagination_per_page]: ../plugins/blog.md#config.archive_pagination_per_page
+ [config.categories_sort_by]: ../plugins/blog.md#config.categories_sort_by
+ [config.categories_sort_reverse]: ../plugins/blog.md#config.categories_sort_reverse
+ [config.categories_pagination]: ../plugins/blog.md#config.categories_pagination
+ [config.categories_pagination_per_page]: ../plugins/blog.md#config.categories_pagination_per_page
+ [config.authors_profiles_pagination]: ../plugins/blog.md#config.authors_profiles_pagination
+ [config.authors_profiles_pagination_per_page]: ../plugins/blog.md#config.authors_profiles_pagination_per_page
+
+### RSS
+
+
+
+
+The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
+which provides a simple way to add an RSS feed to your blog (or to your whole
+documentation). Install it with `pip`:
+
+```
+pip install mkdocs-rss-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - rss:
+ match_path: blog/posts/.* # (1)!
+ date_from_meta:
+ as_creation: date
+ categories:
+ - categories
+ - tags # (2)!
+```
+
+1. The RSS plugin allows to filter for URLs to be included in the feed. In
+ this example, only blog posts will be part of the feed.
+
+2. If you want to include a post's categories as well as its tags in the feed,
+ add both `categories` and `tags` here.
+
+The following configuration options are supported:
+
+
+
+: This option specifies whether
+ the plugin is enabled when building your project. If you want to speed up
+ local builds, you can use an [environment variable][mkdocs.env]:
+
+ ``` yaml
+ plugins:
+ - rss:
+ enabled: !ENV [CI, false]
+ ```
+
+
+
+: This option specifies which
+ pages should be included in the feed. For example, to only include blog
+ posts in the feed, use the following regular expression:
+
+ ``` yaml
+ plugins:
+ - rss:
+ match_path: blog/posts/.*
+ ```
+
+
+
+: This option specifies which
+ front matter property should be used as a creation date of a page in the
+ feed. It's recommended to use the `date` property:
+
+ ``` yaml
+ plugins:
+ - rss:
+ date_from_meta:
+ as_creation: date
+ ```
+
+
+
+: This option specifies which
+ front matter properties are used as categories as part of the feed. If you
+ use [categories] and [tags], add both with the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ categories:
+ - categories
+ - tags
+ ```
+
+
+
+: This option specifies the anchor
+ at which comments for a post or page can be found. If you've integrated a
+ [comment system], add the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ comments_path: "#__comments"
+ ```
+
+Material for MkDocs will automatically add the [necessary metadata] to your site
+which will make the RSS feed discoverable by browsers and feed readers.
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use them
+at your own risk.
+
+ [rss]: https://guts.github.io/mkdocs-rss-plugin/
+ [categories]: ../plugins/blog.md#categories
+ [tags]: setting-up-tags.md#built-in-tags-plugin
+ [comment system]: adding-a-comment-system.md
+ [necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
+ [theme extension]: ../customization.md
+
+### Blog only
+
+You might need to build a pure blog without any documentation.
+In this case, you can create a folder tree like this:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ ├─ posts/ # (1)!
+│ ├─ .authors.yml
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. Notice that the `posts` directory is in the root of `docs` without
+ intermediate `blog` directory.
+
+And add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ blog_dir: . # (1)!
+```
+
+1. Please see the [plugin documentation] for more information about the
+ [`blog_dir`][blog_dir] setting.
+
+With this configuration, the url of the blog post will be `/`
+instead of `/blog/`.
+
+## Usage
+
+### Writing your first post
+
+After you've successfully set up the [built-in blog plugin], it's time to write
+your first post. The plugin doesn't assume any specific directory structure, so
+you're completely free in how you organize your posts, as long as they are all
+located inside the `posts` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ │ └─ hello-world.md # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. If you'd like to arrange posts differently, you're free to do so. The URLs
+ are built from the format specified in [`post_url_format`][post slugs] and
+ the titles and dates of posts, no matter how they are organized
+ inside the `posts` directory.
+
+Create a new file called `hello-world.md` and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2024-01-31 # (2)!
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+1. If you mark a post as a [draft], a red marker appears next to the post date
+ on index pages. When the site is built, drafts are not included in the
+ output. [This behavior can be changed], e.g. for rendering drafts when
+ building deploy previews.
+
+2. If you wish to provide multiple dates, you can use the following syntax,
+ allowing you to define a date when you last updated the blog post +
+ further custom dates you can add to the template:
+
+ ``` yaml
+ ---
+ date:
+ created: 2022-01-31
+ updated: 2022-02-02
+ ---
+
+ # Hello world!
+ ```
+
+ Note that the creation date __must__ be set under `date.created`, as each
+ blog post must have a creation date set.
+
+When you spin up the [live preview server], you should be greeted by your first
+post! You'll also realize, that [archive] and [category] indexes have been
+automatically generated for you.
+
+ [draft]: ../plugins/blog.md#drafts
+ [This behavior can be changed]: ../plugins/blog.md#config.draft
+ [live preview server]: ../creating-your-site.md#previewing-as-you-write
+
+#### Adding an excerpt
+
+The blog index, as well as [archive] and [category] indexes can either list the
+entire content of each post, or excerpts of posts. An excerpt can be created by
+adding a `` separator after the first few paragraphs of a post:
+
+``` py
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+massa, nec semper lorem quam in massa.
+
+
+...
+```
+
+When the [built-in blog plugin] generates all indexes, the content before the
+[excerpt separator] is automatically extracted, allowing the user to start
+reading a post before deciding to jump in.
+
+ [excerpt separator]: ../plugins/blog.md#config.post_excerpt_separator
+
+#### Adding authors
+
+In order to add a little more personality to your posts, you can associate each
+post with one or multiple [authors]. First, create the
+[`.authors.yml`][authors_file] file in your blog directory, and add an author:
+
+``` yaml
+authors:
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
+```
+
+The [`.authors.yml`][authors_file] file associates each author with an
+identifier (in this example `squidfunk`), which can then be used in posts.
+Different attributes can be configured. For a list of all possible attributes,
+please consult the [`authors_file`][authors_file] documentation.
+
+Now, you can assign one or more authors to a post by referencing their
+identifiers in the front matter of the Markdown file under the `authors`
+property. For each author, a small profile is rendered in the left sidebar of
+each post, as well as in post excerpts on index pages:
+
+``` yaml
+---
+date: 2024-01-31
+authors:
+ - squidfunk
+ ...
+---
+
+# Hello world!
+...
+```
+
+ [authors]: ../plugins/blog.md#authors
+ [authors_file]: ../plugins/blog.md#config.authors_file
+
+#### Adding author profiles
+
+
+
+
+
+If you wish to add a dedicated page for each author, you can enable author
+profiles by setting the [`authors_profiles`][authors_profiles] configuration
+option to `true`. Just add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+If you combine this with [custom index pages], you can create a dedicated page
+for each author with a short description, social media links, etc. – basically
+anything you can write in Markdown. The list of posts is then appended after
+the content of the page.
+
+ [authors_profiles]: ../plugins/blog.md#config.authors_profiles
+ [custom index pages]: #custom-index-pages
+
+#### Adding categories
+
+Categories are an excellent way for grouping your posts thematically on
+dedicated index pages. This way, a user interested in a specific topic can
+explore all of your posts on this topic. Make sure [categories] are enabled and
+add them to the front matter `categories` property:
+
+``` yaml
+---
+date: 2024-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+If you want to save yourself from typos when typing out categories, you can
+define your desired categories in `mkdocs.yml` as part of the
+[`categories_allowed`][categories_allowed] configuration option. The
+[built-in blog plugin] will stop the build if a category is not found within
+the list.
+
+ [categories_allowed]: ../plugins/blog.md#config.categories_allowed
+
+#### Adding tags
+
+Besides [categories], the [built-in blog plugin] also integrates with the
+[built-in tags plugin]. If you add tags in the front matter `tags` property as
+part of a post, the post is linked from the [tags index]:
+
+``` yaml
+---
+date: 2024-01-31
+tags:
+ - Foo
+ - Bar
+---
+
+# Hello world!
+...
+```
+
+As usual, the tags are rendered above the main headline and posts are linked
+on the tags index page, if configured. Note that posts are, as pages, only
+linked with their titles.
+
+ [built-in tags plugin]: ../plugins/tags.md
+ [tags index]: setting-up-tags.md#adding-a-tags-index
+
+#### Changing the slug
+
+Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:
+
+``` yaml
+---
+slug: hello-world
+---
+
+# Hello there world!
+...
+```
+
+#### Adding related links
+
+
+
+
+
+Related links offer the perfect way to prominently add a _further reading_
+section to your post that is included in the left sidebar, guiding the user to
+other destinations of your documentation. Use the front matter `links` property
+to add related links to a post:
+
+``` yaml
+---
+date: 2024-01-31
+links:
+ - plugins/search.md
+ - insiders/how-to-sponsor.md
+---
+
+# Hello world!
+...
+```
+
+You can use the exact same syntax as for the [`nav`][mkdocs.nav] section in
+`mkdocs.yml`, which means you can set explicit titles for links, add external
+links and even use nesting:
+
+``` yaml
+---
+date: 2024-01-31
+links:
+ - plugins/search.md
+ - insiders/how-to-sponsor.md
+ - Nested section:
+ - External link: https://example.com
+ - setup/setting-up-site-search.md
+---
+
+# Hello world!
+...
+```
+
+If you look closely, you'll realize that you can even use an anchor to link to
+a specific section of a document, extending the possibilities of the
+[`nav`][mkdocs.nav] syntax in `mkdocs.yml`. The [built-in blog plugin] resolves
+the anchor and sets the title of the anchor as a [subtitle] of the related link.
+
+Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is
+also the case for the [`nav`][mkdocs.nav] setting.
+
+ [subtitle]: ../reference/index.md#setting-the-page-subtitle
+
+#### Linking from and to posts
+
+While [post URLs][post slugs] are dynamically computed, the [built-in blog
+plugin] ensures that all links from and to posts and a post's assets are
+correct. If you want to link to a post, just use the path to the Markdown file
+as a link reference (links must be relative):
+
+``` markdown
+[Hello World!](blog/posts/hello-world.md)
+```
+
+Linking from a post to a page, e.g. the index, follows the same method:
+
+``` markdown
+[Blog](../index.md)
+```
+
+All assets inside the `posts` directory are copied to the `blog/assets` folder
+when the site is being built. Of course, you can also reference assets from
+posts outside of the `posts` directory. The [built-in blog plugin] ensures that
+all links are correct.
+
+#### Pinning a post :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" }
+
+
+
+
+
+If you want to pin a post to the top of the index page, as well as the archive
+and category indexes it is part of, you can use the front matter `pin` property:
+
+``` yaml
+---
+date: 2024-01-31
+pin: true
+---
+
+# Hello world!
+...
+```
+
+If multiple posts are pinned, they are sorted by their creation date, with the
+most recent pinned post being shown first, followed by the other pinned posts in
+descending order.
+
+#### Setting the reading time
+
+When [enabled], the [readtime] package is used to compute the expected reading
+time of each post, which is rendered as part of the post and post excerpt.
+Nowadays, many blogs show reading times, which is why the [built-in blog plugin]
+offers this capability as well.
+
+Sometimes, however, the computed reading time might not feel accurate, or
+result in odd and unpleasant numbers. For this reason, reading time can be
+overridden and explicitly set with the front matter `readtime` property for a
+post:
+
+``` yaml
+---
+date: 2024-01-31
+readtime: 15
+---
+
+# Hello world!
+...
+```
+
+This will disable automatic reading time computation.
+
+ [readtime]: https://pypi.org/project/readtime/
+ [enabled]: ../plugins/blog.md#config.post_readtime
+
+#### Setting defaults
+
+
+
+
+
+
+If you have a lot of posts, it might feel redundant to define all of the above
+for each post. Luckily, the [built-in meta plugin] allows to set default front
+matter properties per folder. You can group your posts by categories, or
+authors, and add a `.meta.yml` file to set common properties:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ ├─ .meta.yml # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. As already noted, you can also place a `.meta.yml` file in nested folders
+ of the `posts` directory. This file then can define all front matter
+ properties that are valid in posts, e.g.:
+
+ ``` yaml
+ authors:
+ - squidfunk
+ categories:
+ - Hello
+ - World
+ ```
+
+Note that order matters – the [built-in meta plugin] must be defined before the
+blog plugin in `mkdocs.yml`, so that all set defaults are correctly picked up
+by the [built-in blog plugin]:
+
+``` yaml
+plugins:
+ - meta
+ - blog
+```
+
+Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
+values defined for a post, which means you can define common properties in
+`.meta.yml` and then add specific properties or overrides for each post.
+
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Adding pages
+
+Besides posts, it's also possible to add static pages to your blog by listing
+the pages in the [`nav`][mkdocs.nav] section of `mkdocs.yml`. All generated
+indexes are included after the last specified page. For example, to add a page
+on the authors of the blog, add the following to `mkdocs.yml`:
+
+``` yaml
+nav:
+ - Blog:
+ - blog/index.md
+ - blog/authors.md
+ ...
+```
+
+## Customization
+
+### Custom index pages
+
+
+
+
+
+If you want to add custom content to automatically generated [archive] and
+[category] indexes, e.g. to add a category description prior to the list of
+posts, you can manually create the category page in the same location where
+the [built-in blog plugin] would create it:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ category/
+│ │ └─ hello.md # (1)!
+│ ├─ posts/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. The easiest way is to first [add the category] to the blog post, then take
+ the URL generated by the [built-in blog plugin] and create the file at the
+ corresponding location in the [`blog_dir`][blog_dir] folder.
+
+ Note that the shown directory listing is based on the default configuration.
+ If you specify different values for the following options, be sure to adjust
+ the path accordingly:
+
+ - [`blog_dir`][blog_dir]
+ - [`categories_url_format`][categories_url_format]
+ - [`categories_slugify`][categories_slugify]
+
+You can now add arbitrary content to the newly created file, or set specific
+front matter properties for this page, e.g. to change the [page description]:
+
+``` yaml
+---
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+---
+
+# Hello
+...
+```
+
+All post excerpts belonging to the category are automatically appended.
+
+ [add the category]: #adding-categories
+ [page description]: ../reference/index.md#setting-the-page-description
+ [categories_url_format]: ../plugins/blog.md#config.categories_url_format
+ [categories_slugify]: ../plugins/blog.md#config.categories_slugify
+ [blog_dir]: ../plugins/blog.md#config.blog_dir
+
+### Overriding templates
+
+The [built-in blog plugin] is built on the same basis as Material for MkDocs,
+which means you can override all templates used for the blog by using
+[theme extension] as usual.
+
+The following templates are added by the [built-in blog plugin]:
+
+- [`blog.html`][blog.html] – Template for blog, archive and category index
+- [`blog-post.html`][blog-post.html] – Template for blog post
+
+ [theme extension]: ../customization.md#extending-the-theme
+
+ [blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog.html
+ [blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog-post.html
diff --git a/mkdocs-material/docs/setup/setting-up-navigation.md b/mkdocs-material/docs/setup/setting-up-navigation.md
new file mode 100644
index 0000000..3aa3b76
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-navigation.md
@@ -0,0 +1,648 @@
+# Setting up navigation
+
+A clear and concise navigation structure is an important aspect of good project
+documentation. Material for MkDocs provides a multitude of options to configure
+the behavior of navigational elements, including [tabs] and [sections], and one
+of its flagship features: [instant loading].
+
+ [tabs]: #navigation-tabs
+ [sections]: #navigation-sections
+ [instant loading]: #instant-loading
+
+Additional navigation can be configured [in the footer] as well as with the
+[tags plugin]. The [blog plugin] also sets up additional navigation.
+
+[in the footer]: setting-up-the-footer.md#navigation
+[tags plugin]: ../plugins/tags.md
+[blog plugin]: ../plugins/blog.md
+
+## Configuration
+
+### Instant loading
+
+
+
+
+When instant loading is enabled, clicks on all internal links will be
+intercepted and dispatched via [XHR] without fully reloading the page. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+```
+
+The resulting page is parsed and injected and all event handlers and components
+are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
+Page Application__. Now, the search index survives navigation, which is
+especially useful for large documentation sites.
+
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ navigation, as instant navigation relies on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+ [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
+
+#### Instant prefetching
+
+
+
+
+
+
+Instant prefetching is a new experimental feature that will start to fetch a
+page once the user hovers over a link. This will reduce the perceived loading
+time for the user, especially on slow connections, as the page will be available
+immediately upon navigation. Enable it with:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+ - navigation.instant.prefetch
+```
+
+#### Progress indicator
+
+
+
+
+
+In order to provide a better user experience on slow connections when using
+instant navigation, a progress indicator can be enabled. It will be shown at
+the top of the page and will be hidden once the page has fully loaded. You can
+enable it in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+ - navigation.instant.progress
+```
+
+The progress indicator will only show if the page hasn't finished loading after
+400ms, so that fast connections will never show it for a better instant
+experience.
+
+### Instant previews :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" }
+
+
+
+
+
+
+Instant previews are a brand new feature that allow the user to preview another
+site of your documentation without navigating to it. They can be very helpful to
+keep the user in context. Instant previews can be enabled on any header link
+with the `data-preview` attribute:
+
+```` markdown title="Link with instant preview"
+``` markdown
+[Attribute Lists](#){ data-preview }
+```
+````
+
+
+
+!!! info "Limitations"
+
+ Instant previews are still an experimental feature and currently limited to
+ headerlinks. This means, you can use them on any internal link that points
+ to a header on another page, but not other elements with `id` attributes.
+ After we have gathered enough feedback, we will consider extending this
+ feature to other, and possibly arbitrary elements.
+
+#### Automatic previews
+
+
+
+
+
+
+The recommended way to work with instant previews is to use the Markdown
+extension that is included with Material for MkDocs, as it allows you to enable
+instant previews on a per-page or per-section level for your documentation:
+
+``` yaml
+markdown_extensions:
+ - material.extensions.preview:
+ targets:
+ include:
+ - changelog/index.md
+ - customization.md
+ - insiders/changelog/*
+ - setup/extensions/*
+```
+
+The above configuration is what we use for our documentation. We've enabled
+instant previews for our changelogs, customization guide, and Insiders sections,
+as well as for all Markdown extensions that we support.
+
+!!! info "Full configuration example"
+
+ ``` yaml
+ markdown_extensions:
+ - material.extensions.preview:
+ sources: # (1)!
+ include:
+ - ...
+ exclude:
+ - ...
+ targets: # (2)!
+ include:
+ - ...
+ exclude:
+ - ...
+ ```
+
+ 1. Sources specify the pages _on_ which instant previews should be enabled.
+ If this setting is omitted, instant previews will be enabled on all
+ pages. You can use patterns to include or exclude pages. Exclusion is
+ evaluated on top of inclusion, so if a page is matched by both, it will
+ be excluded.
+
+ 2. Targets specify the pages _to_ which instant previews should be enabled.
+ This is the recommended way to enable instant previews.
+---
+
+Instant previews can also be enabled globally by adding the following lines to
+`mkdocs.yml`, which will enable instant previews for all header links,
+alleviating the need to add data attributes:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant.preview
+```
+
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ previews, as instant previews rely on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+### Anchor tracking
+
+
+
+
+When anchor tracking is enabled, the URL in the address bar is automatically
+updated with the active anchor as highlighted in the table of contents. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.tracking
+```
+
+### Navigation tabs
+
+
+
+
+When tabs are enabled, top-level sections are rendered in a menu layer below
+the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
+the following lines to `mkdocs.yml`:
+
+ [^1]:
+ Prior to , navigation tabs had a slightly different
+ behavior. All top-level pages (i.e. all top-level entries directly
+ referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
+ were grouped under the first tab which received the title of the first page.
+ This made it impossible to include a top-level page (or external link) as a
+ tab item, as was reported in #1884 and #2072. From
+ on, navigation tabs include all top-level pages and sections.
+
+``` yaml
+theme:
+ features:
+ - navigation.tabs
+```
+
+=== "With tabs"
+
+ [![Navigation tabs enabled]][Navigation tabs enabled]
+
+=== "Without"
+
+ [![Navigation tabs disabled]][Navigation tabs disabled]
+
+ [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
+ [Navigation tabs disabled]: ../assets/screenshots/navigation.png
+
+#### Sticky navigation tabs
+
+
+
+
+When sticky tabs are enabled, navigation tabs will lock below the header and
+always remain visible when scrolling down. Just add the following two feature
+flags to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.tabs
+ - navigation.tabs.sticky
+```
+
+=== "With sticky tabs"
+
+ [![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
+
+=== "Without"
+
+ [![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
+
+ [Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
+ [Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
+
+### Navigation sections
+
+
+
+
+When sections are enabled, top-level sections are rendered as groups in the
+sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.sections
+```
+
+=== "With sections"
+
+ [![Navigation sections enabled]][Navigation sections enabled]
+
+=== "Without"
+
+ [![Navigation sections disabled]][Navigation sections disabled]
+
+ [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
+ [Navigation sections disabled]: ../assets/screenshots/navigation.png
+
+Both feature flags, [`navigation.tabs`][tabs] and
+[`navigation.sections`][sections], can be combined with each other. If both
+feature flags are enabled, sections are rendered for level 2 navigation items.
+
+### Navigation expansion
+
+
+
+
+When expansion is enabled, the left sidebar will expand all collapsible
+subsections by default, so the user doesn't have to open subsections manually.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.expand
+```
+
+=== "With expansion"
+
+ [![Navigation expansion enabled]][Navigation expansion enabled]
+
+=== "Without"
+
+ [![Navigation expansion disabled]][Navigation expansion disabled]
+
+ [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
+ [Navigation expansion disabled]: ../assets/screenshots/navigation.png
+
+### Navigation path Breadcrumbs { id=navigation-path }
+
+
+
+
+
+
+When navigation paths are activated, a breadcrumb navigation is rendered above
+the title of each page, which might make orientation easier for users visiting your
+documentation on devices with smaller screens. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.path
+```
+
+=== "With navigation path"
+
+ [![Navigation path enabled]][Navigation path enabled]
+
+=== "Without"
+
+ [![Navigation path disabled]][Navigation path disabled]
+
+ [Navigation path enabled]: ../assets/screenshots/navigation-path-on.png
+ [Navigation path disabled]: ../assets/screenshots/navigation-path-off.png
+
+### Navigation pruning
+
+
+
+
+
+When pruning is enabled, only the visible navigation items are included in the
+rendered HTML, __reducing the size of the built site by 33% or more__. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.prune # (1)!
+```
+
+1. This feature flag is not compatible with
+ [`navigation.expand`][navigation.expand], as navigation expansion requires
+ the complete navigation structure.
+
+This feature flag is especially useful for documentation sites with 100+ or even
+1,000+ of pages, as the navigation makes up a significant fraction of the HTML.
+Navigation pruning will replace all expandable sections with links to the first
+page in that section (or the section index page).
+
+ [navigation.expand]: #navigation-expansion
+
+### Section index pages
+
+
+
+
+When section index pages are enabled, documents can be directly attached to
+sections, which is particularly useful for providing overview pages. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.indexes # (1)!
+```
+
+1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
+ as sections cannot host the table of contents due to missing space.
+
+=== "With section index pages"
+
+ [![Section index pages enabled]][Section index pages enabled]
+
+=== "Without"
+
+ [![Section index pages disabled]][Section index pages disabled]
+
+In order to link a page to a section, create a new document with the name
+`index.md` in the respective folder, and add it to the beginning of your
+navigation section:
+
+``` yaml
+nav:
+ - Section:
+ - section/index.md # (1)!
+ - Page 1: section/page-1.md
+ ...
+ - Page n: section/page-n.md
+```
+
+1. MkDocs also considers files called `README.md` as [index pages].
+
+ [Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
+ [Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
+ [toc.integrate]: #navigation-integration
+ [index pages]: https://www.mkdocs.org/user-guide/writing-your-docs/#index-pages
+
+### Table of contents
+
+#### Anchor following
+
+
+
+
+
+When anchor following for the [table of contents] is enabled, the sidebar is
+automatically scrolled so that the active anchor is always visible. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - toc.follow
+```
+
+#### Navigation integration
+
+
+
+
+When navigation integration for the [table of contents] is enabled, it is always
+rendered as part of the navigation sidebar on the left. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - toc.integrate # (1)!
+```
+
+1. This feature flag is not compatible with
+ [`navigation.indexes`][navigation.indexes], as sections cannot host the
+ table of contents due to missing space.
+
+=== "With navigation integration"
+
+ [![Navigation integration enabled]][Navigation integration enabled]
+
+=== "Without"
+
+ [![Navigation integration disabled]][Navigation integration disabled]
+
+ [table of contents]: extensions/python-markdown.md#table-of-contents
+ [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
+ [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
+ [navigation.indexes]: #section-index-pages
+
+### Back-to-top button
+
+
+
+
+A back-to-top button can be shown when the user, after scrolling down, starts
+to scroll up again. It's rendered centered and just below the header. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.top
+```
+
+## Usage
+
+### Hiding the sidebars
+
+
+
+
+The navigation and/or table of contents sidebars can be hidden for a document
+with the front matter `hide` property. Add the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+hide:
+ - navigation
+ - toc
+---
+
+# Page title
+...
+```
+
+=== "Hide navigation"
+
+ [![Hide navigation enabled]][Hide navigation enabled]
+
+=== "Hide table of contents"
+
+ [![Hide table of contents enabled]][Hide table of contents enabled]
+
+=== "Hide both"
+
+ [![Hide both enabled]][Hide both enabled]
+
+ [Hide navigation enabled]: ../assets/screenshots/hide-navigation.png
+ [Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
+ [Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
+
+### Hiding the navigation path
+
+
+
+
+
+While the [navigation path] is rendered above the main headline, sometimes, it
+might be desirable to hide it for a specific page, which can be achieved with
+the front matter `hide` property:
+
+``` yaml
+---
+hide:
+ - path
+---
+
+# Page title
+...
+```
+
+ [navigation path]: #navigation-path
+
+## Customization
+
+### Keyboard shortcuts
+
+Material for MkDocs includes several keyboard shortcuts that make it possible
+to navigate your project documentation via keyboard. There are two modes:
+
+
+
+: This mode is active when the _search is focused_. It provides several key
+ bindings to make search accessible and navigable via keyboard:
+
+ * ++arrow-down++ , ++arrow-up++ : select next / previous result
+ * ++esc++ , ++tab++ : close search dialog
+ * ++enter++ : follow selected result
+
+
+
+: This mode is active when _search is not focussed_ and when there's no other
+ focussed element that is susceptible to keyboard input. The following keys
+ are bound:
+
+ * ++f++ , ++s++ , ++slash++ : open search dialog
+ * ++p++ , ++comma++ : go to previous page
+ * ++n++ , ++period++ : go to next page
+
+Let's say you want to bind some action to the ++x++ key. By using [additional
+JavaScript], you can subscribe to the `keyboard$` observable and attach
+your custom event listener:
+
+=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
+
+ ``` js
+ keyboard$.subscribe(function(key) {
+ if (key.mode === "global" && key.type === "x") {
+ /* Add custom keyboard handler here */
+ key.claim() // (1)!
+ }
+ })
+ ```
+
+ 1. The call to `key.claim()` will execute `preventDefault()` on the
+ underlying event, so the keypress will not propagate further and
+ touch other event listeners.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/shortcuts.js
+ ```
+
+ [additional JavaScript]: ../customization.md#additional-javascript
+
+### Content area width
+
+The width of the content area is set so the length of each line doesn't exceed
+80-100 characters, depending on the width of the characters. While this
+is a reasonable default, as longer lines tend to be harder to read, it may be
+desirable to increase the overall width of the content area, or even make it
+stretch to the entire available space.
+
+This can easily be achieved with an [additional style sheet] and a few lines
+of CSS:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .md-grid {
+ max-width: 1440px; /* (1)! */
+ }
+ ```
+
+ 1. If you want the content area to always stretch to the available screen
+ space, reset `max-width` with the following CSS:
+
+ ``` css
+ .md-grid {
+ max-width: initial;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/mkdocs-material/docs/setup/setting-up-site-analytics.md b/mkdocs-material/docs/setup/setting-up-site-analytics.md
new file mode 100644
index 0000000..d1dc086
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-site-analytics.md
@@ -0,0 +1,320 @@
+# Setting up site analytics
+
+As with any other service offered on the web, understanding how your project
+documentation is actually used can be an essential success factor. Material for
+MkDocs natively integrates with [Google Analytics] and offers a customizable
+[cookie consent] and a [feedback widget].
+
+ [Google Analytics]: https://developers.google.com/analytics
+ [cookie consent]: ensuring-data-privacy.md#cookie-consent
+ [feedback widget]: #was-this-page-helpful
+
+## Configuration
+
+### Google Analytics
+
+
+
+
+Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
+already set up Google Analytics and have a property, enable it by adding the
+following lines to `mkdocs.yml`:
+
+ [^1]:
+ Prior to Material for MkDocs 9.2.0, Universal Analytics was supported as
+ well. However, since Universal Analytics has been sunset, this integration
+ was removed in 9.2.0.
+
+``` yaml
+extra:
+ analytics:
+ provider: google
+ property: G-XXXXXXXXXX
+```
+
+??? question "How to measure site search usage?"
+
+ Besides page views and events, [site search] can be tracked to better
+ understand how people use your documentation and what they expect to find.
+ In order to enable site search tracking, the following steps are required:
+
+ 1. Go to your Google Analytics __admin settings__
+ 2. Select the property for the respective tracking code
+ 3. Select the __data streams__ tab and click the corresponding URL
+ 4. Click the gear icon within the __enhanced measurement__ section
+ 5. Ensure that __site search__ is enabled
+
+ [site search]: setting-up-site-search.md
+
+### Was this page helpful?
+
+
+
+
+A simple [feedback widget] can be included at the bottom of each page,
+encouraging users to give instant feedback whether a page was helpful or not.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra:
+ analytics: # (1)!
+ feedback:
+ title: Was this page helpful?
+ ratings:
+ - icon: material/emoticon-happy-outline
+ name: This page was helpful
+ data: 1
+ note: >-
+ Thanks for your feedback!
+ - icon: material/emoticon-sad-outline
+ name: This page could be improved
+ data: 0
+ note: >- # (2)!
+ Thanks for your feedback! Help us improve this page by
+ using our feedback form.
+```
+
+1. This feature is natively integrated with [Google Analytics][analytics],
+ which is why `provider` and `property` are also required. However, it's also
+ possible to provide a [custom feedback integration].
+
+2. You can add arbitrary HTML tags to the note which is shown after the user
+ submitted the feedback, e.g. to link to a feedback form.
+
+Both properties, `title` and `ratings`, are required. Note that it's allowed to
+define more than two ratings, e.g. to implement a 1-5 star rating. Since the
+feedback widget sends data to a third-party service, it is, of course, natively
+integrated with the [cookie consent] feature[^2].
+
+ [^2]:
+ If the user doesn't accept the `analytics` cookie, the feedback widget is
+ not shown.
+
+??? question "How to visualize the collected feedback ratings?"
+
+ To visualize feedback ratings you'll need to create a custom report with
+ [Google Analytics] that will quickly show you the worst- and best-rated
+ pages of your project documentation.
+
+ 1. Go to your Google Analytics __dashboard__
+
+ 2. Go to the __configure__ page on the left hand menu, then select
+ __custom definitions__
+
+ 3. Click the __custom metrics__ tab and then __create custom metrics__,
+ enter the following values:
+
+ * Metric name: Page helpful
+ * Description: Was this page helpful?
+ * Event parameter: `data`
+ * Unit of measurement: Standard
+
+ 4. Go to the __explore__ page on the left hand menu, create a new
+ __blank exploration__
+
+ 5. Configure the report as follows:
+
+ * Dimensions: Add `Event name` and `Page location`
+ * Metrics: Add `Event count` and `Page helpful`
+ (the custom metric created in step 3)
+ * Rows: `Page location`
+ * Values: Drag in both `Event count` and `Page helpful`
+ * Filters: Add a new filter for
+ `Event name / exactly matches / feedback`
+
+ !!! warning "Delay in data availability"
+
+ The report may take 24 hours or longer to begin displaying data
+
+ Now, after you've saved the report and collected some feedback ratings,
+ you'll have a list of all pages with the total number of ratings, and an
+ average rating per page. This should help you identify pages that need to
+ be improved:
+
+ !!! danger "Google Analytics 4 does not support average values"
+
+ To our knowledge, Google Analytics 4 has currently no feature that
+ allows to define a custom calculated metric to compute the average
+ rating of a page. See #5740.
+
+ [![feedback report]][feedback report]
+
+The following properties are available for each rating:
+
+
+
+:
+ This property must point to a valid icon path referencing [any icon bundled
+ with the theme][custom icons], or the build will not succeed. Some popular
+ combinations:
+
+ * :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
+ * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
+ * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
+
+
+
+:
+ The value of this property is shown on user interaction (i.e. keyboard focus
+ or mouse hover), explaining the meaning of the rating behind the icon.
+
+
+
+:
+ The value of this property is sent as a data value with the custom event
+ that is transmitted to Google Analytics[^3] (or any custom integration).
+
+ [^3]:
+ Note that for Google Analytics, the data value must be an integer.
+
+
+
+:
+ The value of this property is shown after the user selected the rating.
+ It may contain arbitrary HTML tags, which is especially useful to ask the
+ user to provide more detailed feedback for the current page through a form.
+ It's also possible to pre-fill forms with the URL and title of the current
+ page by using the following placeholders:
+
+ - `{url}` – Page URL
+ - `{title}` – Page title
+
+ ```
+ https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
+ ```
+
+ In this example, when clicking the link, the user is redirected to the "new
+ issue" form of your repository, with a pre-filled title including the path
+ of the current document, e.g.:
+
+ ```
+ [Feedback] Setting up site analytics – /setup/setting-up-site-analytics/
+ ```
+
+ An alternative to GitHub issues is [Google Forms].
+
+ [feedback widget]: #feedback
+ [analytics]: #google-analytics
+ [feedback report]: ../assets/screenshots/feedback-report.png
+ [custom feedback integration]: #custom-site-feedback
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+ [Google Forms]: https://www.google.com/forms/about/
+
+## Usage
+
+### Hiding the feedback widget
+
+The [feedback widget] can be hidden for a document with the front matter `hide`
+property. Add the following lines at the top of a Markdown file:
+
+``` yaml
+---
+hide:
+ - feedback
+---
+
+# Page title
+...
+```
+
+## Customization
+
+### Custom site analytics
+
+In order to integrate another analytics service provider offering a
+JavaScript-based tracking solution, just follow the guide on [theme extension]
+and create a new partial in the `overrides` folder. The name of the partial is
+used to configure the custom integration via `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`"
+
+ ``` html
+
+ ```
+
+ 1. As an example, this variable receives the value set in `mkdocs.yml`,
+ which is `"foobar"` for `property`.
+ 2. If you're using [instant loading], you can use the `location$`
+ observable to listen for navigation events, which always emits the
+ current `URL`.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra:
+ analytics:
+ provider: custom
+ property: foobar # (1)!
+ ```
+
+ 1. You can add arbitrary key-value combinations to configure your
+ custom integration. This is especially useful if you're sharing the
+ custom integration across multiple repositories.
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [instant loading]: setting-up-navigation.md#instant-loading
+
+### Custom site feedback
+
+A custom feedback widget integration just needs to process the events that are
+generated by users interacting with the feedback widget with the help of some
+[additional JavaScript]:
+
+=== ":octicons-file-code-16: `docs/javascripts/feedback.js`"
+
+ ``` js
+ var feedback = document.forms.feedback
+ feedback.hidden = false // (1)!
+
+ feedback.addEventListener("submit", function(ev) {
+ ev.preventDefault()
+
+ var page = document.location.pathname // (2)!
+ var data = ev.submitter.getAttribute("data-md-value")
+
+ console.log(page, data) // (3)!
+
+ feedback.firstElementChild.disabled = true // (4)!
+
+ var note = feedback.querySelector(
+ ".md-feedback__note [data-md-value='" + data + "']"
+ )
+ if (note)
+ note.hidden = false // (5)!
+ })
+ ```
+
+ 1. The feedback widget is hidden by default so that it does not appear when
+ people have JavaScript turned off. So, it needs to be turned on here.
+
+ 2. Retrieve page and feedback value.
+
+ 3. Replace this with the code that sends the data off to your analytics
+ provider.
+
+ 4. Disable the form after submission.
+
+ 5. Show the configured notes. Which one is shown depends on the user
+ feedback.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/feedback.js
+ ```
+
+
+{ #feedback style="margin: 0; height: 0" }
+
+ [additional JavaScript]: ../customization.md#additional-javascript
diff --git a/mkdocs-material/docs/setup/setting-up-site-search.md b/mkdocs-material/docs/setup/setting-up-site-search.md
new file mode 100644
index 0000000..605c9c9
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-site-search.md
@@ -0,0 +1,229 @@
+---
+search:
+ boost: 1.05
+---
+
+# Setting up site search
+
+Material for MkDocs provides an excellent client-side search implementation,
+omitting the need for the integration of third-party services, which might
+not be compliant with privacy regulations. Moreover, search even works
+[offline], allowing users to download your documentation.
+
+ [offline]: building-for-offline-usage.md
+
+## Configuration
+
+### Built-in search plugin
+
+
+
+
+The built-in search plugin integrates seamlessly with Material for MkDocs,
+adding multilingual client-side search with [lunr] and [lunr-languages]. It's
+enabled by default, but must be re-added to `mkdocs.yml` when other plugins
+are used:
+
+``` yaml
+plugins:
+ - search
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/search.md
+
+ [lunr]: https://lunrjs.com
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+
+### Search suggestions
+
+
+
+
+
+When search suggestions are enabled, the search will display the likeliest
+completion for the last word which can be accepted with the ++arrow-right++ key.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.suggest
+```
+
+Searching for [:octicons-search-24: search su][Search suggestions example]
+yields ^^search suggestions^^ as a suggestion.
+
+ [Search suggestions example]: ?q=search+su
+
+### Search highlighting
+
+
+
+
+
+When search highlighting is enabled and a user clicks on a search result,
+Material for MkDocs will highlight all occurrences after following the link.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.highlight
+```
+
+Searching for [:octicons-search-24: code blocks][Search highlighting example]
+highlights all occurrences of both terms.
+
+ [Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
+
+### Search sharing
+
+
+
+
+When search sharing is activated, a :material-share-variant: share button is
+rendered next to the reset button, which allows to deep link to the current
+search query and result. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.share
+```
+
+When a user clicks the share button, the URL is automatically copied to the
+clipboard.
+
+## Usage
+
+### Search boosting
+
+
+
+
+Pages can be boosted in search with the front matter `search.boost` property,
+which will make them rank higher. Add the following lines at the top of a
+Markdown file:
+
+=== ":material-arrow-up-circle: Rank up"
+
+ ``` yaml
+ ---
+ search:
+ boost: 2 # (1)!
+ ---
+
+ # Page title
+ ...
+ ```
+
+ 1. :woman_in_lotus_position: When boosting pages, be gentle and start with
+ __low values__.
+
+=== ":material-arrow-down-circle: Rank down"
+
+ ``` yaml
+ ---
+ search:
+ boost: 0.5
+ ---
+
+ # Page title
+ ...
+ ```
+
+### Search exclusion
+
+
+
+
+
+Pages can be excluded from search with the front matter `search.exclude`
+property, removing them from the index. Add the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
+
+#### Excluding sections
+
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
+from search by adding the `data-search-exclude` pragma after a Markdown
+heading:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ ## Section 1
+
+ The content of this section is included
+
+ ## Section 2 { data-search-exclude }
+
+ The content of this section is excluded
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"",
+ "title":"Document title"
+ },
+ {
+ "location":"page/#section-1",
+ "text":"
The content of this section is included
",
+ "title":"Section 1"
+ }
+ ]
+ }
+ ```
+
+ [Attribute Lists]: extensions/python-markdown.md#attribute-lists
+
+#### Excluding blocks
+
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
+from search by adding the `data-search-exclude` pragma after a Markdown
+inline- or block-level element:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ The content of this block is included
+
+ The content of this block is excluded
+ { data-search-exclude }
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"
The content of this block is included
",
+ "title":"Document title"
+ }
+ ]
+ }
+ ```
diff --git a/mkdocs-material/docs/setup/setting-up-social-cards.md b/mkdocs-material/docs/setup/setting-up-social-cards.md
new file mode 100644
index 0000000..0603cb0
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-social-cards.md
@@ -0,0 +1,642 @@
+# Setting up social cards
+
+Material for MkDocs can automatically create beautiful social cards for your
+documentation, which appear as link previews on social media platforms. You
+can select from several [pre-designed layouts][default layouts] or create
+[custom layouts] to match your unique style and branding.
+
+---
+
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__[How to build custom social cards]__ by @james-willett – :octicons-clock-24:
+24m – Learn how to create entirely custom social cards perfectly matching your
+branding for each page automatically!
+
+ [How to build custom social cards]: https://www.youtube.com/watch?v=4OjnOc6ftJ8
+
+
+
+[![Layout default variant]][Layout default variant]
+
+
+
+Social card of our [formatting] reference
+
+
+
+
+ [default layouts]: ../plugins/social.md#layouts
+ [custom layouts]: #customization
+ [formatting]: ../reference/formatting.md
+ [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+
+## Configuration
+
+### Built-in social plugin
+
+
+
+
+
+The built-in social plugin automatically generate a custom preview image for
+each page. Install all [dependencies for image processing] and add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - social
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/social.md
+
+!!! info "The [`site_url`][site_url] setting must be set"
+
+ Note that you must set [`site_url`][site_url] when using the social plugin,
+ or the generated cards will not be correctly linked. Social media services
+ like X and Facebook demand that social previews point to an absolute
+ URL, which the plugin can only compute when [`site_url`][site_url] is set.
+ Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+ [dependencies for image processing]: ../plugins/requirements/image-processing.md
+ [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+
+## Usage
+
+If you want to adjust the title or set a custom description for the social card,
+you can set the front matter [`title`][Changing the title] and
+[`description`][Changing the description] properties, which take precedence over
+the defaults, or use:
+
+- [`cards_layout_options.title`](../plugins/social.md#option.title)
+- [`cards_layout_options.description`](../plugins/social.md#option.description)
+
+ [Changing the title]: ../reference/index.md#setting-the-page-title
+ [Changing the description]: ../reference/index.md#setting-the-page-description
+
+### Choosing a font
+
+Some fonts do not contain CJK characters, like for example the
+[default font, `Roboto`][font]. In case your `site_name`, `site_description`, or
+page title contain CJK characters, choose another font from [Google Fonts] which
+comes with CJK characters, e.g. one from the `Noto Sans` font family:
+
+=== "Chinese (Simplified)"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans SC
+ ```
+
+=== "Chinese (Traditional)"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans TC
+ ```
+
+=== "Japanese"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans JP
+ ```
+
+=== "Korean"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans KR
+ ```
+
+ [font]: changing-the-fonts.md#regular-font
+
+### Changing the layout
+
+
+
+
+
+If you want to use a different layout for a single page (e.g. your landing
+page), you can use the `social` front matter property together with the
+[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
+in `mkdocs.yml`:
+
+``` yaml
+---
+social:
+ cards_layout: custom
+---
+
+# Page title
+...
+```
+
+You can apply those changes for entire subtrees of your documentation, e.g.,
+to generate different social cards for your blog and API reference, by using
+the [built-in meta plugin].
+
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Parametrizing the layout
+
+
+
+
+
+Besides changing the entire layout, you can override all options that a layout
+exposes. This means you can parametrize social cards with custom front matter
+properties, such as `tags`, `date`, `author` or anything you can think of.
+Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
+
+``` yaml
+---
+social:
+ cards_layout_options:
+ background_color: blue # Change background color
+ background_image: null # Remove background image
+---
+
+# Page title
+...
+```
+
+You can apply those changes for entire subtrees of your documentation, e.g.,
+to generate different social cards for your blog and API reference, by using
+the [built-in meta plugin].
+
+### Disabling social cards
+
+
+
+
+
+If you wish to disable social cards for a page, simply add the following to the
+front matter of the Markdown document:
+
+``` yaml
+---
+social:
+ cards: false
+---
+
+# Page title
+...
+```
+
+## Customization
+
+
+
+
+
+[Insiders] ships a ground up rewrite of the [built-in social plugin] and
+introduces a brand new layout system based on a combination of YAML and
+[Jinja templates] – the same engine Material for MkDocs uses for HTML
+templating – allowing for the creation of complex custom layouts:
+
+
+
+
+ Layer 0
+
+
+
+
+
+ Layer 1
+
+
+
+
+
+ Layer 2
+
+
+
+
+
+ Layer 3
+
+
+
+
+
+ Layer 4
+
+
+
+
+
+ Layer 5
+
+
+
+
+
+Social cards are composed of layers, analogous to how they are represented in
+graphic design software such as Adobe Photoshop. As many layers are common
+across the cards generated for each page (e.g., backgrounds or logos), the
+built-in social plugin can automatically deduplicate layers and render them
+just once, substantially accelerating card generation. The generated cards are
+cached to ensure they are only regenerated when their contents change.
+
+Layouts are written in YAML syntax. Before starting to create a custom layout,
+it is a good idea to [study the pre-designed layouts] (link to [Insiders]
+repository), in order to get a better understanding of how they work. Then,
+create a new layout and reference it in `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `layouts/custom.yml`"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers: []
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_dir: layouts
+ cards_layout: custom
+ debug: true
+ ```
+
+Note that the `.yml` file extension should be omitted. Next, run `mkdocs serve`,
+and see how the `.cache` directory is populated with the generated cards. Open
+any card in your editor, so you can see your changes immediately. Since we
+haven't defined any layers, the cards are transparent.
+
+The following sections explain how to create custom layouts.
+
+ [Insiders]: ../insiders/index.md
+ [built-in social plugin]: ../plugins/social.md
+ [Google Fonts]: https://fonts.google.com/
+ [Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
+ [study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material-insiders/tree/master/src/plugins/social/layouts
+
+### Size and offset
+
+Each layer has an associated size and offset, which is defined in pixels. The
+`size` is defined by a `width` and `height` property, and the `offset` by `x`
+and `y` properties:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 1200, height: 630 }
+ offset: { x: 0, y: 0 }
+```
+
+If the `size` is omitted, it defaults to the size of the layout. If the `offset`
+is omitted, it defaults to the top left corner, which is the default `origin`.
+Saving the layout and reloading renders:
+
+![Layer size]
+
+The layer outline and grid are visible because we enabled [`debug`][debug]
+mode in `mkdocs.yml`. The top left shows the layer index and offset, which is
+useful for alignment and composition.
+
+ [Layer size]: ../assets/screenshots/social-cards-layer-size.png
+ [debug]: ../plugins/social.md#debugging
+
+#### Origin
+
+
+
+
+The `origin` for the `x` and `y` values can be changed, so that the layer is
+aligned to one of the edges or corners of the layout, e.g., to the bottom right
+corner of the layout:
+
+``` yaml hl_lines="5"
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 1200, height: 630 }
+ offset: { x: 0, y: 0 }
+ origin: end bottom
+```
+
+The following table shows the supported values:
+
+
+
+| Origin | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+
+ Supported values for origin
+
+
+
+### Backgrounds
+
+Each layer can be assigned a background color and image. If both are given, the
+color is rendered on top of the image, allowing for semi-transparent, tinted
+backgrounds:
+
+=== "Background color"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ color: "#4051b5"
+ ```
+
+ ![Layer background color]
+
+=== "Background image"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ ```
+
+ ![Layer background image]
+
+=== "Background image, tinted"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ color: "#4051b5ee" # (1)!
+ ```
+
+ 1. The color value can be set to a [CSS color keyword], or a 3, 4, 6 or 8
+ letter HEX color code, allowing for semi-transparent layers.
+
+ ![Layer background]
+
+Background images are automatically scaled to fit the layer while preserving
+aspect-ratio. Notice how we omitted `size` and `offset`, because we want to
+fill the entire area of the social card.
+
+[Layer background color]: ../assets/screenshots/social-cards-layer-background-color.png
+[Layer background image]: ../assets/screenshots/social-cards-layer-background-image.png
+[Layer background]: ../assets/screenshots/social-cards-layer-background.png
+
+### Typography
+
+Now, we can add dynamic typography that is sourced from Markdown files - this is
+the actual raison d'être of the [built-in social plugin]. [Jinja templates] are
+used to render a text string that is then added to the image:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}" # (1)!
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+1. The following variables can be used in [Jinja templates]:
+
+ - [`config.*`][config variable]
+ - [`page.*`][page variable]
+ - [`layout.*`][layout options]
+
+ The author is free in defining `layout.*` options, which can be used to pass
+ arbitrary data to the layout from `mkdocs.yml`.
+
+This renders a text layer with the title of the page with a line height of 1.25,
+and a maximum number of 3 lines. The plugin automatically computes the font size
+from the line height, the number of lines, and font metrics like ascender and
+descender.[^2] This renders:
+
+ [^2]:
+ If the plugin would require the author to specify the font size and line
+ height manually, it would be impossible to guarantee that the text fits
+ into the layer. For this reason we implemented a declarative approach,
+ where the author specifies the desired line height and number of lines, and
+ the plugin computes the font size automatically.
+
+![Layer typography]
+
+ [config variable]: https://www.mkdocs.org/dev-guide/themes/#config
+ [page variable]: https://www.mkdocs.org/dev-guide/themes/#page
+ [Layer typography]: ../assets/screenshots/social-cards-layer-typography.png
+
+#### Overflow
+
+If the text overflows the layer, there are two possible behaviors: either the
+text is automatically truncated and shortened with an ellipsis, or the text is
+automatically scaled down to fit the layer:
+
+``` { .markdown .no-copy }
+# If we use a very long headline, we can see how the text will be truncated
+```
+
+=== ":octicons-ellipsis-16: Ellipsis"
+
+ ![Layer typography ellipsis]
+
+=== ":material-arrow-collapse: Shrink"
+
+ ![Layer typography shrink]
+
+While truncating with an ellipsis is the default, auto-shrinking can be enabled
+by setting `overflow` to `shrink`:
+
+``` yaml hl_lines="7"
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}"
+ overflow: shrink
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+ [Layer typography ellipsis]: ../assets/screenshots/social-cards-layer-typography-ellipsis.png
+ [Layer typography shrink]: ../assets/screenshots/social-cards-layer-typography-shrink.png
+
+#### Alignment
+
+Text can be aligned to all corners and edges of the layer. For example, if we
+want to align the text to the middle of the layer, we can set `align` to `start center`, which will render as:
+
+![Layer typography align]
+
+ [Layer typography align]: ../assets/screenshots/social-cards-layer-typography-align.png
+
+The following table shows the supported values:
+
+
+
+| Alignment | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+
+ Supported values for text alignment
+
+
+
+#### Font
+
+The [built-in social plugin] integrates with [Google Fonts] and will
+automatically download the font files for you. The `font` property accepts a
+`family` and `style` property, where the `family` must be set to the name of the
+font, and the `style` to one of the supported font styles. For example, setting
+`family` to `Roboto` will automatically download the following files:
+
+``` { .sh .no-copy #example }
+.cache/plugins/social/fonts
+└─ Roboto/
+ ├─ Black.ttf
+ ├─ Black Italic.ttf
+ ├─ Bold.ttf
+ ├─ Bold Italic.ttf
+ ├─ Italic.ttf
+ ├─ Light.ttf
+ ├─ Light Italic.ttf
+ ├─ Medium.ttf
+ ├─ Medium Italic.ttf
+ ├─ Regular.ttf
+ ├─ Thin.ttf
+ └─ Thin Italic.ttf
+```
+
+In that case, the author can use `Bold` or `Medium Italic` as the `style`. If
+the font style specified in the layer is not part of the font family, the
+font always falls back to `Regular` and prints a warning in [`debug`][debug]
+mode, as `Regular` is included with all font families.
+
+### Icons
+
+Authors can leverage the full range of icons that are shipped with Material for
+MkDocs, or even provide custom icons by using theme extension and going through
+the process described in the guide on [additional icons]. Icons can even be
+tinted by using the `color` property:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 144, height: 144 }
+ offset: { x: 992, y: 64 }
+ icon:
+ value: material/cat
+ color: white
+```
+
+This will render the icon in the top right corner of the social card:
+
+![Layer icon]
+
+The possibilities are endless. For example, icons can be used to draw shapes
+like circles:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 2400, height: 2400 }
+ offset: { x: -1024, y: 64 }
+ icon:
+ value: material/circle
+ color: "#5c6bc0"
+ - size: { width: 1800, height: 1800 }
+ offset: { x: 512, y: -1024 }
+ icon:
+ value: material/circle
+ color: "#3949ab"
+```
+
+This will add two circles to the background:
+
+![Layer icon circles]
+
+### Tags
+
+The new [built-in social plugin] gives full flexibility of the meta tags that
+are added to your site, which are necessary to instruct services like X
+or Discord how to display your social card. All default layouts use the following
+set of tags, which you can copy to your layout and adapt:
+
+``` yaml
+definitions:
+
+ - &page_title_with_site_name >-
+ {%- if not page.is_homepage -%}
+ {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
+ {%- else -%}
+ {{ page.meta.get("title", page.title) }}
+ {%- endif -%}
+
+ - &page_description >-
+ {{ page.meta.get("description", config.site_description) or "" }}
+
+tags:
+
+ og:type: website
+ og:title: *page_title_with_site_name
+ og:description: *page_description
+ og:image: "{{ image.url }}"
+ og:image:type: "{{ image.type }}"
+ og:image:width: "{{ image.width }}"
+ og:image:height: "{{ image.height }}"
+ og:url: "{{ page.canonical_url }}"
+
+ twitter:card: summary_large_image
+ twitter:title: *page_title_with_site_name
+ twitter:description: *page_description
+ twitter:image: "{{ image.url }}"
+```
+
+Note that this example makes use of [YAML anchors] to minify repetition. The
+ `definitions` property is solely intended for the definition on aliases that
+ can then be referenced with anchors.
+
+ [YAML anchors]: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
+
+__Are you missing something? Please [open a discussion] and let us know!__
+
+ [additional icons]: ./changing-the-logo-and-icons.md#additional-icons
+ [Layer icon]: ../assets/screenshots/social-cards-layer-icon.png
+ [Layer icon circles]: ../assets/screenshots/social-cards-layer-icon-circles.png
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new
diff --git a/mkdocs-material/docs/setup/setting-up-tags.md b/mkdocs-material/docs/setup/setting-up-tags.md
new file mode 100644
index 0000000..644ea45
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-tags.md
@@ -0,0 +1,356 @@
+# Setting up tags
+
+Material for MkDocs adds first-class support for categorizing pages with tags,
+which adds the possibility to group related pages and make them discoverable
+via search and a dedicated [tags index]. If your documentation is large, tags
+can help to discover relevant information faster.
+
+ [tags index]: #adding-a-tags-index
+
+## Configuration
+
+### Built-in tags plugin
+
+
+
+
+The built-in tags plugin adds the ability to categorize any page with tags
+as part of the front matter of the page. In order to add support for tags, add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - tags
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/tags.md
+
+#### Advanced settings
+
+
+
+
+
+The following advanced settings are currently reserved to our [sponsors]
+[Insiders]. They are entirely optional, and only add additional capabilities to
+the tags plugin:
+
+
+- [`listings_toc`][config.listings_toc]
+
+We'll add more settings here in the near future.
+
+ [Insiders]: ../insiders/index.md
+ [config.listings_layout]: ../plugins/tags.md#config.listings_layout
+ [config.listings_toc]: ../plugins/tags.md#config.listings_toc
+
+### Tag icons and identifiers
+
+
+
+
+
+Each tag can be associated with an icon, which is then rendered inside the tag.
+Before assigning icons to tags, associate each tag with a unique identifier,
+by adding the following to `mkdocs.yml`:
+
+``` yaml
+extra:
+ tags:
+ : # (1)!
+```
+
+1. The identifier can only include alphanumeric characters, as well as dashes
+ and underscores. For example, if you have a tag `Compatibility`, you can
+ set `compat` as an identifier:
+
+ ``` yaml
+ extra:
+ tags:
+ Compatibility: compat
+ ```
+
+ Identifiers can be reused between tags. Tags which are not explicitly
+ associated will use the default tag icon which is :material-pound:
+
+Next, each identifier can be associated with an icon, even a [custom icon], by
+adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
+setting:
+
+=== "Tag icon"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ : # (1)!
+ ```
+
+ 1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+
+
+
+
+
+
+
+
+=== "Tag default icon"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ default:
+ ```
+
+??? example "Expand to inspect example"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ html: fontawesome/brands/html5
+ js: fontawesome/brands/js
+ css: fontawesome/brands/css3
+ extra:
+ tags:
+ HTML5: html
+ JavaScript: js
+ CSS: css
+ ```
+
+ [custom icon]: changing-the-logo-and-icons.md#additional-icons
+ [icon search]: ../reference/icons-emojis.md#search
+
+## Usage
+
+### Adding tags
+
+
+
+
+When the [built-in tags plugin] is enabled, tags can be added for a document
+with the front matter `tags` property. Add the following lines at the top of a
+Markdown file:
+
+``` sh
+---
+tags:
+ - HTML5
+ - JavaScript
+ - CSS
+---
+
+...
+```
+
+The page will now render with those tags above the main headline and within the
+search preview, which now allows to __find pages by tags__.
+
+??? question "How to set tags for an entire folder?"
+
+ With the help of the [built-in meta plugin], you can ensure that tags are
+ set for an entire section and all nested pages, by creating a `.meta.yml`
+ file in the corresponding folder with the following content:
+
+ ``` yaml
+ tags:
+ - HTML5
+ - JavaScript
+ - CSS
+ ```
+
+ The tags set in `.meta.yml` are merged and deduplicated with the tags
+ defined for a page, which means you can define common tags in `.meta.yml`
+ and then add specific tags for each page. The tags in `.meta.yml` are
+ appended.
+
+ [built-in tags plugin]: ../plugins/tags.md
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Adding a tags index
+
+
+
+
+The [built-in tags plugin] allows to define a file to render a tags index,
+which can be any page that is part of the `nav` section. To add a tags index,
+create a page, e.g. `tags.md`:
+
+``` markdown
+# Tags
+
+Following is a list of relevant tags:
+
+
+```
+
+Then in your `mkdocs.yml` file, add the following.
+
+``` yaml
+plugins:
+ - tags:
+ tags_file: tags.md # (1)!
+```
+
+1. This setting is not necessary when using [Insiders].
+
+Note that the path to `tags.md` is relative to the `docs/` directory.
+
+The tags marker specifies the position of the tags index, i.e. it is
+replaced with the actual tags index when the page is rendered. You can include
+arbitrary content before and after the marker:
+
+[![Tags index][tags index enabled]][tags index enabled]
+
+ [tags.tags_file]: #tags-file
+ [tags index enabled]: ../assets/screenshots/tags-index.png
+
+### Advanced features
+
+[Insiders] ships a __ground up rewrite of the tags plugin__ which is infinitely
+more powerful than the current version in the community edition. It allows
+for an arbitrary number of tags indexes (listings), [scoped listings],
+[shadow tags], [nested tags], and much more.
+
+ [scoped listings]: #scoped-listings
+ [shadow tags]: #shadow-tags
+ [nested tags]: #nested-tags
+
+#### Configurable listings
+
+
+
+
+
+Listings can be configured in `mkdocs.yml` or directly at the location of the
+marker that you position in a Markdown document. Some examples:
+
+- __Use [scoped listings]__: limit the tags index to pages that are on the same
+ level of the subsection of the documentation the page is in:
+
+ ``` html
+
+ ```
+
+- __List only specific tags__: limit the tags index to a single or multiple
+ selected tags, e.g., `Foo` and `Bar`, excluding all other tags:
+
+ ``` html
+
+ ```
+
+- __Exclude pages with specific tags__: don't include pages that are tagged
+ with specific tags, e.g. `Internal`. This can be any tag, including a shadow
+ tag:
+
+ ``` html
+
+ ```
+
+- __Enable or disable tags inside the table of contents__: specify whether the
+ table of contents lists all tags under the nearest headline:
+
+ ``` html
+
+ ```
+
+See the [listing configuration] for all options.
+
+ [listing configuration]: ../plugins/tags.md#listing-configuration
+
+#### Scoped listings
+
+
+
+
+
+If your documentation is large, you might want to consider using scoped listings
+which will only include pages that are on the same level or below the page
+containing the listing. Just use:
+
+``` html
+
+```
+
+If you plan to use multiple scoped indexes, it's a good idea to define a
+listing configuration in `mkdocs.yml`, which you can then reference by its id:
+
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ scoped:
+ scope: true
+```
+
+You can now use:
+
+``` html
+
+```
+
+#### Shadow tags
+
+
+
+
+
+Shadow tags are tags that are solely meant to organization, which can be
+included or excluded for rendering with a simple flag. They can be enumerated
+in the [`shadow_tags`][config.shadow_tags] setting:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags:
+ - Draft
+ - Internal
+```
+
+If a document is tagged with `Draft`, the tag will only be rendered if
+[`shadow`][config.shadow] setting is enabled, and excluded when it is disabled.
+This is an excellent opportunity for using tags for structuring.
+
+ [config.shadow]: ../plugins/tags.md#config.shadow
+ [config.shadow_tags]: ../plugins/tags.md#config.shadow_tags
+
+#### Nested tags
+
+
+
+
+
+[Insiders] ships support for nested tags. The
+[`tags_hierarchy_separator`][config.tags_hierarchy_separator] allows to create
+hierarchies of tags, e.g., `Foo/Bar`. Nested tags will be rendered as children
+of the parent tag:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy: true
+```
+
+ [config.tags_hierarchy_separator]: ../plugins/tags.md#config.tags_hierarchy_separator
+
+### Hiding tags on a page
+
+While the tags are rendered above the main headline, sometimes, it might be
+desirable to hide them for a specific page, which can be achieved with the
+front matter `hide` property:
+
+``` yaml
+---
+hide:
+ - tags
+---
+
+# Page title
+...
+```
diff --git a/mkdocs-material/docs/setup/setting-up-the-footer.md b/mkdocs-material/docs/setup/setting-up-the-footer.md
new file mode 100644
index 0000000..35194f2
--- /dev/null
+++ b/mkdocs-material/docs/setup/setting-up-the-footer.md
@@ -0,0 +1,187 @@
+# Setting up the footer
+
+The footer of your project documentation is a great place to add links to
+websites or platforms you or your company are using as additional marketing
+channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
+configure via `mkdocs.yml`.
+
+## Configuration
+
+### Navigation
+
+
+
+
+The footer can include links to the previous and next page of the current page.
+If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.footer
+```
+
+### Social links
+
+
+
+
+Social links are rendered next to the copyright notice as part of the
+footer of your project documentation. Add a list of social links in `mkdocs.yml`
+with:
+
+``` yaml
+extra:
+ social:
+ - icon: fontawesome/brands/mastodon # (1)!
+ link: https://fosstodon.org/@squidfunk
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+