diff --git a/.dockerignore b/.dockerignore
index 89756197a64..ee5a90b3c29 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -18,8 +18,10 @@
# 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/.editorconfig b/.editorconfig
index a686b2439c1..eaff7430261 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -34,11 +34,7 @@ trim_trailing_whitespace = true
[*.md]
trim_trailing_whitespace = false
-# Makefiles
+# Python
[*.py]
+indent_style = space
indent_size = 4
-
-# Makefiles
-[Makefile]
-indent_style = tab
-indent_size = 8
diff --git a/.eslintignore b/.eslintignore
index 926686b8558..faff795bfb4 100644
--- a/.eslintignore
+++ b/.eslintignore
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
diff --git a/.eslintrc b/.eslintrc
index c749ebb255d..5c202c084d2 100644
--- a/.eslintrc
+++ b/.eslintrc
@@ -214,7 +214,7 @@
],
"@typescript-eslint/no-empty-interface": "off",
"@typescript-eslint/no-extraneous-class": "error",
- "@typescript-eslint/no-misused-promises": "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",
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index 046490789d0..958523efc0f 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -19,5 +19,3 @@
# IN THE SOFTWARE.
github: squidfunk
-custom:
- - paypal.me/squidfunk
diff --git a/.github/ISSUE_TEMPLATE/01-report-a-bug.yml b/.github/ISSUE_TEMPLATE/01-report-a-bug.yml
new file mode 100644
index 00000000000..bf8c18acde1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/01-report-a-bug.yml
@@ -0,0 +1,119 @@
+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/#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/contributing/reporting-a-bug/reproduction/)
+ that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/reproduction/#creating-a-zip-file) (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 .zip file with 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: >-
+ 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/contributing/reporting-a-bug/reproduction/).
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml b/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml
new file mode 100644
index 00000000000..648d5bb9891
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml
@@ -0,0 +1,65 @@
+name: Report a docs 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., it's 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 reporting guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
+ required: true
+ - label: >-
+ I have attached the links to the described sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/03-request-a-change.yml b/.github/ISSUE_TEMPLATE/03-request-a-change.yml
new file mode 100644
index 00000000000..3fa6a03223f
--- /dev/null
+++ b/.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
+ 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 how the change would positively impact not only
+ you, but the community, and how it aligns with the goals and [philopsophy](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 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/.github/ISSUE_TEMPLATE/04-add-a-translation.yml b/.github/ISSUE_TEMPLATE/04-add-a-translation.yml
new file mode 100644
index 00000000000..a49acf395b2
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/04-add-a-translation.yml
@@ -0,0 +1,81 @@
+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 make sure that
+ Material for MkDocs does not already include support for your language.
+ Please check the list of all [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language)
+ and help us by adding missing translations.
+
+ - type: textarea
+ id: translations
+ attributes:
+ label: Translations
+ description: Please translate the labels on the right, e.g. "Copy to clipboard", etc.
+ 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",
+ "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",
+ "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.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: 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 my best 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/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
deleted file mode 100644
index d6bc1b52004..00000000000
--- a/.github/ISSUE_TEMPLATE/bug.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-name: Bug
-about: Report a bug
-title: ''
-assignees: ''
----
-
-
-
-- [ ] I've read the [contribution guidelines][1] and agree with them
-
-__I've found a bug and checked that ...__
-
-- [ ] ... the problem doesn't occur with the default MkDocs template
-- [ ] ... the problem is not in any of my customizations (CSS, JS, template)
-- [ ] ... the documentation does not mention anything about my problem
-- [ ] ... there are no open or closed issues that are related to my problem
-
-## Description
-
-
-
-### Expected behavior
-
-
-
-### Actual behavior
-
-
-
-### Steps to reproduce the bug
-
-
-
-1. ...
-2. ...
-3. ...
-
-### Package versions
-
-
-
-* Python: `python --version`
-* MkDocs: `mkdocs --version`
-* Material: `pip show mkdocs-material | grep -E ^Version`
-
-### Project configuration
-
-
-
-``` yaml
-The contents of your mkdocs.yml
-```
-
-### System information
-
-
-
-* OS: ...
-* Browser: ...
-
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 4e85845ce94..43c226a6eec 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -20,6 +20,6 @@
blank_issues_enabled: false
contact_links:
- - name: Question
+ - name: Ask a question
url: https://github.com/squidfunk/mkdocs-material/discussions
- about: Please ask your question here
+ about: Have a question or need help? Connect with the community on our discussion board
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
deleted file mode 100644
index 98a6908e5c8..00000000000
--- a/.github/ISSUE_TEMPLATE/feature.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-name: Feature
-about: Suggest an idea
-title: ''
-assignees: ''
----
-
-
-
-- [ ] I've read the [contribution guidelines][1] and agree with them
-
-__I want to suggest an idea and checked that ...__
-
-- [ ] ... to my best knowledge, my idea wouldn't break something for other users
-- [ ] ... the documentation does not mention anything about my idea
-- [ ] ... there are no open or closed issues that are related to my idea
-
-## Description
-
-
-
-### Use Cases
-
-
-
-### Screenshots / Mockups
-
-
-
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md
diff --git a/.github/ISSUE_TEMPLATE/translate.md b/.github/ISSUE_TEMPLATE/translate.md
deleted file mode 100644
index c8626ab9c1f..00000000000
--- a/.github/ISSUE_TEMPLATE/translate.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-name: Translate
-about: 'Help translate Material into more languages '
-title: 'New translation: {Insert language}'
-labels: enhancement
-assignees: ''
----
-
-## Instructions
-
-1. Check, if your language is already available: [here](https://bit.ly/33vFDD0)
-2. If it isn't, please translate the labels on the right:
-
-``` jinja
-{% macro t(key) %}{{ {
- "language": "en",
- "direction": "ltr",
- "clipboard.copy": "Copy to clipboard",
- "clipboard.copied": "Copied to clipboard",
- "edit.link.title": "Edit this page",
- "footer.previous": "Previous",
- "footer.next": "Next",
- "footer.title": "Footer",
- "header.title": "Header",
- "meta.comments": "Comments",
- "meta.source": "Source",
- "nav.title": "Navigation",
- "search.config.lang": "en",
- "search.config.pipeline": "trimmer, stopWordFilter",
- "search.config.separator": "[\s\-]+",
- "search.placeholder": "Search",
- "search.reset": "Clear",
- "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",
- "skip.link.title": "Skip to content",
- "source.link.title": "Go to repository",
- "source.revision.date": "Last update",
- "tabs.title": "Tabs",
- "toc.title": "Table of contents"
-}[key] }}{% endmacro %}
-```
-
-
diff --git a/.github/assets/logo-dark.svg b/.github/assets/logo-dark.svg
new file mode 100644
index 00000000000..8c8b75dae9b
--- /dev/null
+++ b/.github/assets/logo-dark.svg
@@ -0,0 +1,236 @@
+
diff --git a/.github/assets/logo.svg b/.github/assets/logo.svg
index da550f7bfae..e3e17df2ba8 100644
--- a/.github/assets/logo.svg
+++ b/.github/assets/logo.svg
@@ -1,7 +1,7 @@
-
-
-
-
+
+
@@ -230,8 +230,8 @@
Material for MkDocs
-
Technical documentation that just works
-
-
-
+
Documentation that simply works
+
+
+
diff --git a/.github/assets/screenshot.png b/.github/assets/screenshot.png
index 4dc021a321f..7aec41f9a3a 100644
Binary files a/.github/assets/screenshot.png and b/.github/assets/screenshot.png differ
diff --git a/.github/assets/sponsors/basler.png b/.github/assets/sponsors/basler.png
deleted file mode 100644
index 9a180e27016..00000000000
Binary files a/.github/assets/sponsors/basler.png and /dev/null differ
diff --git a/.github/assets/sponsors/cirrus-ci.svg b/.github/assets/sponsors/cirrus-ci.svg
deleted file mode 100644
index 42772694b6f..00000000000
--- a/.github/assets/sponsors/cirrus-ci.svg
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
- Cirrus CI
-
diff --git a/.github/assets/sponsors/sponsor-apex-ai.png b/.github/assets/sponsors/sponsor-apex-ai.png
new file mode 100644
index 00000000000..74ee858693e
Binary files /dev/null and b/.github/assets/sponsors/sponsor-apex-ai.png differ
diff --git a/.github/assets/sponsors/sponsor-automation-technology.png b/.github/assets/sponsors/sponsor-automation-technology.png
new file mode 100644
index 00000000000..7f95476415e
Binary files /dev/null and b/.github/assets/sponsors/sponsor-automation-technology.png differ
diff --git a/.github/assets/sponsors/sponsor-basler.png b/.github/assets/sponsors/sponsor-basler.png
new file mode 100644
index 00000000000..679da9c81aa
Binary files /dev/null and b/.github/assets/sponsors/sponsor-basler.png differ
diff --git a/.github/assets/sponsors/sponsor-cashapp.png b/.github/assets/sponsors/sponsor-cashapp.png
new file mode 100644
index 00000000000..91bc9eba012
Binary files /dev/null and b/.github/assets/sponsors/sponsor-cashapp.png differ
diff --git a/.github/assets/sponsors/sponsor-cirrus-ci.png b/.github/assets/sponsors/sponsor-cirrus-ci.png
new file mode 100644
index 00000000000..7146f8cefcc
Binary files /dev/null and b/.github/assets/sponsors/sponsor-cirrus-ci.png differ
diff --git a/.github/assets/sponsors/sponsor-civic-actions.png b/.github/assets/sponsors/sponsor-civic-actions.png
new file mode 100644
index 00000000000..8da7b9ef445
Binary files /dev/null and b/.github/assets/sponsors/sponsor-civic-actions.png differ
diff --git a/.github/assets/sponsors/sponsor-coda.png b/.github/assets/sponsors/sponsor-coda.png
new file mode 100644
index 00000000000..014934f7516
Binary files /dev/null and b/.github/assets/sponsors/sponsor-coda.png differ
diff --git a/.github/assets/sponsors/sponsor-consensys.png b/.github/assets/sponsors/sponsor-consensys.png
new file mode 100644
index 00000000000..cb221efa24b
Binary files /dev/null and b/.github/assets/sponsors/sponsor-consensys.png differ
diff --git a/.github/assets/sponsors/sponsor-datadog.png b/.github/assets/sponsors/sponsor-datadog.png
new file mode 100644
index 00000000000..8d5c8befcfb
Binary files /dev/null and b/.github/assets/sponsors/sponsor-datadog.png differ
diff --git a/.github/assets/sponsors/sponsor-dogado.png b/.github/assets/sponsors/sponsor-dogado.png
new file mode 100644
index 00000000000..c926c03f514
Binary files /dev/null and b/.github/assets/sponsors/sponsor-dogado.png differ
diff --git a/.github/assets/sponsors/sponsor-eccenca.png b/.github/assets/sponsors/sponsor-eccenca.png
new file mode 100644
index 00000000000..f3c21532e4d
Binary files /dev/null and b/.github/assets/sponsors/sponsor-eccenca.png differ
diff --git a/.github/assets/sponsors/sponsor-elastic.png b/.github/assets/sponsors/sponsor-elastic.png
new file mode 100644
index 00000000000..080d9a00ee3
Binary files /dev/null and b/.github/assets/sponsors/sponsor-elastic.png differ
diff --git a/.github/assets/sponsors/sponsor-elli.png b/.github/assets/sponsors/sponsor-elli.png
new file mode 100644
index 00000000000..3424e1815ae
Binary files /dev/null and b/.github/assets/sponsors/sponsor-elli.png differ
diff --git a/.github/assets/sponsors/sponsor-hummingbot.png b/.github/assets/sponsors/sponsor-hummingbot.png
new file mode 100644
index 00000000000..2d172e7cc7d
Binary files /dev/null and b/.github/assets/sponsors/sponsor-hummingbot.png differ
diff --git a/.github/assets/sponsors/sponsor-hyperledger.png b/.github/assets/sponsors/sponsor-hyperledger.png
new file mode 100644
index 00000000000..460ee088086
Binary files /dev/null and b/.github/assets/sponsors/sponsor-hyperledger.png differ
diff --git a/.github/assets/sponsors/sponsor-ip-fabric.png b/.github/assets/sponsors/sponsor-ip-fabric.png
new file mode 100644
index 00000000000..839944e220f
Binary files /dev/null and b/.github/assets/sponsors/sponsor-ip-fabric.png differ
diff --git a/.github/assets/sponsors/sponsor-jitterbit.png b/.github/assets/sponsors/sponsor-jitterbit.png
new file mode 100644
index 00000000000..aeade4d2c2e
Binary files /dev/null and b/.github/assets/sponsors/sponsor-jitterbit.png differ
diff --git a/.github/assets/sponsors/sponsor-kx.png b/.github/assets/sponsors/sponsor-kx.png
new file mode 100644
index 00000000000..fb2b8adce31
Binary files /dev/null and b/.github/assets/sponsors/sponsor-kx.png differ
diff --git a/.github/assets/sponsors/sponsor-manticore-games.png b/.github/assets/sponsors/sponsor-manticore-games.png
new file mode 100644
index 00000000000..8cbe67af205
Binary files /dev/null and b/.github/assets/sponsors/sponsor-manticore-games.png differ
diff --git a/.github/assets/sponsors/sponsor-n8n.png b/.github/assets/sponsors/sponsor-n8n.png
new file mode 100644
index 00000000000..57fc96906e6
Binary files /dev/null and b/.github/assets/sponsors/sponsor-n8n.png differ
diff --git a/.github/assets/sponsors/sponsor-neptune-ai.png b/.github/assets/sponsors/sponsor-neptune-ai.png
new file mode 100644
index 00000000000..0158c8ebe20
Binary files /dev/null and b/.github/assets/sponsors/sponsor-neptune-ai.png differ
diff --git a/.github/assets/sponsors/sponsor-prefect.png b/.github/assets/sponsors/sponsor-prefect.png
new file mode 100644
index 00000000000..c30ec9e5812
Binary files /dev/null and b/.github/assets/sponsors/sponsor-prefect.png differ
diff --git a/.github/assets/sponsors/sponsor-rackn.png b/.github/assets/sponsors/sponsor-rackn.png
new file mode 100644
index 00000000000..77bf33dc23b
Binary files /dev/null and b/.github/assets/sponsors/sponsor-rackn.png differ
diff --git a/.github/assets/sponsors/sponsor-rstudio.png b/.github/assets/sponsors/sponsor-rstudio.png
new file mode 100644
index 00000000000..06bba300912
Binary files /dev/null and b/.github/assets/sponsors/sponsor-rstudio.png differ
diff --git a/.github/assets/sponsors/sponsor-sealvault.png b/.github/assets/sponsors/sponsor-sealvault.png
new file mode 100644
index 00000000000..2974490fc49
Binary files /dev/null and b/.github/assets/sponsors/sponsor-sealvault.png differ
diff --git a/.github/assets/sponsors/sponsor-sparkfun.png b/.github/assets/sponsors/sponsor-sparkfun.png
new file mode 100644
index 00000000000..e155d95c0ba
Binary files /dev/null and b/.github/assets/sponsors/sponsor-sparkfun.png differ
diff --git a/.github/assets/sponsors/sponsor-wwt.png b/.github/assets/sponsors/sponsor-wwt.png
new file mode 100644
index 00000000000..6bc5148841e
Binary files /dev/null and b/.github/assets/sponsors/sponsor-wwt.png differ
diff --git a/.github/assets/sponsors/sponsor-zenoss.png b/.github/assets/sponsors/sponsor-zenoss.png
new file mode 100644
index 00000000000..fae4549939d
Binary files /dev/null and b/.github/assets/sponsors/sponsor-zenoss.png differ
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000000..3df61b35c40
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,43 @@
+# Copyright (c) 2016-2023 Martin Donath
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+version: 2
+updates:
+- package-ecosystem: npm
+ open-pull-requests-limit: 10
+ directory: "/"
+ labels: []
+ schedule:
+ interval: weekly
+ time: "04:00"
+- package-ecosystem: pip
+ open-pull-requests-limit: 10
+ 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/.github/workflows/build.yml b/.github/workflows/build.yml
index 712e732f124..52b30da895a 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -26,6 +26,9 @@ on:
env:
NODE_VERSION: 14.x
+permissions:
+ contents: read
+
jobs:
build:
name: Build project
@@ -33,26 +36,26 @@ jobs:
steps:
- name: Checkout repository
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
- name: Set up Node.js runtime
- uses: actions/setup-node@v1
+ uses: actions/setup-node@v3
with:
node-version: ${{ env.NODE_VERSION }}
- name: Set up Node.js dependency cache
- uses: actions/cache@v2
+ uses: actions/cache@v3
id: cache
with:
- path: node_modules
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 lint
+ run: npm run check
- name: Build project
run: |
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 286803a5161..4be118233ef 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -27,6 +27,9 @@ on:
env:
PYTHON_VERSION: 3.x
+permissions:
+ contents: write
+
jobs:
documentation:
name: Build documentation
@@ -34,22 +37,54 @@ jobs:
steps:
- name: Checkout repository
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
- name: Set up Python runtime
- uses: actions/setup-python@v1
+ uses: actions/setup-python@v4
with:
python-version: ${{ env.PYTHON_VERSION }}
+ - name: Set up build cache
+ uses: actions/cache@v3
+ id: cache
+ with:
+ key: ${{ runner.os }}-${{ hashFiles('.cache/**') }}
+ path: .cache
+
+ - name: Install dependencies
+ run: sudo apt-get install pngquant
+
- name: Install Python dependencies
run: |
- pip install .
pip install \
- mkdocs-minify-plugin>=0.3 \
- mkdocs-redirects>=1.0
+ "cairosvg>=2.5" \
+ "mkdocs-git-committers-plugin-2>=1.1.1" \
+ "mkdocs-git-revision-date-localized-plugin>=1.0" \
+ "mkdocs-minify-plugin>=0.3" \
+ "mkdocs-rss-plugin>=1.2" \
+ "mkdocs-redirects>=1.0" \
+ "pillow<10"
+
+ - 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
+ rm -rf material
+ cp -r mkdocs-material-insiders/material material
- name: Deploy documentation
env:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
run: |
mkdocs gh-deploy --force
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 3fa0659104b..dab67447da8 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -27,26 +27,29 @@ on:
env:
PYTHON_VERSION: 3.x
+permissions:
+ contents: read
+
jobs:
publish_pypi:
name: Build and push Python package
- if: github.event.pull_request.head.repo.fork == false
+ if: github.event.repository.fork == false
runs-on: ubuntu-latest
steps:
- name: Checkout repository
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
- name: Set up Python runtime
- uses: actions/setup-python@v1
+ uses: actions/setup-python@v4
with:
python-version: ${{ env.PYTHON_VERSION }}
- name: Set up Python dependencies
- run: pip install --upgrade setuptools wheel twine
+ run: pip install --upgrade build twine
- name: Build Python package
- run: python setup.py build sdist bdist_wheel --universal
+ run: python -m build
- name: Publish Python package
env:
@@ -56,30 +59,31 @@ jobs:
publish_docker:
name: Build and push Docker image
- if: github.event.pull_request.head.repo.fork == false
+ if: github.event.repository.fork == false
runs-on: ubuntu-latest
steps:
- name: Checkout repository
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
- name: Login to DockerHub
- uses: docker/login-action@v1
+ uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Login to GitHub Container Registry
- uses: docker/login-action@v1
+ uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GHCR_TOKEN }}
- name: Build Docker image
- uses: docker/build-push-action@v2
+ uses: docker/build-push-action@v3
with:
context: .
+ # platforms: linux/amd64,linux/arm64
tags: |
${{ github.event.repository.full_name }}:latest
${{ github.event.repository.full_name }}:${{ github.event.release.tag_name }}
@@ -87,7 +91,9 @@ jobs:
ghcr.io/${{ github.event.repository.full_name }}:${{ github.event.release.tag_name }}
- name: Check Docker image
- run:
+ working-directory: /tmp
+ run: |
+ docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }} new .
docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }} build
- name: Publish Docker image
diff --git a/.gitignore b/.gitignore
index 76fd1a1ad2c..a5569039b38 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -23,24 +23,30 @@
# -----------------------------------------------------------------------------
# Dependencies
-/node_modules
-/__pycache__
-/venv
+node_modules
+__pycache__
+venv
+.venv
# Build files
-/build
-/MANIFEST
-/site
+build
+site
# Distribution files
-/dist
-/mkdocs_material.egg-info
+dist
+mkdocs_material.egg-info
# Caches and logs
*.cpuprofile
*.log
*.tsbuildinfo
+.cache
.eslintcache
+__pycache__
+
+# Examples
+example
+example.zip
# -----------------------------------------------------------------------------
# General
@@ -61,4 +67,4 @@ TODO
tmp
# IDEs
-.vscode
+.idea
diff --git a/.stylelintignore b/.stylelintignore
index 53f05f0abeb..11c4ddf8eef 100644
--- a/.stylelintignore
+++ b/.stylelintignore
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -23,8 +23,6 @@ docs
material
src/**/*.html
-# Don't lint shame
-src/assets/stylesheets/_shame.scss
-
# Prevent stylelint from constantly complaining
+*.css
*.ts
diff --git a/.stylelintrc b/.stylelintrc
index afae9bfe4d6..395ee8ba587 100644
--- a/.stylelintrc
+++ b/.stylelintrc
@@ -1,13 +1,15 @@
{
"extends": [
+ "stylelint-config-rational-order",
"stylelint-config-recommended",
- "stylelint-config-standard",
- "stylelint-config-rational-order"
+ "stylelint-config-standard-scss"
],
"plugins": [
"stylelint-scss"
],
"rules": {
+ "alpha-value-notation": "number",
+ "annotation-no-unknown": null,
"at-rule-empty-line-before": [
"always",
{
@@ -40,6 +42,7 @@
]
}
],
+ "color-function-notation": null,
"color-hex-length": "long",
"color-named": "never",
"comment-empty-line-before": [
@@ -51,13 +54,23 @@
}
],
"custom-property-empty-line-before": null,
+ "custom-property-pattern": null,
"declaration-colon-space-after": null,
"declaration-no-important": true,
"declaration-block-single-line-max-declarations": 0,
+ "function-calc-no-unspaced-operator": null,
+ "function-no-unknown": null,
"function-url-no-scheme-relative": true,
"function-url-quotes": "always",
"font-family-name-quotes": "always-where-recommended",
"font-weight-notation": "numeric",
+ "hue-degree-notation": "number",
+ "length-zero-no-unit": [
+ true,
+ {
+ "ignore": ["custom-properties"]
+ }
+ ],
"linebreaks": "unix",
"media-feature-name-no-unknown": null,
"no-descending-specificity": null,
@@ -73,8 +86,10 @@
]
}
],
+ "selector-class-pattern": null,
"selector-combinator-space-before": null,
"selector-descendant-combinator-no-non-space": null,
+ "selector-id-pattern": null,
"selector-max-empty-lines": 0,
"selector-max-id": 0,
"selector-no-qualifying-type": null,
@@ -84,16 +99,34 @@
"unicode-bom": "never",
"unit-allowed-list": [
"%",
+ "ch",
"dppx",
"deg",
"em",
+ "fr",
"mm",
"ms",
"px",
"vh",
"vw"
],
+ "value-keyword-case": [
+ "lower",
+ {
+ "ignoreProperties": [
+ "/^--/"
+ ]
+ }
+ ],
"value-list-comma-newline-after": null,
+ "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",
@@ -106,23 +139,22 @@
"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": [
- true,
- {
- "ignore": ["comments"],
- "except": ["function"]
- }
- ],
+ "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/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]+)*$",
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 00000000000..7a34ada8de1
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,17 @@
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Application",
+ "type": "chrome",
+ "request": "launch",
+ "runtimeArgs": [
+ "--disable-features=Translate",
+ "--incognito"
+ ],
+ "url": "http://localhost:8000/mkdocs-material/",
+ "webRoot": "${workspaceFolder}",
+ "smartStep": true
+ }
+ ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000000..36ef96f4058
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,21 @@
+{
+ "git.ignoreLimitWarning": true,
+ "search.exclude": {
+ "**/material": true,
+ "**/node_modules": true,
+ "**/package-lock.json": true
+ },
+ "search.followSymlinks": false,
+ "stylelint.validate": ["css", "scss"],
+ "typescript.tsdk": "node_modules/typescript/lib",
+ "yaml.schemas": {
+ "docs/schema.json": "mkdocs.yml"
+ },
+ "yaml.customTags": [
+ "!ENV scalar",
+ "!ENV sequence",
+ "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+ "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+ ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 00000000000..49179e19df8
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,27 @@
+{
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "label": "Build",
+ "type": "shell",
+ "command": "npm run build",
+ "group": "build",
+ "presentation": {
+ "reveal": "silent"
+ },
+ "problemMatcher": [
+ "$tsc"
+ ]
+ },
+ {
+ "label": "Start and watch for changes",
+ "type": "shell",
+ "command": "npm start",
+ "isBackground": true,
+ "group": "build",
+ "presentation": {
+ "reveal": "silent"
+ }
+ }
+ ]
+}
diff --git a/CHANGELOG b/CHANGELOG
index ad5f1990216..d98b55b258b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,1265 @@
+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 discernability 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://twitter.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 dismissable 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 dismissable 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 dismissable 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)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5710f4aec32..9bcb6bcef4a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,32 +1,32 @@
# Contributing
-Interested in contributing to the Material for MkDocs? Want to report a bug?
-Have a question? Before you do, please read the following guidelines.
+Interested in contributing to the Material for MkDocs? Have a question? Want to
+report a bug? Before you do, please read the following guidelines.
## Submission context
### Got a question or problem?
For quick questions there's no need to open an issue as you can reach us on
-[gitter.im][1].
+[gitter.im].
- [1]: https://gitter.im/squidfunk/mkdocs-material
+ [gitter.im]: https://gitter.im/squidfunk/mkdocs-material
### Found a bug?
If you found a bug in the source code, you can help us by submitting an issue
-to the [issue tracker][2] in our GitHub repository. Even better, you can submit
+to the [issue tracker] in our GitHub repository. Even better, you can submit
a Pull Request with a fix. However, before doing so, please read the
-[submission guidelines][3].
+[submission guidelines].
- [2]: https://github.com/squidfunk/mkdocs-material/issues
- [3]: #submission-guidelines
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [submission guidelines]: #submission-guidelines
### Missing a feature?
You can request a new feature by submitting an issue to our GitHub Repository.
If you would like to implement a new feature, please submit an issue with a
-proposal for your work first, to be sure that it is of use for everyone, as
+proposal for your work first to be sure that it is of use to everyone, as
Material for MkDocs is highly opinionated. Please consider what kind of change
it is:
@@ -40,21 +40,51 @@ it is:
the `master`, as it's always a matter of opinion whether if benefits the
overall functionality of the project.
+### Missing translations?
+
+Material for MkDocs supports 50+ languages with the help of community
+contributions. When new features are added, sometimes, new translations are
+necessary as well. It's impossible for the maintainers of the project to update
+all translations (we just don't speak 50+ languages), so we have to rely on
+our contributors to update translations incrementally. This process is pretty
+simple, so if you find a translation missing in your language, follow these
+guidelines:
+
+1. Fork the repository.
+
+2. Open up the [translation file for your language] as well as the
+ [English translations], as they are always up-to-date. Compare them
+ side-by-side and add the missing translations. __Important__: only add the
+ translations that are different from the defaults, e.g. if your language
+ is left-to-right, don't add the `direction` translation, as English is
+ left-to-right as well. The following translations are for technical
+ purposes and should not be updated, so if they're missing from your
+ language, it's for good reason:
+
+ - `search.config.lang`
+ - `search.config.pipeline`
+ - `search.config.separator`
+
+3. Create a PR (see below) with your changes.
+
+ [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+ [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
## Submission guidelines
### Submitting an issue
Before you submit an issue, please search the issue tracker, maybe an issue for
-your problem already exists and the discussion might inform you of workarounds
+your problem already exists, and the discussion might inform you of workarounds
readily available.
-We want to fix all the issues as soon as possible, but before fixing a bug we
-need to reproduce and confirm it. In order to reproduce bugs we will
+We want to fix all the issues as soon as possible, but before fixing a bug, we
+need to reproduce and confirm it. In order to reproduce bugs, we will
systematically ask you to provide a minimal reproduction scenario using the
custom issue template. Please stick to the issue template.
-Unfortunately we are not able to investigate / fix bugs without a minimal
-reproduction scenario, so if we don't hear back from you we may close the issue.
+Unfortunately, we are not able to investigate / fix bugs without a minimal
+reproduction scenario, so if we don't hear back from you, we may close the issue.
### Submitting a Pull Request (PR)
@@ -62,21 +92,21 @@ Search GitHub for an open or closed PR that relates to your submission. You
don't want to duplicate effort. If you do not find a related issue or PR,
go ahead.
-1. **Development**: Fork the project, set up the [development environment][4],
- make your changes in a separate git branch and add descriptive messages to
- your commits.
+1. **Development**: Fork the project, set up the [development environment],
+ make your changes in a separate git branch and add descriptive messages to
+ your commits.
-2. **Build**: Before submitting a pull requests, [build the theme][5]. This is
- a mandatory requirement for your PR to get accepted, as the theme should at
- all times be installable through GitHub.
+2. **Build**: Before submitting a pull request, [build the theme]. This is
+ a mandatory requirement for your PR to get accepted, as the theme should be
+ installable through GitHub at all times.
-3. **Pull Request**: After building the theme, commit the compiled output, push
- your branch to GitHub and send a PR to `mkdocs-material:master`. If we
- suggest changes, make the required updates, rebase your branch and push the
- changes to your GitHub repository, which will automatically update your PR.
+3. **Pull Request**: After building the theme, commit the compiled output,
+ push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
+ suggest changes, make the required updates, rebase your branch and push the
+ changes to your GitHub repository, which will automatically update your PR.
After your PR is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository.
- [4]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
- [5]: https://squidfunk.github.io/mkdocs-material/customization/#build-process
+ [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
+ [build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme
diff --git a/Dockerfile b/Dockerfile
index 7396918905c..65932963fe6 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2021 Martin Donath
+# Copyright (c) 2016-2023 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -18,48 +18,72 @@
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
-FROM python:3.8.7-alpine3.12
+FROM python:3.11.0-alpine3.17
# Build-time flags
ARG WITH_PLUGINS=true
-# Packages directory
-ENV PACKAGES=/usr/local/lib/python3.8/site-packages
+# 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 MANIFEST.in MANIFEST.in
COPY package.json package.json
COPY README.md README.md
COPY requirements.txt requirements.txt
-COPY setup.py setup.py
+COPY pyproject.toml pyproject.toml
-# Perform build and cleanup artifacts
+# 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 \
- && apk add --no-cache --virtual .build gcc musl-dev \
- && pip install --no-cache-dir . \
- && \
- if [ "${WITH_PLUGINS}" = "true" ]; then \
- pip install --no-cache-dir \
- 'mkdocs-minify-plugin>=0.3' \
- 'mkdocs-redirects>=1.0'; \
- fi \
- && apk del .build gcc musl-dev \
- && \
- for theme in mkdocs readthedocs; do \
- rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
- ln -s \
- ${PACKAGES}/material \
- ${PACKAGES}/mkdocs/themes/$theme; \
- done \
- && rm -rf /tmp/*
+ zlib-dev \
+&& \
+ apk add --no-cache --virtual .build \
+ gcc \
+ libffi-dev \
+ musl-dev \
+&& \
+ pip install --no-cache-dir . \
+&& \
+ if [ "${WITH_PLUGINS}" = "true" ]; then \
+ pip install --no-cache-dir \
+ "mkdocs-minify-plugin>=0.3" \
+ "mkdocs-redirects>=1.0" \
+ "pillow>=9.0" \
+ "cairosvg>=2.5"; \
+ fi \
+&& \
+ apk del .build \
+&& \
+ for theme in mkdocs readthedocs; do \
+ rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
+ ln -s \
+ ${PACKAGES}/material \
+ ${PACKAGES}/mkdocs/themes/$theme; \
+ done \
+&& \
+ rm -rf /tmp/* /root/.cache \
+&& \
+ find ${PACKAGES} \
+ -type f \
+ -path "*/__pycache__/*" \
+ -exec rm -f {} \;
+
+# Trust directory, required for git >= 2.35.2
+RUN git config --global --add safe.directory /docs &&\
+ git config --global --add safe.directory /site
# Set working directory
WORKDIR /docs
diff --git a/LICENSE b/LICENSE
index 0193c63c127..e40940735b7 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2016-2021 Martin Donath
+Copyright (c) 2016-2023 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
diff --git a/MANIFEST.in b/MANIFEST.in
deleted file mode 100644
index 50ff2bbc91a..00000000000
--- a/MANIFEST.in
+++ /dev/null
@@ -1,11 +0,0 @@
-recursive-include material *.js *.css *.map *.html *.svg *.png *.yml
-recursive-include material *.ttf *.woff *.woff2 LICENSE*
-recursive-exclude material/overrides *
-recursive-exclude site *
-recursive-exclude src *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-include LICENSE
-include package.json
-include README.md
-include requirements.txt
diff --git a/README.md b/README.md
index 8035c65bb82..2c6590878f2 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,10 @@
- Create a branded static site from a set of Markdown files to host the
- documentation of your Open Source or commercial project – customizable,
- searchable, mobile-friendly, 40+ languages. Set up in 5 minutes.
+ Write your documentation in Markdown and create a professional static site for
+ your Open Source or commercial project in minutes – searchable, customizable,
+ more than 50 languages, for all devices.
+
+## Everything you would expect
+
+### It's just Markdown
-* **It's just Markdown ...** — write your technical documentation in Markdown –
- no need to know HTML, JavaScript or CSS. Material for MkDocs will do the heavy
- lifting and create a beautiful and functional website.
+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.
-* **... but there's more** — integrates natively with Python Markdown
- Extensions, adding callouts, tabbed content containers, mathematical formulas,
- critic markup, task lists, and [more than 10k icons and emojis][2].
+### Works on all devices
-* **Responsive by design** — built from the ground up to work on all kinds of
- devices – from mobile phones to widescreens. The underlying fluid layout will
- always adapt perfectly to the available screen space.
+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.
-* **Static, but searchable** — almost magically, your technical documentation
- website will be searchable without any further ado. Material for MkDocs comes
- with built-in search – no server needed.
+### Made to measure
-* **Many configuration options** — change the color palette, font families,
- language, icons, favicon and logo. Add a source repository link, links to your
- social profiles, Google Analytics and Disqus - all with a few lines of config.
+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.
-* **Truly international** — thanks to many contributors, Material for MkDocs
- includes translations for more than 40 languages and offers full native RTL
- (right-to-left) support.
+### Fast and lightweight
-* **Accessible** — Material for MkDocs provides extensible keyboard navigation
- and semantic markup including role attributes and landmarks. Furthermore, the
- layout respects the user's default font size.
+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.
-* **Modern architecture** — Material for MkDocs's underlying codebase is built
- on top of TypeScript, RxJS, and SCSS, bringing excellent possibilities for
- theme extension and customization.
+### Built for everyone
-_Material for MkDocs uses the [sponsorware][3] release strategy, which means
-that new features are first exclusively released to sponsors as part of Material
-for MkDocs Insiders. Read on to learn [how sponsorship works][4], and how you
-can [become a sponsor][5]._
+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.
- [2]: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
- [3]: https://github.com/sponsorware/docs
- [4]: https://squidfunk.github.io/mkdocs-material/insiders/#how-sponsorship-works
- [5]: https://squidfunk.github.io/mkdocs-material/insiders/#how-to-become-a-sponsor
+### 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
@@ -112,40 +198,35 @@ Material for MkDocs can be installed with `pip`:
pip install mkdocs-material
```
-Add the following line to `mkdocs.yml`:
+Add the following lines to `mkdocs.yml`:
``` yaml
theme:
name: material
```
-For other installation methods, configuration options, and a demo, visit
-[squidfunk.github.io/mkdocs-material][1]
-
- [1]: https://squidfunk.github.io/mkdocs-material/
-
-## Premium Sponsors
+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 ...
-### ... leading companies
+### ... industry leaders
+[Atlassian](https://atlassian.github.io/data-center-helm-charts/),
[AWS](https://aws.github.io/copilot-cli/),
-[Binance](https://docs.binance.org/),
+[Bloomberg](https://bloomberg.github.io/selekt/),
+[CERN](http://abpcomputing.web.cern.ch/),
[Datadog](https://datadoghq.dev/integrations-core/),
-[Google](https://google.github.io/xls/),
+[Google](https://google.github.io/accompanist/),
+[Hewlett Packard](https://hewlettpackard.github.io/squest/),
[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://www.electionguard.vote/),
+[Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
+[Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
[Netflix](https://netflix.github.io/titus/),
[Salesforce](https://policy-sentry.readthedocs.io/en/latest/),
[SoundCloud](https://intervene.dev/),
@@ -154,17 +235,24 @@ For other installation methods, configuration options, and a demo, visit
### ... and successful Open Source projects
+[Arduino](https://arduino.github.io/arduino-cli/),
[AutoKeras](https://autokeras.com/),
[BFE](https://www.bfe-networks.net/),
+[CentOS](https://docs.infra.centos.org/),
[Crystal](https://crystal-lang.org/reference/),
+[Electron](https://www.electron.build/),
[FastAPI](https://fastapi.tiangolo.com/),
+[GoReleaser](https://goreleaser.com/),
+[Knative](https://knative.dev/docs/),
[Kubernetes](https://kops.sigs.k8s.io/),
[kSQL](https://docs.ksqldb.io/),
+[MindsDB](https://docs.mindsdb.com/),
[Nokogiri](https://nokogiri.org/),
[OpenFaaS](https://docs.openfaas.com/),
+[Percona](https://docs.percona.com/percona-monitoring-and-management/),
[Pi-Hole](https://docs.pi-hole.net/),
[Pydantic](https://pydantic-docs.helpmanual.io/),
-[Renovatebot](https://docs.renovatebot.com/),
+[Renovate](https://docs.renovatebot.com/),
[Traefik](https://docs.traefik.io/),
[Vapor](https://docs.vapor.codes/),
[ZeroNet](https://zeronet.io/docs/),
@@ -174,7 +262,7 @@ For other installation methods, configuration options, and a demo, visit
**MIT License**
-Copyright (c) 2016-2021 Martin Donath
+Copyright (c) 2016-2023 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
diff --git a/docs/alternatives.md b/docs/alternatives.md
new file mode 100644
index 00000000000..f3afe6dcbe2
--- /dev/null
+++ b/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 similarily.
+
+ [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/docs/assets/images/banner.png b/docs/assets/images/banner.png
deleted file mode 100644
index bca0f13fd60..00000000000
Binary files a/docs/assets/images/banner.png and /dev/null differ
diff --git a/docs/assets/images/zelda-dark-world.png b/docs/assets/images/zelda-dark-world.png
new file mode 100644
index 00000000000..275f85876fa
Binary files /dev/null and b/docs/assets/images/zelda-dark-world.png differ
diff --git a/docs/assets/images/zelda-light-world.png b/docs/assets/images/zelda-light-world.png
new file mode 100644
index 00000000000..aaf9f711990
Binary files /dev/null and b/docs/assets/images/zelda-light-world.png differ
diff --git a/docs/assets/screenshots/annotations.png b/docs/assets/screenshots/annotations.png
new file mode 100644
index 00000000000..a4422bc0877
Binary files /dev/null and b/docs/assets/screenshots/annotations.png differ
diff --git a/docs/assets/screenshots/back-to-top.png b/docs/assets/screenshots/back-to-top.png
new file mode 100644
index 00000000000..6771badd429
Binary files /dev/null and b/docs/assets/screenshots/back-to-top.png differ
diff --git a/docs/assets/screenshots/color-palette-toggle.png b/docs/assets/screenshots/color-palette-toggle.png
deleted file mode 100644
index 7915deeb96c..00000000000
Binary files a/docs/assets/screenshots/color-palette-toggle.png and /dev/null differ
diff --git a/docs/assets/screenshots/consent.png b/docs/assets/screenshots/consent.png
new file mode 100644
index 00000000000..2ab700af23a
Binary files /dev/null and b/docs/assets/screenshots/consent.png differ
diff --git a/docs/assets/screenshots/content-tabs-link.png b/docs/assets/screenshots/content-tabs-link.png
new file mode 100644
index 00000000000..c0edb59f713
Binary files /dev/null and b/docs/assets/screenshots/content-tabs-link.png differ
diff --git a/docs/assets/screenshots/content-tabs.png b/docs/assets/screenshots/content-tabs.png
new file mode 100644
index 00000000000..1c68d5b264a
Binary files /dev/null and b/docs/assets/screenshots/content-tabs.png differ
diff --git a/docs/assets/screenshots/diagram.png b/docs/assets/screenshots/diagram.png
deleted file mode 100644
index f2d57d94978..00000000000
Binary files a/docs/assets/screenshots/diagram.png and /dev/null differ
diff --git a/docs/assets/screenshots/feedback-report.png b/docs/assets/screenshots/feedback-report.png
new file mode 100644
index 00000000000..eb7e3be4986
Binary files /dev/null and b/docs/assets/screenshots/feedback-report.png differ
diff --git a/docs/assets/screenshots/hide-navigation-toc.png b/docs/assets/screenshots/hide-navigation-toc.png
index 6df4e9aef4e..12fd440f4b5 100644
Binary files a/docs/assets/screenshots/hide-navigation-toc.png and b/docs/assets/screenshots/hide-navigation-toc.png differ
diff --git a/docs/assets/screenshots/hide-navigation.png b/docs/assets/screenshots/hide-navigation.png
index d1b797033a0..e6c8b346202 100644
Binary files a/docs/assets/screenshots/hide-navigation.png and b/docs/assets/screenshots/hide-navigation.png differ
diff --git a/docs/assets/screenshots/hide-toc.png b/docs/assets/screenshots/hide-toc.png
index faed0dd577c..ab94778640c 100644
Binary files a/docs/assets/screenshots/hide-toc.png and b/docs/assets/screenshots/hide-toc.png differ
diff --git a/docs/assets/screenshots/language-selection.png b/docs/assets/screenshots/language-selection.png
index 08594d9ffeb..964c67193ec 100644
Binary files a/docs/assets/screenshots/language-selection.png and b/docs/assets/screenshots/language-selection.png differ
diff --git a/docs/assets/screenshots/navigation-expand.png b/docs/assets/screenshots/navigation-expand.png
index 34db4c76046..a37c66a090e 100644
Binary files a/docs/assets/screenshots/navigation-expand.png and b/docs/assets/screenshots/navigation-expand.png differ
diff --git a/docs/assets/screenshots/navigation-index-off.png b/docs/assets/screenshots/navigation-index-off.png
index 86beb6f157d..ab3751c4e9d 100644
Binary files a/docs/assets/screenshots/navigation-index-off.png and b/docs/assets/screenshots/navigation-index-off.png differ
diff --git a/docs/assets/screenshots/navigation-index-on.png b/docs/assets/screenshots/navigation-index-on.png
index 5db82df1c42..819069c81c2 100644
Binary files a/docs/assets/screenshots/navigation-index-on.png and b/docs/assets/screenshots/navigation-index-on.png differ
diff --git a/docs/assets/screenshots/navigation-path-off.png b/docs/assets/screenshots/navigation-path-off.png
new file mode 100644
index 00000000000..b212e7839ce
Binary files /dev/null and b/docs/assets/screenshots/navigation-path-off.png differ
diff --git a/docs/assets/screenshots/navigation-path-on.png b/docs/assets/screenshots/navigation-path-on.png
new file mode 100644
index 00000000000..0afb80f6776
Binary files /dev/null and b/docs/assets/screenshots/navigation-path-on.png differ
diff --git a/docs/assets/screenshots/navigation-sections.png b/docs/assets/screenshots/navigation-sections.png
index c846b1913cc..b0edf574498 100644
Binary files a/docs/assets/screenshots/navigation-sections.png and b/docs/assets/screenshots/navigation-sections.png differ
diff --git a/docs/assets/screenshots/navigation-tabs-collapsed.png b/docs/assets/screenshots/navigation-tabs-collapsed.png
index 0e4ed231dfb..1c5d64e21d2 100644
Binary files a/docs/assets/screenshots/navigation-tabs-collapsed.png and b/docs/assets/screenshots/navigation-tabs-collapsed.png differ
diff --git a/docs/assets/screenshots/navigation-tabs-sticky.png b/docs/assets/screenshots/navigation-tabs-sticky.png
index ffe49c415af..b8bd595698b 100644
Binary files a/docs/assets/screenshots/navigation-tabs-sticky.png and b/docs/assets/screenshots/navigation-tabs-sticky.png differ
diff --git a/docs/assets/screenshots/navigation-tabs.png b/docs/assets/screenshots/navigation-tabs.png
index 2fa1bcf4ebe..96af83d513e 100644
Binary files a/docs/assets/screenshots/navigation-tabs.png and b/docs/assets/screenshots/navigation-tabs.png differ
diff --git a/docs/assets/screenshots/navigation.png b/docs/assets/screenshots/navigation.png
index 37792e7407b..82864b525ef 100644
Binary files a/docs/assets/screenshots/navigation.png and b/docs/assets/screenshots/navigation.png differ
diff --git a/docs/assets/screenshots/repository.png b/docs/assets/screenshots/repository.png
deleted file mode 100644
index 726a25bec27..00000000000
Binary files a/docs/assets/screenshots/repository.png and /dev/null differ
diff --git a/docs/assets/screenshots/search-highlighting.png b/docs/assets/screenshots/search-highlighting.png
index b8678cd3ad4..69556e7c121 100644
Binary files a/docs/assets/screenshots/search-highlighting.png and b/docs/assets/screenshots/search-highlighting.png differ
diff --git a/docs/assets/screenshots/search-share.png b/docs/assets/screenshots/search-share.png
index b90f6d74e57..0271ba1b090 100644
Binary files a/docs/assets/screenshots/search-share.png and b/docs/assets/screenshots/search-share.png differ
diff --git a/docs/assets/screenshots/search-suggestions.png b/docs/assets/screenshots/search-suggestions.png
index 44191899a60..20ccde90728 100644
Binary files a/docs/assets/screenshots/search-suggestions.png and b/docs/assets/screenshots/search-suggestions.png differ
diff --git a/docs/assets/screenshots/social-cards.png b/docs/assets/screenshots/social-cards.png
new file mode 100644
index 00000000000..3b348db345d
Binary files /dev/null and b/docs/assets/screenshots/social-cards.png differ
diff --git a/docs/assets/screenshots/tags-index.png b/docs/assets/screenshots/tags-index.png
new file mode 100644
index 00000000000..35de44070d6
Binary files /dev/null and b/docs/assets/screenshots/tags-index.png differ
diff --git a/docs/assets/screenshots/tags-search.png b/docs/assets/screenshots/tags-search.png
new file mode 100644
index 00000000000..4bea8026388
Binary files /dev/null and b/docs/assets/screenshots/tags-search.png differ
diff --git a/docs/assets/screenshots/tags.png b/docs/assets/screenshots/tags.png
new file mode 100644
index 00000000000..9e93a9cd50f
Binary files /dev/null and b/docs/assets/screenshots/tags.png differ
diff --git a/docs/assets/screenshots/toc-integrate.png b/docs/assets/screenshots/toc-integrate.png
index c6080784050..04fe87d5b32 100644
Binary files a/docs/assets/screenshots/toc-integrate.png and b/docs/assets/screenshots/toc-integrate.png differ
diff --git a/docs/assets/screenshots/version-warning.png b/docs/assets/screenshots/version-warning.png
new file mode 100644
index 00000000000..d7262c4d0aa
Binary files /dev/null and b/docs/assets/screenshots/version-warning.png differ
diff --git a/docs/assets/screenshots/versioning.png b/docs/assets/screenshots/versioning.png
index 09898efb7cf..114334c3754 100644
Binary files a/docs/assets/screenshots/versioning.png and b/docs/assets/screenshots/versioning.png differ
diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml
new file mode 100644
index 00000000000..1e2b34d3b96
--- /dev/null
+++ b/docs/blog/.authors.yml
@@ -0,0 +1,4 @@
+squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://avatars.githubusercontent.com/u/932156
diff --git a/docs/blog/.meta.yml b/docs/blog/.meta.yml
new file mode 100644
index 00000000000..ea01dc9ab7a
--- /dev/null
+++ b/docs/blog/.meta.yml
@@ -0,0 +1,3 @@
+comments: true
+hide:
+ - feedback
diff --git a/docs/blog/index.md b/docs/blog/index.md
new file mode 100644
index 00000000000..05761ac57f6
--- /dev/null
+++ b/docs/blog/index.md
@@ -0,0 +1 @@
+# Blog
diff --git a/docs/blog/posts/blog-support-just-landed.md b/docs/blog/posts/blog-support-just-landed.md
new file mode 100644
index 00000000000..6b65a704858
--- /dev/null
+++ b/docs/blog/posts/blog-support-just-landed.md
@@ -0,0 +1,247 @@
+---
+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:
+ - Getting started with Insiders: insiders/getting-started.md#requirements
+ - setup/setting-up-a-blog.md#built-in-blog-plugin
+---
+
+# 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]: ../../setup/setting-up-a-blog.md#built-in-blog-plugin
+ [Jekyll]: https://jekyllrb.com/
+
+## Quick start
+
+### Setting up Insiders
+
+Before we can start bootstrapping a blog and [write our first post], we need to
+set up [Insiders], since the [built-in blog plugin] is currently reserved to
+sponsors. Without the funds this project receives through sponsorships, this
+plugin wouldn't exist. Three steps are necessary:
+
+1. [Subscribe to a monthly sponsorship]
+2. [Create a personal access token]
+3. [Install Insiders]
+
+ [write our first post]: #writing-your-first-post
+ [Insiders]: ../../insiders/index.md
+ [Subscribe to a monthly sponsorship]: ../../insiders/index.md#how-to-become-a-sponsor
+ [Create a personal access token]: ../../insiders/getting-started.md#requirements
+ [Install Insiders]: ../../insiders/getting-started.md#installation
+
+### Creating a standalone blog
+
+After Insiders is installed, 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:
+ - meta
+ - 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]: ../../setup/setting-up-a-blog.md#+blog.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]: ../../setup/setting-up-a-blog.md#+blog.post_url_format
+ [draft]: ../../setup/setting-up-a-blog.md#drafts
+ [This behavior can be changed]: ../../setup/setting-up-a-blog.md#+blog.draft
+ [live preview server]: ../../creating-your-site.md#previewing-as-you-write
+ [archive]: ../../setup/setting-up-a-blog.md#archive
+ [category]: ../../setup/setting-up-a-blog.md#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/docs/blog/posts/blog-support-just-landed/blog.png b/docs/blog/posts/blog-support-just-landed/blog.png
new file mode 100644
index 00000000000..a1ea1eaa05b
Binary files /dev/null and b/docs/blog/posts/blog-support-just-landed/blog.png differ
diff --git a/docs/blog/posts/chinese-search-support.md b/docs/blog/posts/chinese-search-support.md
new file mode 100644
index 00000000000..cf675cd610d
--- /dev/null
+++ b/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
+ - setup/setting-up-site-search.md#chinese-language-support
+ - insiders/index.md#how-to-become-a-sponsor
+---
+
+# 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]: ../../setup/setting-up-site-search.md#built-in-search-plugin
+ [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]: ../../setup/setting-up-site-search.md#separator
+ [q=支持]: ?q=支持
+ [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
diff --git a/docs/blog/posts/excluding-content-from-search.md b/docs/blog/posts/excluding-content-from-search.md
new file mode 100644
index 00000000000..6c7b0d7b5b7
--- /dev/null
+++ b/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/index.md#how-to-become-a-sponsor
+---
+
+# 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
+---
+
+# Document 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
+ # Document 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
+ # Document 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/docs/blog/posts/search-better-faster-smaller.md b/docs/blog/posts/search-better-faster-smaller.md
new file mode 100644
index 00000000000..a6375d86796
--- /dev/null
+++ b/docs/blog/posts/search-better-faster-smaller.md
@@ -0,0 +1,637 @@
+---
+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:
+ - setup/setting-up-site-search.md#built-in-search-plugin
+ - insiders/index.md#how-to-become-a-sponsor
+---
+
+# 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]: ../../setup/setting-up-site-search.md#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]: ../../setup/setting-up-site-search.md#built-in-search-plugin
+
+### 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 :octicons-tag-24: 5.0.0, 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
+ :octicons-tag-24: 5.0.0.
+
+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.
+
+1. __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]: ../../setup/setting-up-site-search.md#search-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:
+
+
+
+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/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#726-_-september-1-2021
+
+#### 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;
+```
+
+Searching for [:octicons-search-24: custom search worker script][q=script]
+brings up the section on [custom search] and matches the `script` tag among the
+other search terms discovered.
+
+---
+
+_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._
+
+ [q=script]: ?q=custom+search+worker+script
+ [custom search]: ../../setup/setting-up-site-search.md#custom-search
+
+### 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:
+
+
+
+ [^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.
+
+ [Twitter survey]: https://twitter.com/squidfunk/status/1434477478823743488
diff --git a/docs/blog/posts/search-better-faster-smaller/search-preview-before.png b/docs/blog/posts/search-better-faster-smaller/search-preview-before.png
new file mode 100644
index 00000000000..7f6fcc8bd99
Binary files /dev/null and b/docs/blog/posts/search-better-faster-smaller/search-preview-before.png differ
diff --git a/docs/blog/posts/search-better-faster-smaller/search-preview-now.png b/docs/blog/posts/search-better-faster-smaller/search-preview-now.png
new file mode 100644
index 00000000000..0935166249a
Binary files /dev/null and b/docs/blog/posts/search-better-faster-smaller/search-preview-now.png differ
diff --git a/docs/blog/posts/search-better-faster-smaller/search-preview.png b/docs/blog/posts/search-better-faster-smaller/search-preview.png
new file mode 100644
index 00000000000..7ca97e1cf37
Binary files /dev/null and b/docs/blog/posts/search-better-faster-smaller/search-preview.png differ
diff --git a/docs/blog/posts/the-past-present-and-future.md b/docs/blog/posts/the-past-present-and-future.md
new file mode 100644
index 00000000000..2cd783f365a
--- /dev/null
+++ b/docs/blog/posts/the-past-present-and-future.md
@@ -0,0 +1,266 @@
+---
+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: anchor links]: ../../reference/code-blocks.md#anchor-links
+ [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#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/index.md#how-to-become-a-sponsor
+
+## 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 Twitter] to stay
+updated.
+
+__Happy new year!__ :tada:
+
+ [Instant previews]: https://twitter.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 Twitter]: https://twitter.com/squidfunk
diff --git a/docs/blog/posts/the-past-present-and-future/funding.png b/docs/blog/posts/the-past-present-and-future/funding.png
new file mode 100644
index 00000000000..d6cf2193ef2
Binary files /dev/null and b/docs/blog/posts/the-past-present-and-future/funding.png differ
diff --git a/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png
new file mode 100644
index 00000000000..22ab1042bb1
Binary files /dev/null and b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png differ
diff --git a/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png
new file mode 100644
index 00000000000..d00c6852033
Binary files /dev/null and b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png differ
diff --git a/docs/browser-support.md b/docs/browser-support.md
new file mode 100644
index 00000000000..e5e3cece8a2
--- /dev/null
+++ b/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 simplemost 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]:
+
+
+
+ [^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
+
+## 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
+ [:octicons-tag-24: 4.6.3][IE support].
+
+ [IE support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.3
diff --git a/docs/changelog.md b/docs/changelog.md
deleted file mode 100644
index f74a8b955c6..00000000000
--- a/docs/changelog.md
+++ /dev/null
@@ -1,1096 +0,0 @@
----
-template: overrides/main.html
----
-
-# Changelog
-
-## Material for MkDocs
-
-### 7.0.3 _ February 26, 2021
-
-- Fixed JavaScript errors in older browsers (target ES2020 -> ES2015)
-
-### 7.0.2 _ February 25, 2021
-
-- 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
-
-- 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
-
-- 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
-
-- Updated Japanese and Polish translations
-- Fixed #2261: Print dialog auto-closing when using instant loading
-
-### 6.2.7 _ January 31, 2021
-
-- Fixed #2251: Updated Docker image to latest Alpine Linux
-
-### 6.2.6 _ January 26, 2021
-
-- Added Bulgarian translations
-- Fixed #2233: Search not shown when using header autohiding
-
-### 6.2.5 _ January 17, 2021
-
-- Fixed syntax error in Swedish translations
-- Optimized navigation partials to improve build speed for huge docs
-
-### 6.2.4 _ January 9, 2021
-
-- Fixed #2156: Missing syntax highlighting for binary numbers
-- Fixed #2186: Disqus showing on 404 page
-
-### 6.2.3 _ December 27, 2020
-
-- Added back hidden overflow on root container
-- Fixed #2142: MathJax formulas sometimes have vertical scrollbars
-
-### 6.2.2 _ December 22, 2020
-
-- Removed Markdown version range limit (6.2.0 regression)
-
-### 6.2.1 _ December 22, 2020
-
-- 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
-
-- 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
-
-- 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
-
-- Fixed #2048: Math formulas show scrollbars (Windows)
-
-### 6.1.5 _ November 15, 2020
-
-- Fixed search reset button not showing/hiding correctly
-
-### 6.1.4 _ November 7, 2020
-
-- Fixed sidebar jitter when scrolling footer into view
-
-### 6.1.3 _ November 5, 2020
-
-- 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
-
-- Fixed sizing of icons in admonitions, task lists, etc. (6.1.1 regression)
-
-### 6.1.1 _ October 31, 2020
-
-- Fixed #2019: Page title not correctly updated when using instant loading
-
-### 6.1.0 _ October 17, 2020
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- Improved spacing around image captions
-- Fixed #1939: Long tables cause header overlap in print view
-
-### 5.5.13 _ September 19, 2020
-
-- Improved abbreviations on touch devices
-
-### 5.5.12 _ August 31, 2020
-
-- Fixed #1638: occasional `404` for images when using instant loading
-
-### 5.5.11 _ August 28, 2020
-
-- Fixed Disqus integration, as the minifier killed the config
-
-### 5.5.10 _ August 28, 2020
-
-- 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
-
-- Added Esperanto translations
-- Fixed #1884: External links not included in navigation tabs
-
-### 5.5.8 _ August 23, 2020
-
-- 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
-
-- 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
-
-- Switched base template for `404.html` to `main.html`
-- Fixed #1864: GitHub organisation stats not loading
-
-### 5.5.5 _ August 11, 2020
-
-- Fixed missing vendor and worker distribution files
-
-### 5.5.4 _ August 11, 2020
-
-- Added support for sortable data tables
-
-### 5.5.3 _ August 4, 2020
-
-- Fixed search for languages other than English (5.5.1 regression)
-
-### 5.5.2 _ August 3, 2020
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- Added Bengali translations
-- Fixed #1773: Search for numbers does not return any result (regression)
-
-### 5.3.2 _ June 21, 2020
-
-- Improved search typeahead experience with non-Latin characters
-- Fixed #1753: Japanese search doesn't work anymore
-
-### 5.3.1 _ June 20, 2020
-
-- Fixed #1761: Duplication of search worker when subscribing to observable
-
-### 5.3.0 _ June 15, 2020
-
-- Added support for color schemes based on user preference
-- Fixed #1755: Tokenizer separator setting ignored
-
-### 5.2.3 _ June 6, 2020
-
-- 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
-
-- Fixed #1728: Legacy Edge doesn't support `deg` values in `hsla` colors
-
-### 5.2.1 _ May 22, 2020
-
-- 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
-
-- Added color schemes implementation + dark mode
-- Fixed #1583: Missing option for separate link colors
-
-### 5.1.7 _ May 16, 2020
-
-- 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
-
-- 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
-
-- 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
-
-- Switched to [@mdi/svg][3] 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
-
- [3]: https://github.com/Templarian/MaterialDesign-SVG
-
-### 5.1.3 _ April 26, 2020
-
-- Fixed overflowing content area after switch to flexbox
-
-### 5.1.2 _ April 26, 2020
-
-- 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
-
-- 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
-
-- Added support for icons from Markdown through [mkdocs-material-extensions][2]
-
- [2]: https://github.com/facelessuser/mkdocs-material-extensions
-
-### 5.0.2 _ April 10, 2020
-
-- 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
-
-- Fixed syntax error in Spanish translation
-
-### 5.0.0 _ April 7, 2020
-
-- 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
-
-- Removed optional third-party plugins from `requirements.txt`
-- Updated Docker image to contain all supported third-party plugins
-
-### 4.6.2 _ February 8, 2020
-
-- Added Romanian translations
-- Fixed #1451: Inconsistent spacing for fenced code blocks
-
-### 4.6.1 _ February 8, 2020
-
-- 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
-
-- Added support for [mkdocs-git-revision-date-localized-plugin][1]
-- Fixed invalid character in Google Fonts URL
-
- [1]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
-
-### 4.5.1 _ December 2, 2019
-
-- Added Thai translations
-- Fixed missing assets in GitHub release `.zip` and `.tar.gz`
-
-### 4.5.0 _ November 16, 2019
-
-- 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
-
-- 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
-
-- 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
-
-- Added support for `black` as a primary color
-- Fixed broken footer bar when `h1` contained HTML tags
-
-### 4.4.0 _ June 15, 2019
-
-- 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
-
-- Fixed spelling error in Danish translations
-
-### 4.3.0 _ May 17, 2019
-
-- 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
-
-- 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
-
-- Fixed #1072: HTML tags appearing in navigation link titles
-
-### 4.1.1 _ March 28, 2019
-
-- Fixed minor CSS errors detected during validation
-
-### 4.1.0 _ March 22, 2019
-
-- 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
-
-- Fixed #1012: HTML character entities appear in search result titles
-
-### 4.0.1 _ February 13, 2019
-
-- Fixed #762, #816: Glitch in sidebar when collapsing items
-- Fixed #869: Automatically expand details before printing
-
-### 4.0.0 _ February 13, 2019
-
-- 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
-
-- 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
-
-- Added support for redirects using metadata refresh
-- Fixed #921: Load Google Analytics snippet asynchronously
-
-### 3.1.0 _ November 17, 2018
-
-- Added support for Progressive Web App Manifest
-- Fixed #915: Search bug in Safari (upgraded Lunr.js)
-
-### 3.0.6 _ October 26, 2018
-
-- Added Taiwanese translations
-- Fixed #906: JavaScript code blocks evaluated in search results
-
-### 3.0.5 _ October 23, 2018
-
-- 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
-
-- Updated Dutch translations
-- Fixed #856: Removed preconnect meta tag if Google Fonts are disabled
-
-### 3.0.3 _ August 7, 2018
-
-- Fixed #841: Additional path levels for extra CSS and JS
-
-### 3.0.2 _ August 6, 2018
-
-- Fixed #839: Lunr.js stemmer imports incorrect
-
-### 3.0.1 _ August 5, 2018
-
-- Fixed #838: Search result links incorrect
-
-### 3.0.0 _ August 5, 2018
-
-- 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
-
-- Fixed build error after MkDocs upgrade
-
-### 2.9.3 _ July 29, 2018
-
-- Added link to home for logo in drawer
-- Fixed dependency problems between MkDocs and Tornado
-
-### 2.9.2 _ June 29, 2018
-
-- Added Hindi and Czech translations
-
-### 2.9.1 _ June 18, 2018
-
-- 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
-
-- Added support for theme color on Android
-- Fixed #796: Rendering of nested tabbed code blocks
-
-### 2.8.0 _ June 10, 2018
-
-- 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
-
-- Added Finnish translations
-
-### 2.7.2 _ April 9, 2018
-
-- Fixed rendering issue for `details` on Edge
-
-### 2.7.1 _ March 21, 2018
-
-- 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
-
-- Added ability to set absolute URL for logo
-- Added Hebrew translations
-
-### 2.6.6 _ February 22, 2018
-
-- 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
-
-- Reverted `--dev-addr` flag removal from `Dockerfile`
-
-### 2.6.4 _ February 21, 2018
-
-- 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
-
-- Added Vietnamese translations
-
-### 2.6.2 _ February 12, 2018
-
-- Added Arabic translations
-- Fixed incorrect rounding of amount of GitHub stars
-- Fixed double-layered borders for tables
-
-### 2.6.1 _ February 11, 2018
-
-- 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
-
-- 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
-
-- Added Hungarian translations
-
-### 2.5.4 _ January 29, 2018
-
-- Fixed #683: `gh-deploy` fails inside Docker
-
-### 2.5.3 _ January 25, 2018
-
-- Added Ukrainian translations
-
-### 2.5.2 _ January 22, 2018
-
-- 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
-
-- 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
-
-- Added support for right-to-left languages
-
-### 2.4.0 _ January 11, 2018
-
-- 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
-
-- Added `example` (synonym: `snippet`) style for admonitions
-- Added synonym `abstract` for `summary` style for admonitions
-
-### 2.2.6 _ December 27, 2017
-
-- Added Turkish translations
-- Fixed unclickable area below header in case JavaScript is not available
-
-### 2.2.5 _ December 18, 2017
-
-- Fixed #639: Broken default favicon
-
-### 2.2.4 _ December 18, 2017
-
-- Fixed #638: Build breaks with Jinja < 2.9
-
-### 2.2.3 _ December 13, 2017
-
-- Fixed #630: Admonition sets padding on any last child
-- Adjusted Chinese (Traditional) translations
-
-### 2.2.2 _ December 8, 2017
-
-- Added Dutch translations
-- Adjusted targeted link and footnote offsets
-- Simplified admonition styles and fixed padding bug
-
-### 2.2.1 _ December 2, 2017
-
-- Fixed #616: Minor styling error with title-only admonitions
-- Removed border for table of contents and improved spacing
-
-### 2.2.0 _ November 22, 2017
-
-- 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
-
-- 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
-
-- 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
-
-- Fixed `details` not opening with footnote reference
-
-### 2.0.3 _ November 5, 2017
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- Added Italian, Norwegian, French and Chinese translations
-
-### 1.12.1 _ October 22, 2017
-
-- 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
-
-- 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
-
-- Added localization to clipboard
-- Refactored localization logic
-
-### 1.10.4 _ October 18, 2017
-
-- 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
-
-- Fixed #484: Vertical scrollbar on some MathJax formulas
-- Fixed #483: Footnote backref target offset regression
-
-### 1.10.2 _ October 6, 2017
-
-- Fixed #468: Sidebar shows scrollbar if content is shorter (in Safari)
-
-### 1.10.1 _ September 14, 2017
-
-- Fixed #455: Bold code blocks rendered with normal font weight
-
-### 1.10.0 _ September 1, 2017
-
-- 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
-
-- 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
-
-- Fixed #421: Missing pagination for GitHub API
-
-### 1.8.0 _ August 2, 2017
-
-- 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
-
-- 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
-
-- Fixed functional link colors in table of contents for active palette
-- Fixed #368: Compatibility issues with IE11
-
-### 1.7.3 _ June 7, 2017
-
-- Fixed error when setting language to Japanese for site search
-
-### 1.7.2 _ June 6, 2017
-
-- Fixed offset of search box when `repo_url` is not set
-- Fixed non-disappearing tooltip
-
-### 1.7.1 _ June 1, 2017
-
-- Fixed wrong `z-index` order of header, overlay and drawer
-- Fixed wrong offset of targeted footnote back references
-
-### 1.7.0 _ June 1, 2017
-
-- 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
-
-- Fixed #337: JavaScript error for GitHub organization URLs
-
-### 1.6.3 _ May 16, 2017
-
-- Fixed #329: Broken source stats for private or unknown GitHub repos
-
-### 1.6.2 _ May 15, 2017
-
-- 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
-
-- Fixed following of active/focused element if search input is focused
-- Fixed layer order of search component elements
-
-### 1.6.0 _ April 22, 2017
-
-- 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
-
-- Fixed #282: Browser search (Meta+F) is hijacked
-
-### 1.5.4 _ April 8, 2017
-
-- 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
-
-- 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
-
-- Added requirements as explicit dependencies in `setup.py`
-- Fixed non-synchronized transitions in search form
-
-### 1.5.1 _ March 30, 2017
-
-- Fixed rendering and offset of targeted footnotes
-- Fixed #238: Link on logo is not set to `site_url`
-
-### 1.5.0 _ March 24, 2017
-
-- 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
-
-- Fixed invalid destructuring attempt on NodeList (in Safari, Edge, IE)
-
-### 1.4.0 _ March 16, 2017
-
-- 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
-
-- 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
-
-- 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
-
-- Fixed incorrectly displayed nested lists when using tabs
-
-### 1.1.0 _ February 26, 2017
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- Fixed #108: Horizontal scrollbar in content area
-
-### 1.0.1 _ January 14, 2017
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- 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
-
-- Initial release
diff --git a/docs/changelog/index.md b/docs/changelog/index.md
new file mode 100644
index 00000000000..4d1d61b0ed6
--- /dev/null
+++ b/docs/changelog/index.md
@@ -0,0 +1,1816 @@
+# Changelog
+
+## Material for MkDocs
+
+### 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 discernability 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://twitter.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 dismissable 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 overriden 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 integation – 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/docs/changelog/insiders.md b/docs/changelog/insiders.md
deleted file mode 100644
index 01ebf8d2192..00000000000
--- a/docs/changelog/insiders.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-template: overrides/main.html
----
-
-# Changelog
-
-## Material for MkDocs Insiders
-
-### 2.0.0 _ February 24, 2021
-
-- Migrated Insiders to the new architecture
-- Swapped color palette toggle configuration
-
-### 1.17.0 _ January 31, 2021
-
-- Added support for section index pages
-
-### 1.16.1 _ January 26, 2021
-
-- 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
-
-- Added latest release to repository info (GitHub)
-- Slight facelift of repository info (lighter fonts, spacing and icons)
-
-### 1.15.0 _ January 2, 2021
-
-- Added support for native Mermaid.js integration
-
-### 1.14.0 _ December 30, 2020
-
-- Added support for sharing searches
-
-### 1.13.2 _ December 22, 2020
-
-- Fixed version selector + sticky tabs navigation rendering issues
-- Fixed version selector wrapping
-
-### 1.13.1 _ December 20, 2020
-
-- Removed horizontal scrollbars on language and version selector
-- Fixed type conversion in JavaScript config
-
-### 1.13.0 _ December 13, 2020
-
-- 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
-
-- Fixed empty language selector being shown
-
-### 1.12.0 _ December 6, 2020
-
-- Added support for adding a language selector
-
-### 1.11.2 _ November 29, 2020
-
-- Fixed #2068: Search highlight interprets code blocks as JavaScript
-
-### 1.11.1 _ November 29, 2020
-
-- Refactored styling to be more stable and easier to adjust
-- Fixed some styling regressions from latest features
-
-### 1.11.0 _ November 22, 2020
-
-- Added support for rendering admonitions as inline blocks
-
-### 1.10.0 _ November 15, 2020
-
-- Added support for integrating table of contents into navigation
-
-### 1.9.0 _ November 7, 2020
-
-- 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
-
-- Added support for navigation sections
-- Fixed appearance of inactive search suggestions
-
-### 1.7.0 _ October 25, 2020
-
-- Added support for deploying multiple versions
-- Fixed alignment of sidebar when content area is too small
-
-### 1.6.0 _ October 11, 2020
-
-- 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
-
-- Fixed content area stretching to whole width for long code blocks
-
-### 1.5.0 _ September 19, 2020
-
-- Added support for autohiding table of contents when empty
-
-### 1.4.1 _ September 6, 2020
-
-- Improved typeahead and search result relevance and scoring
-
-### 1.4.0 _ August 30, 2020
-
-- Added support for autohiding header on scroll
-
-### 1.3.0 _ August 26, 2020
-
-- Added support for user-selectable color palettes
-
-### 1.2.0 _ August 11, 2020
-
-- Added feature to expand navigation by default
-
-### 1.1.0 _ August 3, 2020
-
-- Added highlighting of search results
-
-### 1.0.0 _ July 14, 2020
-
-- Added grouping of search results
-- Added missing query terms to search result
-- Improved search result relevance and scoring
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
new file mode 100644
index 00000000000..11af1a9b48b
--- /dev/null
+++ b/docs/contributing/index.md
@@ -0,0 +1,58 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly improved project
+that caters to a diverse user base with varying backgrounds and needs. In order
+to effectively address the needs of all our users, evaluate requests, and fix
+bugs, a lot of work from us maintainers is required.
+
+## How to contribute
+
+We have invested quite a lot of time in 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. This section of
+the documentation explains each process.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+### Creating an issue
+
+
+
+- :material-bug:{ .lg .middle } __Something is not working?__
+
+ ---
+
+ Report a bug in Material for MkDocs by creating an issue and a reproduction
+
+ [:octicons-arrow-right-24: Report a bug][report a bug]
+
+- :material-file-document:{ .lg .middle } __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:{ .lg .middle } __Want to submit an idea?__
+
+ ---
+
+ Propose a change or feature request or suggest an improvement
+
+ [:octicons-arrow-right-24: Request a change][request a change]
+
+- :material-chat-question:{ .lg .middle } __Have a question or need help?__
+
+ ---
+
+ Ask questions on our discussion board and get in touch with our community
+
+ [:octicons-arrow-right-24: Ask as question][ask a question]
+
+
+
+ [report a bug]: reporting-a-bug.md
+ [report a docs issue]: reporting-a-docs-issue.md
+ [request a change]: requesting-a-change.md
+ [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md
new file mode 100644
index 00000000000..acb6a933d15
--- /dev/null
+++ b/docs/contributing/reporting-a-bug.md
@@ -0,0 +1,314 @@
+# Reporting a bug
+
+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] by 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 try 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]
+ - [`theme.hooks`][theme.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
+ [theme.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 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 the 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
+- [Description]
+- [Related links]
+- [Reproduction]
+- [Steps to reproduce]
+- [Browser] optional
+- [Checklist]
+
+ [Title]: #title
+ [Context]: #context
+ [Description]: #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" } __Generic__ | Please help
+
+### Context optional { #context }
+
+Before describing the bug, 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 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.
+
+### 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 encountered 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 quickly recreate the necessary conditions to inspect
+the bug and 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 a 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]: ../guides/creating-a-reproduction.md#creating-a-zip-file
+
+### Steps to reproduce
+
+At this point, you provided us with enough information to understand the bug,
+and you gave us a reproduction that we can run and inspect. However, when we
+run your reproduction, it might not be immediately apparent how we can see
+the bug in action.
+
+Next, 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 happens 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.
+
+> __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. This section 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.__
+
+## Incomplete issues
+
+Please understand that we reserve the right to close incomplete issues which
+do not contain minimal reproductions or do not adhere to the quality standards
+and requirements mentioned in this document. Issues can be reopened when the
+missing information has been provided.
diff --git a/docs/contributing/reporting-a-docs-issue.md b/docs/contributing/reporting-a-docs-issue.md
new file mode 100644
index 00000000000..ce6cf853c4b
--- /dev/null
+++ b/docs/contributing/reporting-a-docs-issue.md
@@ -0,0 +1,89 @@
+# Reporting a docs issue
+
+In the past 7 years, our documentation has grown to more than 60 pages. With a
+site being this large, inconsistencies can occur. If you found an inconsistency
+or see room for clarification or improvement, please submit an issue to
+our public [issue tracker] by following this guide.
+
+ [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 the following 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
+the 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" } __Generic__ | Please 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 encountered 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__: 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.
+
+### 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__: 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 creating a high-quality and complete issue
+report – you are almost done. This section 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 our documentation.
+
+__We'll take it from here.__
diff --git a/docs/contributing/requesting-a-change.md b/docs/contributing/requesting-a-change.md
new file mode 100644
index 00000000000..cf4ba03f830
--- /dev/null
+++ b/docs/contributing/requesting-a-change.md
@@ -0,0 +1,204 @@
+# Requesting a change
+
+Material for MkDocs is a powerful tool to create beautiful and functional
+project 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 the 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 find answers to the following questions before creating an issue.__
+
+ [philosophy]: ../philosophy.md
+
+### It's not a bug, it's a feature
+
+Change requests are intended for suggesting minor adjustments, ideas for new
+features, or to 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
+
+### Source 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.
+
+### Benefit for the 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.
+
+[:octicons-comment-discussion-16: Start a discussion][Start a discussion]{ .md-button .md-button--primary }
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [Start a discussion]: 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 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 the 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" } __Generic__ | Please 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:[^1]
+
+ [^1]:
+ Sometimes, users suggest ideas on our [issue tracker] that concern one of
+ our upstream dependencies, including [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 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.
+
+ [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
+
+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 the 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 the 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 we need this__: 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 change request guide and creating a high-quality
+change request. This section 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.__
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index 26026ad8add..0a9d141389f 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -1,10 +1,6 @@
----
-template: overrides/main.html
----
-
# Creating your site
-After you've [installed][1] Material for MkDocs, you can bootstrap your project
+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:
@@ -14,7 +10,7 @@ mkdocs new .
Alternatively, if you're running Material for MkDocs from within Docker, use:
-=== "Unix"
+=== "Unix, Powershell"
```
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
@@ -28,98 +24,135 @@ Alternatively, if you're running Material for MkDocs from within Docker, use:
This will create the following structure:
-```
+``` { .sh .no-copy }
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
- [1]: getting-started.md
+ [installed]: getting-started.md
## Configuration
### Minimal configuration
-Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
-since there are several [installation methods][2], configuration might be
-slightly different:
-
-=== "pip, docker"
-
- ``` yaml
- theme:
- name: material
- ```
-
-=== "git"
-
- ``` yaml
- theme:
- name: null
- custom_dir: mkdocs-material/material
-
- # 404 page
- static_templates:
- - 404.html
-
- # Necessary for search to work properly
- include_search_page: false
- search_index_only: true
-
- # Default values, taken from mkdocs_theme.yml
- language: en
- font:
- text: Roboto
- code: Roboto Mono
- favicon: assets/favicon.png
- icon:
- logo: logo
- ```
+Simply add the following lines to `mkdocs.yml` to enable the theme:
-_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
-defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
-[described in the official documentation][4]._
+``` yaml
+theme:
+ name: material
+```
- [2]: getting-started.md#installation
- [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
- [4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
+ [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",
+ "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+ "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+ ]
+ }
+ ```
+
+ 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://twitter.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
+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][5]
-- [Changing the fonts][6]
-- [Changing the language][7]
-- [Changing the logo and icons][8]
-- [Setting up navigation][9]
-- [Setting up site search][10]
-- [Setting up site analytics][11]
-- [Setting up versioning][12]
-- [Setting up the header][13]
-- [Setting up the footer][14]
-- [Adding a git repository][15]
-- [Adding a comment system][16]
+
+
+- [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]
- [5]: setup/changing-the-colors.md
- [6]: setup/changing-the-fonts.md
- [7]: setup/changing-the-language.md
- [8]: setup/changing-the-logo-and-icons.md
- [9]: setup/setting-up-navigation.md
- [10]: setup/setting-up-site-search.md
- [11]: setup/setting-up-site-analytics.md
- [12]: setup/setting-up-versioning.md
- [13]: setup/setting-up-the-header.md
- [14]: setup/setting-up-the-footer.md
- [15]: setup/adding-a-git-repository.md
- [16]: setup/adding-a-comment-system.md
+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
## Previewing as you write
@@ -127,13 +160,22 @@ 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)!
```
-mkdocs serve
-```
+
+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"
+=== "Unix, Powershell"
```
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
@@ -145,12 +187,13 @@ If you're running Material for MkDocs from within Docker, use:
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```
-Point your browser to [localhost:8000][17] and you should see:
+Point your browser to [localhost:8000][live preview] and you should see:
-[![Creating your site][18]][18]
+[![Creating your site]][Creating your site]
- [17]: http://localhost:8000
- [18]: assets/screenshots/creating-your-site.png
+ [--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
@@ -161,10 +204,24 @@ 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][19], [GitLab Pages][20], a CDN of your
-choice or your private web space.
+The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
+or your private web space.
- [19]: publishing-your-site.md#github-pages
- [20]: publishing-your-site.md#gitlab-pages
+ [GitHub Pages]: publishing-your-site.md#github-pages
+ [GitLab pages]: publishing-your-site.md#gitlab-pages
diff --git a/docs/customization.md b/docs/customization.md
index 2a1444383c5..720889dfa19 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -1,7 +1,3 @@
----
-template: overrides/main.html
----
-
# Customization
Project documentation is as diverse as the projects themselves and Material for
@@ -11,19 +7,19 @@ necessary to preserve your brand's style.
## Adding assets
-[MkDocs][1] provides several ways to customize a theme. In order to make a few
-tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
-files to the `docs` directory.
+[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.
- [1]: https://www.mkdocs.org
+ [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 stylesheet. The easiest way is by creating a
-new stylesheet file in the `docs` directory:
+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
+``` { .sh .no-copy }
.
├─ docs/
│ └─ stylesheets/
@@ -31,25 +27,19 @@ new stylesheet file in the `docs` directory:
└─ mkdocs.yml
```
-Then, add the following line to `mkdocs.yml`:
+Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
-Spin up the [live preview server][2] and start typing your changes in your
-additional stylesheet file – you should see them almost instantly after saving.
-
- [2]: creating-your-site.md#previewing-as-you-write
-
### Additional JavaScript
-The same is true for 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:
+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
+``` { .sh .no-copy }
.
├─ docs/
│ └─ javascripts/
@@ -57,30 +47,27 @@ JavaScript file in the `docs` directory:
└─ mkdocs.yml
```
-Then, add the following line to `mkdocs.yml`:
+Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
```
-Further assistance can be found in the [MkDocs documentation][3].
-
- [3]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
-
## 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][4], an easy way to override
+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.
- [4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
+ [theme extension]: https://www.mkdocs.org/user-guide/styling-your-docs/#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` key:
+for `overrides` which you then reference using the [`custom_dir`][custom_dir]
+setting:
``` yaml
theme:
@@ -90,58 +77,72 @@ theme:
!!! warning "Theme extension prerequisites"
- As the `custom_dir` variable is used for the theme extension process,
- Material for MkDocs needs to be installed via `pip` and referenced with the
- `name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.
+ 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.
-
-The directory layout of the theme is as follows:
+assets may also be put in the `overrides` directory:
-``` sh
+``` { .sh .no-copy }
.
├─ .icons/ # Bundled icon sets
├─ assets/
│ ├─ images/ # Images and icons
-│ ├─ javascripts/ # JavaScript
-│ └─ stylesheets/ # Stylesheets
+│ ├─ javascripts/ # JavaScript files
+│ └─ stylesheets/ # Style sheets
├─ partials/
│ ├─ integrations/ # Third-party integrations
-│ │ ├─ analytics.html # - Google Analytics
-│ │ └─ disqus.html # - Disqus
-│ ├─ languages/ # Localized languages
+│ │ ├─ analytics/ # Analytics integrations
+│ │ └─ analytics.html # Analytics setup
+│ ├─ languages/ # Translation languages
+│ ├─ actions.html # Actions
+│ ├─ 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
-│ ├─ language.html # Localized labels
+│ ├─ 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
-│ ├─ palette.html # Color palette
-│ ├─ search.html # Search box
+│ ├─ pagination.html # Pagination (used for blog)
+│ ├─ post.html # Blog post excerpt
+│ ├─ search.html # Search interface
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
-│ ├─ source-date.html # Last updated date
-│ ├─ source-link.html # Link to source file
+│ ├─ 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
├─ 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`, create a `footer.html` file in the `overrides/partials`
+`footer.html` partial, create a new `footer.html` partial in the `overrides`
directory:
-``` sh
+``` { .sh .no-copy }
.
├─ overrides/
│ └─ partials/
@@ -152,21 +153,21 @@ directory:
MkDocs will now use the new partial when rendering the theme. This can be done
with any file.
-### Overriding blocks
+### 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. To override a block, create a `main.html` file inside the `overrides`
-directory:
+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
+``` { .sh .no-copy }
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
```
-Then, e.g. to override the site title, add the following line to `main.html`:
+Then, e.g. to override the site title, add the following lines to `main.html`:
``` html
{% extends "base.html" %}
@@ -176,54 +177,65 @@ Then, e.g. to override the site title, add the following line to `main.html`:
{% endblock %}
```
-Material for MkDocs provides the following template blocks:
-
-| Block name | Wrapped contents |
-| ------------ | ----------------------------------------------- |
-| `analytics` | Wraps the Google Analytics integration |
-| `announce` | Wraps the announcement bar |
-| `config` | Wraps the JavaScript application config |
-| `content` | Wraps the main content |
-| `disqus` | Wraps the Disqus integration |
-| `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) |
-| `scripts` | Wraps the JavaScript application (footer) |
-| `source` | Wraps the linked source files |
-| `site_meta` | Wraps the meta tags in the document head |
-| `site_nav` | Wraps the site navigation and table of contents |
-| `styles` | Wraps the stylesheets (also extra sources) |
-| `tabs` | Wraps the tabs navigation (if available) |
-
-For more on this topic refer to the [MkDocs documentation][5].
-
- [5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
+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][6], [RxJS][7] and [SASS][8],
-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.
+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 version 7.0, the build was based on Webpack. This led to broken
- builds due to frequent incompatibilities with loaders and plugins, so we
- decided to swap Webpack for a leaner custom solution which is now based on
- [RxJS][7] as the application itself. This enabled us to remove more than
- 500 dependencies (~30% less).
+ Prior to :octicons-tag-24: 7.0.0 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).
- [6]: https://www.typescriptlang.org/
- [7]: https://github.com/ReactiveX/rxjs
- [8]: https://sass-lang.com
+ [TypeScript]: https://www.typescriptlang.org/
+ [RxJS]: https://github.com/ReactiveX/rxjs
+ [SASS]: https://sass-lang.com
### Environment setup
-In order to start development on Material for MkDocs, a [Node.js][9] version of
+In order to start development on Material for MkDocs, a [Node.js] version of
at least 14 is required. First, clone the repository:
```
@@ -234,13 +246,13 @@ Next, all dependencies need to be installed, which is done with:
```
cd mkdocs-material
-pip install -r requirements.txt
+pip install -e .
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install
```
- [9]: https://nodejs.org
+ [Node.js]: https://nodejs.org
### Development mode
@@ -250,35 +262,44 @@ Start the watcher with:
npm start
```
-Then, in a second session, start the MkDocs server with:
+Then, in a second terminal window, start the MkDocs live preview server with:
```
-mkdocs serve
+mkdocs serve --watch-theme
```
-Point your browser to [localhost:8000][10] and you should see this documentation
-in front of you.
+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
- overridden when the theme is built.
+ overwritten when the theme is built.
- [10]: http://localhost:8000
+ [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)!
```
-npm run build
-```
-This triggers the production-level compilation and minification of all
-stylesheets and JavaScript sources. When the command exits, the final files are
-located in the `material` directory. Add the `theme_dir` variable pointing to
-the aforementioned directory in the original `mkdocs.yml`.
+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, 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.
-Now you can run `mkdocs build` and you should see your documentation with your
-changes to the original theme.
+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/docs/data-privacy.md b/docs/data-privacy.md
deleted file mode 100644
index 626f26e65cd..00000000000
--- a/docs/data-privacy.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-template: overrides/main.html
----
-
-# Data privacy
-
-In itself, Material for MkDocs does not perform any tracking and should adhere
-to the [General Data Protection Regulation][1] (GDPR), but it integrates with
-some third-party services that may not.
-
- [1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
-
-## Third-party services
-
-### Google Fonts
-
-Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
-CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
-disabled][3] via `mkdocs.yml`.
-
- [2]: setup/changing-the-fonts.md
- [3]: setup/changing-the-fonts.md#disabling-font-loading
-
-### Google Analytics and Disqus
-
-Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
-integrations, both of which must be enabled explicitly, so there's no immediate
-action if you don't use those.
-
- [4]: setup/setting-up-site-analytics.md#google-analytics
- [5]: setup/adding-a-comment-system.md#disqus
diff --git a/docs/deprecations.md b/docs/deprecations.md
deleted file mode 100644
index 3f1b99043cb..00000000000
--- a/docs/deprecations.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-template: overrides/main.html
----
-
-# Deprecations
-
-This page includes a list of deprecations, indicating which features of Material
-for MkDocs were replaced with newer, more flexible alternatives, and thus should
-not be used anymore.
-
-## Front matter
-
-### Redirect
-
-:octicons-archive-24: Deprecated: 5.5 ·
-:octicons-trash-24: Removed: 6.0
-
-The `redirect` key, which could be added via [Metadata][1], allowed to
-specify a redirect from within a document to a new address, which is a good
-idea when moving content around:
-
-``` markdown
----
-redirect: /path/to/new/file
----
-```
-
-The [redirects][2] plugin provides the ability to define redirect mappings via
-`mkdocs.yml`, which is considered to be a much better solution to achieve the
-same result. It can be installed with `pip`:
-
-```
-pip install mkdocs-redirects
-```
-
-Redirect mappings can then be added to `mkdocs.yml`:
-
-``` yaml
-plugins:
- - redirects:
- redirect_maps:
- path/to/old/file.md: path/to/new/file.md
-```
-
- [1]: reference/meta-tags.md#metadata
- [2]: https://github.com/datarobot/mkdocs-redirects
-
-### Source link
-
-:octicons-archive-24: Deprecated: 5.5 ·
-:octicons-trash-24: Removed: 6.0
-
-The `source` and `path` keys, which could be added via [Metadata][1], showed
-a source icon at the top right corner of a document, linking a document to a
-single source file:
-
-``` markdown
----
-path: tree/master/docs
-source: deprecations.md
----
-```
-
-Only a single source file could be linked, which is useless if a document refers
-to multiple files (or multiple sections within a single file). A more flexible
-approach is to use the new [icon integration][3]:
-
-``` markdown
-[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
-```
-
-This will render as [:octicons-file-code-24: Source][4], which can be included
-at arbitrary positions in any document.
-
- [3]: setup/changing-the-logo-and-icons.md#icons
- [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md
-
-### Hero
-
-:octicons-archive-24: Deprecated: 5.5 ·
-:octicons-trash-24: Removed: 6.0
-
-The `hero` key, which could be added via [Metadata][1], allowed to render a
-simple, text-only and page-local teaser text as part of a document. It could
-be set from front matter with:
-
-``` markdown
----
-hero: Lorem ipsum dolor sit amet
----
-```
-
-The recommended way is to [override the `hero` block][5] via [theme
-extension][6] for a specific page, which has the nice side effect that hero
-templates can be shared among multiple pages:
-
-=== "Markdown"
-
- ``` markdown
- ---
- template: overrides/hero.html
- ---
- ```
-
-=== "Template"
-
- ``` html
- {% block hero %}
-
- {% endblock %}
- ```
-
- [5]: customization.md#overriding-blocks
- [6]: customization.md#extending-the-theme
-
-## Docker image
-
-### Bundled plugins
-
-:octicons-archive-24: Deprecated: 5.5 ·
-:octicons-trash-24: Removed: 6.0
-
-Over the last years, the Docker image has continually increased in size. For CI
-it's important that download times are as short as possible, which is why the
-following plugins will be removed:
-
-- [mkdocs-awesome-pages-plugin][7]
-- [mkdocs-git-revision-date-localized-plugin][8]
-
-Note that it's trivial to install plugins inside the Docker image before
-building your documentation. See the [installation guide][9] for a step-by-step
-guide.
-
- [7]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
- [8]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
- [9]: getting-started.md#with-docker
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f0c5f6021d2..bb8a41f5e50 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,80 +1,94 @@
----
-template: overrides/main.html
-title: Getting started
----
-
# Getting started
-Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
+Material for MkDocs is a theme for [MkDocs], a static site generator geared
towards (technical) project documentation. If you're familiar with Python, you
-can install Material for MkDocs with [`pip`][2], the Python package manager.
-If not, we recommended using [`docker`][3].
-
-In case you're running into problems, consult the [troubleshooting][4] section.
+can install Material for MkDocs with [`pip`][pip], the Python package manager.
+If not, we recommend using [`docker`][docker].
- [1]: https://www.mkdocs.org
- [2]: #with-pip
- [3]: #with-docker
- [4]: troubleshooting.md
+ [MkDocs]: https://www.mkdocs.org
+ [pip]: #with-pip
+ [docker]: #with-docker
## Installation
-### with pip
+### with pip recommended { #with-pip data-toc-label="with pip" }
-Material for MkDocs can be installed 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:
-=== "Material for MkDocs"
+=== "Latest"
- ```
+ ``` sh
pip install mkdocs-material
```
-=== "Insiders"
+=== "9.x"
``` sh
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ pip install mkdocs-material=="9.*" # (1)!
```
-This will automatically install compatible versions of all dependencies:
-[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
-Material for MkDocs always strives to support the latest versions, so there's
-no need to install those packages separately.
+ 1. Material for MkDocs uses [semantic versioning][^1], 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:
-_Note that in order to install [Insiders][8], you'll need to [become a
-sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN`
-_environment variable to the token's value._
+ ```
+ pip freeze > requirements.txt
+ ```
+
+ Now, the lockfile can be used for installation:
+
+ ```
+ pip install -r requirements.txt
+ ```
[^1]:
- In order to use `pip` to install from the private repository over HTTPS, the
- [personal access token][14] requires the [`repo`][15] scope. The creation
- and usage of an access token is only necessary when installing Insiders
- over HTTPS, which is the recommended way when building from within a CI/CD
- workflow, e.g. using [GitHub Pages][16] or [GitLab Pages][17].
-
-
- [5]: https://python-markdown.github.io/
- [6]: https://pygments.org/
- [7]: https://facelessuser.github.io/pymdown-extensions/
- [8]: insiders.md
- [9]: insiders.md#how-to-become-a-sponsor
+ 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.
+
+---
+
+__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][10] is a great way to get up and running in a few
-minutes, as it comes with all dependencies pre-installed. Pull the image for the
-`latest` version with:
+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:
-=== "Material for MkDocs"
+=== "Latest"
```
docker pull squidfunk/mkdocs-material
```
-=== "Insiders"
+=== "9.x"
```
- docker login -u ${GH_USERNAME} -p ${GH_TOKEN} ghcr.io
- docker pull ghcr.io/squidfunk/mkdocs-material-insiders
+ docker pull squidfunk/mkdocs-material:9
```
The `mkdocs` executable is provided as an entry point and `serve` is the
@@ -83,31 +97,18 @@ covered in the following sections.
The following plugins are bundled with the Docker image:
-- [mkdocs-minify-plugin][11]
-- [mkdocs-redirects][12]
-
-_Note that in order to install [Insiders][8], you'll need to [become a
-sponsor][9], create a personal access token[^2], and set the_ `GH_TOKEN`
-_environment variable to the token's value._
+- [mkdocs-minify-plugin]
+- [mkdocs-redirects]
- [^2]:
- If you want to use `docker` to pull the private Docker image from the
- [GitHub Container Registry][18], the [personal access token][14] requires
- the [`read:packages`][15] scope. Note that you need to login before pulling
- the Docker image. As an example, see the [`publish`][19] workflow of the
- Material for MkDocs repository. You'll also need to enable "[Improved Container Support][20]"
- on your account.
-
- [10]: https://hub.docker.com/r/squidfunk/mkdocs-material/
- [11]: https://github.com/byrnereese/mkdocs-minify-plugin
- [12]: https://github.com/datarobot/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 bundles useful and common plugins while trying not to
- blow up the size of the official image. If the plugin you want to use is
- not included, create a new `Dockerfile` and extend the official Docker image
- with your custom installation routine:
+ 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,
+ create a new `Dockerfile` and extend the official Docker image:
``` Dockerfile
FROM squidfunk/mkdocs-material
@@ -122,40 +123,34 @@ _environment variable to the token's value._
The new image can be used exactly like the official image.
-### with git
-
-Material for MkDocs can be directly used from [GitHub][13] by cloning the
-repository into a subfolder of your project root which might be useful if you
-want to use the very latest version:
+!!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: Raspberry Pi"
-=== "Material for MkDocs"
+ The official Docker image is only available for `linux/amd64`. We recommend
+ the [third-party image] by @afritzler if you want to run Material for MkDocs
+ via Docker on `arm64` or `armv7`, as it is automatically built on every
+ release:
```
- git clone https://github.com/squidfunk/mkdocs-material.git
+ docker pull ghcr.io/afritzler/mkdocs-material
```
-=== "Insiders"
+ [third-party image]: https://github.com/afritzler/mkdocs-material
- ```
- git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
- ```
+### with git
-The theme will reside in the folder `mkdocs-material/material`. When cloning
-from `git`, you must install all required dependencies yourself:
+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:
```
-pip install -r mkdocs-material/requirements.txt
+git clone https://github.com/squidfunk/mkdocs-material.git
```
-_Note that in order to install [Insiders][8], you'll need to [become a
-sponsor][9]._
+The theme will reside in the folder `mkdocs-material/material`. After cloning
+from `git`, you must install all required dependencies with:
- [13]: https://github.com/squidfunk/mkdocs-material
+```
+pip install -e mkdocs-material
+```
- [14]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
- [15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
- [16]: publishing-your-site.md#github-pages
- [17]: publishing-your-site.md#gitlab-pages
- [18]: https://docs.github.com/en/free-pro-team@latest/packages/getting-started-with-github-container-registry/about-github-container-registry
- [19]: https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/publish.yml
- [20]: https://docs.github.com/en/free-pro-team@latest/packages/guides/enabling-improved-container-support
+ [GitHub]: https://github.com/squidfunk/mkdocs-material
diff --git a/docs/guides/creating-a-reproduction.md b/docs/guides/creating-a-reproduction.md
new file mode 100644
index 00000000000..70a18309589
--- /dev/null
+++ b/docs/guides/creating-a-reproduction.md
@@ -0,0 +1,109 @@
+# 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:
+
+ ``` sh
+ . venv/bin/activate # (1)!
+ ```
+
+ 1. Your terminal should now print `(venv)` before the prompt, which is
+ how you know that you are inside an environment.
+
+- 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 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/#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/docs/index.md b/docs/index.md
index ad49ab43721..cb9f98f4fca 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,4 +1,6 @@
---
-template: overrides/home.html
+template: home.html
title: Material for MkDocs
---
+
+Welcome to Material for MkDocs.
diff --git a/docs/insiders.md b/docs/insiders.md
deleted file mode 100644
index 89d7a5cd465..00000000000
--- a/docs/insiders.md
+++ /dev/null
@@ -1,261 +0,0 @@
----
-template: overrides/main.html
----
-
-# Insiders :logo: :material-plus: :octicons-heart-fill-24:{: .mdx-heart }
-
-Material for MkDocs uses the _sponsorware_ release strategy, which means
-that _new features are first exclusively released to sponsors_ as part of
-__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
-to [get access to Insiders][2].
-
-
-
- [1]: #how-sponsorship-works
- [2]: #how-to-become-a-sponsor
- [3]: https://squidfunk.github.io/mkdocs-material-insiders/
-
-## How sponsorship works
-
-New features first land in Insiders, which means that _sponsors will have access
-immediately_. Every feature is tied to a funding goal in monthly subscriptions.
-When a funding goal is hit, the features that are tied to it are merged back
-into Material for MkDocs and released for general availability. Bugfixes are
-always released simultaneously in both editions.[^1]
-
- [^1]:
- You may ask yourself why you should pay for something that is Open Source.
- Doesn't that contradict the ethos of Open Source software? Yes and no. Yes,
- some features are locked behind a monthly subscription, which means they are
- only accessible when paying a small amount of money. No, the features are
- only exclusive for a short time until specific funding goals are hit. Making
- an Open Source project sustainable is exceptionally hard: maintainers burn
- out, projects are abandoned. That's not great and very unpredictable. The
- sponsorware model ensures that if you decide to use Material for MkDocs,
- you can be sure that bugs are fixed quickly and new features are added
- regularly.
-
-_Don't want to sponsor? No problem, Material for MkDocs already has tons of
-features available, so chances are that most of your requirements are already
-satisfied. See the [list of exclusive features][4] to learn which features are
-currently only available to sponsors._
-
- [4]: #exclusive-features
-
-## How to become a sponsor
-
-You can become a sponsor using your individual or organization's GitHub account.
-Just visit __[squidfunk's sponsor profile][5]__, pick any tier __from
-$10/month__, and complete the checkout. Then, after a few hours, @squidfunk will
-add you as a collaborator to the super-secret private GitHub repositority
-containing the Insiders edition, which contains all [brand new and exclusive
-features][4].
-
-__Important__: If you're sponsoring @squidfunk through a GitHub organization,
-please send a short email to sponsors@squidfunk.com with the name of your
-organization and the account that should be added as a collaborator.[^2]
-
- [^2]:
- It's currently not possible to grant access to each member of an
- organization, as GitHub only allows for adding users. Thus, after
- sponsoring, please send an email to sponsors@squidfunk.com, stating which
- account should become a collaborator of the Insiders repository. We're
- working on a solution which will make access to organizations much simpler.
- To ensure that access is not tied to a particular individual GitHub account,
- create a bot account (i.e. a GitHub account that is not tied to a specific
- individual), and use this account for the sponsoring. After being added to
- the list of collaborators, the bot account can create a private fork of the
- private Insiders GitHub repository, and grant access to all members of the
- organizations.
-
-You can cancel your sponsorship anytime.[^3]
-
- [^3]:
- If you cancel your sponsorship, GitHub schedules a cancellation request
- which will become effective at the end of the billing cycle, which ends at
- the 22nd of a month for monthly sponsorships. This means that even though
- you cancel your sponsorship, you will keep your access to Insiders as long
- as your cancellation isn't effective. All charges are processed by GitHub
- through Stripe. As we don't receive any information regarding your payment,
- and GitHub doesn't offer refunds, sponsorships are non-refundable.
-
-[:octicons-heart-fill-24:{: .mdx-heart } Join our awesome sponsors][5]{: .md-button .md-button--primary .mdx-insiders-button }
-
-
-
- _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._
-
-
-
-
- [5]: https://github.com/sponsors/squidfunk
-
-## Exclusive features
-
-The following features are currently exclusively available to sponsors:
-
-
-
-_New features are added to this list every few weeks, so be sure to come back
-from time to time to learn about what's new, or follow [@squidfunk on
-:fontawesome-brands-twitter:{: .twitter } Twitter][6] to stay updated._
-
- [6]: https://twitter.com/squidfunk
-
-## Funding
-
-### Goals
-
-Following is a list of funding goals. When a funding goal is hit, the features
-that are tied to it are merged back into Material for MkDocs and released to
-the public for general availability.
-
-#### $ 2,000 – Black Pearl
-
-- [x] [Latest release tag][15]
-- [x] [Color palette toggle][16]
-- [ ] Code block palette toggle
-
- [15]: setup/adding-a-git-repository.md#latest-release
- [16]: setup/changing-the-colors.md#color-palette-toggle
-
-#### $ 2,500 – Biquinho Vermelho
-
-- [x] [Search suggestions][17]
-- [x] [Search highlighting][18]
-- [x] [Search sharing][19]
-
- [17]: setup/setting-up-site-search.md#search-suggestions
- [18]: setup/setting-up-site-search.md#search-highlighting
- [19]: setup/setting-up-site-search.md#search-sharing
-
-#### $ 3,000 – Caribbean Red
-
-- [x] [Sticky navigation tabs][20]
-- [x] [Section index pages][21]
-- [x] [Remove generator notice][22]
-
- [20]: setup/setting-up-navigation.md#sticky-navigation-tabs
- [21]: setup/setting-up-navigation.md#section-index-pages
- [22]: setup/setting-up-the-footer.md#remove-generator
-
-
-#### $ 5,000 – Aji Panca
-
-- [x] [Native Mermaid.js integration][23]
-
- [23]: reference/diagrams.md
-
-#### Future
-
-- [ ] [Material for MkDocs Live Edit][24]
-- [ ] Improved search result summaries
-- [ ] List of last searches
-- [ ] Table of contents follows active anchor
-- [ ] Table of contents auto-collapse
-- [ ] Table of contents shows which sections have search results
-- [ ] Native lightbox for (inline) images
-- [ ] New layouts and styles (e.g. vertical)
-- [ ] ... and much more ...
-
- [24]: https://twitter.com/squidfunk/status/1338252230265360391
-
-### Goals completed
-
-#### $ 500 – Madame Jeanette
-
-- [x] Improved search result grouping
-- [x] Improved search result relevance and scoring
-- [x] Missing query terms in search results
-
-#### $ 1,000 – Prairie Fire
-
-- [x] [Navigation sections][7]
-- [x] [Navigation expansion][8]
-- [x] [Hiding the sidebars][9]
-- [x] [Table of contents in navigation][10]
-- [x] [Header hides on scroll][11]
-
- [7]: setup/setting-up-navigation.md#navigation-sections
- [8]: setup/setting-up-navigation.md#navigation-expansion
- [9]: setup/setting-up-navigation.md#hide-the-sidebars
- [10]: setup/setting-up-navigation.md#navigation-integration
- [11]: setup/setting-up-the-header.md#automatic-hiding
-
-#### $ 1,500 – Bhut Jolokia
-
-- [x] [Admonition inline blocks][12]
-- [x] [Site language selection][13]
-- [x] [Versioning][14]
-
- [12]: reference/admonitions.md#inline-blocks
- [13]: setup/changing-the-language.md#site-language-selector
- [14]: setup/setting-up-versioning.md#versioning
-
-## Frequently asked questions
-
-### Compatibility
-
-_We're running an open source project and want to make sure that users can build
-the documentation without having access to Insiders. Is this still possible?_
-
-Yes. Insiders is compatible with Material for MkDocs. All new features are
-implemented behind feature flags; all configuration changes are
-backward-compatible. This means that your users will be able to build the
-documentation locally with Material for MkDocs and when they push their changes,
-it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][25] only in CI, as you don't want to expose
-your `GH_TOKEN` to users.
-
- [25]: publishing-your-site.md#github-pages
-
-### Terms
-
-_We're using Material for MkDocs to build the developer documentation of a
-commercial project. Can we use Insiders under the same terms and conditions?_
-
-Yes. Whether you're an individual or a company, you may use _Material for MkDocs
-Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][26]. However, we kindly ask you to respect the following
-guidelines:
-
-- Please __don't distribute the source code__ of Insiders. You may freely use
- it for public, private or commercial projects, fork it, mirror it, do whatever
- you want with it, but please don't release the source code, as it would
- counteract the sponsorware strategy.
-
-- If you cancel your subscription, you're removed as a collaborator and will
- miss out on future updates of Insiders. However, you may __use the latest
- version__ that's available to you __as long as you like__. Just remember that
- [GitHub deletes private forks][27].
-
- [26]: license.md
- [27]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
new file mode 100644
index 00000000000..2bf0b2822ce
--- /dev/null
+++ b/docs/insiders/changelog.md
@@ -0,0 +1,704 @@
+# Changelog
+
+## Material for MkDocs Insiders
+
+### 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 obervables
+- 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 dismissable 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 integation – 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 intergration, 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/docs/insiders/getting-started.md b/docs/insiders/getting-started.md
new file mode 100644
index 00000000000..8b8157dfe95
--- /dev/null
+++ b/docs/insiders/getting-started.md
@@ -0,0 +1,211 @@
+---
+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 similarily 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]: index.md#how-to-become-a-sponsor
+
+## 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
+
+## Installation
+
+### with pip
+
+Material for MkDocs Insiders can be installed with `pip`:
+
+``` sh
+pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+```
+
+The `GH_TOKEN` environment variable must be 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.
+
+### 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
+```
+
+ [^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 disables 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
+
+## Upgrading
+
+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 `8.x.x`:
+
+```
+8.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. If you installed Insiders via `pip`, you
+can upgrade your installation with the following command:
+
+```
+pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+```
+
+ [upgrade guide]: ../upgrade.md
+
+## Caveats
+
+This section describes some aspects to consider when using Insiders together
+with Material for MkDocs to ensure that users without access to Insiders can
+still build your documentation.
+
+### Built-in plugins
+
+When using built-in plugins that are solely available via Insiders, it might be
+necessary to split the `mkdocs.yml` configuration into a base configuration, and
+one with plugin overrides. Note that this is a limitation of MkDocs, which can
+be mitigated by using [configuration inheritance]:
+
+=== ":octicons-file-code-16: `mkdocs.insiders.yml`"
+
+ ``` yaml
+ INHERIT: mkdocs.yml
+ plugins:
+ - search
+ - social
+ - tags
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ # Configuration with everything except Insiders plugins
+ ```
+
+Now, when you're in an environment with access to Insiders (e.g. in your CI
+pipeline), you can build your documentation project with the following lines:
+
+```
+mkdocs build --config-file mkdocs.insiders.yml
+```
+
+!!! tip "Sharing plugin and extension configuration"
+
+ If you want to share `plugins` or `markdown_extensions` between both
+ configuration files `mkdocs.insiders.yml` and `mkdocs.yml`, you can use
+ the alternative key-value syntax in both files. The above example would
+ then look like:
+
+ === ":octicons-file-code-16: `mkdocs.insiders.yml`"
+
+ ``` yaml
+ INHERIT: mkdocs.yml
+ plugins:
+ social: {}
+ ```
+
+ === ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ # Additional configuration above
+ plugins:
+ search: {}
+ tags: {}
+ ```
+
+
+ [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
new file mode 100644
index 00000000000..85cef750b7e
--- /dev/null
+++ b/docs/insiders/index.md
@@ -0,0 +1,523 @@
+---
+title: Insiders
+---
+
+# Insiders
+
+Material for MkDocs follows the __sponsorware__ release strategy, which means
+that new features are first exclusively released to sponsors as part of
+[Insiders]. Read on to learn [what sponsorships achieve],
+[how to become a sponsor] to get access to Insiders, and [what's in it for you]!
+
+
+
+ [Insiders]: #what-is-insiders
+ [what sponsorships achieve]: #what-sponsorships-achieve
+ [how to become a sponsor]: #how-to-become-a-sponsor
+ [what's in it for you]: #whats-in-it-for-me
+ [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+
+## What is Insiders?
+
+Material for MkDocs Insiders is a private fork of Material for MkDocs, hosted as
+a private GitHub repository. Almost[^1] [all new features][what's in it for you]
+are developed as part of this fork, which means that they are immediately
+available to all eligible sponsors, as they are made collaborators of this
+repository.
+
+ [^1]:
+ In general, every new feature is first exclusively released to sponsors, but
+ sometimes upstream dependencies like [Python Markdown Extensions] enhance
+ existing features that must be supported by Material for MkDocs.
+
+Every feature is tied to a [funding goal] in monthly subscriptions. When a
+funding goal is hit, the features that are tied to it are merged back into
+Material for MkDocs and released for general availability, making them available
+to all users. Bugfixes are always released in tandem.
+
+Sponsorships start as low as [__$15 a month__][how to become a sponsor].[^2]
+
+ [^2]:
+ Note that $15 a month is the minimum amount to become eligible for
+ Insiders. While GitHub Sponsors also allows to sponsor lower amounts or
+ one-time amounts, those can't be granted access to Insiders due to
+ technical reasons.
+
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [funding goal]: #funding
+
+## What sponsorships achieve
+
+Sponsorships make this project sustainable, as they buy the maintainers of this
+project time – a very scarce resource – which is spent on the development of new
+features, bug fixing, stability improvement, issue triage and general support.
+The biggest bottleneck in Open Source is time.[^3]
+
+ [^3]:
+ Making an Open Source project sustainable is exceptionally hard: maintainers
+ burn out, projects are abandoned. That's not great and very unpredictable.
+ The sponsorware model ensures that if you decide to use Material for MkDocs,
+ you can be sure that bugs are fixed quickly and new features are added
+ regularly.
+
+If you're unsure if you should sponsor this project, check out the list of
+[completed funding goals] to learn whether you're already using features that
+were developed with the help of sponsorships. You're most likely using at least
+a handful of them, [thanks to our awesome sponsors]!
+
+ [completed funding goals]: #goals-completed
+ [thanks to our awesome sponsors]: #how-to-become-a-sponsor
+
+
+
+## What's in it for me?
+
+The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
+access to 22 additional features__ that you can start using right away, and
+which are currently exclusively available to sponsors:
+
+
+
+New features are added every other week. Be sure to come back.
+
+## How to become a sponsor
+
+Thanks for your interest in sponsoring! In order to become an eligible sponsor
+with your GitHub account, visit [squidfunk's sponsor profile], and complete
+a sponsorship of __$15 a month or more__. You can use your individual or
+organization GitHub account for sponsoring.
+
+__Important__: If you're sponsoring @squidfunk through a GitHub organization,
+please send a short email to sponsors@squidfunk.com with the name of your
+organization and the GitHub account of the individual that should be added as a
+collaborator.[^4]
+
+You can cancel your sponsorship anytime.[^5]
+
+ [^4]:
+ It's currently not possible to grant access to each member of an
+ organization, as GitHub only allows for adding users. Thus, after
+ sponsoring, please send an email to sponsors@squidfunk.com, stating which
+ account should become a collaborator of the Insiders repository. We're
+ working on a solution which will make access to organizations much simpler.
+ To ensure that access is not tied to a particular individual GitHub account,
+ create a bot account (i.e. a GitHub account that is not tied to a specific
+ individual), and use this account for the sponsoring. After being added to
+ the list of collaborators, the bot account can create a private fork of the
+ private Insiders GitHub repository, and grant access to all members of the
+ organizations.
+
+ [^5]:
+ If you cancel your sponsorship, GitHub schedules a cancellation request
+ which will become effective at the end of the billing cycle. This means
+ that even though you cancel your sponsorship, you will keep your access to
+ Insiders as long as your cancellation isn't effective. All charges are
+ processed by GitHub through Stripe. As we don't receive any information
+ regarding your payment, and GitHub doesn't offer refunds, sponsorships are
+ non-refundable.
+
+[:octicons-heart-fill-24:{ .mdx-heart } Join our awesome sponsors][squidfunk's sponsor profile]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+
+
+
+
+
+ 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.
+
+
+
+ [squidfunk's sponsor profile]: https://github.com/sponsors/squidfunk?metadata_origin=docs
+
+## 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. When the funding goal is hit, the features
+are released for general availability.
+
+#### $ 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
+
+#### $ 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
+ [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
+
+#### $ 16,000 – Chipotle
+
+- [x] [Meta plugin]
+- [x] [Blog plugin: related links]
+- [x] [Blog plugin: custom index pages]
+- [x] [Tags plugin: additional indexes]
+- [x] [Tags plugin: allow list] and [custom sorting]
+- [x] [Navigation subtitles]
+
+ [Meta plugin]: ../reference/index.md#built-in-meta-plugin
+ [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: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
+ [Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
+ [custom sorting]: ../setup/setting-up-tags.md#+tags.tags_compare
+ [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
+
+#### $ 20,000 – Jalapeño
+
+- [x] [Optimize plugin]
+- [x] [Typeset plugin]
+- [x] [Privacy plugin: external links]
+- [x] [Navigation path] (Breadcrumbs)
+- [ ] Privacy plugin: optimization support
+- [ ] Code block line wrapping
+
+ [Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
+ [Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
+ [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.external_links
+ [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
+ [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
+
+#### $ 24,000 – Blockpaprika
+
+- [ ] [Instant previews]
+
+### Goals completed
+
+This section lists all funding goals that were previously completed, which means
+that those features were part of Insiders, but are now generally available and
+can be used by all users.
+
+#### $ 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: anchor links]: ../reference/code-blocks.md#anchor-links
+ [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
+
+## Frequently asked questions
+
+### Compatibility
+
+_We're building an open source project and want to allow outside collaborators
+to run and build our documentation locally without having access to Insiders.
+Is this still possible?_
+
+Yes. Insiders is compatible with Material for MkDocs. Almost all new features
+and configuration options are either backward-compatible or implemented behind
+feature flags. When working with outside collaborators, it should be rarely
+necessary to change the general appearance of your site. Most Insiders features
+enhance the overall experience, e.g. by adding icons to pages or providing a
+feedback widget. While this features add value for the user of your site, they
+shouldn't be necessary for previewing when making changes to content. Currently,
+the only content-related features in Insiders that can't be properly previewed
+by non-Insiders users are:
+
+- [Annotations]
+- [Card grids]
+
+This means that outside collaborators are able to build the documentation
+locally with Material for MkDocs and when they push their changes, your CI
+pipeline will build it with Insiders. When using built-in plugins that are
+exclusive to Insiders, it's recommended to split configuration into a base
+`mkdocs.yml` and one with plugin overrides via [configuration inheritance].
+
+See the [getting started guide] for more information.
+
+ [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
+ [getting started guide]: getting-started.md#caveats
+
+### Payment
+
+_We don't want to pay for sponsorship every month. Are there any other options?_
+
+Yes. You can sponsor on a yearly basis by [switching your GitHub account to a
+yearly billing cycle][billing cycle]. If for some reason you cannot do that, you
+could also create a dedicated GitHub account with a yearly billing cycle, which
+you only use for sponsoring (some sponsors already do that).
+
+If you have any problems or further questions, please reach out to
+sponsors@squidfunk.com.
+
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+
+### Terms
+
+_Are we allowed to use Insiders under the same terms and conditions as
+Material for MkDocs?_
+
+Yes. Whether you're an individual or a company, you may use _Material for MkDocs
+Insiders_ precisely under the same terms as Material for MkDocs, which are given
+by the [MIT license]. However, we kindly ask you to respect our
+__fair use policy__:
+
+- Please __don't distribute the source code__ of Insiders. You may freely use
+ it for public, private or commercial projects, privately fork or mirror it,
+ but please don't make the source code public, as it would counteract the
+ sponsorware strategy.
+
+- If you cancel your subscription, you're automatically removed as a
+ collaborator and will miss out on all future updates of Insiders. However, you
+ may __use the latest version__ that's available to you __as long as you like__.
+ Just remember that [GitHub deletes private forks].
+
+ [MIT license]: ../license.md
+ [GitHub deletes private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
diff --git a/docs/license.md b/docs/license.md
index 72def8a6127..9ac1b94f890 100644
--- a/docs/license.md
+++ b/docs/license.md
@@ -1,12 +1,8 @@
----
-template: overrides/main.html
----
-
# License
**MIT License**
-Copyright (c) 2016-2021 Martin Donath
+Copyright (c) 2016-2023 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
diff --git a/docs/philosophy.md b/docs/philosophy.md
new file mode 100644
index 00000000000..13960e9629f
--- /dev/null
+++ b/docs/philosophy.md
@@ -0,0 +1,94 @@
+# 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
+
+## 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 20,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.
+
+## Conventions
+
+### 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:
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders }
+
+: Some features are not yet available in the community edition, but only as
+ part of the Insiders build of Material for MkDocs. Please consult the
+ [Insiders] guide to learn how to get access.
+
+:octicons-tag-24: __{x.x.x}__
+
+: The tag icon 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.
+
+:octicons-file-code-24: __{file.ext}__
+
+: The source file icon together with a file name is sometimes used in code
+ examples which span multiple files. The file name (or path) always starts
+ from the location of `mkdocs.yml`.
+
+:octicons-milestone-24: __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.
+
+:octicons-unlock-24: __Feature flag__
+
+: 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.
+
+:octicons-beaker-24: __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).
+
+
+:octicons-cpu-24: __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.
+
+:octicons-package-24: __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/docs/publishing-your-site.md b/docs/publishing-your-site.md
index 17f16015334..89eae489c4e 100644
--- a/docs/publishing-your-site.md
+++ b/docs/publishing-your-site.md
@@ -1,7 +1,3 @@
----
-template: overrides/main.html
----
-
# Publishing your site
The great thing about hosting project documentation in a `git` repository is
@@ -10,15 +6,15 @@ makes this ridiculously simple.
## GitHub Pages
-If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly
+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.
- [1]: https://pages.github.com/
+ [GitHub Pages]: https://pages.github.com/
### with GitHub Actions
-Using [GitHub Actions][2] you can automate the deployment of your project
+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:
@@ -26,24 +22,45 @@ contents:
=== "Material for MkDocs"
``` yaml
- name: ci
+ name: ci # (1)!
on:
push:
branches:
- - master
+ - master # (2)!
- main
+ permissions:
+ contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v2
- - uses: actions/setup-python@v2
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
with:
python-version: 3.x
- - run: pip install mkdocs-material
+ - uses: actions/cache@v2
+ with:
+ key: ${{ github.ref }}
+ path: .cache
+ - run: pip install mkdocs-material # (3)!
- 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. 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
@@ -53,35 +70,52 @@ contents:
branches:
- master
- main
+ permissions:
+ contents: write
jobs:
deploy:
runs-on: ubuntu-latest
- if: github.event.pull_request.head.repo.fork == false
+ if: github.event.repository.fork == false
steps:
- - uses: actions/checkout@v2
- - uses: actions/setup-python@v2
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
with:
python-version: 3.x
+ - uses: actions/cache@v2
+ with:
+ key: ${{ github.ref }}
+ path: .cache
+ - 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 }}
+ 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` environment variable 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.
-Your documentation should shortly appear at `.github.io/`.
+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`.
-_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
-[personal access token][3] when deploying [Insiders][4], which can be done
-using [secrets][5]._
+Your documentation should shortly appear at `.github.io/`.
- [2]: https://github.com/features/actions
- [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
- [4]: insiders.md
- [5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
+ [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]: setup/building-an-optimized-site.md#built-in-optimize-plugin
+ [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
### with MkDocs
@@ -94,10 +128,10 @@ mkdocs gh-deploy --force
## GitLab Pages
-If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be
-done by using the [GitLab CI][7] task runner. At the root of your repository,
-create a task definition named `.gitlab-ci.yml` and copy and paste the
-following contents:
+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"
@@ -105,14 +139,14 @@ following contents:
image: python:latest
pages:
stage: deploy
- only:
- - master
script:
- pip install mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
+ rules:
+ - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```
=== "Insiders"
@@ -121,26 +155,26 @@ following contents:
image: python:latest
pages:
stage: deploy
- only:
- - master
- script:
+ 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` environment variable 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 `master`, 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/`.
-_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
-[personal access token][3] when deploying [Insiders][4], which can be done
-using [masked custom variables][8]._
-
- [6]: https://gitlab.com/pages
- [7]: https://docs.gitlab.com/ee/ci/
- [8]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
+ [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
diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md
deleted file mode 100644
index 2b3c9949913..00000000000
--- a/docs/reference/abbreviations.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-template: overrides/main.html
----
-
-# Abbreviations
-
-Technical documentation often incurs the usage of a lot of 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
-
-### Abbreviations
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Abbreviations][2] extension, which is part of the standard Markdown
-library, allows to __add additional content to parts of the text which are then
-shown on hover__, e.g. for glossaries:
-
-``` yaml
-markdown_extensions:
- - abbr
-```
-
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
- [2]: https://python-markdown.github.io/extensions/abbreviations/
-
-### Snippets
-
-The [Snippets][3] extension, which is part of [Python Markdown Extensions][4],
-allows to __insert content from other files__ or other, regular content, and can
-be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
- - pymdownx.snippets
-```
-
- [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
- [4]: https://facelessuser.github.io/pymdown-extensions/
-
-## Usage
-
-### Adding abbreviations
-
-When the [Abbreviations][5] extension is enabled, abbreviations can be defined
-with a special syntax similar to URLs and [footnotes][6] at any point in the
-Markdown document.
-
-_Example_:
-
-``` markdown
-The HTML specification is maintained by the W3C.
-
-*[HTML]: Hyper Text Markup Language
-*[W3C]: World Wide Web Consortium
-```
-
-_Result_:
-
-The HTML specification is maintained by the W3C.
-
-*[HTML]: Hyper Text Markup Language
-*[W3C]: World Wide Web Consortium
-
- [5]: #abbreviations_1
- [6]: footnotes.md
-
-### Adding a glossary
-
-When [Snippets][7] is enabled, content from other files can be embedded, which
-is especially useful to include abbreviations from a central file – a glossary –
-and embed them into any other file.
-
-_Example_:
-
-=== "docs/page.md"
-
- ```` markdown
- The HTML specification is maintained by the W3C.
-
- --8<-- "includes/abbreviations.md"
- ````
-
-=== "includes/abbreviations.md"
-
- ```` markdown
- *[HTML]: Hyper Text Markup Language
- *[W3C]: World Wide Web Consortium
- ````
-
-_Result_:
-
-The HTML specification is maintained by the W3C.
-
-_Remember to locate the Markdown file containing the definitions outside of the_
-`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
-unreferenced file._
-
- [7]: #snippets
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index 655e4ab15bb..4eac4d2661e 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -1,5 +1,5 @@
---
-template: overrides/main.html
+icon: material/alert-outline
---
# Admonitions
@@ -11,67 +11,116 @@ inclusion and nesting of arbitrary content.
## Configuration
-### Admonition
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Admonition][2] extension, which is part of the standard Markdown
-library, is integrated with Material for MkDocs and can be enabled via
+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
```
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss
- [2]: https://python-markdown.github.io/extensions/admonition/
-
-### Details
+See additional configuration options:
-[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
+- [Admonition]
+- [Details]
+- [SuperFences]
-The [Details][4] extension, which is part of [Python Markdown Extensions][5],
-adds the ability to __make admonitions collapsible__. It can be enabled via
-`mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
- - pymdownx.details
-```
+ [Admonition]: ../setup/extensions/python-markdown.md#admonition
+ [Details]: ../setup/extensions/python-markdown-extensions.md#details
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
- [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_details.scss
- [4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
- [5]: https://facelessuser.github.io/pymdown-extensions/
+### Admonition icons
-### SuperFences
+[:octicons-tag-24: 8.3.0][Admonition icons support]
-The [SuperFences][6] extension, which is also part of [Python Markdown
-Extensions][5], allows for the __nesting of code and content blocks inside
-admonitions__, and is therefore strongly recommended:
+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
-markdown_extensions:
- - pymdownx.superfences
+theme:
+ icon:
+ admonition:
+ : # (1)!
```
- [6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-## Usage
+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
+ ```
+
+ [Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [supported types]: #supported-types
+ [icon search]: icons-emojis.md#search
-Admonitions follow a simple syntax: a block must start with `!!!`, followed
-by a single keyword which is used as the [type qualifier][7] of the block. The
-content of the block then follows on the next line, indented by four spaces.
+## Usage
-_Example_:
+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
+``` 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.
```
-_Result_:
+
!!! note
@@ -79,24 +128,25 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
- [7]: #supported-types
+
+
+ [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.
-
-_Example_:
+links, formatting, ...) after the type qualifier:
-``` markdown
+``` 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.
```
-_Result_:
+
!!! note "Phasellus posuere in sem ut cursus"
@@ -104,99 +154,50 @@ _Result_:
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][8], 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][9].
+
-_Example_:
-
-``` markdown
-!!! 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.
-```
+### Removing the title
-_Result_:
+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.
-
- [8]: #changing-the-title
- [9]: #collapsible-blocks
-
-### Embedded content
-
-Admonitions can contain all kinds of text content, including headlines, lists,
-paragraphs and other blocks. While the parser from the standard Markdown library
-doesn't account for nested blocks, the [SuperFences][10] extension adds the
-ability to nest arbitrary content inside admonitions.
-
-_Example_:
-
-``` markdown
-!!! 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.
-
- ``` python
- 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]
- ```
-
- Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
- sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
- Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
```
-_Result_:
+
-!!! note
+!!! 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.
- ``` python
- 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]
- ```
-
- Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
- sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
- Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
+
- [10]: #superfences
+ [changing the title]: #changing-the-title
+ [collapsible blocks]: #collapsible-blocks
### Collapsible blocks
-The [Details][11] extension adds support for rendering collapsible admonition
-blocks. This is useful for FAQs or content that is of secondary nature. A
-details block follows the syntax and semantics of admonition blocks, but must
-start with `???`.
-
-_Example_:
+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
+``` 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.
```
-_Result_:
+
??? note
@@ -204,18 +205,19 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
-Adding a `+` after `???` will render the block as open on page load:
+
-_Example_:
+Adding a `+` after the `???` token renders the block expanded:
-``` markdown
+``` 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.
```
-_Result_:
+
???+ note
@@ -223,20 +225,15 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
- [11]: #details
+
### Inline blocks
-[:octicons-file-code-24: Source][12] ·
-:octicons-beaker-24: Experimental
-
-Admonitions and [Details][11] can also be rendered as inline blocks (i.e.
-sidebars), moving them to the right using the `inline` + `end` modifiers, or
-to the left using only the `inline` modifier.
+Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
+them to the right using the `inline` + `end` modifiers, or to the left using
+only the `inline` modifier:
-=== "inline end"
-
- _Example_ / _Result_:
+=== ":octicons-arrow-right-16: inline end"
!!! info inline end
@@ -246,6 +243,7 @@ to the left using only the `inline` modifier.
``` markdown
!!! info inline end
+
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
@@ -255,9 +253,7 @@ to the left using only the `inline` modifier.
Use `inline end` to align to the right (left for rtl languages).
-=== "inline"
-
- _Example_ / _Result_:
+=== ":octicons-arrow-left-16: inline"
!!! info inline
@@ -267,6 +263,7 @@ to the left using only the `inline` modifier.
``` markdown
!!! info inline
+
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
@@ -276,18 +273,25 @@ to the left using only the `inline` modifier.
Use `inline` to align to the left (right for rtl languages).
-_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._
-
- [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_modifiers.scss
+__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`:
+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`{: #note }, `seealso`
+[`note`](#type:note){ #type:note }
: !!! note
@@ -295,7 +299,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`abstract`{: #abstract }, `summary`, `tldr`
+[`abstract`](#type:abstract){ #type:abstract }
: !!! abstract
@@ -303,7 +307,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`info`{: #info }, `todo`
+[`info`](#type:info){ #type:info }
: !!! info
@@ -311,7 +315,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`tip`{: #tip }, `hint`, `important`
+[`tip`](#type:tip){ #type:tip }
: !!! tip
@@ -319,7 +323,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`success`{: #success }, `check`, `done`
+[`success`](#type:success){ #type:success }
: !!! success
@@ -327,7 +331,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`question`{: #question }, `help`, `faq`
+[`question`](#type:question){ #type:question }
: !!! question
@@ -335,7 +339,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`warning`{: #warning }, `caution`, `attention`
+[`warning`](#type:warning){ #type:warning }
: !!! warning
@@ -343,7 +347,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`failure`{: #failure }, `fail`, `missing`
+[`failure`](#type:failure){ #type:failure }
: !!! failure
@@ -351,7 +355,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`danger`{: #danger }, `error`
+[`danger`](#type:danger){ #type:danger }
: !!! danger
@@ -359,7 +363,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`bug`{: #bug }
+[`bug`](#type:bug){ #type:bug }
: !!! bug
@@ -367,7 +371,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`example`{: #example }
+[`example`](#type:example){ #type:example }
: !!! example
@@ -375,7 +379,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
-`quote`{: #quote }, `cite`
+[`quote`](#type:quote){ #type:quote }
: !!! quote
@@ -385,35 +389,51 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
## Customization
+### Classic admonitions
+
+Prior to version [:octicons-tag-24: 8.5.6][Admonition modern], 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
+ ```
+
+[Admonition modern]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.6
+
### Custom admonitions
If you want to add a custom admonition type, all you need is a color and an
-`svg` icon. Copy the icon's `svg` code from the [`.icons`][13] folder and add the
-following CSS to an [additional stylesheet][14]:
-
-``` 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);
-}
-```
-
-You should now be able to create an admonition of the `pied-piper` type. Note
-that you can also use this technique to override existing admonition icons or
-colors. [You can even add animations][15].
+`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
+and add the following CSS to an [additional style sheet]:
-_Example_:
+=== ":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
+``` 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.
+
+ 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.
```
-_Result_:
+
!!! pied-piper "Pied Piper"
@@ -452,6 +502,7 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
- [13]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
- [14]: ../customization.md#additional-css
- [15]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+
+
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
new file mode 100644
index 00000000000..8d15e3d07cd
--- /dev/null
+++ b/docs/reference/annotations.md
@@ -0,0 +1,210 @@
+---
+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
+
+## Usage
+
+### Using annotations
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.6.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Annotations consist of two parts: a marker, which can be placed anywhere in
+a block marked with the `annotate` class, and content located in a list below
+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.
+
+ [Insiders]: ../insiders/index.md
+
+#### 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/docs/reference/buttons.md b/docs/reference/buttons.md
index 4e670b2ae03..963c70e1b58 100644
--- a/docs/reference/buttons.md
+++ b/docs/reference/buttons.md
@@ -1,5 +1,5 @@
---
-template: overrides/main.html
+icon: material/button-cursor
---
# Buttons
@@ -10,74 +10,75 @@ useful for documents or landing pages with dedicated _call-to-actions_.
## Configuration
-### Attribute List
-
-The [Attribute List][1] extension, which is part of the standard Markdown
-library, allows to __add HTML attributes and CSS classes to Markdown elements__,
-and can be enabled via `mkdocs.yml`
+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
```
- [1]: https://python-markdown.github.io/extensions/attr_list/
+See additional configuration options:
+
+- [Attribute Lists]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
## Usage
### Adding buttons
-When the [Attribute List][2] extension is enabled, any clickable element can be
-converted into a button by adding the `.md-button` CSS class, which will receive
-the selected [primary color][3].
+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.
-_Example_:
-
-``` markdown
-[Subscribe to our mailing list](#){: .md-button }
+``` markdown title="Button"
+[Subscribe to our newsletter](#){ .md-button }
```
-_Result_:
+
-### Adding primary buttons
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [Demo]: javascript:alert$.next("Demo")
-If you want to display a filled, primary button (like on the [landing page][5]
-of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
-CSS classes.
+### Adding primary buttons
-_Example_:
+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
-[Subscribe to our mailing list](#){: .md-button .md-button--primary }
+``` markdown title="Button, primary"
+[Subscribe to our newsletter](#){ .md-button .md-button--primary }
```
-_Result_:
+
-[Subscribe to our mailing list][4]{: .md-button .md-button--primary }
+[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
- [5]: ../index.md
+
-### Adding icon buttons
+ [landing page]: ../index.md
-Of course, icons can be added to both types of buttons by using the [regular
-icon syntax][6] and referencing a valid path to [any icon bundled with the
-theme][7].
+### Adding icon buttons
-_Example_:
+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
-[Submit :fontawesome-solid-paper-plane:](#){: .md-button .md-button--primary }
+``` markdown title="Button with icon"
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
```
-_Result_:
+
- [6]: icons-emojis.md#using-icons
- [7]: icons-emojis.md#search
+ [icon syntax]: icons-emojis.md#using-icons
+ [icon search]: icons-emojis.md#search
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index f81ff4d0743..8dd03408049 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -1,222 +1,272 @@
---
-template: overrides/main.html
+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][1] or
+highlighting for code blocks, either during build time using [Pygments] or
during runtime using a JavaScript syntax highlighter.
- [1]: https://pygments.org
+ [Pygments]: https://pygments.org
## Configuration
-### Highlight
+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`:
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
-:octicons-zap-24: Supersedes: [CodeHilite][4]
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets
+ - pymdownx.superfences
+```
-The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
-integrates with Material for MkDocs and provides several options for
-configuring syntax highlighting of code blocks:
+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.
-`use_pygments`{: #use-pygments }
+See additional configuration options:
-: :octicons-milestone-24: Default: `true` – This option allows to control
- whether highlighting should be carried out during build time by
- [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
- necessary [additional stylesheets][6] and [JavaScript][7] if you want to
- use the latter:
+- [Highlight]
+- [InlineHilite]
+- [SuperFences]
+- [Snippets]
- === "Pygments"
+ [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
- ``` yaml
- markdown_extensions:
- - pymdownx.highlight
- - pymdownx.superfences
- ```
+### Code copy button
- === "JavaScript"
+[:octicons-tag-24: 9.0.0][Code copy button support] ·
+:octicons-unlock-24: Feature flag
- ``` yaml
- markdown_extensions:
- - pymdownx.highlight:
- use_pygments: false
- ```
+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:
- ??? example "Syntax highlighting with Highlight.js"
+``` yaml
+theme:
+ features:
+ - content.code.copy
+```
- [Highlight.js][8] can be integrated by creating an [additional
- JavaScript][7] file initializing the highlighter and including the
- respective stylesheet and JavaScript from a [CDN][9] serving
- Highlight.js in `mkdocs.yml`:
+ [Code copy button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
- === "docs/javascripts/config.js"
+??? info "Enabling or disabling code copy buttons for a specific code block"
- ``` js
- hljs.initHighlighting()
- ```
+ 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:
- === "mkdocs.yml"
+ ```` yaml
+ ``` { .yaml .copy }
+ # Code block content
+ ```
+ ````
- ``` yaml
- extra_javascript:
- - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
- - javascripts/config.js
- extra_css:
- - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css
- ```
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`. Similarily, the copy button can also be disabled for a
+ specific code block:
- Note that Highlight.js has no affiliation with the Highlight extension.
+ ```` { .yaml .no-copy }
+ ``` { .yaml .no-copy }
+ # Code block content
+ ```
+ ````
-`linenums`{: #linenums }
+### Code annotations
-: :octicons-milestone-24: Default: `false` – 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][10] later in this
- document, which also contains some tips on working with line numbers:
+[:octicons-tag-24: 8.0.0][Code annotations support] ·
+:octicons-unlock-24: Feature flag
- ``` yaml
- markdown_extensions:
- - pymdownx.highlight:
- linenums: true
- ```
+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:
-`linenums_style`{: #linenums-style }
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)!
+```
-: :octicons-milestone-24: Default: `table` – The Highlight extension provides
- three ways to add line numbers, all of which are supported by Material for
- MkDocs. While `table` wraps a code block in a table, `inline` and
- `pymdownx.inline` render line numbers as part of the line itself:
+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
- markdown_extensions:
- - pymdownx.highlight:
- linenums_style: pymdownx.inline
- ```
+??? 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:
- 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 `table` or
- `pymdownx.inline` is recommended.
+ ```` yaml
+ ``` { .yaml .annotate }
+ # Code block content
+ ```
+ ````
-_Material for MkDocs doesn't provide official support for the other options of
-this extension, so they may be supported but can also yield weird results. Use
-them at your own risk._
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`.
- [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
- [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
- [4]: https://python-markdown.github.io/extensions/code_hilite/
- [5]: https://facelessuser.github.io/pymdown-extensions/
- [6]: ../customization.md#additional-css
- [7]: ../customization.md#additional-javascript
- [8]: https://highlightjs.org/
- [9]: https://cdnjs.com/libraries/highlight.js/
- [10]: #adding-line-numbers
+ [Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
-### InlineHilite
+#### Anchor links
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
+[:octicons-tag-24: 8.5.0][Anchor links support] ·
+:octicons-beaker-24: Experimental
-The [InlineHilite][11] extension, which is part of [Python Markdown
-Extensions][5] also integrates with Material for MkDocs and adds support for
-__syntax highlighting of inline code blocks__. It's built on top of the
-[Highlight][3] extension and can be enabled via `mkdocs.yml`:
+In order to be able to link to code annotations and share them more easily, an
+anchor link is automatically added to each annotation, which you can copy via
+right click or open in a new tab:
``` yaml
-markdown_extensions:
- - pymdownx.inlinehilite
+# (1)!
```
-See the section on [inline code blocks][12] for usage information.
+1. If you ++cmd++ :material-plus::material-cursor-default-outline: me, I'm
+ rendered open in a new tab. You can also right-click me to __copy link
+ address__ to share me with others.
- [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
- [12]: #highlighting-inline-code-blocks
+ [Anchor links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-### Keys
+## Usage
-[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
+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:
-The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
-allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
-can be enabled via `mkdocs.yml`:
+```` markdown title="Code block"
+``` py
+import tensorflow as tf
+```
+````
-``` yaml
-markdown_extensions:
- - pymdownx.keys
+
-### SuperFences
+ [list of available lexers]: https://pygments.org/docs/lexers/
-The [SuperFences][15] extension, which is also part of [Python Markdown
-Extensions][5], allows for the __nesting of code blocks inside other blocks__,
-and is therefore strongly recommended:
+### Adding a title
-``` yaml
-markdown_extensions:
- - pymdownx.superfences
+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]
```
- [15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
-### Snippets
+### Adding annotations
-The [Snippets][16] extension, which is also part of [Python Markdown
-Extensions][5], allows to __insert content from other files__ or other, regular
-content, and can be enabled via `mkdocs.yml`:
+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
-markdown_extensions:
- - pymdownx.snippets
+theme:
+ features:
+ - content.code.annotate # (1)
```
- [16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+````
-## Usage
+
-This section discusses how to use different syntax highlighting features with
-[Pygments][1] – the default highlighter – so they don't apply when using
-a JavaScript syntax highlighter.
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)
+```
-### Specifying the language
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
-Code blocks must be enclosed with two separate lines containing three backticks.
-To add code highlighting to those blocks, add the language short name directly
-after the opening block. See the [list of available lexers][17] to find the
-short name for a given language.
+
-_Example_:
+#### Stripping comments
-```` markdown
-``` python
-import tensorflow as tf
+[:octicons-tag-24: 8.5.0][Stripping comments support] ·
+:octicons-beaker-24: Experimental
+
+If you wish to strip the comment characters surrounding a code annotation,
+simply add an `!` after the closing parenthesis of the code annotation:
+
+```` markdown title="Code block with annotation, stripped"
+``` yaml
+# (1)!
```
+
+1. Look ma, less line noise!
````
-_Result_:
+
-``` python
-import tensorflow as tf
+``` yaml
+# (1)!
```
- [17]: https://pygments.org/docs/lexers/
+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.
+
+ [Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
### Adding line numbers
Line numbers can be added to a code block by using the `linenums=""`
-option directly after the short name, whereas `` represents the starting
+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 splitting large code blocks for readability.
-
-_Example_:
+allows to split large code blocks for readability:
-```` markdown
-``` python linenums="1"
+```` 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):
@@ -225,9 +275,9 @@ def bubble_sort(items):
```
````
-_Result_:
+
-``` python linenums="1"
+``` py linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
@@ -235,16 +285,17 @@ def bubble_sort(items):
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 short name. Note that line counts start
-at `1`, regardless of the starting line number specified as part of `linenums`.
-
-_Example_:
+argument placed right after the language shortcode. Note that line counts start
+at `1`, regardless of the starting line number specified as part of
+[`linenums`][Adding line numbers]:
-```` markdown
-``` python hl_lines="2 3"
+```` 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):
@@ -253,9 +304,9 @@ def bubble_sort(items):
```
````
-_Result_:
+
-``` python hl_lines="2 3"
+``` 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):
@@ -263,125 +314,180 @@ def bubble_sort(items):
items[j], items[j + 1] = items[j + 1], items[j]
```
-### Highlighting inline code blocks
+
+
+ [Adding line numbers]: #adding-line-numbers
-When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
-prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
-the [language short name][17].
+### Highlighting inline code blocks
-_Example_:
+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
+``` markdown title="Inline code block"
The `#!python range()` function is used to generate a sequence of numbers.
```
-_Result_:
+
The `#!python range()` function is used to generate a sequence of numbers.
- [18]: #inlinehilite
+
-### Adding keyboard keys
+### Embedding external files
-When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
-Consult the [Python Markdown Extensions][16] documentation to learn about all
-available key codes.
+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"
+```
+````
-_Example_:
+
-++ctrl+alt+del++
+ [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
- [19]: #keys
+## Customization
-### Embedding external files
+### Custom syntax theme
-_Also known as transcludes or file transclusion in [MultiMarkdown][20]_.
+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`
-When [Snippets][21] is enabled, content from other files can be embedded, which
-is especially useful to reference and embed the contents of source files
-directly into your project documentation.
+Code block foreground, background and line highlight colors are defined via:
-_Example_:
+- :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`
-```` markdown
-```
---8<-- ".browserslistrc"
-```
-````
+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]:
-_Result_:
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
-```
-last 4 years
-```
+ ``` css
+ :root > * {
+ --md-code-hl-string-color: #0FF1CE;
+ }
+ ```
-Note that [Snippets][21] is not limited to code blocks, but can be used anywhere
-from a document to move repeating content to separate files, which is also
-explained in the [official documentation][16].
+=== ":octicons-file-code-16: `mkdocs.yml`"
- [20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
- [21]: #snippets
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
-## Customization
+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]:
-### Custom syntax theme
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
-[:octicons-file-code-24: Source][22] ·
-:octicons-mortar-board-24: Difficulty: _easy_
-
-If [Pygments][23] is used, Material for MkDocs provides the [styles for code
-blocks][22], which are built with a custom and well-balanced palette that works
-equally well for both [color schemes][24]:
-
-- :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`
+ ``` css
+ .highlight .sb {
+ color: #0FF1CE;
+ }
+ ```
-Code block foreground, background and line highlight colors are defined via:
+=== ":octicons-file-code-16: `mkdocs.yml`"
-- :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`
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
-Let's say you want to change the color of `#!js "strings"`. While there are
-several [types of string tokens][25], Material for MkDocs assigns a single color
-to most of them.
+ [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [types of string tokens]: https://pygments.org/docs/tokens/#literals
+ [additional style sheet]: ../customization.md#additional-css
+ [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
-Create an [additional stylesheet][6], and add:
+### Annotation tooltip width
-``` css
-:root > * {
- --md-code-hl-string-color: #0FF1CE;
-}
-```
+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
+ ```
-If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
-can lookup the specific class name in the [syntax theme definition][26], and
-override it as part of your additional stylesheet:
+This will render annotations with a larger width:
-``` css
-.highlight .sb {
- color: #0FF1CE;
-}
+
+
+``` yaml
+# (1)!
```
- [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
- [23]: #use-pygments
- [24]: ../setup/changing-the-colors.md#color-scheme
- [25]: https://pygments.org/docs/tokens/#literals
- [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss
+1. Muuuuuuuuuuuuuuuch more space for content
+
+
+
+### Annotations with numbers
+
+Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
+were rendered with markers showing the original number as used by the author.
+However, for technical reasons code annotation numbers restart each code block,
+which might lead to confusion. For this reason, code annotations now render as
+`+` signs which are rotated if they're open to denote that clicking them again
+will close them.
+
+If you wish to revert to the prior behavior and display code annotation numbers,
+you can add an [additional style sheet] and copy and paste the following CSS:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .md-typeset .md-annotation__index > ::before {
+ content: attr(data-md-annotation-id);
+ }
+ .md-typeset :focus-within > .md-annotation__index > ::before {
+ transform: none;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+ [code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index 4d459cf38d4..fc01226d7d6 100644
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@@ -1,43 +1,109 @@
---
-template: overrides/main.html
+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.
+environments. Material for MkDocs allows for beautiful and functional tabs,
+grouping code blocks and other content.
## Configuration
-### Tabbed
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
-integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:
+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.tabbed
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
```
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss
- [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
- [3]: https://facelessuser.github.io/pymdown-extensions/
+See additional configuration options:
+
+- [SuperFences]
+- [Tabbed]
+
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+ [Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
+
+### Anchor links
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.17.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+In order to link to content tabs and share them more easily, [Insiders] adds
+an anchor link to each content tab automatically, which you can copy via right
+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:
-### SuperFences
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ Fore more information, please [see the extension guide][slugification].
+
+ [Insiders]: ../insiders/index.md
+ [tab_1]: #-or-even-me
+ [tab_2]: ../publishing-your-site.md#insiders
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [slugification]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.tabbed.slugify
+
+### Linked content tabs
-The [SuperFences][4] extension, which is also part of [Python Markdown
-Extensions][3], allows for the __nesting of code and content blocks inside
-tabs__, and is therefore strongly recommended:
+[:octicons-tag-24: 8.3.0][Linked content tabs support] ·
+:octicons-unlock-24: Feature flag
+
+When enabled, all content tabs across the whole documentation site will be
+linked and switch to the same label when the user clicks on a tab. Add the
+following lines to `mkdocs.yml`:
``` yaml
-markdown_extensions:
- - pymdownx.superfences
+theme:
+ features:
+ - content.tabs.link
```
- [4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+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]
+
+ [Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
+ [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
## Usage
@@ -45,11 +111,9 @@ markdown_extensions:
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.
-
-_Example_:
+rendered without horizontal spacing:
-```
+``` title="Content tabs with code blocks"
=== "C"
``` c
@@ -73,7 +137,7 @@ _Example_:
```
```
-_Result_:
+
=== "C"
@@ -97,15 +161,15 @@ _Result_:
}
```
+
+
### 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.
-
-_Example_:
+by nesting tabs in other blocks:
-```
+``` title="Content tabs"
=== "Unordered list"
* Sed sagittis eleifend rutrum
@@ -119,7 +183,7 @@ _Example_:
3. Nulla tempor lobortis orci
```
-_Result_:
+
=== "Unordered list"
@@ -133,86 +197,54 @@ _Result_:
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
+
+
### Embedded content
-When [SuperFences][5] is enabled, content tabs can contain arbitrary nested
+When [SuperFences] is enabled, content tabs can contain arbitrary nested
content, including further content tabs, and can be nested in other blocks like
-[admonitions][6], [details][7] or blockquotes:
+[admonitions] or blockquotes:
-_Example_:
-
-``` markdown
+``` title="Content tabs in admonition"
!!! example
=== "Unordered List"
- _Example_:
-
``` markdown
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
```
- _Result_:
-
- * Sed sagittis eleifend rutrum
- * Donec vitae suscipit est
- * Nulla tempor lobortis orci
-
=== "Ordered List"
- _Example_:
-
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
-
- _Result_:
-
- 1. Sed sagittis eleifend rutrum
- 2. Donec vitae suscipit est
- 3. Nulla tempor lobortis orci
```
-_Result_:
+
!!! example
=== "Unordered List"
- _Example_:
-
``` markdown
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
```
- _Result_:
-
- * Sed sagittis eleifend rutrum
- * Donec vitae suscipit est
- * Nulla tempor lobortis orci
-
=== "Ordered List"
- _Example_:
-
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
- _Result_:
-
- 1. Sed sagittis eleifend rutrum
- 2. Donec vitae suscipit est
- 3. Nulla tempor lobortis orci
+
- [5]: #superfences
- [6]: admonitions.md
- [7]: admonitions.md#details
+ [admonitions]: admonitions.md
diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md
index 59f5aab6b6f..03b91d6a968 100644
--- a/docs/reference/data-tables.md
+++ b/docs/reference/data-tables.md
@@ -1,32 +1,40 @@
---
-template: overrides/main.html
+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][1] can be achieved with a third-party library and some
-[additional JavaScript][2].
+like [sortable tables] can be achieved with a third-party library and some
+[additional JavaScript].
- [1]: #sortable-tables
- [2]: ../customization.md#additional-javascript
+ [sortable tables]: #sortable-tables
+ [additional JavaScript]: ../customization.md#additional-javascript
## Configuration
-None.
+This configuration enables Markdown table support, which should normally be
+enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
-## Usage
+``` yaml
+markdown_extensions:
+ - tables
+```
+
+See additional configuration options:
-### Using data tables
+- [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][3].
-
-_Example_:
+emojis]:
-``` markdown
+``` markdown title="Data table"
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
@@ -34,7 +42,7 @@ _Example_:
| `DELETE` | :material-close: Delete resource |
```
-_Result_:
+
+
+ [icons and emojis]: icons-emojis.md
### Column alignment
If you want to align a specific column to the `left`, `center` or `right`, you
-can use the [regular Markdown syntax][4] placing `:` characters at the beginning
+can use the [regular Markdown syntax] placing `:` characters at the beginning
and/or end of the divider.
=== "Left"
- _Example_:
-
- ``` markdown hl_lines="2"
+ ``` markdown hl_lines="2" title="Data table, columns aligned to left"
| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
@@ -62,7 +70,7 @@ and/or end of the divider.
| `DELETE` | :material-close: Delete resource |
```
- _Result_:
+
+
+ [regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
## Customization
### Sortable tables
-If you want to make data tables sortable, you can add [tablesort][5], which is
+If you want to make data tables sortable, you can add [tablesort], which is
natively integrated with Material for MkDocs and will also work with [instant
-loading][6] via [additional JavaScript][2]:
+loading] via [additional JavaScript]:
-=== "docs/javascripts/tables.js"
+=== ":octicons-file-code-16: `docs/javascripts/tablesort.js`"
``` js
document$.subscribe(function() {
- var tables = document.querySelectorAll("article table")
+ var tables = document.querySelectorAll("article table:not([class])")
tables.forEach(function(table) {
new Tablesort(table)
})
})
```
-=== "mkdocs.yml"
+=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
extra_javascript:
- - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- - javascripts/tables.js
+ - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+ - javascripts/tablesort.js
```
-_Note that [tablesort][5] provides alternative comparison implementations like
-numbers, dates, filesizes and month names. See the official documentation for
-more information._
-
-_Example_:
+After applying the customization, data tables can be sorted by clicking on a
+column:
-``` markdown
+``` markdown title="Data table, columns sortable"
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
@@ -153,7 +160,7 @@ _Example_:
| `DELETE` | :material-close: Delete resource |
```
-_Result_:
+
+
+Note that [tablesort] provides alternative comparison implementations like
+numbers, filesizes, dates and month names. See the [tablesort documentation]
+[tablesort] for more information.
+
+
- [5]: http://tristen.ca/tablesort/demo/
- [6]: ../setup/setting-up-navigation.md#instant-loading
+ [tablesort]: http://tristen.ca/tablesort/demo/
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md
index b56b56af19e..ffdefdef2c5 100644
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@@ -1,82 +1,73 @@
---
-template: overrides/main.html
+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][1], a very
+documentation. Material for MkDocs integrates with [Mermaid.js], a very
popular and flexible solution for drawing diagrams.
- [1]: https://mermaid-js.github.io/mermaid/
+ [Mermaid.js]: https://mermaid-js.github.io/mermaid/
## Configuration
-### SuperFences
+[:octicons-tag-24: 8.2.0][Diagrams support]
-[:octicons-file-code-24: Source][2] ·
-:octicons-beaker-24: Experimental ·
-[:octicons-heart-fill-24:{: .mdx-heart } Insiders only][2]{: .mdx-insiders }
-
-The [SuperFences][3] extension, which is part of [Python Markdown
-Extensions][4], allows for adding __custom fences__, which can be used to
-render [Mermaid.js][1] diagrams with zero effort:
+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-experimental
+ class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
```
-No further configuration is necessary. Material for MkDocs will automatically
-load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced
-`mermaid` block][5]. Furthermore:
+No further configuration is necessary. Advantages over a custom integration:
-- [x] Works with [instant loading][6] without any additional effort
+- [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 stylesheets][7]
-- [x] Support for both, light and dark color schemes
-
-_While it's also possible to integrate [Mermaid.js][1] using existing
-third-party plugins[^2], the new native integration is recommended as it
-ensures interoperability with all Material for MkDocs features._
+- [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][1] features should work out-of-the-box, Material for
- MkDocs will currently only adjust the fonts and colors for flow charts,
- class and state diagrams. Support for further diagram types will be added
- gradually.
-
- [^2]:
- If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8]
- might be a good alternative. However, note that this plugin cannot be used
- in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to
- dark mode.
-
- [2]: ../insiders.md
- [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
- [4]: https://facelessuser.github.io/pymdown-extensions/
- [5]: #usage
- [6]: ../setup/setting-up-navigation.md#instant-loading
- [7]: ../customization.md#additional-css
- [8]: https://github.com/fralau/mkdocs-mermaid2-plugin
- [9]: https://github.com/byrnereese/mkdocs-minify-plugin
+ 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.
+
+ [Diagrams support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [additional style sheets]: ../customization.md#additional-css
+ [other diagrams]: #other-diagrams
## Usage
-### Using diagrams
+### 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:
-Mermaid diagrams are written as [code blocks][10] with the help of the
-[SuperFences][11] extension. They must be enclosed with two separate lines
-containing three backticks:
+```` markdown title="Flow chart"
+``` mermaid
+graph LR
+ A[Start] --> B{Error?};
+ B -->|Yes| C[Hmm...];
+ C --> D[Debug];
+ D --> B;
+ B ---->|No| E[Yay!];
+```
+````
-_Example_:
+
-```` markdown
``` mermaid
graph LR
A[Start] --> B{Error?};
@@ -85,15 +76,203 @@ graph LR
D --> B;
B ---->|No| E[Yay!];
```
+
+
+
+ [Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
+
+### 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!
+```
````
-_Result_:
+
+
+``` 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.github.io/mermaid/#/sequenceDiagram
+
+### 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.github.io/mermaid/#/stateDiagram
+
+### Using class diagrams
+
+[Class diagrams] are central to object oriented programing, 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.github.io/mermaid/#/classDiagram
+
+### 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
+ CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+````
+
+
+
+ [entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
-[![Diagram][12]{: style="width: 100%; max-width: 594px" }][12]
+### Other diagram types
-_See the [official documentation][1] to learn about all available 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.
- [10]: code-blocks.md
- [11]: #superfences
- [12]: ../assets/screenshots/diagram.png
+ [pie charts]: https://mermaid-js.github.io/mermaid/#/pie
+ [gantt charts]: https://mermaid-js.github.io/mermaid/#/gantt
+ [user journeys]: https://mermaid-js.github.io/mermaid/#/user-journey
+ [git graphs]: https://mermaid-js.github.io/mermaid/#/gitgraph
+ [requirement diagrams]: https://mermaid-js.github.io/mermaid/#/requirementDiagram
diff --git a/docs/reference/footnotes.md b/docs/reference/footnotes.md
index 5f15b5c7ffc..16380c2cb2b 100644
--- a/docs/reference/footnotes.md
+++ b/docs/reference/footnotes.md
@@ -1,22 +1,18 @@
---
-template: overrides/main.html
+icon: material/format-align-bottom
---
# Footnotes
-Footnotes are a great way to add references to supplemental or additional
-information for a specific section of a document without interrupting the
-document flow. Material for MkDocs provides the ability to insert inline
-footnotes and render them at the bottom of the page.
+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
-### Footnotes
-
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
-
-The [Footnotes][2] extension, which is part of the standard Markdown library,
-adds the ability to add inline footnotes to a document and can be enabled via
+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
@@ -24,8 +20,11 @@ markdown_extensions:
- footnotes
```
- [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
- [2]: https://python-markdown.github.io/extensions/footnotes/
+See additional configuration options:
+
+- [Footnotes]
+
+ [Footnotes]: ../setup/extensions/python-markdown.md#footnotes
## Usage
@@ -35,16 +34,16 @@ 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.
-_Example_:
-
-``` markdown
+``` title="Text with footnote references"
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
```
-_Result_:
+
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.
@@ -54,38 +53,38 @@ reference is automatically added.
#### on a single line
-Short statements can be written on the same line.
+Short footnotes can be written on the same line:
-_Example_:
-
-``` markdown
+``` title="Footnote"
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
-_Result_:
+
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:1)
-[Jump to footnote at the bottom of the page](#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.
-
-_Example_:
+Paragraphs can be written on the next line and must be indented by four spaces:
-``` markdown
+``` 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.
```
-_Result_:
+
- [^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)
-[Jump to footnote at the bottom of the page](#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/docs/reference/formatting.md b/docs/reference/formatting.md
index 9a94be3a433..7dec1ca6997 100644
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@@ -1,189 +1,140 @@
---
-template: overrides/main.html
+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][1] is supported, adding the ability to display suggested changes
+[Critic Markup] is supported, adding the ability to display suggested changes
for a document.
- [1]: http://criticmarkup.com/
+ [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
## Configuration
-### Critic
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
-
-The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
-allows for the __usage of [Critic Markup][1] to highlight changes__ in a
-document, and can be enabled via `mkdocs.yml`:
+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
-```
-
-The following options are supported:
-
-`mode`{: #mode }
-
-: :octicons-milestone-24: Default: `view` – This option defines how the markup
- should be parsed, i.e. whether to just `view` all suggest 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
- ```
-
- [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
- [3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
- [4]: https://facelessuser.github.io/pymdown-extensions/
-
-### BetterEm
-
-The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
-improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
-and can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
- - pymdownx.betterem:
- smart_enable: all
-```
-
- [5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
-
-### Caret, Mark & Tilde
-
-The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
-Markdown Extensions][4], allow for the __highlighting of text__, as well as
-__handling sub- and superscripts__:
-
-``` yaml
-markdown_extensions:
- pymdownx.caret
+ - pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
```
- [6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
- [7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
- [8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
-
-### SmartSymbols
-
-The [SmartSymbols][9] extension, which is also part of [Python Markdown
-Extensions][4], __converts special characters into their corresponding
-symbols__, and can be enabled via `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
- - pymdownx.smartsymbols
-```
+See additional configuration options:
-See the [official documentation][9] for a list of supported symbols.
+- [Critic]
+- [Caret, Mark & Tilde]
+- [Keys]
- [9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+ [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][10] is enabled, [Critic Markup][1] can be used, which adds the
-ability to _highlight suggested changes_, as well as add _inline comments_ to a
-document:
-
- [10]: #critic
+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:
-_Example_:
-
-``` markdown
-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<<}.
+``` 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
+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.
==}
```
-_Result_:
+
-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<<}.
-
-{==
+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.
+
+
+
+ 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 the [Caret, Mark & Tilde][11] extensions are enabled, text can be
-highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
-`del` HTML tags:
+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:
-_Example_:
-
-``` markdown
+``` title="Text with highlighting"
- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
```
-_Result_:
+
- ==This was marked==
- ^^This was inserted^^
- ~~This was deleted~~
- [11]: #caret-mark-tilde
+
-### Sub- and superscripts
+ [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
-When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
-superscripted with a nicer syntax than using the corresponding `sub` and `sup`
-HTML tags:
+### Sub- and superscripts
-_Example_:
+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
-- H~2~0
+``` markdown title="Text with sub- und superscripts"
+- H~2~O
- A^T^A
```
-_Result_:
+
+
+ [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/docs/reference/grids.md b/docs/reference/grids.md
new file mode 100644
index 00000000000..021394d3fe7
--- /dev/null
+++ b/docs/reference/grids.md
@@ -0,0 +1,304 @@
+---
+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
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Card grids wrap each grid item with a beautiful hover card that levitates on
+hover. They come in two slightly different syntaxes: [list] and [block syntax],
+adding support for distinct use cases.
+
+ [Insiders]: ../insiders/index.md
+ [list]: #list-syntax
+ [block syntax]: #block-syntax
+
+#### 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
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Generic grids allow for arranging arbitrary block elements in a grid, including
+[admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks
+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/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index cd618656ede..7243014baa9 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -1,13 +1,15 @@
---
-template: overrides/main.html
+icon: material/emoticon-happy-outline
---
-# Icons + Emojis
+# Icons, Emojis
One of the best features of Material for MkDocs is the possibility to use [more
-than 8.000 icons][1] and thousands of emojis in your project documentation
-with practically zero additional effort. Furthermore, custom icons can be added
-and used in `mkdocs.yml`, documents and templates.
+than 10,000 icons][icon search] and thousands of emojis in your project
+documentation with practically zero additional effort. Moreover, custom icons
+can be added and used in `mkdocs.yml`, documents and templates.
+
+ [icon search]: #search
## Search
@@ -24,22 +26,19 @@ and used in `mkdocs.yml`, documents and templates.
:octicons-light-bulb-16:
- **Tip:** Enter some keywords to find the perfect icon or emoji and click on
- the shortcode to copy it to your clipboard.
+ **Tip:** Enter some keywords to find icons and emojis and click on the
+ shortcode to copy it to your clipboard.
## Configuration
-### Emoji
-
-[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
-
-The [Emoji][3] extension, which is part of [Python Markdown Extensions][4],
-adds the ability to __integrate emojis and icons__ in the `*.svg` file format,
-which are inlined when [building your site][5]:
+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:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
@@ -47,184 +46,186 @@ markdown_extensions:
The following icon sets are bundled with Material for MkDocs:
-- :material-material-design: – [Material Design][6]
-- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
-- :octicons-mark-github-16: – [Octicons][8]
-
-You can also add [additional icons][9]. When using emojis, it's recommended to
-consult the official documentation of [Python Markdown Extensions][3] to learn
-about configuration options.
+- :material-material-design: – [Material Design]
+- :fontawesome-brands-font-awesome: – [FontAwesome]
+- :octicons-mark-github-16: – [Octicons]
+- :simple-simpleicons: – [Simple Icons]
- [1]: icons-emojis.md#search
- [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
- [3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
- [4]: https://facelessuser.github.io/pymdown-extensions/
- [5]: ../creating-your-site.md#building-your-site
- [6]: https://materialdesignicons.com/
- [7]: https://fontawesome.com/icons?d=gallery&m=free
- [8]: https://octicons.github.com/
- [9]: ../setup/changing-the-logo-and-icons.md#additional-icons
+See additional configuration options:
-### Attribute List
+- [Attribute Lists]
+- [Emoji]
+- [Emoji with custom icons]
-The [Attribute List][10] extension, which is part of the standard Markdown
-library, allows to __add HTML attributes and CSS classes to Markdown elements__,
-and can be enabled via `mkdocs.yml`
-
-``` yaml
-markdown_extensions:
- - attr_list
-```
-
- [10]: https://python-markdown.github.io/extensions/attr_list/
+ [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#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][11] (recommended), you can look up
-the shortcodes at [Emojipedia][12].
-
-_Example_:
+between two colons. If you're using [Twemoji] (recommended), you can look up
+the shortcodes at [Emojipedia]:
-```
+``` title="Emoji"
:smile:
```
-_Result_:
+
+
+ [Twemoji]: https://twemoji.twitter.com/
+ [Emojipedia]: https://emojipedia.org/twitter/
### Using icons
-When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing
+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`][1] directory, and replacing `/` with `-`:
+[`.icons`][custom icons] directory, and replacing `/` with `-`:
-_Example_:
-
-```
-- :material-account-circle: – `.icons/material/account-circle.svg`
-- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
-- :octicons-octoface-24: – `.icons/octicons/octoface-24.svg`
+``` title="Icon"
+:fontawesome-regular-face-laugh-wink:
```
-_Result_:
+
-#### with colors
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
-When the [Attribute List][17] extension is enabled, custom CSS classes and
-attributes can be added to icons by suffixing the icon with a special syntax.
-While HTML and CSS allow to use [inline styles][18], it's always best to add
-an [additional stylesheet][19] and put styles into dedicated CSS classes:
-
-``` css
-.medium {
- color: #00AB6C;
-}
-.twitter {
- color: #1DA1F2;
-}
-.facebook {
- color: #4267B2;
-}
-```
+#### with colors
-Then, simply add the CSS class to the icon.
+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:
-_Example_:
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .twitter {
+ color: #1DA1F2;
+ }
+ ```
-``` markdown
-- :fontawesome-brands-medium:{: .medium } – Medium
-- :fontawesome-brands-twitter:{: .twitter } – Twitter
-- :fontawesome-brands-facebook:{: .facebook } – Facebook
+=== ":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-twitter:{ .twitter }
```
-_Result_:
+
+
+ [colors]: #with-colors
+ [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
-_Result_:
+### Icons, emojis in sidebars :smile:
-:octicons-heart-fill-24:{: .mdx-heart }
+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.
- [20]: #with-colors
- [21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
+ [built-in typeset plugin]: ./index.md#built-in-typeset-plugin
## Customization
### Using icons in templates
-When you're [extending the theme][22] with partials or blocks, you can simply
-reference any icon that's [bundled with the theme][1] with Jinja's
-[`include`][23] function and wrap it with the `twemoji` class:
+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/twitter.svg" %}
+ {% include ".icons/fontawesome/brands/twitter.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.
- [22]: ../customization.md#extending-the-theme
- [23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
+ [extending the theme]: ../customization.md#extending-the-theme
+ [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
diff --git a/docs/reference/images.md b/docs/reference/images.md
index 6dbf4292813..729107dab94 100644
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@@ -1,112 +1,178 @@
---
-template: overrides/main.html
+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 by providing styles for alignment and image captions.
-
- [1]: https://www.markdownguide.org/basic-syntax/#images-1
+images more comfortable, providing styles for image alignment and image
+captions.
## Configuration
-### Attribute List
-
-The [Attribute List][2] extension, which is part of the standard Markdown
-library, allows to __add HTML attributes and CSS classes to Markdown elements__,
-and can be enabled via `mkdocs.yml`
+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
```
- [2]: https://python-markdown.github.io/extensions/attr_list/
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+
+### Lightbox
+
+[:octicons-tag-24: 0.1.0][Lightbox support] ·
+[:octicons-cpu-24: Plugin][glightbox]
+
+If you want to add image zoom functionality to your documentation, the
+[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].
+
+ [Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+ [glightbox]: https://github.com/blueswen/mkdocs-glightbox
+ [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
## Usage
### Image alignment
-When the [Attribute List][3] extension is enabled, images can be aligned by
-adding the respective alignment directions via the `align` attribute, i.e.
-`align=left` or `align=right`
+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"
- _Example_:
-
- ``` markdown
- ![Placeholder](https://dummyimage.com/600x400/eee/aaa){: align=left }
+ ``` markdown title="Image, aligned to left"
+ ![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }
```
- _Result_:
+
- ![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){: align=left width=300 }
+ ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ 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.
-=== "Right"
+
- ![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){: align=right width=300 }
+ ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ 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._
+
+
+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.
- [3]: #attribute-list
+ [^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 resort to HTML. Using `figure` and `figcaption`, captions can be added to images.
-
-_Example_:
+but it's always possible to use the [Markdown in HTML] extension with literal
+`figure` and `figcaption` tags:
-```html
-