OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into fix/instant-loading

Browse Source
This commit is contained in:
squidfunk
2023-09-22 18:17:17 +02:00
parent 5e64e92e23 433c137bc1
commit a3b619fc4b
13368 changed files with 20270 additions and 8358 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.dockerignore
View File

@@ -22,6 +22,6 @@
.git
.github
docs
material/.overrides
material/overrides
node_modules
src

4
.editorconfig
View File

@@ -30,10 +30,6 @@ end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
# Markdown
[*.md]
trim_trailing_whitespace = false
# Python
[*.py]
indent_style = space

29
.github/ISSUE_TEMPLATE/01-report-a-bug.yml vendored
View File

@@ -10,7 +10,8 @@ body:
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)
leave this field empty.
[More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#context)
- type: textarea
id: description
@@ -20,7 +21,8 @@ body:
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)
please let us maintainers (and all other users) know.
[More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#bug-description)
validations:
required: true
@@ -30,7 +32,7 @@ body:
label: Related links
description: >-
Please list all links to the sections of
[our documentation](https://squidfunk.github.io/mkdocs-material) that
[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)
@@ -50,11 +52,12 @@ body:
description: >-
Please create a __.zip file__ with a __minimal reproduction__ for the
bug. First, read our [reproduction guide](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/)
that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/#creating-a-zip-file) (mandatory) to create a self-contained
that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/plugins/info/) (mandatory) to create a self-contained
.zip file with the reproduction. We reserve the right to close issues
without .zip files. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
without .zip files.
[More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
placeholder: |-
Drag and drop the .zip file with minimal reproduction here.
Drag and drop the .zip file with the minimal reproduction here.
validations:
required: true
@@ -66,7 +69,8 @@ body:
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)
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. ...
@@ -79,10 +83,11 @@ body:
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)
This field is optional. If the bug only happens in __specific browsers__,
please select them from the dropdown below. If your browser is not
listed or the version is relevant, you may select _Other_ and provide
more details in the field above.
[More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#browser)
multiple: true
options:
- Chrome
@@ -106,7 +111,7 @@ body:
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),
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

10
.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml vendored
View File

@@ -1,4 +1,4 @@
name: Report a docs issue
name: Report a documentation issue
description: Missing information in our docs? Report a documentation issue
labels:
- documentation
@@ -10,7 +10,7 @@ body:
label: Description
description: >-
Please describe the inconsistency or issue you have found in
[our documentation](https://squidfunk.github.io/mkdocs-material)
[our documentation](https://squidfunk.github.io/mkdocs-material/)
or indicate where you feel there is a need for improvement. Furthermore,
explain the severity of the issue, i.e., its impact on you and potentially
other users.
@@ -23,7 +23,7 @@ body:
attributes:
label: Related links
description: >-
Please list all links to the sections of [our documentation](https://squidfunk.github.io/mkdocs-material)
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)
@@ -58,8 +58,8 @@ body:
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/).
I have read and followed the [documentation issue guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
required: true
- label: >-
I have attached the links to the described sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
I have attached the links to the affected sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
required: true

14
.github/ISSUE_TEMPLATE/03-request-a-change.yml vendored
View File

@@ -10,7 +10,8 @@ body:
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)
can leave this field empty.
[More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#context)
- type: textarea
id: description
@@ -32,10 +33,9 @@ body:
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)
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: |-
@@ -51,7 +51,7 @@ body:
description: >-
Please explain how your idea will work from an author's and user's
perspective. Elaborate on how the change would positively impact not only
you but the community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
of the project.
[More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
validations:
@@ -90,6 +90,6 @@ body:
I have ensured that, to the best of my knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
required: true
- label: >-
I have included relevant links to [the documentation](https://squidfunk.github.io/mkdocs-material), related [issues](https://github.com/squidfunk/mkdocs-material/issues),
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

94
.github/ISSUE_TEMPLATE/04-add-a-translation.yml vendored
View File

@@ -1,94 +0,0 @@
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",
"blog.archive": "Archive",
"blog.categories": "Categories",
"blog.categories.in": "in",
"blog.continue": "Continue reading",
"blog.draft": "Draft",
"blog.index": "Back to index",
"blog.meta": "Metadata",
"blog.references": "Related links",
"clipboard.copy": "Copy to clipboard",
"clipboard.copied": "Copied to clipboard",
"consent.accept": "Accept",
"consent.manage": "Manage settings",
"consent.reject": "Reject",
"footer": "Footer",
"footer.next": "Next",
"footer.previous": "Previous",
"header": "Header",
"meta.comments": "Comments",
"meta.source": "Source",
"nav": "Navigation",
"readtime.one": "1 min read",
"readtime.other": "# min read",
"rss.created": "RSS feed",
"rss.updated": "RSS feed of updated content",
"search": "Search",
"search.placeholder": "Search",
"search.share": "Share",
"search.reset": "Clear",
"search.result.initializer": "Initializing search",
"search.result.placeholder": "Type to start searching",
"search.result.none": "No matching documents",
"search.result.one": "1 matching document",
"search.result.other": "# matching documents",
"search.result.more.one": "1 more on this page",
"search.result.more.other": "# more on this page",
"search.result.term.missing": "Missing",
"select.language": "Select language",
"select.version": "Select version",
"source": "Go to repository",
"source.file.contributors": "Contributors",
"source.file.date.created": "Created",
"source.file.date.updated": "Last update",
"tabs": "Tabs",
"toc": "Table of contents",
"top": "Back to top"
}[key] }}{% endmacro %}
render: Jinja
validations:
required: true
- type: checkboxes
id: checklist
attributes:
label: Before submitting
description: >-
Please ensure that your translation fulfills the following
requirements.
options:
- label: I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
required: true
- label: I assure that the translations are accurate to the best of my knowledge.
required: true
- label: >-
__Optional__: I want to integrate this translation myself and create a
pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).

111
.github/ISSUE_TEMPLATE/04-add-translations.yml vendored Normal file
View File

@@ -0,0 +1,111 @@
name: Add a translation
description: Missing support for your language? Add a translation
title: Add translations for ...
labels:
- change request
body:
- type: markdown
attributes:
value: >-
**Important**: Before creating a new translation, please check if
Material for MkDocs already supports your language. Review the list of
[available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
pick your language to add new or improve existing translations.
- type: textarea
id: translations
attributes:
label: Translations
description: >-
Please translate the labels on the right. For new languages, translate
each line. For existing languages, only translate lines containing the
:arrow_left: icon and remove the icon before submitting.
[More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#translations_1)
value: |-
{% macro t(key) %}{{ {
"language": "en ⬅️",
"direction": "ltr ⬅️",
"action.edit": "Edit this page ⬅️",
"action.skip": "Skip to content ⬅️",
"action.view": "View source of this page ⬅️",
"announce.dismiss": "Don't show this again ⬅️",
"blog.archive": "Archive ⬅️",
"blog.categories": "Categories ⬅️",
"blog.categories.in": "in ⬅️",
"blog.continue": "Continue reading ⬅️",
"blog.draft": "Draft ⬅️",
"blog.index": "Back to index ⬅️",
"blog.meta": "Metadata ⬅️",
"blog.references": "Related links ⬅️",
"clipboard.copy": "Copy to clipboard ⬅️",
"clipboard.copied": "Copied to clipboard ⬅️",
"consent.accept": "Accept ⬅️",
"consent.manage": "Manage settings ⬅️",
"consent.reject": "Reject ⬅️",
"footer": "Footer ⬅️",
"footer.next": "Next ⬅️",
"footer.previous": "Previous ⬅️",
"header": "Header ⬅️",
"meta.comments": "Comments ⬅️",
"meta.source": "Source ⬅️",
"nav": "Navigation ⬅️",
"readtime.one": "1 min read ⬅️",
"readtime.other": "# min read ⬅️",
"rss.created": "RSS feed ⬅️",
"rss.updated": "RSS feed of updated content ⬅️",
"search": "Search ⬅️",
"search.placeholder": "Search ⬅️",
"search.share": "Share ⬅️",
"search.reset": "Clear ⬅️",
"search.result.initializer": "Initializing search ⬅️",
"search.result.placeholder": "Type to start searching ⬅️",
"search.result.none": "No matching documents ⬅️",
"search.result.one": "1 matching document ⬅️",
"search.result.other": "# matching documents ⬅️",
"search.result.more.one": "1 more on this page ⬅️",
"search.result.more.other": "# more on this page ⬅️",
"search.result.term.missing": "Missing ⬅️",
"select.language": "Select language ⬅️",
"select.version": "Select version ⬅️",
"source": "Go to repository ⬅️",
"source.file.contributors": "Contributors ⬅️",
"source.file.date.created": "Created ⬅️",
"source.file.date.updated": "Last update ⬅️",
"tabs": "Tabs ⬅️",
"toc": "Table of contents ⬅️",
"top": "Back to top ⬅️"
}[key] }}{% endmacro %}
render: Jinja
validations:
required: true
- type: input
id: country-flag
attributes:
label: Country flag
description: >-
This field is optional. Please add the flag of the country when adding a
new language. Go to our [emoji search](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
and enter `flag` to find all available shortcodes. If your flag is not
included, please choose the most appropriate available flag.
[More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#country-flag)
placeholder: |-
Country flag shortcode, e.g. :flag_en:
- type: checkboxes
id: checklist
attributes:
label: Before submitting
description: >-
Please ensure that your translation fulfills the following requirements.
options:
- label: >-
I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
required: true
- label: >-
I assure that the translations are accurate to the best of my knowledge.
required: true
- label: >-
__Optional__: I want to integrate this translation myself and create a
pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).

4
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@@ -22,4 +22,6 @@ blank_issues_enabled: false
contact_links:
- name: Ask a question
url: https://github.com/squidfunk/mkdocs-material/discussions
about: Have a question or need help? Connect with the community on our discussion board
about: >
Have a question or need help? Connect with our community on the
discussion board

BIN
.github/assets/sponsors/sponsor-buhler.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.9 KiB

BIN
.github/assets/sponsors/sponsor-ip-fabric.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 16 KiB

BIN
.github/assets/sponsors/sponsor-transformationflow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

4
.github/dependabot.yml vendored
View File

@@ -28,7 +28,9 @@ updates:
interval: weekly
time: "04:00"
- package-ecosystem: pip
open-pull-requests-limit: 10
# We only want to bump versions of packages in case of security updates, as
# we want to keep maximum compatibility - see https://t.ly/INSR_
open-pull-requests-limit: 0
directory: "/"
labels: []
schedule:

20
.github/workflows/build.yml vendored
View File

@@ -41,7 +41,7 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Set up Node.js runtime
uses: actions/setup-node@v3
@@ -72,7 +72,7 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Set up Python runtime
uses: actions/setup-python@v4
@@ -97,24 +97,24 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v3
- name: Login to DockerHub
if: github.event_name == 'release'
uses: docker/login-action@v2
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Login to GitHub Container Registry
if: github.event_name == 'release'
uses: docker/login-action@v2
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
@@ -122,7 +122,7 @@ jobs:
- name: Generate Docker tags and labels
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: |
${{ github.event.repository.full_name }}
@@ -137,7 +137,7 @@ jobs:
latest=${{ github.event.release.prerelease == false }}
- name: Build Docker image
uses: docker/build-push-action@v4
uses: docker/build-push-action@v5
with:
context: .
load: true
@@ -158,7 +158,7 @@ jobs:
echo "PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7" >> $GITHUB_ENV
- name: Publish Docker image
uses: docker/build-push-action@v4
uses: docker/build-push-action@v5
with:
context: .
platforms: ${{ env.PLATFORMS }}

3
.github/workflows/documentation.yml vendored
View File

@@ -37,7 +37,7 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v3
uses: actions/checkout@v4
with:
fetch-depth: 0
@@ -70,6 +70,7 @@ jobs:
"mkdocs-minify-plugin>=0.3" \
"mkdocs-rss-plugin>=1.2" \
"mkdocs-redirects>=1.0" \
"lxml" \
"pillow<10"
- name: Install Insiders build

4
.gitignore vendored
View File

@@ -55,10 +55,6 @@ example.zip
# Never ignore .gitkeep files
!**/.gitkeep
# Husky hooks
.husky/.gitignore
.husky/_
# macOS internals
.DS_Store

4
.vscode/settings.json vendored
View File

@@ -14,8 +14,8 @@
"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:material.extensions.emoji.to_svg",
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
]
}

201
CHANGELOG
View File

@@ -1,3 +1,202 @@
mkdocs-material-9.4.1 (2023-09-22)
* Improved colors and contrast in dark mode
* Improved admonition borders to match font weight
* Switched content tabs to neutral color
mkdocs-material-9.4.0 (2023-09-21)
* Added Belarusian translations
* Added version info to entrypoint of package
* Added emoji extension as a replacement for materialx
* Improved slate color scheme (dark mode) - now even darker
* Restructured project to improve development experience
* Updated MkDocs to 1.5.3
* Fixed #3890: Development mode crashes on Linux
mkdocs-material-9.3.2+insiders-4.42.0 (2023-09-19)
* Added support for using git submodules in projects plugin
* Added support for transforming project configurations
* Improved resilience of optimize and blog plugin
* Fixed optimize plugin crashing on .jpeg extension
* Fixed project URLs not using site URLs in projects plugin
mkdocs-material-9.3.2 (2023-09-19)
* Updated Slovenian translations
* Updated Python dependencies in requirements to use minimum versions
* Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
* Fixed #6001: Contributor avatars display incorrectly in Firefox
* Fixed #6000: Blog post drafts are included in navigation
mkdocs-material-9.3.1+insiders-4.41.0 (2023-09-11)
* Improved multi-instance support for optimize plugin
* Added inclusion and exclusion patterns for optimize plugin
* Added transparent keyword for color handling in social plugin
* Changed default quality of PNGs to 3 in optimize plugin
* Fixed #5979: meta file not detected in root of docs directory
mkdocs-material-9.3.1 (2023-09-11)
* Fixed crash of group plugin when used together with hooks
mkdocs-material-9.3.0 (2023-09-11)
* Improved configuration sharing between Community and Insiders edition
* Added experimental built-in group plugin for enabling plugins conditionally
* Added new settings in tags plugin for enabling/disabling
* Dropped support for Python 3.7 (EOL)
mkdocs-material-9.2.8+insiders-4.40.4 (2023-09-04)
* Fixed privacy plugin choking on boolean HTML5 attributes
* Fixed wrapping of inline code blocks in typeset table of contents
* Fixed blog plugin error when running under dirty reload
mkdocs-material-9.2.8 (2023-09-04)
* Updated Italian and Russian translations
* Fixed #5952: Combining blog and tags plugin leads to wrong links
* Fixed #5951: Blog plugin ignores post title in metadata
* Fixed #5949: Blog plugin ignores post linked in nav
mkdocs-material-9-2.7+insiders-4.40.3 (2023-09-02)
* Fixed #5946: Docker image missing pngquant for optimize plugin
mkdocs-material-9.2.7 (2023-09-02)
* Switched dependencies to compatible release clauses
* Removed readtime and lxml dependencies for blog plugin
* Reduced size of Docker image to improve CI build performance
* Fixed #5945: Incorrect footer navigation for sibling pages of blog
* Fixed #5939: Page jumps when changing color palette (Firefox 117)
* Fixed #5901: Announcement bar reappears when using instant loading
* Fixed #5824: Allow to customize styles of sequence diagrams
mkdocs-material-9-2.6+insiders-4.40.2 (2023-08-31)
* Added configurable error handling capabilities for social plugin
* Fixed #5922: Blog plugin shows no posts when building a standalone blog
* Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
* Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
mkdocs-material-9-2.6 (2023-08-31)
* Added Basque translations
* Added template for simple redirects
* Improved blog plugin interop by moving view generation to on_files
* Fixed #5924: Social plugin still checks dependencies when disabled
* Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
mkdocs-material-9-2.5+insiders-4.40.1 (2023-08-27)
* Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
* Fixed empty category pages in blog plugin (4.40.0 regression)
mkdocs-material-9-2.5 (2023-08-27)
* Fixed error in dirty serve mode when using blog plugin
* Fixed page title not being consistent in blog plugin pagination
* Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
mkdocs-material-9.2.4+insiders-4.40.0 (2023-08-26)
* Added logo, title and description options to social plugin default layouts
* Fixed privacy plugin compatibility issue with Python < 3.10
* Fixed #5896: Blog plugin errors when using custom index pages
mkdocs-material-9.2.4 (2023-08-26)
* Added version to bug report name in info plugin
* Updated Afrikaans translations
mkdocs-material-9.2.3+insiders-4.39.3 (2023-08-24)
* Fixed lxml dependency missing in Docker image (4.39.2 regression)
mkdocs-material-9.2.3+insiders-4.39.2 (2023-08-23)
* Fixed color palette toggle being reversed (9.2.0 regression)
mkdocs-material-9.2.3 (2023-08-22)
* Fixed blog plugin rendering wrongly with markdown.extensions.toc
* Fixed blog plugin entrypoint generation
mkdocs-material-9.2.2 (2023-08-22)
* Fixed #5880: Blog plugin failing when building a standalone blog
* Fixed #5881: Blog plugin not compatible with Python < 3.10
mkdocs-material-9.2.1 (2023-08-21)
* Fixed #5879: Blog plugin failing when building a standalone blog
* Fixed error in blog plugin when using draft tagging on future date
* Fixed error in blog plugin when toc extension is not enabled
mkdocs-material-9.2.0+insiders-4.39.1 (2023-08-21)
* Fixed git diff in tags plugin after merging back 9.2.0 changes
mkdocs-material-9.2.0 (2023-08-21)
Additions and improvements
* Added blogging support via built-in blog plugin
* Added support for Chinese language segmentaiton in search plugin
* Added support for adding custom dates to blog posts
* Added support for paginating archive and category pages
* Added support for annotations (outside of code blocks)
* Added support for navigation icons
* Added support for navigation pruning
* Added support for navigation status
* Added support for customizing site icons
* Added support for customizing (code) annotation icons
* Added focus outline to admonitions and details
* Added prompt for bug report name to info plugin
* Added Luxembourgish translations
* Improved rendering of (code) annotation markers
* Improved print styles for (code) annotations
* Improved customizability of navigation tabs
* Improved interop of plugins with external tools like mike
* Improved interop of blog plugin with awesome pages plugin
* Improved header partial by moving buttons into separate partials
* Improved clarity of site_url warning in social plugin
* Improved blog plugin to automatically setup directory structure
* Switched info plugin to importlib to mitigate deprecations
* Automatically download ResizeObserver polyfill when necessary
* Automatically add iframe-worker polyfill when necessary in offline plugin
* Automatically focus and bring up keyboard on touch devices
* Updated Serbo-Croatian translations
* Updated MkDocs to 1.5.2
Removals
* Removed Universal Analytics integration
* Removed ancient polyfills to reduce size of bundled JavaScript by 20%
* Removed necessity for Array.flat and Array.flatMap polyfill
* Removed announcement bar button when JavaScript is not available
Fixes
* Fixed rendering of tags when announcement bar is present
* Fixed tags plugin rendering pages excluded by other plugins
* Fixed #5132: Blog plugin requires nav entry in mkdocs.yml
* Fixed #5599: Insufficient contrast for default link color
* Fixed #5715: Blog plugin missing integrated table of contents in pagination
* Fixed #5806: Version selector not hoverable on some Android devices
* Fixed #5826: Blog post drafts with tags show up in tags index
mkdocs-material-9.1.21+insiders-4.39.0 (2023-08-01)
* Added support for hoisting theme media files when building projects
* Added support for sorting pages on tags index for tags plugin
* Added support for adding date of last update to blog posts
* Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
mkdocs-material-9.1.21+insiders-4.38.1 (2023-08-01)
* Improved nested serve mode for projects plugin
@@ -330,7 +529,7 @@ mkdocs-material-9.0.8 (2023-01-29)
mkdocs-material-9.0.7 (2023-01-28)
* Improved accessibility of sidebar navigation
* Moved all translations into community edition
* 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

24
CODE_OF_CONDUCT.md
View File

@@ -5,7 +5,7 @@
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
@@ -16,7 +16,7 @@ Examples of behavior that contributes to creating a positive environment include
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Focusing on what is best for our community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
@@ -36,7 +36,7 @@ Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject
Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
@@ -45,21 +45,21 @@ offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at
https://gitter.im/squidfunk/mkdocs-material. The project team will review and
investigate all complaints, and will respond in a way that it deems appropriate
to the circumstances. The project team is obligated to maintain confidentiality
with regard to the reporter of an incident. Further details of specific
enforcement policies may be posted separately.
reported by contacting the project team privately at hello@squidfunk.com. The
project team will review and investigate all complaints, and will respond in a
way that it deems appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an
incident. Further details of specific enforcement policies may be posted
separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other

131
CONTRIBUTING.md
View File

@@ -1,112 +1,61 @@
# Contributing
Interested in contributing to the Material for MkDocs? Have a question? Want to
report a bug? Before you do, please read the following guidelines.
Material for MkDocs is an actively maintained and constantly improved project
that serves a diverse user base with varying backgrounds and needs. In order to
effectively address the needs of all our users, evaluate change requests, and
fix bugs, we maintainers need to put in a lot of work. We have devoted
significant effort to creating better templates for our issue tracker,
optimizing the processes for our users to report bugs, request features or
changes, contribute to the project, or exchange with our community.
## 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].
[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] in our GitHub repository. Even better, you can submit
a Pull Request with a fix. However, before doing so, please read the
[submission guidelines].
Given the wealth of valuable knowledge contained in numerous issues and
discussions, we consider our [issue tracker] and [discussion board] to serve as
a crucial __knowledge base__ that is an important addition to our [documentation]
and brings value to both new and experienced users of Material for MkDocs.
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
[submission guidelines]: #submission-guidelines
[documentation]: https://squidfunk.github.io/mkdocs-material/
### Missing a feature?
## How to contribute
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 to everyone, as
Material for MkDocs is highly opinionated. Please consider what kind of change
it is:
### Creating an issue
* For a **major feature**, first open an issue and outline your proposal so
that it can be discussed. This will also allow us to better coordinate our
efforts, prevent duplication of work, and help you to craft the change so
that it is successfully accepted into the project.
- #### [Report a bug]
* **Small features and bugs** can be crafted and directly submitted as a Pull
Request. However, there is no guarantee that your feature will make it into
the `master`, as it's always a matter of opinion whether if benefits the
overall functionality of the project.
__Something is not working?__ Report a bug in Material for MkDocs by
creating an issue with a reproduction
### Missing translations?
- #### [Report a docs issue]
Material for MkDocs supports 60+ 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 60+ 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:
__Missing information in our docs?__ Report missing information or
potential inconsistencies in our documentation
1. Fork the repository.
- #### [Request a change]
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:
__Want to submit an idea?__ Propose a change, feature request, or
suggest an improvement
- `search.config.lang`
- `search.config.pipeline`
- `search.config.separator`
- #### [Ask a question]
3. Create a PR (see below) with your changes.
__Have a question or need help?__ Ask a question on our [discussion board]
and get in touch with our community
[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
### Contributing
## Submission guidelines
- #### [Add a translation]
### Submitting an issue
__Missing support for your language?__ Add missing translations for a new
or already supported language
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
readily available.
- #### [Create a pull request]
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.
__Want to create a pull request?__ Learn how to create a comprehensive
and useful pull request (PR)s
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)
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],
make your changes in a separate git branch and add descriptive messages to
your commits.
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.
After your PR is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository.
[development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
[build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme
[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
[Add translations]: https://github.com/squidfunk/mkdocs-material/adding-translations
[Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls

8
Dockerfile
View File

@@ -61,10 +61,8 @@ RUN \
&& \
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"; \
mkdocs-material[recommended] \
mkdocs-material[imaging]; \
fi \
&& \
if [ -e user-requirements.txt ]; then \
@@ -76,7 +74,7 @@ RUN \
for theme in mkdocs readthedocs; do \
rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
ln -s \
${PACKAGES}/material \
${PACKAGES}/material/templates \
${PACKAGES}/mkdocs/themes/$theme; \
done \
&& \

36
README.md
View File

@@ -17,19 +17,15 @@
alt="Build"
/></a>
<a href="https://pypistats.org/packages/mkdocs-material"><img
src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
alt="Downloads"
/></a>
<a href="https://gitter.im/squidfunk/mkdocs-material"><img
src="https://badges.gitter.im/squidfunk/mkdocs-material.svg"
alt="Chat on Gitter"
/></a>
<a href="https://pypi.org/project/mkdocs-material"><img
src="https://img.shields.io/pypi/v/mkdocs-material.svg"
<a href="https://pypi.org/project/mkdocs-material"><img
src="https://img.shields.io/pypi/v/mkdocs-material.svg"
alt="Python Package Index"
/></a>
<a href="https://hub.docker.com/r/squidfunk/mkdocs-material/"><img
src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material"
<a href="https://hub.docker.com/r/squidfunk/mkdocs-material/"><img
src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material"
alt="Docker Pulls"
/></a>
</p>
@@ -48,7 +44,7 @@
<p align="center">
<em>
Check out the demo –
Check out the demo –
<a
href="https://squidfunk.github.io/mkdocs-material/"
>squidfunk.github.io/mkdocs-material</a>.
@@ -123,9 +119,9 @@
<a href="https://neptune.ai/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png" height="58"
/></a>
<a href="https://cash.app/" target=_blank><img
<!-- <a href="https://cash.app/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58"
/></a>
/></a> -->
<a href="https://rackn.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png" height="58"
/></a>
@@ -159,6 +155,12 @@
<a href="https://oikolab.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-oikolab.png" height="58"
/></a>
<a href="https://www.buhlergroup.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-buhler.png" height="58"
/></a>
<a href="https://transformationflow.io/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-transformationflow.png" height="58"
/></a>
</p>
<p>&nbsp;</p>
@@ -224,10 +226,12 @@ For detailed installation instructions, configuration options, and a demo, visit
### ... industry leaders
[ArXiv](https://info.arxiv.org),
[Atlassian](https://atlassian.github.io/data-center-helm-charts/),
[AWS](https://aws.github.io/copilot-cli/),
[Bloomberg](https://bloomberg.github.io/selekt/),
[CERN](http://abpcomputing.web.cern.ch/),
[CloudFlare](https://cloudflare.github.io/itty-router-openapi/),
[Datadog](https://datadoghq.dev/integrations-core/),
[Google](https://google.github.io/accompanist/),
[Hewlett Packard](https://hewlettpackard.github.io/squest/),
@@ -238,14 +242,16 @@ For detailed installation instructions, configuration options, and a demo, visit
[Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
[Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
[Netflix](https://netflix.github.io/titus/),
[Red Hat](https://ansible.readthedocs.io/projects/lint/),
[Salesforce](https://policy-sentry.readthedocs.io/en/latest/),
[SoundCloud](https://intervene.dev/),
[Slack](https://slackhq.github.io/circuit/),
[Square](https://square.github.io/okhttp/),
[Zalando](https://opensource.zalando.com/skipper/)
### ... and successful Open Source projects
[Arduino](https://arduino.github.io/arduino-cli/),
[Auto-GPT](https://docs.agpt.co/),
[AutoKeras](https://autokeras.com/),
[BFE](https://www.bfe-networks.net/),
[CentOS](https://docs.infra.centos.org/),
@@ -256,15 +262,15 @@ For detailed installation instructions, configuration options, and a demo, visit
[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/),
[PyPI](https://docs.pypi.org/),
[Renovate](https://docs.renovatebot.com/),
[Traefik](https://docs.traefik.io/),
[Trivy](https://github.com/aquasecurity/trivy)
[Trivy](https://aquasecurity.github.io/trivy/),
[Vapor](https://docs.vapor.codes/),
[ZeroNet](https://zeronet.io/docs/),
[WebKit](https://docs.webkit.org/),

9
docs/blog/.authors.yml
View File

@@ -1,4 +1,5 @@
squidfunk:
name: Martin Donath
description: Creator
avatar: https://avatars.githubusercontent.com/u/932156
authors:
squidfunk:
name: Martin Donath
description: Creator
avatar: https://avatars.githubusercontent.com/u/932156

12
docs/blog/posts/blog-support-just-landed.md
View File

@@ -8,7 +8,7 @@ categories:
- Blog
links:
- Getting started with Insiders: insiders/getting-started.md#requirements
- setup/setting-up-a-blog.md#built-in-blog-plugin
- plugins/blog.md
---
# Blog support just landed
@@ -31,7 +31,7 @@ _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
[built-in blog plugin]: ../../plugins/blog.md
[Jekyll]: https://jekyllrb.com/
## Quick start
@@ -168,9 +168,9 @@ 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
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
@@ -233,7 +233,7 @@ Some ideas already proposed by users:
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
- __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.

20
docs/blog/posts/chinese-search-support.md
View File

@@ -3,25 +3,25 @@ date: 2022-05-05
authors: [squidfunk]
title: Chinese search support
description: >
Insiders adds Chinese language support for the built-in search plugin – a
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
- plugins/search.md#segmentation
- insiders/index.md#how-to-become-a-sponsor
---
# Chinese search support – 中文搜索​支持
__Insiders adds experimental Chinese language support for the [built-in search
__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
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.
@@ -35,7 +35,7 @@ _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
[built-in search plugin]: ../../plugins/search.md
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
## Configuration
@@ -49,8 +49,8 @@ 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]
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:
@@ -65,14 +65,14 @@ That's all that is necessary.
## Usage
If you followed the instructions in the configuration guide, Chinese words will
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
[: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
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].

6
docs/blog/posts/excluding-content-from-search.md
View File

@@ -119,7 +119,7 @@ search:
exclude: true
---
# Document title
# Page title
...
```
@@ -133,7 +133,7 @@ filtered by the search plugin before the page is rendered:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
# Page title
## Section 1
@@ -173,7 +173,7 @@ supported by the [Attribute Lists] extension:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
# Page title
The content of this block is included

26
docs/blog/posts/search-better-faster-smaller.md
View File

@@ -9,7 +9,7 @@ categories:
- Search
- Performance
links:
- setup/setting-up-site-search.md#built-in-search-plugin
- plugins/search.md
- insiders/index.md#how-to-become-a-sponsor
---
@@ -58,7 +58,7 @@ const index$ = document.forms.namedItem("search")
[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
[built-in search plugin]: ../../plugins/search.md
### Search index
@@ -176,10 +176,10 @@ 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.
Prior to <!-- md:version 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
<!-- md:version 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
@@ -196,7 +196,7 @@ the following steps are taken:
> 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
3. __Indexing__: As a final step, each section is indexed. When querying the
index, if a search query includes one of the tokens as returned by step 2.,
the section is considered to be part of the search result and passed to the
main thread.
@@ -244,7 +244,7 @@ carefully considered:
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 …
```
@@ -262,7 +262,7 @@ carefully considered:
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
[truncated]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/javascripts/templates/search/index.tsx#L90
[search preview]: search-better-faster-smaller/search-preview.png
[Just the Docs]: https://pmarsceill.github.io/just-the-docs/
[Docusaurus]: https://github.com/lelouch77/docusaurus-lunr-search
@@ -286,7 +286,7 @@ 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
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
@@ -463,7 +463,7 @@ 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
[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.
@@ -499,7 +499,7 @@ following expression to the separator allows for just that:
&[lg]t;
```
Searching for [:octicons-search-24: custom search worker script][q=script]
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.
@@ -548,7 +548,7 @@ powerful as tokenization:
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
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

6
docs/browser-support.md
View File

@@ -47,6 +47,8 @@ check the distribution of browser types and versions among your users.
[open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
[caniuse.com]: https://caniuse.com/
[:is pseudo selector]: https://caniuse.com/css-matches-pseudo
[browser support]: #supported-browsers
[built-in privacy plugin]: plugins/privacy.md
## Other browsers
@@ -62,6 +64,4 @@ the following older browser versions might work 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
<!-- md:version 4.6.3 -->.

140
docs/changelog/index.md
View File

@@ -2,7 +2,143 @@
## Material for MkDocs
### 9.1.21 <small>July 27, 2023</small> { id="9.1.20" }
### 9.4.1 <small>September 22, 2023</small> { id="9.4.1" }
- Improved colors and contrast in dark mode
- Improved admonition borders to match font weight
- Switched content tabs to neutral color
### 9.4.0 <small>September 21, 2023</small> { id="9.4.0" }
- Added Belarusian translations
- Added version info to entrypoint of package
- Added emoji extension as a replacement for `materialx`
- Improved slate color scheme (dark mode) - now even darker
- Restructured project to improve development experience
- Updated MkDocs to 1.5.3
- Fixed #3890: Development mode crash on Linux
### 9.3.2 <small>September 19, 2023</small> { id="9.3.2" }
- Updated Slovenian translations
- Updated Python dependencies in requirements to use minimum versions
- Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
- Fixed #6001: Contributor avatars display incorrectly in Firefox
- Fixed #6000: Blog post drafts are included in navigation
### 9.3.1 <small>September 11, 2023</small> { id="9.3.1" }
- Fixed crash of group plugin when used together with hooks
### 9.3.0 <small>September 11, 2023</small> { id="9.3.0" }
- Improved configuration sharing between Community and Insiders edition
- Added experimental built-in group plugin for enabling plugins conditionally
- Added new settings in tags plugin for enabling/disabling
- Dropped support for Python 3.7 (EOL)
### 9.2.8 <small>September 4, 2023</small> { id="9.2.8" }
- Updated Italian and Russian translations
- Fixed #5952: Combining blog and tags plugin leads to wrong links
- Fixed #5951: Blog plugin ignores post title in metadata
- Fixed #5949: Blog plugin ignores post linked in nav
### 9.2.7 <small>September 2, 2023</small> { id="9.2.7" }
- Switched dependencies to compatible release clauses
- Removed `readtime` and `lxml` dependencies for blog plugin
- Reduced size of Docker image to improve CI build performance
- Fixed #5945: Incorrect footer navigation for sibling pages of blog
- Fixed #5939: Page jumps when changing color palette (Firefox 117)
- Fixed #5901: Announcement bar reappears when using instant loading
- Fixed #5824: Allow to customize styles of sequence diagrams
### 9.2.6 <small>August 31, 2023</small> { id="9.2.6" }
- Added Basque translations
- Added template for simple redirects
- Improved blog plugin interop by moving view generation to `on_files`
- Fixed #5924: Social plugin still checks dependencies when disabled
- Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
### 9.2.5 <small>August 27, 2023</small> { id="9.2.5" }
- Fixed error in dirty serve mode when using blog plugin
- Fixed page title not being consistent in blog plugin pagination
- Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
### 9.2.4 <small>August 26, 2023</small> { id="9.2.4" }
- Added version to bug report name in info plugin
- Updated Afrikaans translations
### 9.2.3 <small>August 22, 2023</small> { id="9.2.3" }
- Fixed blog plugin rendering wrongly with `markdown.extensions.toc`
- Fixed blog plugin entrypoint generation
### 9.2.2 <small>August 22, 2023</small> { id="9.2.2" }
- Fixed #5880: Blog plugin failing when building a standalone blog
- Fixed #5881: Blog plugin not compatible with Python < 3.10
### 9.2.1 <small>August 21, 2023</small> { id="9.2.1" }
- Fixed #5879: Blog plugin failing when building a standalone blog
- Fixed error in blog plugin when using draft tagging on future date
- Fixed error in blog plugin when toc extension is not enabled
### 9.2.0 <small>August 21, 2023</small> { id="9.2.0" }
__Additions and improvements__
- Added blogging support via built-in blog plugin
- Added support for Chinese language segmentaiton in search plugin
- Added support for adding custom dates to blog posts
- Added support for paginating archive and category pages
- Added support for annotations (outside of code blocks)
- Added support for navigation icons
- Added support for navigation pruning
- Added support for navigation status
- Added support for customizing site icons
- Added support for customizing (code) annotation icons
- Added focus outline to admonitions and details
- Added prompt for bug report name to info plugin
- Added Luxembourgish translations
- Improved rendering of (code) annotation markers
- Improved print styles for (code) annotations
- Improved customizability of navigation tabs
- Improved interop of plugins with external tools like mike
- Improved interop of blog plugin with awesome pages plugin
- Improved header partial by moving buttons into separate partials
- Improved clarity of `site_url` warning in social plugin
- Improved blog plugin to automatically setup directory structure
- Switched info plugin to `importlib` to mitigate deprecations
- Automatically download ResizeObserver polyfill when necessary
- Automatically add iframe-worker polyfill when necessary in offline plugin
- Automatically focus and bring up keyboard on touch devices
- Updated Serbo-Croatian translations
- Updated MkDocs to 1.5.2
__Removals__
- Removed Universal Analytics integration
- Removed ancient polyfills to reduce size of bundled JavaScript by 20%
- Removed necessity for `Array.flat` and `Array.flatMap` polyfill
- Removed announcement bar button when JavaScript is not available
__Fixes__
- Fixed rendering of tags when announcement bar is present
- Fixed tags plugin rendering pages excluded by other plugins
- Fixed #5132: Blog plugin requires `nav` entry in `mkdocs.yml`
- Fixed #5599: Insufficient contrast for default link color
- Fixed #5715: Blog plugin missing integrated table of contents in pagination
- Fixed #5806: Version selector not hoverable on some Android devices
- Fixed #5826: Blog post drafts with tags show up in tags index
### 9.1.21 <small>July 27, 2023</small> { id="9.1.21" }
- Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
@@ -188,7 +324,7 @@
### 9.0.7 <small>January 28, 2023</small> { id="9.0.7" }
- Improved accessibility of sidebar navigation
- Moved all translations into community edition
- 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

125
docs/contributing/adding-translations.md Normal file
View File

@@ -0,0 +1,125 @@
# Translations
It's unbelievable – with the help of international community contributions,
Material for MkDocs has been translated into 60+ languages. As you can imagine,
it's impossible for us maintainers to keep all languages up-to-date, and new
features sometimes require new translations.
If you would like to help us to make Material for MkDocs even more globally
accessible and have noticed a missing translation in your language, or would
like to add a new language, you can help us by following the steps of the guide
below.
## Before creating an issue
Translations change frequently, which is why we want to make sure that you don't
invest your time in duplicating work. Before adding translations, please check
the following things:
### Check language availability
With more than 60 languages, the chances are good that your language is already
supported by Material for MkDocs. You can check if your language is available,
or needs improvements or additional translations by inspecting the list of
[supported languages]:
- __Your language is already supported__ – in this case, you can check if there
are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
- __Your language is missing__ – in that case, you can help us add support
for your language to Material for MkDocs! Read on, to learn how to do this.
[supported languages]: ../setup/changing-the-language.md#site-language
### Search our issue tracker
Another user might have already created an issue supplying the missing
translations for your language that still needs to be integrated by us
maintainers. To avoid investing your time in duplicated work, please search the
[issue tracker] beforehand.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
---
At this point, when you have made sure that Material for MkDocs doesn't already
support your language, you can add new translations for it by following the
issue template.
## Issue template
We have created an issue template that makes contributing translations as simple
as possible. It is the result of our experience with 60+ language contributions
and updates over the last couple of years, and consists of the following parts:
- [Title]
- [Translations]
- [Country flag] <small>optional</small>
- [Checklist]
[Title]: #title
[Translations]: #translations
[Country flag]: #country-flag
[Checklist]: #checklist
### Title
When you update an already existing language, you can just leave the title as it
is. Adding support for a new language, replace the `...` in the pre-filled title
with the name of your language.
| <!-- --> | Example |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Translations
If a translation contains an :arrow_left: icon on the right side, it is missing.
You can translate this line and remove the :arrow_left: icon. If you don't know
how to translate specific lines, simply leave them for other contributors to
complete. To ensure the accuracy of your translation, consider double-checking the
context of the words by looking at our [English translations].
[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
### Country flag <small>optional</small> { #country-flag }
For a better overview, our list of [supported languages] includes country flags
next to the language names. You can help us select a flag for your language by
adding the shortcode for the country flag to this field. Go to our
[emoji search] and enter `flag` to find all available shortcodes.
!!! question "What if my flag is not available?"
[Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
such as states, provinces, or regions, are not supported. If you're adding
translations for a subdivision, please choose the most appropriate available
flag.
[Twemoji]: https://twemoji.twitter.com/
[emoji search]: ../reference/icons-emojis.md#search
> __Why this might be helpful__: adding a country flag next to the country name
> can be helpful for you and for others to find the language in the list of
> supported languages faster and easier. If your country's flag is not supported
> by [Twemoji], you can help us choose an alternative.
### Checklist
Thanks for following the guide and helping us to add new translations to Material
for MkDocs – you are almost done. The checklist ensures that you have read this
guide and have worked to your best knowledge to provide us with everything we need
to integrate your contribution.
__We'll take it from here.__
---
## Attribution
If you submit a translation using the template above, you will be __credited as
a co-author__ in the commit, so you don't need to open a pull request. You have
done a significant contribution to the project, making Material for MkDocs
accessible to more people around the world. Thank you!

184
docs/contributing/index.md
View File

@@ -1,58 +1,202 @@
# 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.
Material for MkDocs is an actively maintained and constantly evolving project
serving a diverse user base with versatile backgrounds and needs. In order to
efficiently address the requirements of all our users, evaluate change requests,
and fix bugs, we put in a lot of work.
## 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.
Our ever-growing community includes many active users, who open new
issues and discussions several times a day, evolving our [issue tracker] and
[discussion board] into a knowledge base – an important addition to
our [documentation] – yielding value to both new and experienced users.
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
[documentation]: https://squidfunk.github.io/mkdocs-material/
## How you can contribute
We understand that reporting bugs, raising change requests, as well as engaging
in discussions can be time-consuming, which is why we've carefully optimized our
issue templates and defined guidelines to improve the overall interaction
within the project. We've invested a lot of time and effort into making our
[issue tracker] and [discussion board] as efficient as possible.
Our goal is to ensure that our documentation, as well as issue tracker and
discussion board, are __well-structured__, __easy to navigate__, and
__searchable__, so you can find what you need quickly and efficiently. Thus,
when you follow our guidelines, we can help you much faster.
In this section, we guide your through our processes.
### Creating an issue
<div class="grid cards" markdown>
- :material-bug:{ .lg .middle } __Something is not working?__
- :material-bug-outline: &nbsp;
__Something is not working?__
---
Report a bug in Material for MkDocs by creating an issue and a reproduction
Report a bug in Material for MkDocs by creating an issue with a
reproduction
---
[:octicons-arrow-right-24: Report a bug][report a bug]
- :material-file-document:{ .lg .middle } __Missing information in our docs?__
- :material-file-document-remove-outline: &nbsp;
__Missing information in our docs?__
---
Report missing information or potential inconsistencies in our documentation
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?__
- :material-lightbulb-on-20: &nbsp;
__Want to submit an idea?__
---
Propose a change or feature request or suggest an improvement
Propose a change, 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?__
- :material-account-question-outline: &nbsp;
__Have a question or need help?__
---
Ask questions on our discussion board and get in touch with our community
Ask a question on our [discussion board] and get in touch with our
community
[:octicons-arrow-right-24: Ask a question][ask a question]
---
[:octicons-arrow-right-24: Ask a question][discussion board]
</div>
### Contributing
<div class="grid cards" markdown>
- :material-translate: &nbsp;
__Missing support for your language?__
---
Add or improve translations for a new or already supported language
---
[:octicons-arrow-right-24: Add translations][add translations]
- :material-source-pull: &nbsp;
__Want to create a pull request?__
---
Learn how to create a comprehensive and useful pull request (PR)
---
[:octicons-arrow-right-24: Create a pull request][create a pull request]
</div>
[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
[add translations]: https://github.com/squidfunk/mkdocs-material/adding-translations
[create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
## Checklist
Before interacting within the project, please take a moment to consider the
following questions. By doing so, you can ensure that you are using the correct
issue template and that you provide all necessary information when interacting
with our community.
!!! warning "Issues, discussions, and comments are forever"
Please note that everything you write is permanent and will remain
for everyone to read – forever. Therefore, please always be nice and
constructive, follow our contribution guidelines, and comply with our
[Code of Conduct].
### Before creating an issue
- Are you using the appropriate issue template, or is there another issue
template that better fits the context of your request?
- Have you checked if a similar bug report or change request has already been
created, or have you stumbled upon something that might be related?
- Did your fill out every field as requested and did you provide all additional
information we maintainers need to comprehend your request?
### Before asking a question
- Is the topic a question for our [discussion board], or is it a bug report or
change request that should better be raised on our [issue tracker]?
- Is there an open discussion on the topic of your request? If the answer is yes,
does your question match the direction of the discussion, or should you open a
new discussion?
- Did your provide our community with all the necessary information to
understand your question and help you quickly, or can you make it easier to
help you?
### Before commenting
- Is your comment relevant to the topic of the current page, post, issue, or
discussion, or is it a better idea to create a new issue or discussion?
- Does your comment add value to the conversation? Is it constructive and
respectful to our community and us maintainers? Could you just use a
[:octicons-smiley-16: reaction][reaction] instead?
[Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
[reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
## Rights and responsibilities
As maintainers, we reserve the right and have the responsibility to close,
remove, reject, or edit contributions, such as issues, discussions, comments,
or commits, that do not align with our contribution guidelines and our
[Code of Conduct].
### Incomplete issues
We have invested significant time in reviewing our contribution process and
carefully assessed the essential requirements when reviewing and responding to
issues. Each field in our issue templates has been thoughtfully curated, helping
us to understand your matter.
__Therefore, it is mandatory to fill out every field as requested__ to the best
of your knowledge. We need all of this information because it ensures that every
user and maintainer, regardless of their experience, can understand the content
and severity of your bug report or change request.
__We reserve the right to close issues missing essential information__, such as
but not limited to [minimal reproductions], or that do not comply with the
quality standards and requirements stated in our issue templates. Issues
can be reopened once the missing information has been provided.
[minimal reproductions]: ../guides/creating-a-reproduction.md
### Code of Conduct
As stated in our [Code of Conduct], we expect all members of our community to
treat each other with respect, and use inclusive and welcoming language. We
always strive to create a positive and supportive environment and do not accept
inappropriate, offensive, or harmful behavior.
We take violations seriously and will take appropriate action in response.

77
docs/contributing/reporting-a-bug.md
View File

@@ -1,9 +1,9 @@
# Reporting a bug
# Bug reports
Material for MkDocs is an actively maintained project that we constantly strive
to improve. With a project of this size and complexity, bugs may occur. If you
think you have discovered a bug, you can help us by submitting an issue in our
public [issue tracker] by following this guide.
public [issue tracker], following this guide.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
@@ -14,7 +14,7 @@ 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.__
__But first, please do the following things before creating an issue.__
### Upgrade to latest version
@@ -37,7 +37,7 @@ 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]
- [`hooks`][hooks]
- [`extra_css`][extra_css]
- [`extra_javascript`][extra_javascript]
@@ -63,10 +63,10 @@ problems.__
[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
[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
[discussion board]: https://github.com/squidfunk/mkdocs-material/issues
[StackOverflow]: https://stackoverflow.com
[that our documentation explicitly mentions]: ?q="extends+base"
@@ -104,7 +104,7 @@ 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
but we mean the same. When you include the search terms and related links
in your bug report, you help us to adjust and improve the documentation.
---
@@ -119,13 +119,13 @@ how to create a complete and helpful bug report.
## 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
as possible and more efficient for our community and us. It is the result of
our experience answering and fixing more than 1,600 issues (and counting) and
consists of the following parts:
- [Title]
- [Context] <small>optional</small>
- [Description]
- [Bug description]
- [Related links]
- [Reproduction]
- [Steps to reproduce]
@@ -134,7 +134,7 @@ consists of the following parts:
[Title]: #title
[Context]: #context
[Description]: #description
[Bug description]: #bug-description
[Related links]: #related-links
[Reproduction]: #reproduction
[Steps to reproduce]: #steps-to-reproduce
@@ -148,16 +148,16 @@ 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
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context <small>optional</small> { #context }
Before describing the bug, you can provide additional context for us to
understand what you are trying to achieve. Explain the circumstances
understand what you were trying to achieve. Explain the circumstances
in which you're using Material for MkDocs, and what you _think_ might be
relevant. Don't write about the bug here.
@@ -165,7 +165,7 @@ relevant. Don't write about the bug here.
> environments or edge cases, for example, when your documentation contains
> thousands of documents.
### Description
### Bug description
Now, to the bug you want to report. Provide a clear, focused, specific, and
concise summary of the bug you encountered. Explain why you think this is a bug
@@ -235,17 +235,17 @@ make it easier for us maintainers to improve the documentation.
### 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.
it allows us maintainers to instantly recreate the necessary conditions to
inspect the bug to quickly find its root cause. It's a proven fact that issues
with concise and small reproductions can be fixed much faster.
[:material-bug:&nbsp; Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
---
After you have created the reproduction, you should have a .zip file, ideally not
larger than 1 MB. Just drag and drop the .zip file into this field, which will
automatically upload it to GitHub.
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
@@ -256,24 +256,24 @@ automatically upload it to GitHub.
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
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
[built-in info plugin]: ../plugins/info.md
### Steps to reproduce
At this point, you provided us with enough information to understand the bug,
and you gave us a reproduction that we could run and inspect. However, when we
run your reproduction, it might not be immediately apparent how we can see
At this point, you provided us with enough information to understand the bug
and provided us with a reproduction that we could run and inspect. However, when
we run your reproduction, it might not be immediately apparent how we can see
the bug in action.
Next, please list the specific steps we should follow when running your
Thus, please list the specific steps we should follow when running your
reproduction to observe the bug. Keep the steps short and concise, and make sure
not to leave anything out. Use simple language as you would explain it to a
five-year-old, and focus on continuity.
@@ -284,11 +284,17 @@ five-year-old, and focus on continuity.
### Browser <small>optional</small> { #browser }
If you're reporting a bug that only happens in one or more _specific_ browsers,
If you're reporting a bug that only occurs in one or more _specific_ browsers,
we need to know which browsers are affected. This field is optional, as it is
only relevant when the bug you are reporting does not involve a crash when
[previewing] or [building] your site.
---
:material-incognito: __Incognito mode__ – Please verify that a the bug is
not caused by a browser extension. Switch to incognito mode and try to reproduce
the bug. If it's gone, it's caused by an extension.
> __Why we need this__: some bugs only occur in specific browsers or versions.
> Since now, almost all browsers are evergreen, we usually don't need to know the
> version in which it occurs, but we might ask for it later. When in doubt, add
@@ -300,15 +306,8 @@ only relevant when the bug you are reporting does not involve a crash when
### 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 the best of your knowledge to provide us with everything we
need to know to help you.
report – you are almost done. The checklist ensures that you have read this guide
and have worked to your best knowledge to provide us with everything we need to
know to help you.
__We'll take it from here.__
## 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.

66
docs/contributing/reporting-a-docs-issue.md
View File

@@ -1,18 +1,18 @@
# Reporting a docs issue
# Documentation issues
In the past seven years, our documentation has grown to more than 60 pages. With
a site being this large, inconsistencies can occur. If you find an inconsistency
or see room for clarification or improvement, please submit an issue to
our public [issue tracker] by following this guide.
Our documentation is composed of more than 80 pages and includes extensive
information on features, configurations, customizations, and much more. If you
have found an inconsistency or see room for improvement, please follow this
guide to submit an issue on our [issue tracker].
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
## Issue template
Reporting a documentation issue is usually less involved than reporting a bug,
as we don't need a [reproduction]. Please thoroughly read the following guide
before creating a new documentation issue, and provide the following information
as part of the issue:
as we don't need a [reproduction]. Please thoroughly read this guide before
creating a new documentation issue, and provide the following information as
part of the issue:
- [Title]
- [Description]
@@ -31,43 +31,45 @@ as part of the issue:
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.
our issue tracker.
| <!-- --> | Example |
| -------- | -------- |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Description
Provide a clear and concise summary of the inconsistency or issue you
encountered in the documentation or the documentation section that needs
improvement. Explain why you think the documentation should be adjusted and
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.
- __Keep it short and concise__ – if the inconsistency or issue can be
precisely explained in one or two sentences, perfect. Maintainers and future
users will be grateful for having to read less.
- __One issue at a time__ – if you encounter several unrelated inconsistencies,
please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
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.
> __Why we need this__: describing the problem clearly and concisely is a
> prerequisite for improving our documentation – we need to understand what's
> wrong, so we can fix it.
### Related links
After you described the documentation section that needs to be adjusted above,
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)
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,
> __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 <small>optional</small> { #proposed-change }
Now that you have provided us with the description and links to the
@@ -75,15 +77,15 @@ 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.
> __Why we need this__: an improvement proposal can be beneficial for other
> users who encounter the same issue, as they offer solutions before we
> maintainers can update the documentation.
### Checklist
Thanks for following the guide and 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 the best of your knowledge to provide us with every piece of
information we need to improve our documentation.
Thanks for following the guide and providing valuable feedback for our
documentation – you are almost done. The checklist ensures that you have read
this guide and have worked to your best knowledge to provide us with every piece
of information we need to improve it.
__We'll take it from here.__

151
docs/contributing/requesting-a-change.md
View File

@@ -1,22 +1,22 @@
# Requesting a change
# Change requests
Material for MkDocs is a powerful tool for creating 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.
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.
we kindly ask you to take the time to read the following guidelines before
submitting your change request in our public [issue tracker]. This will help us
better understand the proposed change and how it will benefit our community.
This guide is our best effort to explain the criteria and reasoning behind our
decisions when evaluating change requests and considering them for
implementation.
implementation.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
@@ -27,45 +27,52 @@ 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.__
__Please do the following things before creating an issue.__
[philosophy]: ../philosophy.md
### It's not a bug, it's a feature
Change requests are intended to suggest minor adjustments, ideas for new
features, or to 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.
features, or to kindly influence the project's direction and vision. It is
important to note that change requests are not intended for reporting bugs, as
they're missing essential information for debugging.
If you want to report a bug, please refer to our [bug reporting guide] instead.
[bug reporting guide]: reporting-a-bug.md
### Source of inspiration
### Look for sources of inspiration
If you have seen your idea implemented in another static site generator or
theme, make sure to collect enough information on its implementation before
submitting, as this allows us to evaluate potential fit more quickly. Explain
what you like and dislike about the implementation.
### Benefit for the community
### Connect with our community
Our [discussion board] is the best place to connect with our community. When
evaluating new ideas, it's essential to seek input from other users and consider
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:&nbsp; Start a discussion][Start a discussion]{ .md-button .md-button--primary }
__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
them in the change request.__[^1]
[^1]:
We might be using terminology in our documentation different from yours,
but we mean the same. When you include the search terms and related links
in your change request, you help us to adjust and improve the documentation.
[:octicons-comment-discussion-16:&nbsp; Start a discussion][discussion board]{ .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
Now that you have taken the time to do the necessary preliminary work and ensure
that your idea meets our requirements, you are invited to create a change
request. The following guide will walk you through all the necessary steps to
request. The following guide will walk you through all the necessary steps to
help you submit a comprehensive and useful issue:
- [Title]
@@ -87,15 +94,15 @@ help you submit a comprehensive and useful issue:
### 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
summary of the idea, so the potential impact and benefit for our community can
be inferred from the title.
| <!-- --> | Example |
| -------- | -------- |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context <small>optional</small> { #context }
@@ -111,13 +118,13 @@ relevant. Don't write about the change request here.
### 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]
Next, provide a detailed and clear description of your idea. Explain why your
idea is relevant to Material for MkDocs and must be implemented here and not
in one of its dependencies:[^2]
[^1]:
[^2]:
Sometimes, users suggest ideas on our [issue tracker] that concern one of
our upstream dependencies, including [MkDocs], [Python Markdown],
our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
[Python Markdown Extensions] or third-party plugins. It's a good idea to
think about whether your idea is beneficial to other themes, upstreaming
change requests for a bigger impact.
@@ -126,12 +133,12 @@ in one of its dependencies:[^1]
[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
- __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.
- __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.
---
@@ -140,65 +147,95 @@ 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
> 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
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
discussed this idea with our community on our discussion board, please include
the link to the discussion as well.
> __Why we need this__: Related links help us gain a comprehensive
> understanding of your change request by providing additional context.
> Additionally, linking to previous issues and discussions allows us
> to quickly evaluate the feedback and input already provided by the community.
> to quickly evaluate the feedback and input already provided by our community.
### Use cases
Explain how your change request would work from an author's and user's
perspective – what's the expected impact, and why does it benefit not only you
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
> __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 <small>optional</small> { #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
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
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.
> __Why this might be helpful__: Illustrations and visuals can help us
> maintainers better understand and envision your idea. Screenshots, sketches,
> or mockups can create an additional level of detail and clarity that text
> alone may not be able to convey. Also, seeing how your idea has been
> implemented in other projects can help us understand its potential impact and
> feasibility in Material for MkDocs, which helps us maintainers evaluate and
> triage change requests.
### Checklist
Thanks for following the change request guide and creating a high-quality
change request. This section ensures that you have read this guide and have
worked to the best of your knowledge to provide us with every piece of
information to review your idea for Material for MkDocs.
Thanks for following the guide and creating a high-quality change request – you
are almost done. The checklist ensures that you have read this guide and have
worked to your best knowledge to provide us with every piece of information to
review your idea for Material for MkDocs.
__We'll take it from here.__
---
## Rejected requests
__Your change request got rejected? We're sorry for that.__ We understand it can
be frustrating when your ideas don't get accepted, but as the maintainers of a
very popular project, we always need to consider the needs of our entire
community, sometimes forcing us to make tough decisions.
We always have to consider and balance many factors when evaluating change
requests, and we explain the reasoning behind our decisions whenever we can.
If you're unsure why your change request was rejected, please don't hesitate
to ask for clarification.
The following principles (in no particular order) form the basis for our
decisions:
- [ ] Alignment with vision and tone of the project
- [ ] Compatibility with existing features and plugins
- [ ] Compatibility with all screen sizes and browsers
- [ ] Effort of implementation and maintenance
- [ ] Usefulness to the majority of users
- [ ] Simplicity and ease of use
- [ ] Accessibility
But that's not the end of your idea – you can always implement it on your own
via [customization]. If you're unsure about how to do that or want to know if
someone has already done it, feel free to get in touch with our community on
the [discussion board].
[customization]: ../customization.md

93
docs/conventions.md Normal file
View File

@@ -0,0 +1,93 @@
# Conventions
This section explains several conventions used in this documentation.
## Symbols
This documentation use some symbols for illustration purposes. Before you read
on, please make sure you've made yourself familiar with the following list of
conventions:
### <!-- md:sponsors --> – Sponsors only { data-toc-label="Sponsors only" }
The pumping heart symbol denotes that a specific feature or behavior is only
available to sponsors via [Insiders]. Make sure that you have access to
[Insiders] if you want to use the feature.
### <!-- md:version --> – Version { data-toc-label="Version" }
The tag symbol in conjunction with a version number denotes when a specific
feature or behavior was added. Make sure you're at least on this version
if you want to use it.
### <!-- md:version insiders- --> – Version (Insiders) { data-toc-label="Version (Insiders)" }
The tag symbol with a heart in conjunction with a version number denotes that a
specific feature or behavior was added to the [Insiders] version of Material for
MkDocs.
### <!-- md:default --> – Default value { #default data-toc-label="Default value" }
Some properties in `mkdocs.yml` have default values for when the author does not
explicitly define them. The default value of the property is always included.
#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
Some default values are not set to static values but computed form other values,
like the site language, repository provider, or other settings.
#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }
Some properties do not contain default values. This means that the functionality
that is associated with them is not available unless explicitly enabled.
### <!-- md:flag metadata --> – Metadata property { #metadata data-toc-label="Metadata property" }
This symbol denotes that the thing described is a metadata property, which can
be used in Markdown documents as part of the front matter definition.
### <!-- md:flag multiple --> – Multiple instances { #multiple-instances data-toc-label="Multiple instances" }
This symbol denotes that the plugin supports multiple instances, i.e, that it
can be used multiple times in the `plugins` setting in `mkdocs.yml`.
### <!-- md:feature --> – Optional feature { #feature data-toc-label="Optional feature" }
Most of the features are hidden behind feature flags, which means they must
be explicitly enabled via `mkdocs.yml`. This allows for the existence of
potentially orthogonal features.
### <!-- md:flag experimental --> – Experimental { data-toc-label="Experimental" }
Some newer features are still considered experimental, which means they might
(although rarely) change at any time, including their complete removal (which
hasn't happened yet).
### <!-- md:plugin --> – Plugin { data-toc-label="Plugin" }
Several features are implemented through MkDocs excellent plugin architecture,
some of which are built-in and distributed with Material for MkDocs, so no
installation is required.
### <!-- md:extension --> – Markdown extension { data-toc-label="Markdown extension" }
This symbol denotes that the thing described is a Markdown extension, which can
be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
parser.
### <!-- md:flag required --> – Required value { #required data-toc-label="Required value" }
Some (very few in fact) properties or settings are required, which means the
authors must explicitly define them.
### <!-- md:flag customization --> – Customization { #customization data-toc-label="Customization" }
This symbol denotes that the thing described is a customization that must be
added by the author.
### <!-- md:utility --> – Utility { data-toc-label="Utility" }
Besides plugins, there are some utilities that build on top of MkDocs in order
to provide extended functionality, like for example support for versioning.
[Insiders]: insiders/index.md

15
docs/creating-your-site.md
View File

@@ -1,6 +1,6 @@
# Creating your site
After you've [installed] 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:
@@ -48,7 +48,7 @@ theme:
???+ tip "Recommended: [configuration validation and auto-complete]"
In order to minimize friction and maximize productivity, Material for MkDocs
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:
@@ -66,8 +66,8 @@ theme:
"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:material.extensions.emoji.to_svg",
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
]
}
@@ -223,12 +223,5 @@ need for operating a database or server, as it is completely self-contained.
The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
or your private web space.
!!! note "Enterprise support"
If you're using Material for MkDocs in your organization and need
assistance, e.g., to __reduce build times__, __improve performance__ or
ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
to discuss our __enterprise support__ offerings. We're happy to help!
[GitHub Pages]: publishing-your-site.md#github-pages
[GitLab pages]: publishing-your-site.md#gitlab-pages

45
docs/customization.md
View File

@@ -100,6 +100,7 @@ assets may also be put in the `overrides` directory:
│ │ └─ analytics.html # Analytics setup
│ ├─ languages/ # Translation languages
│ ├─ actions.html # Actions
│ ├─ alternate.html # Site language selector
│ ├─ comments.html # Comment system (empty by default)
│ ├─ consent.html # Consent
│ ├─ content.html # Page content
@@ -113,6 +114,7 @@ assets may also be put in the `overrides` directory:
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ pagination.html # Pagination (used for blog)
│ ├─ palette.html # Color palette toggle
│ ├─ post.html # Blog post excerpt
│ ├─ search.html # Search interface
│ ├─ social.html # Social links
@@ -223,7 +225,7 @@ 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 :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
Prior to <!-- md:version 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
@@ -235,20 +237,38 @@ directly in the source of the theme and recompile it.
### Environment setup
In order to start development on Material for MkDocs, a [Node.js] version of
at least 14 is required. First, clone the repository:
First, clone the repository:
```
git clone https://github.com/squidfunk/mkdocs-material
```
Next, all dependencies need to be installed, which is done with:
```
cd mkdocs-material
```
Next, create a new [Python virtual environment][venv] and
[activate][venv-activate] it:
```
python -m venv venv
source venv/bin/activate
```
[venv]: https://docs.python.org/3/library/venv.html
[venv-activate]: https://docs.python.org/3/library/venv.html#how-venvs-work
Then, install all Python dependencies:
```
pip install -e .
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
pip install nodeenv
```
Finally, install the [Node.js] LTS version into the Python virtual environment
and install all Node.js dependencies:
```
nodeenv -p -n lts
npm install
```
@@ -290,7 +310,7 @@ npm run build # (1)!
1. While this command will build all theme files, it will skip the overrides
used in Material for MkDocs' own documentation which are not distributed
with the theme. If you forked the theme and want to build the overrides
as well, use:
as well, e.g. before submitting a PR with changes, use:
```
npm run build:all
@@ -303,10 +323,3 @@ 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.
!!! note "Enterprise support"
If you're using Material for MkDocs in your organization and need
assistance, e.g., to __reduce build times__, __improve performance__ or
ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
to discuss our __enterprise support__ offerings. We're happy to help!

5
docs/enterprise-support.md Normal file
View File

@@ -0,0 +1,5 @@
---
template: redirect.html
location: https://calendly.com/squidfunk/enterprise
status: new
---

37
docs/faq/sponsoring.md
View File

@@ -79,15 +79,28 @@ Note that [$15] is the minimum amount to be granted access to Insiders.
[$15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
[__How is my sponsorship contribution used to support the project?__](#sponsorship-support){ #sponsorship-support }
[__How are sponsorship contributions used?__](#sponsorship-support){ #sponsorship-support }
Your sponsorship contribution directly supports the development and
maintenance of the project, by buying us maintainers time. It allows us to
dedicate more time and resources to enhance the project's features and
functionality. The additional funding helps us prioritize improvements and
updates, benefiting Insiders users and the wider community. We also actively
contribute to other upstream projects, fostering collaboration and giving
back to the Open Source ecosystem.
It's vital to recognize that the total sponsorship amount doesn't directly
translate into the funds we have available for use. The way we allocate
sponsorship amounts is detailed as follows:
1. __Taxes__: Since we provide a service to our sponsors, we're of course
legally obligated to pay sales tax. This requirement applies to all
sponsorship contributions, aligning us with standard business practices
as for the rest of the world.
2. __Sponsorships__: A significant portion of our funding is redirected to
upstream projects. This cultivates collaboration and supports the broader
Open Source ecosystem. Those projects and their maintainers are essential
for the ongoing development of Material for MkDocs.
[Explore our sponsorships](https://github.com/squidfunk?tab=sponsoring).
3. __Funds__: We are in the process of forming a team devoted to Material for
MkDocs and are proactively compensating critical contributors. These
funds cover various aspects of the project, like the creation of new
features, bug resolution, support, and sponsor relations.
[__Are there any limitations on the number of sponsors for a particular tier?__](#sponsorship-limitations){ #sponsorship-limitations }
@@ -115,7 +128,7 @@ We manage all our transactions and sponsorships through [GitHub Sponsors] and
[our sponsors' page]. On there, you can choose from five different sponsorship
tiers and pay by credit card. Please note that as of the beginning of 2023,
[GitHub no longer supports PayPal] payments. If you wish to pay with PayPal,
ou can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
you can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
provide you with a payment receipt once your purchase is successful.
If you're a company and need assistance choosing the right payment method,
@@ -371,8 +384,8 @@ appearance of your site should be optional. Most Insiders features enhance the
overall experience, e.g., by adding icons to pages or providing a feedback
widget. While these features add value for your site's users, they should be
optional for previewing when making changes to content. Currently, the only
content-related features in Insiders that non-Insiders users can't properly
preview are [Annotations] and [Card grids].
content-related feature in Insiders that non-Insiders users can't properly
preview are [Card grids].
This means that outside collaborators can build the documentation locally with
Material for MkDocs, and when they push their changes, your CI pipeline will
@@ -384,10 +397,8 @@ See the [getting started guide] for more information.
[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
[getting started guide]: ../insiders/getting-started.md#caveats
[Annotations]: ../reference/annotations.md?h=anno#annotations
[Card grids]: ../reference/grids.md?h=grids#using-card-grids
## Support
[__How can I contact support if I have questions about becoming a sponsor?__ ](#support-contact){ #support-contact }

20
docs/getting-started.md
View File

@@ -1,7 +1,7 @@
# Getting started
Material for MkDocs is a powerful documentation framework on top of [MkDocs],
a static site generator for project documentation.[^1] If you're familiar with
a static site generator for project documentation.[^1] If you're familiar with
Python, you can install Material for MkDocs with [`pip`][pip], the Python
package manager. If not, we recommend using [`docker`][docker].
@@ -68,14 +68,14 @@ install those packages separately.
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
15m – Learn how to create and host a documentation site using Material for
15m – Learn how to create and host a documentation site using Material for
MkDocs on GitHub Pages in a step-by-step guide.
[How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20
---
__Tip__: If you don't have prior experience with Python, we recommend reading
__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.
@@ -107,7 +107,7 @@ and pull the image with:
docker pull squidfunk/mkdocs-material:9
```
The `mkdocs` executable is provided as an entry point and `serve` is the
The `mkdocs` executable is provided as an entry point and `serve` is the
default command. If you're not familiar with Docker don't worry, we have you
covered in the following sections.
@@ -126,7 +126,7 @@ The following plugins are bundled with the Docker image:
of the official image small. If the plugin you want to use is not included,
you can add them easily:
=== "Material for MkDocs"
=== "Material for MkDocs"
Create a `Dockerfile` and extend the official image:
@@ -166,18 +166,10 @@ want to use the very latest version:
git clone https://github.com/squidfunk/mkdocs-material.git
```
The theme will reside in the folder `mkdocs-material/material`. After cloning
from `git`, you must install all required dependencies with:
Next, install the theme and its dependencies with:
```
pip install -e mkdocs-material
```
!!! note "Enterprise support"
If you're using Material for MkDocs in your organization and need
assistance, e.g., to __reduce build times__, __improve performance__ or
ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
to discuss our __enterprise support__ offerings. We're happy to help!
[GitHub]: https://github.com/squidfunk/mkdocs-material

14
docs/guides/creating-a-reproduction.md
View File

@@ -1,8 +1,8 @@
# 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
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
@@ -56,7 +56,7 @@ just delete and recreate the environment. It's trivial to set up:
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
so create a new folder in your working directory and a new virtual environment
inside it. Next:
1. As mentioned in our [bug reporting guide], ensure that you're running the
@@ -87,7 +87,7 @@ inside it. Next:
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
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.
@@ -95,11 +95,11 @@ inside it. Next:
[bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
[minimal configuration]: ../creating-your-site.md#minimal-configuration
### Creating a .zip file
### 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
will add all relevant files to a `.zip`, print a summary to the terminal and
exit. Add the following lines to `mkdocs.yml`:
``` yaml

3
docs/index.md
View File

@@ -1,6 +1,9 @@
---
template: home.html
title: Material for MkDocs
social:
cards_layout_options:
title: Documentation that simply works
---
Welcome to Material for MkDocs.

65
docs/insiders/changelog.md
View File

@@ -2,6 +2,69 @@
## Material for MkDocs Insiders
### 4.42.0 <small>September 19, 2023</small> { id="4.42.0" }
- Added support for using git submodules in projects plugin
- Added support for transforming project configurations
- Improved resilience of optimize and blog plugin
- Fixed optimize plugin crashing on `.jpeg` extension
- Fixed project URLs not using site URLs in projects plugin
### 4.41.0 <small>September 11, 2023</small> { id="4.41.0" }
- Improved multi-instance support for optimize plugin
- Added inclusion and exclusion patterns for optimize plugin
- Added transparent keyword for color handling in social plugin
- Changed default quality of PNGs to 3 in optimize plugin
- Fixed #5979: meta file not detected in root of docs directory
### 4.40.4 <small>September 4, 2023</small> { id="4.40.4" }
- Fixed privacy plugin choking on boolean HTML5 attributes
- Fixed wrapping of inline code blocks in typeset table of contents
- Fixed blog plugin error when running under dirty reload
### 4.40.3 <small>September 2, 2023</small> { id="4.40.3" }
- Fixed #5946: Docker image missing pngquant for optimize plugin
### 4.40.2 <small>August 31, 2023</small> { id="4.40.2" }
- Added configurable error handling capabilities for social plugin
- Fixed #5922: Blog plugin shows no posts when building a standalone blog
- Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
- Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
### 4.40.1 <small>August 27, 2023</small> { id="4.40.1" }
- Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
- Fixed empty category pages in blog plugin (4.40.0 regression)
### 4.40.0 <small>August 26, 2023</small> { id="4.40.0" }
- Added logo, title and description options to social plugin default layouts
- Fixed privacy plugin compatibility issue with Python < 3.10
- Fixed #5896: Blog plugin errors when using custom index pages
### 4.39.3 <small>August 24, 2023</small> { id="4.39.3" }
- Fixed lxml dependency missing in Docker container (4.39.2 regression)
### 4.39.2 <small>August 23, 2023</small> { id="4.39.2" }
- Fixed color palette toggle being reversed (9.2.0 regression)
### 4.39.1 <small>August 21, 2023</small> { id="4.39.1" }
- Fixed git diff in tags plugin after merging back 9.2.0 changes
### 4.39.0 <small>August 3, 2023</small> { id="4.39.0" }
- Added support for hoisting theme media files when building projects
- Added support for sorting pages on tags index for tags plugin
- Added support for adding date of last update to blog posts
- Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
### 4.38.1 <small>August 1, 2023</small> { id="4.38.1" }
- Improved nested serve mode for projects plugin
@@ -425,7 +488,7 @@
### 4.12.0 <small>March 27, 2022</small> { id="4.12.0" }
- Added support for card grids and grid layouts
- Fixed #3685: Annotations sometimes broken when using instant loading
- Fixed #3685: Annotations sometimes broken when using instant loading
- Fixed #3742: Automatically add Mermaid.js when building for offline usage
### 4.11.0 <small>March 6, 2022</small> { id="4.11.0" }

92
docs/insiders/getting-started.md
View File

@@ -6,7 +6,7 @@ title: Getting started with Insiders
Material for MkDocs Insiders is a compatible drop-in replacement for Material
for MkDocs, and can be installed similarly using [`pip`][pip],
[`docker`][docker] or [`git`][git]. Note that in order to access the Insiders
[`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
@@ -18,7 +18,7 @@ repository, you need to [become an eligible sponsor] of @squidfunk on GitHub.
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
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
@@ -66,7 +66,7 @@ comfortable self-hosting:
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
(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
@@ -88,7 +88,7 @@ outlined in the [Getting Started guide](../getting-started.md#with-docker).
outlined and discussed in #2442. It was removed on June 1, 2021.
[^3]:
When forking a repository, GitHub will disables all workflows. While this
When forking a repository, GitHub will disable all workflows. While this
is a reasonable default setting, you need to enable GitHub Actions to be
able to automatically build and publish a Docker image on
[GitHub Container Registry].
@@ -150,65 +150,45 @@ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-materi
[upgrade guide]: ../upgrade.md
## Caveats
## Built-in plugins
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.
When you're using built-in plugins that are solely available via Insiders,
outside contributors won't be able to build your documentation project on their
local machine. This is the reason why we developed the [built-in group plugin]
that allows to conditionally load plugins:
### Built-in plugins
``` yaml
plugins:
- search
- social
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]:
# CI=1 mkdocs build
- group:
enabled: !ENV CI
plugins:
- git-revision-date-localized
- git-committers
=== ":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
# INSIDERS=1 mkdocs build
- group:
enabled: !ENV INSIDERS
plugins:
- optimize
- privacy
```
!!! tip "Sharing plugin and extension configuration"
Of course, you can also enable both groups with:
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: {}
```
```
CI=1 INSIDERS=1 mkdocs build
```
[^1]:
Previously we recommended to use [configuration inheritance] to work around
this limitations, but the brand new [built-in group plugin] is a much better
approach, as it allows you to use a single configuration file for building
your project with the community edition and Insiders version of Material
for MkDocs.
[built-in group plugin]: ../plugins/group.md
[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance

21
docs/insiders/index.md
View File

@@ -130,7 +130,7 @@ 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
organization and the GitHub account of the individual that should be added as a
collaborator.[^4]
You can cancel your sponsorship anytime.[^5]
@@ -188,7 +188,6 @@ You can cancel your sponsorship anytime.[^5]
[![Sparkfun]](https://sparkfun.com/){ target=_blank title="Sparkfun Electronics" }
[![Eccenca]](https://eccenca.com/){ target=_blank title="Eccenca" }
[![Neptune]](https://neptune.ai/){ target=_blank title="Neptune" }
[![Cash App]](https://cash.app/){ target=_blank title="Cash App" }
[![RackN]](https://rackn.com/){ target=_blank title="RackN" }
[![CivicActions]](https://civicactions.com/){ target=_blank title="CivicActions" }
[![bitcrowd]](https://bitcrowd.net/){ target=_blank title="bitcrowd" }
@@ -200,6 +199,8 @@ You can cancel your sponsorship anytime.[^5]
[![Koor]](https://koor.tech/){ target=_blank title="Koor" }
[![Astral]](https://astral.sh/){ target=_blank title="Astral" }
[![Oikolab]](https://oikolab.com/){ target=_blank title="Oikolab" }
[![Bühler Group]](https://www.buhlergroup.com/){ target=_blank title="Bühler Group" }
[![Transformation Flow]](https://transformationflow.io/){ target=_blank title="Transformation Flow" }
</div>
@@ -235,6 +236,8 @@ You can cancel your sponsorship anytime.[^5]
[Koor]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-koor.png
[Astral]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-astral.png
[Oikolab]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-oikolab.png
[Bühler Group]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-buhler.png
[Transformation Flow]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-transformationflow.png
<hr />
@@ -257,7 +260,7 @@ You can cancel your sponsorship anytime.[^5]
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: #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.
@@ -286,7 +289,7 @@ are released for general availability.
- [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Navigation subtitles]
[Meta plugin]: ../reference/index.md#built-in-meta-plugin
[Meta plugin]: ../plugins/meta.md
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
@@ -303,8 +306,8 @@ are released for general availability.
- [x] [Privacy plugin: external links]
- [x] [Instant prefetching]
[Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
[Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
[Optimize plugin]: ../plugins/optimize.md
[Typeset plugin]: ../plugins/typeset.md
[Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
[Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
[Navigation path]: ../setup/setting-up-navigation.md#navigation-path
@@ -319,7 +322,7 @@ are released for general availability.
- [x] [Code annotations: custom selectors]
- [ ] Code line wrap button
[Projects plugin]: ../setup/building-an-optimized-site.md#built-in-projects-plugin
[Projects plugin]: ../plugins/projects.md
[Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
[Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
[Code range selection]: ../reference/code-blocks.md#code-selection-button
@@ -488,7 +491,7 @@ 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
feedback widget. While these 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:
@@ -533,7 +536,7 @@ __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
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

65
docs/philosophy.md
View File

@@ -13,12 +13,12 @@ discusses the [conventions] used in this documentation.
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
- __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
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
@@ -33,62 +33,3 @@ discusses the [conventions] used in this documentation.
- __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 } &nbsp; 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: &nbsp; __{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: &nbsp; __{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: &nbsp; __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: &nbsp; __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: &nbsp; __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: &nbsp; __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: &nbsp; __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

1460
docs/plugins/blog.md Normal file
View File

File diff suppressed because it is too large Load Diff

121
docs/plugins/group.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: Built-in group plugin
icon: material/format-list-group
---
# Built-in group plugin
The group plugin allows to group plugins into logical units to conditionally
enable or disable them for specific environments with the use of
[environment variables][mkdocs.env], e.g., to only enable a subset of
plugins when [building your project] during continuous integration (CI).
[building your project]: ../creating-your-site.md#building-your-site
## Objective
### How it works
The plugin conditionally and lazily loads all plugins that are part of a group
if and only if the group is enabled, which means that the plugin doesn't add any
overhead when the group is disabled. It also means that the grouped plugins
only need to be installed when the group is enabled.
The plugins that are part of the group are executed in the same order as if
they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
Thus, order is preserved and deterministic.
### When to use it
Whenever you're using multiple plugins that are only required in specific
environments, e.g., when building your project during continuous integration
(CI), the plugin is the perfect utility for making configuration simpler, as it
removes the need for splitting configuration into multiple files.
It can be used with any built-in or third-party plugin.
## Configuration
<!-- md:version 9.3.0 -->
<!-- md:plugin [group] – built-in -->
<!-- md:flag multiple -->
<!-- md:flag experimental -->
As with all [built-in plugins], getting started with the group plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start
splitting plugins into logical units:
``` yaml
plugins:
- group
```
The group plugin is built into Material for MkDocs and doesn't need to be
installed.
[group]: group.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.2.0 -->
<!-- md:default `false` -->
Use this setting to enable or disable the plugin when [building your project].
The plugin behaves differently than all other built-in plugins – __it is
disabled by default__. To enable a group, use:
``` yaml
plugins:
- group:
enabled: !ENV CI # (1)!
```
1. If you only want to use the group plugin for better organization and
always want to enable the plugins that are part of it, use:
``` yaml
plugins:
- group:
enabled: true
```
The decision to disable the plugin by default was made to simplify the usage
of environment variables, as it removes the need to provide a default value for
an environment variable.
Now, when [building your project], you can enable a group by setting the
[environment variable][mkdocs.env]:
``` sh
CI=true mkdocs build
```
[building your project]: ../creating-your-site.md#building-your-site
---
#### <!-- md:setting config.plugins -->
<!-- md:version 9.2.0 -->
<!-- md:default none -->
Use this setting to list the plugins that are part of the group. The syntax is
exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
simply copy the list of plugins that you want to group, e.g:
``` yaml
plugins:
- group:
plugins:
- optimize
- minify
```
The plugins mentioned here are just used for illustration purposes.

246
docs/plugins/index.md Normal file
View File

@@ -0,0 +1,246 @@
# Built-in plugins
Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
evolved into a full-fledged framework for building and maintaining documentation.
The theme is still the core of the project, but it's now accompanied by a
growing number of complementary built-in plugins.
We strive to make those plugins as modular and generic as possible, so that they
can be used in a wide variety of projects and use cases. By providing useful
default settings, we also try to make them as easy to use as possible, so that
you can get started quickly, tweaking their settings later on. When
developing built-in plugins, we always adhere to the following design principles:
- **Modularity:** Built-in plugins are designed to be modular, so that they can
be easily combined to implement sophisticated pipelines. For example, the
[offline], [optimize] and [privacy] plugins can be used together to build
truly [offline-capable documentation].
- **Interoperability:** Built-in plugins are designed to be as compatible as
possible, so they can be used in combination with other plugins, including
third-party plugins. We strive to make it simple to integrate with the vast
ecosystem that has evolved around [MkDocs][mkdocs].
- **Performance:** Built-in plugins are designed to be as fast and
memory-efficient as possible, so that they don't unnecessarily slow down
builds. This is particularly important for large documentation projects with
thousands of pages.
[mkdocs]: https://www.mkdocs.org/
[design principles]: ../design-principles.md
[offline-capable documentation]: ../setup/building-for-offline-usage.md
## Categories
### Management
The following plugins greatly improve the authoring experience when working on
documentation projects by providing better management capabilities, from the
management of plugins, multiple projects, and metadata, to the creation of
minimal reproductions for bug reports:
<div class="grid cards" markdown>
- :material-format-list-group: &nbsp; __[Built-in group plugin][group]__
---
The group plugin allows to group plugins into logical units to conditionally
enable or disable them for specific environments with the use of
[environment variables][mkdocs.env].
---
__Optimal management of plugins when building in different environments__
- :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
---
The meta plugin makes it easy to manage metadata (front matter) for all
pages in a folder, so a certain subset of pages uses specific tags or a
custom template.
---
__Simpler organization, categorization and management of metadata__
- :material-folder-open: &nbsp; __[Built-in projects plugin][projects]__
---
The projects plugin allows to split your main project into multiple distinct
projects, build them concurrently and preview them together as one.
---
__Connect multiple projects together, and build them separately or as one__
- :material-information: &nbsp; __[Built-in info plugin][info]__
---
The info plugin is a small and useful utility that helps to create
self-contained minimal reproductions, so we maintainers can fix reported
bugs more quickly.
---
__Your bug reports are of the highest quality, so we can fix them as fast as
possible__
</div>
[group]: group.md
[info]: info.md
[meta]: meta.md
[projects]: meta.md
### Optimization
The following plugins are designed to help you build optimized documentation,
making it more accessible to your users through faster loading times, better
search engine rankings, beautiful preview images on social media, and GDPR
compliance with a few lines of configuration:
<div class="grid cards" markdown>
- :material-share-circle: &nbsp; __[Built-in social plugin][social]__
---
The social plugin automatically generates beautiful and customizable
social cards for each page of your documentation, showing as previews on
social media.
---
__Links to your site render beautiful social cards when shared on social
media__
- :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
---
The optimize plugin automatically identifies and optimizes all media files
that you reference in your project by using compression and conversion
techniques.
---
__Your site loads faster as smaller images are served to your users__
- :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
---
The privacy plugin downloads external assets automatically for easy
self-hosting, allowing for GDPR compliance with a single line of
configuration.
---
__Your documentation can be made GDPR compliant with minimal effort__
- :material-connection: &nbsp; __[Built-in offline plugin][offline]__
---
The offline plugin adds support for building [offline-capable documentation],
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
file that can be downloaded.
---
__Your documentation can work without connectivity to the internet__
</div>
[offline]: offline.md
[optimize]: optimize.md
[privacy]: privacy.md
[social]: social.md
### Content
The following plugins are designed to help you set up a blog, provide search
functionality to your users, add tags to pages and posts, and use the same
typesetting capabilities in specific parts of the documentation exactly as in
the main content:
<div class="grid cards" markdown>
- :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
---
The blog plugin adds first-class support for blogging to Material for
MkDocs, either as a sidecar to your documentation or as a standalone
installation.
---
__Your blog is built with the same powerful engine as your documentation__
- :material-magnify: &nbsp; __[Built-in search plugin][search]__
---
The search plugin adds a search bar to the header, allowing users to search
the entire documentation, so it's easier for them to find what they're
looking for.
---
__Your documentation is searchable without any external services, even
offline__
- :material-tag-text: &nbsp; __[Built-in tags plugin][tags]__
---
The tags plugin adds first-class support for categorizing pages with tags,
adding the ability to group related pages to improve the discovery of
related content.
---
__Your pages are categorized with tags, yielding additional context__
- :material-format-title: &nbsp; __[Built-in typeset plugin][typeset]__
---
The typeset plugin allows to preserve the enriched presentation of titles
and headlines within the navigation and table of contents.
---
__Sidebars preserve the same formatting as section titles in pages__
</div>
[blog]: blog.md
[search]: search.md
[tags]: tags.md
[typeset]: typeset.md
## Architecture
### Multiple instances
Several built-in plugins have support for multiple instances, which means that
they can be used multiple times in the same configuration file, allowing to
fine-tune behavior for separate sections of your project. Currently, the
following plugins have support for multiple instances:
<div class="mdx-columns" markdown>
- [Built-in blog plugin][blog]
- [Built-in group plugin][group]
- [Built-in optimize plugin][optimize]
- [Built-in privacy plugin][privacy]
- [Built-in social plugin][social]
</div>

155
docs/plugins/info.md Normal file
View File

@@ -0,0 +1,155 @@
---
title: Built-in info plugin
icon: material/information
---
# Built-in info plugin
The info plugin is a utility that is solely intended to create self-contained
[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
[change requests], making communication between us maintainers and you much
easier, as we have a common ground to work on.
[minimal reproductions]: ../guides/creating-a-reproduction.md
[reporting bugs]: ../contributing/reporting-a-bug.md
[change requests]: ../contributing/requesting-a-change.md
## Objective
### How it works
The plugin helps you to prepare a minimal reproduction by collecting the
necessary information about the environment and configuration of your project.
This makes it easier for us to fix bugs, as it requires that you
[upgrade to the latest version] and [remove your customizations].
When following these principles, you can be confident that you don't report a
bug that has already been fixed in a subsequent release, or which is caused by
one of your customizations. Even more importantly, you actively help
us to fix the bug as quickly as possible.
The output of the plugin is a `.zip` file that you can share with us maintainers.
[Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
[Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
### When to use it
Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
like a question or [change request][change requests], you should attach
a small, self-contained minimal reproduction. Runnable examples help to make
communication much more efficient, giving us maintainers more time to benefit
more users by pushing the project forward. Minimal reproductions are mandatory
for bug reports.
## Configuration
<!-- md:version 9.0.0 -->
<!-- md:plugin [info] – built-in -->
In order to get started with the built-in info plugin, just add the following
lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
with us maintainers:
``` yaml
plugins:
- info
```
The info plugin is built into Material for MkDocs and doesn't need to be
installed.
[info]: info.md
[create a minimal reproduction]: ../guides/creating-a-reproduction.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.0.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
It's normally not necessary to specify this setting, but if you want to disable
the plugin, use:
``` yaml
plugins:
- info:
enabled: false
```
[building your project]: ../creating-your-site.md#building-your-site
---
#### <!-- md:setting config.enabled_on_serve -->
<!-- md:version 9.0.6 -->
<!-- md:default `false` -->
Use this setting to control whether the plugin should be enabled when
[previewing your site]. It's normally not necessary to specify this setting,
but if you want to change this behavior, use:
``` yaml
plugins:
- info:
enabled_on_serve: true
```
This setting streamlines the process of creating and inspecting minimal
reproductions, as it allows to quickly iterate on the reproduction without
having to disable the plugin first.
[previewing your site]: ../creating-your-site.md#previewing-as-you-write
### Archive
---
#### <!-- md:setting config.archive -->
<!-- md:version 9.0.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should create a `.zip` file
from the project or exit after the version check. This setting is solely
intended for debugging the plugin itself:
``` yaml
plugins:
- info:
archive: false
```
---
#### <!-- md:setting config.archive_stop_on_violation -->
<!-- md:version 9.0.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should stop creating the `.zip`
file when one of the [requirements] is not satisfied. This setting must only be
used when [reporting a bug][reporting bugs] that is related to a customization
[explicitly mentioned in our documentation]. You can change it with:
``` yaml
plugins:
- info:
archive_stop_on_violation: false
```
If you're using this setting when [reporting a bug][reporting bugs], please
explain why you think it is necessary to include customizations. If you're
unsure, please ask us first by [creating a discussion].
[requirements]: #how-it-works
[explicitly mentioned in our documentation]: ?q=%22extends+base%22
[creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions

195
docs/plugins/meta.md Normal file
View File

@@ -0,0 +1,195 @@
---
title: Built-in meta plugin
icon: material/file-tree
---
# Built-in meta plugin
The meta plugin solves the problem of setting metadata (front matter) for all
pages in a folder, i.e., a subsection of your project, which is particularly
useful to ensure that a certain subset of pages features specific tags, uses a
custom template, or is attributed to an author.
## Objective
### How it works
The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
and recursively merges the contents of those files with the metadata (front
matter) of all pages that are contained in the same folder and all subfolders.
For example, if you want to add the tag <span class="md-tag">Example</span> to
multiple pages, use:
``` yaml title=".meta.yml"
tags:
- Example
```
Now, given the following directory layout, if you store the file in the folder
named `example`, all pages in that folder receive the tag, while all pages
outside of the folder remain unaffected:
``` { .sh .no-copy hl_lines="4-8" }
.
├─ docs/
│ ├─ ...
│ ├─ example/
│ │ ├─ .meta.yml
│ │ ├─ a.md
│ │ ├─ ...
│ │ └─ z.md
│ └─ ...
└─ mkdocs.yml
```
When combining metadata, lists and dictionaries are recursively merged, which
means you can append values to a list and add or set specific properties in a
dictionary on arbitrary levels.
### When to use it
While the plugin itself doesn't offer much functionality beyond adding and
merging metadata, it is a perfect companion for many of the other built-in
plugins that Material for MkDocs offers. Some of the most powerful combinations
of the meta plugin and other built-in plugins are:
<div class="grid cards" markdown>
- :material-share-circle: &nbsp; __[Built-in social plugin][social]__
---
The meta plugin can be used to [change the layout] for social cards or
[change specific layout options] like [background] or [color]
for a subset of pages.
``` yaml title=".meta.yml"
social:
cards_layout: default/variant
```
- :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
---
The meta plugin allows to automatically associate blog posts with specific
[authors] and [categories], ensuring that blog posts are always correctly
annotated.
``` yaml title=".meta.yml"
authors:
- squidfunk
```
- :material-tag-text: &nbsp; __[Built-in tags plugin][tags]__
---
The meta plugin makes it possible to ensure that subsections of your
project are annotated with [specific tags], so they can't be forgotten when
adding pages.
``` yaml title=".meta.yml"
tags:
- Example
```
- :material-magnify: &nbsp; __[Built-in search plugin][search]__
---
The meta plugin makes it easy to [boost] specific sections in search results
or to [exclude] them entirely from being indexed, giving more granular
control over search.
``` yaml title=".meta.yml"
search:
exclude: true
```
</div>
[social]: social.md
[change the layout]: social.md#meta.social.cards_layout
[change specific layout options]: social.md#meta.social.cards_layout_options
[background]: social.md#option.background_color
[color]: social.md#option.color
[blog]: blog.md
[authors]: blog.md#meta.authors
[categories]: blog.md#meta.categories
[tags]: tags.md
[specific tags]: tags.md#meta.tags
[search]: search.md
[exclude]: search.md#meta.search.exclude
[boost]: search.md#meta.search.boost
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.21.0 -->
<!-- md:plugin [meta] – built-in -->
<!-- md:flag experimental -->
As with all [built-in plugins], getting started with the meta plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start
applying metadata for multiple pages at once:
``` yaml
plugins:
- meta
```
The meta plugin is included with Material for MkDocs and doesn't need to be
installed.
[meta]: meta.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
It's normally not necessary to specify this setting, but if you want to disable
the plugin, use:
``` yaml
plugins:
- meta:
enabled: false
```
[building your project]: ../creating-your-site.md#building-your-site
### Meta file
The following settings are available for meta files:
---
#### <!-- md:setting config.meta_file -->
<!-- md:sponsors -->
<!-- md:version insiders-4.21.0 -->
<!-- md:default `.meta.yml` -->
Use this setting to change the meta file name the plugin will look for when
scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
change this setting, but if you want to change it, use:
``` yaml
plugins:
- meta:
meta_file: .meta.yml
```
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
recursively.

153
docs/plugins/offline.md Normal file
View File

@@ -0,0 +1,153 @@
---
title: Built-in offline plugin
icon: material/connection
---
# Built-in offline plugin
[MkDocs][mkdocs] is one of the few frameworks that allow to build offline-capable
documentation that can be directly viewed by the user – no server needed. With
the offline plugin, you can distribute the [`site` directory][mkdocs.site_dir]
as a downloadable `.zip` file while retaining most interactive functionality.
## Objective
### How it works
After [building your project], switch to the [`site` directory][mkdocs.site_dir]
and open `index.html` in your browser – you're now viewing your documentation
from your local file system! Most browsers will denote this by showing `file://`
in the address bar. However, you'll realize that the site search is gone.
Material for MkDocs offers many interactive features, some of which will not
work from the local file system due to the restrictions of modern browsers. More
specifically and technically, all calls to the [Fetch API] will error with a
message like:
```
Cross origin requests are only supported for protocol schemes: http, [...]
```
While browsers impose those restriction for security reasons, it reduces the
interactivity of your project. The offline plugin makes sure that site search
keeps working by moving the search index to a JavaScript file, and leveraging
@squidfunk's [iframe-worker] shim.
Additionally, the plugin automatically disables the [`use_directory_urls`]
[mkdocs.use_directory_urls] setting, ensuring that users can open your
documentation directly from the local file system.
There are some [limitations].
[building your project]: ../creating-your-site.md#building-your-site
[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
[iframe-worker]: https://github.com/squidfunk/iframe-worker
[limitations]: #limitations
### When to use it
As the name already indicates, the plugin should only be used when you're
[building your project] for offline distribution. It's also good to know, that
the offline plugin plays nicely with the following other plugins, helping to
create even better offline-capable documentation:
<div class="grid cards" markdown>
- :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
---
The privacy plugin makes it easy to use external assets when building for
offline usage, as it automatically downloads them for distribution with
your documentation.
---
__Your documentation can work without connectivity to the internet[^1]__
- :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
---
The optimize plugin automatically identifies and optimizes all media files
that you reference in your project by using compression and conversion
techniques.
---
__Your documentation can be distributed as a smaller `.zip` download__
</div>
[^1]:
You might wonder why the [privacy plugin][privacy] is necessary to build
truly offline-capable documentation with the offline plugin. While it's
certainly possible to also add support for downloading external assets to
the offline plugin, this functionality is already fully implemented in the
privacy plugin and is its very raison d'être.
Material for MkDocs follows a modular approach for its plugin system – many
of the plugins work perfectly together and enhance each others
functionalities, allowing to solve complex problems with a few lines
of configuration.
[privacy]: privacy.md
[optimize]: optimize.md
## Configuration
<!-- md:version 9.0.0 -->
<!-- md:plugin [offline] – built-in -->
As with all [built-in plugins], getting started with the offline plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start
building offline-capable documentation:
``` yaml
plugins:
- offline
```
The offline plugin is built into Material for MkDocs and doesn't need to be
installed.
[offline]: offline.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.0.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
If you want to build online- as well as offline-capable documentation, it's a
good idea to use an [environment variable][mkdocs.env]:
``` yaml
plugins:
- offline:
enabled: !ENV [OFFLINE, false]
```
## Limitations
When enabling the offline plugin, make sure to disable the following settings,
as they make use of the [Fetch API] which will error when invoked from the local
file system:
- [Instant loading]
- [Site analytics]
- [Versioning]
- [Comment systems]
[Instant loading]: ../setup/setting-up-navigation.md#instant-loading
[Site analytics]: ../setup/setting-up-site-analytics.md
[Versioning]: ../setup/setting-up-versioning.md
[Comment systems]: ../setup/adding-a-comment-system.md

443
docs/plugins/optimize.md Normal file
View File

@@ -0,0 +1,443 @@
---
title: Built-in optimize plugin
icon: material/rabbit
---
# Built-in optimize plugin
The optimize plugin automatically identifies and optimizes all media files when
[building your project] by using common compression and conversion techniques.
As a result, your site loads significantly faster and yields better rankings in
search engines.
[building your project]: ../creating-your-site.md#building-your-site
## Objective
### How it works
The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
assets, optimizing them automatically in order to reduce the final size of the
[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
ship less bytes to your users, as well as a smaller download for
[offline-capable documentation].
Optimized images are [intelligently cached][intelligent caching], which is why
the plugin will only optimize media files that changed since the last build.
This makes it possible to swap out or update images, without having to worry
about optimizing them, or even worse, forgetting to do so.
In order to optimize media files, a few [dependencies] need to be available on
your system.
[offline-capable documentation]: ../setup/building-for-offline-usage.md
[dependencies]: #configuration
### When to use it
It's generally recommended to use the plugin, as media files are optimized
automatically without the need for intervention, ensuring that your site loads
as fast as possible. Optimized media files are one of the key components for a
high and consistent ranking in search engines.
Additionally, the plugin can be combined with other built-in plugins
that Material for MkDocs offers, in order to create sophisticated
build pipelines tailored to your project:
<div class="grid cards" markdown>
- :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
---
The privacy plugin makes it easy to use unoptimized external assets, passing
them to the optimize plugin before copying them to the [`site` directory]
[mkdocs.site_dir].
---
__External media files can be automatically downloaded and optimized__
- :material-connection: &nbsp; __[Built-in offline plugin][offline]__
---
The offline plugin adds support for building offline-capable documentation,
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
file that can be downloaded.
---
__Your documentation can be distributed as a smaller `.zip` download__
</div>
[privacy]: privacy.md
[offline]: offline.md
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:plugin [optimize] – built-in -->
<!-- md:flag multiple -->
<!-- md:flag experimental -->
As with all [built-in plugins], getting started with the optimize plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and observe how
media files are optimized automatically:
``` yaml
plugins:
- optimize
```
The optimize plugin is built into Material for MkDocs and doesn't need to be
installed.
However, in order to optimize all media files, it's necessary to install the
dependencies for [image processing], if they're not already available on your
system. The linked guide includes instructions for several operating systems
and mentions some alternative environments.
[optimize]: optimize.md
[built-in plugins]: index.md
[image processing]: requirements/image-processing.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
If you want to disable the plugin, e.g., for local builds, you can use an
[environment variable][mkdocs.env] in `mkdocs.yml`:
``` yaml
plugins:
- optimize:
enabled: !ENV [CI, false]
```
This configuration enables the plugin only during continuous integration (CI).
---
#### <!-- md:setting config.concurrency -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default available CPUs - 1 -->
With more CPUs available, the plugin can do more work in parallel, and thus
complete media file optimization faster. If you want to disable concurrent
processing completely, use:
``` yaml
plugins:
- optimize:
concurrency: 1
```
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
### Caching
The plugin implements an [intelligent caching] mechanism, ensuring that a media
file or asset is only passed through the optimization pipeline when its contents
change. If you swap out or update an image, the plugin detects it and updates
the optimized version of the media file.
The following settings are available for caching:
[intelligent caching]: requirements/caching.md
---
#### <!-- md:setting config.cache -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to instruct the plugin to bypass the cache, in order to
re-optimize all media files, even though the cache may not be stale. It's
normally not necessary to specify this setting, except for when debugging
the plugin itself. Caching can be disabled with:
``` yaml
plugins:
- optimize:
cache: false
```
---
#### <!-- md:setting config.cache_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `.cache/plugin/optimize` -->
It is normally not necessary to specify this setting, except for when you want
to change the path within your root directory where media files are cached.
If you want to change it, use:
``` yaml
plugins:
- optimize:
cache_dir: my/custom/dir
```
If you're using [multiple instances] of the plugin, it can be a good idea to
set different cache directories for both instances, so that they don't interfere
with each other.
[multiple instances]: index.md#multiple-instances
### Optimization
Documentation often makes use of screenshots or diagrams for better
visualization of things, both of which are prime candidates for optimization.
The plugin automatically optimizes images using [pngquant] for `.png` files,
and [Pillow] for `.jpg` files.
The following settings are available for optimization:
[pngquant]: https://pngquant.org/
[Pillow]: https://pillow.readthedocs.io/
---
#### <!-- md:setting config.optimize -->
<!-- md:sponsors -->
<!-- md:version insiders-4.41.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable media file optimization. Currently,
the plugin's sole purpose is to optimize media files, so it's equivalent to the
[`enabled`][config.enabled] setting, but in the near future, other features
might be added. If you want to disable optimization, use:
``` yaml
plugins:
- optimize:
optimize: false
```
---
#### <!-- md:setting config.optimize_png -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the optimization of `.png` files. It's
normally not necessary to specify this setting, but if you want to disable
the optimization of `.png` files, use:
``` yaml
plugins:
- optimize:
optimize_png: false
```
---
#### <!-- md:setting config.optimize_png_speed -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `3` of `1-10` -->
Use this setting to specify the speed/quality tradeoff that [pngquant] applies
when optimizing `.png` files. The lower the number, the more aggressively
[pngquant] will try to optimize:
=== "Slower <small>smaller</small>"
``` yaml
plugins:
- optimize:
optimize_png_speed: 1
```
=== "Faster <small>larger</small>"
``` yaml
plugins:
- optimize:
optimize_png_speed: 10
```
A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
---
#### <!-- md:setting config.optimize_png_strip -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to specify whether [pngquant] should strip optional metadata
from `.png` files that are not required to display the image, e.g., [EXIF].
If you want to preserve metadata, use:
``` yaml
plugins:
- optimize:
optimize_png_strip: false
```
[EXIF]: https://en.wikipedia.org/wiki/Exif
---
#### <!-- md:setting config.optimize_jpg -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the optimization of `.jpg` files. It's
normally not necessary to specify this setting, but if you want to disable
the optimization of `.jpg` files, use:
``` yaml
plugins:
- optimize:
optimize_jpg: false
```
---
#### <!-- md:setting config.optimize_jpg_quality -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `60` of `0-100` -->
Use this setting to specify the image quality that [Pillow] applies when
optimizing `.jpg` files. If the images look blurry, it's a good idea to
fine-tune and change this setting:
``` yaml
plugins:
- optimize:
optimize_jpg_quality: 75
```
---
#### <!-- md:setting config.optimize_jpg_progressive -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to specify whether [Pillow] should use progressive encoding
when optimizing `.jpg` files, rendering faster on slow connections. If you want
to disable progressive encoding, use:
``` yaml
plugins:
- optimize:
optimize_jpg_progressive: false
```
[progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
---
#### <!-- md:setting config.optimize_include -->
<!-- md:sponsors -->
<!-- md:version insiders-4.41.0 -->
<!-- md:default none -->
Use this setting to enable media file optimization for specific directories
of your project, e.g., when using [multiple instances] of the plugin to optimize
media files differently:
``` yaml
plugins:
- optimize:
optimize_include:
- screenshots/*
```
This configuration enables optimization for all media files that are contained
in the `screenshots` folder and its subfolders inside the [`docs` directory]
[mkdocs.docs_dir].
---
#### <!-- md:setting config.optimize_exclude -->
<!-- md:sponsors -->
<!-- md:version insiders-4.41.0 -->
<!-- md:default none -->
Use this setting to disable media file optimization for specific directories
of your project, e.g., when using [multiple instances] of the plugin to optimize
media files differently:
``` yaml
plugins:
- social:
optimize_exclude:
- vendor/*
```
This configuration disables optimization for all media files that are contained
in the `vendor` folder and its subfolders inside the [`docs` directory]
[mkdocs.docs_dir].
### Reporting
The following settings are available for reporting:
---
#### <!-- md:setting config.print_gain -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should print the number of bytes
gained after optimizing each file. If you want to disable this behavior, use:
``` yaml
plugins:
- optimize:
print_gain: false
```
---
#### <!-- md:setting config.print_gain_summary -->
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should print the total number of
bytes gained after optimizing all files. If you want to disable this behavior,
use:
``` yaml
plugins:
- optimize:
print_gain_summary: false
```

416
docs/plugins/privacy.md Normal file
View File

@@ -0,0 +1,416 @@
---
title: Built-in privacy plugin
icon: material/shield-account
---
# Built-in privacy plugin
The privacy plugin offers a streamlined solution for automatically self-hosting
external assets. With just a single line of configuration, the plugin can
automatically identify and download external assets, making GDPR compliance
as effortless as it can possibly be.
## Objective
### How it works
The plugin scans the generated HTML for external assets, i.e., scripts, style
sheets, images, and web fonts, downloads them, stores them in the
[`site` directory][mkdocs.site_dir] and replaces all references with links to
the downloaded copies for effortless self-hosting. For example:
``` html
<script src="https://example.com/script.js"></script>
```
This external script is downloaded, and the link is replaced with:
``` html
<script src="assets/external/example.com/script.js"></script>
```
Of course, scripts and style sheets can reference further external assets,
which is why this process is repeated recursively until no further external
assets are detected:
- Scripts are scanned for further scripts, style sheets and JSON files
- Style sheets are scanned for images and web fonts
Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
requesting external assets, are removed from the output, as they're not
necessary when self-hosting. After the plugin has done it's work, your project
will be free of requests to external services.
There are some [limitations].
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
[limitations]: #limitations
### When to use it
The plugin was developed to make compliance with the 2018 European
__General Data Protection Regulation__ (GDPR) as simple as possible, while
retaining the flexibility and power that Material for MkDocs offers, like for
example its tight integration with [Google Fonts].
But, that's only the start. For example, if your project includes a lot of
images, enabling the plugin allows to move them outside of your repository, as
the plugin will automatically download and store them in the [`site` directory]
[mkdocs.site_dir] when [building your project].
Even more interestingly, the plugin can be combined with other built-in plugins
that Material for MkDocs offers, in order to create sophisticated build
pipelines tailored to your project:
<div class="grid cards" markdown>
- :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
---
The optimize plugin allows to optimize all downloaded external assets
detected by the privacy plugin by using compression and conversion
techniques.
---
__External media files are automatically downloaded and optimized__
- :material-connection: &nbsp; __[Built-in offline plugin][offline]__
---
The offline plugin adds support for building [offline-capable documentation],
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
file that can be downloaded.
---
__Your documentation can work without connectivity to the internet__
</div>
[Google Fonts]: ../setup/changing-the-fonts.md
[building your project]: ../creating-your-site.md#building-your-site
[optimize]: optimize.md
[offline]: offline.md
[offline-capable documentation]: ../setup/building-for-offline-usage.md
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.9.0 -->
<!-- md:plugin [privacy] – built-in -->
<!-- md:flag multiple -->
<!-- md:flag experimental -->
As with all [built-in plugins], getting started with the privacy plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start
effortlessly self-hosting external assets:
``` yaml
plugins:
- privacy
```
The privacy plugin is built into Material for MkDocs and doesn't need to be
installed.
[privacy]: privacy.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.10.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
If you want to disable the plugin, e.g., for local builds, you can use an
[environment variable][mkdocs.env] in `mkdocs.yml`:
``` yaml
plugins:
- privacy:
enabled: !ENV [CI, false]
```
This configuration enables the plugin only during continuous integration (CI).
---
#### <!-- md:setting config.concurrency -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:default available CPUs - 1 -->
With more CPUs available, the plugin can do more work in parallel, and thus
complete handling of external assets faster. If you want to disable concurrent
processing completely, use:
``` yaml
plugins:
- privacy:
concurrency: 1
```
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
### Caching
The plugin implements an [intelligent caching] mechanism, ensuring that external
assets are only downloaded when they're not already contained in the cache.
While the initial build might take some time, it's a good idea to use caching,
as it will speed up consecutive builds.
The following settings are available for caching:
[intelligent caching]: requirements/caching.md
---
#### <!-- md:setting config.cache -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:default `true` -->
Use this setting to instruct the plugin to bypass the cache, in order to
re-schedule downloads for all external assets, even though the cache may not be
stale. It's normally not necessary to specify this setting, except for when
debugging the plugin itself. Caching can be disabled with:
``` yaml
plugins:
- privacy:
cache: false
```
---
#### <!-- md:setting config.cache_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:default `.cache/plugin/privacy` -->
It is normally not necessary to specify this setting, except for when you want
to change the path within your root directory where downloaded copies are
cached. If you want to change it, use:
``` yaml
plugins:
- privacy:
cache_dir: my/custom/dir
```
If you're using [multiple instances] of the plugin, it can be a good idea to
set different cache directories for both instances, so that they don't interfere
with each other.
[multiple instances]: index.md#multiple-instances
### External assets
The following settings are available for external assets:
---
#### <!-- md:setting config.assets -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should download external
assets. If you only want the plugin to process [external links], you can disable
handling of external assets with:
``` yaml
plugins:
- privacy:
assets: false
```
[external links]: #external-links
---
#### <!-- md:setting config.assets_fetch -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should downloads or only report
external assets when they're encountered. If you already self-host all external
assets, this setting can be used as a safety net to detect links to external
assets placed by the author in pages:
``` yaml
plugins:
- privacy:
assets_fetch: true
```
---
#### <!-- md:setting config.assets_fetch_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default `assets/external` -->
It is normally not necessary to specify this setting, except for when you want
to change the path within the [`site` directory][mkdocs.site_dir] where
external assets are stored. If you want to change it, use:
``` yaml
plugins:
- privacy:
assets_fetch_dir: my/custom/dir
```
This configuration stores the downloaded copies at `my/custom/dir` in the
[`site` directory][mkdocs.site_dir].
---
#### <!-- md:setting config.assets_include -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default none -->
Use this setting to enable downloading of external assets for specific origins,
e.g., when using [multiple instances] of the plugin to fine-tune processing of
external assets for different origins:
``` yaml
plugins:
- privacy:
assets_include:
- unsplash.com/*
```
---
#### <!-- md:setting config.assets_exclude -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default none -->
Use this setting to disable downloading of external assets for specific origins,
e.g., when using [multiple instances] of the plugin to fine-tune processing of
external assets for different origins:
``` yaml
plugins:
- privacy:
assets_exclude: # (1)!
- cdn.jsdelivr.net/npm/mathjax@3/*
- giscus.app/*
```
1. [MathJax] loads web fonts for typesetting of mathematical content
through relative URLs, and thus cannot be automatically bundled by the
privacy plugin. [MathJax can be self-hosted].
[Giscus], which we recommend to use as a [comment system], uses a technique
called code-splitting to load only the code that is necessary, which
is implemented via relative URLs. [Giscus can be self-hosted] as well.
[MathJax]: ../reference/math.md
[MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
[Giscus]: https://giscus.app/
[comment system]: ../setup/adding-a-comment-system.md
[Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
---
### External links
The following settings are available for external links:
---
#### <!-- md:setting config.links -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default `true` -->
Use this setting to instruct the plugin to parse and process external links to
annotate them for [improved security], or to automatically add additional
attributes to external links. If you want to disable processing of external
links, use:
``` yaml
plugins:
- privacy:
links: false
```
[improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
---
#### <!-- md:setting config.links_attr_map -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default none -->
Use this setting to specify additional attributes that should be added to
external links, for example, to add `target="_blank"` to all external links
so they open in a new tab:
``` yaml
plugins:
- privacy:
links_attr_map:
target: _blank
```
---
#### <!-- md:setting config.links_noopener -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:default `true` -->
It is normally not recommended to change this setting, as it will automatically
annotate external links that open in a new window with `rel="noopener"` for
[improved security]:
``` yaml
plugins:
- privacy:
links_noopener: true
```
## Limitations
Dynamically created URLs as part of scripts are not detected, and thus cannot be
downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
``` js
const cdn = "https://polyfill.io"
const url = `${cdn}/v3/polyfill.min.js`
```
Instead, always use fully qualified URLs:
``` js
const url ="https://polyfill.io/v3/polyfill.min.js"
```

365
docs/plugins/projects.md Normal file
View File

@@ -0,0 +1,365 @@
---
title: Built-in projects plugin
icon: material/folder-open
---
# Built-in projects plugin
The projects plugin adds the ability to split your main project into multiple
distinct projects, build them concurrently and preview them together as one.
This is particularly useful when creating a multi-language project, but can also
be used to split very large projects into smaller parts.
## Objective
### How it works
The plugin scans the configured [`projects` directory][config.projects_dir] for
`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
If not configured otherwise, the plugin expects that your project has
the following directory layout, e.g. for a multi-language project:
``` { .sh .no-copy }
.
├─ docs/
├─ projects/
│ ├─ en/
│ │ ├─ docs/
│ │ └─ mkdocs.yml
│ └─ de/
│ ├─ docs/
│ └─ mkdocs.yml
└─ mkdocs.yml
```
One of the most useful and interesting features of the plugin is that it allows
[previewing your site] from the main project, while still being able to preview
and build each project individually. This is especially useful for
multi-language projects.
If, when [previewing your site], you change a file in one of the projects, the
plugin only rebuilds this project and makes sure that MkDocs will also reload
the associated files. This also creates the opportunity for splitting your
main project into several projects for a better editing experience.
There are some [limitations], but we're working hard to remove them.
[previewing your site]: ../creating-your-site.md#previewing-as-you-write
[limitations]: #limitations
### When to use it
The plugin came into existence because we needed a convenient and scalable
method to build our [examples] repository, which features many self-contained
and runnable projects that users can download and use as a basis when
boostrapping a new project or [creating a reproduction].
When you want to create a multi-language project, or have a very large existing
project, you might consider using the plugin, as it makes managing, editing
and building more comfortable.
[examples]: https://github.com/mkdocs-material/examples
[creating a reproduction]: ../guides/creating-a-reproduction.md
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:plugin [projects] – built-in -->
<!-- md:flag experimental -->
In order to get started with the projects plugin, just add the following lines
to `mkdocs.yml`, and split your main project into several distinct projects that
can be built concurrently:
``` yaml
plugins:
- projects
```
The projects plugin is built into Material for MkDocs and doesn't need to be
installed.
[projects]: projects.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
If you want to disable the plugin, e.g., for local builds, you can use an
[environment variable][mkdocs.env] in `mkdocs.yml`:
``` yaml
plugins:
- projects:
enabled: !ENV [CI, false]
```
This configuration enables the plugin only during continuous integration (CI).
[building your project]: ../creating-your-site.md#building-your-site
---
#### <!-- md:setting config.concurrency -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default available CPUs - 1 -->
With more CPUs available, the plugin can do more work in parallel, and thus
build projects faster. If you want to disable concurrent processing completely,
use:
``` yaml
plugins:
- projects:
concurrency: 1
```
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
### Caching
The plugin implements an [intelligent caching] mechanism, ensuring that a
project is only rebuilt when its contents change. While the initial build might
take some time, it's a good idea to use caching, as it will speed up consecutive
builds.
The following settings are available for caching:
[intelligent caching]: requirements/caching.md
---
#### <!-- md:setting config.cache -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `true` -->
Use this setting to instruct the plugin to bypass the cache, in order to
rebuild all projects, even though the cache may not be stale. It's normally not
necessary to specify this setting, except for when debugging the plugin itself.
Caching can be disabled with:
``` yaml
plugins:
- projects:
cache: false
```
---
#### <!-- md:setting config.cache_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `.cache/plugin/projects` -->
It is normally not necessary to specify this setting, except for when you want
to change the path within your root directory where the metadata is cached.
If you want to change it, use:
``` yaml
plugins:
- projects:
cache_dir: my/custom/dir
```
### Projects
The following settings are available for projects:
---
#### <!-- md:setting config.projects -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable building of projects. Currently, the
plugin's sole purpose is to build projects, so it's equivalent to the
[`enabled`][config.enabled] setting, but in the future, other features might be
added. If you want to disable building of projects, use:
``` yaml
plugins:
- projects:
projects: false
```
---
#### <!-- md:setting config.projects_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:default `projects` -->
Use this setting to change the folder where your projects are located. It's
normally not necessary to change this setting, but if you want to rename the
folder or change its file system location, use:
``` yaml
plugins:
- projects:
projects_dir: projects
```
Note that the [`projects` directory][config.projects_dir] is solely used for
project organization – it is not included in project URLs, since projects are
automatically hoisted by the plugin.
The provided path is resolved from the root directory.
---
#### <!-- md:setting config.projects_config_files -->
<!-- md:sponsors -->
<!-- md:version insiders-4.42.0 -->
<!-- md:default `*/mkdocs.yml` -->
Use this setting to change the location or name of configuration files the
plugin will look for when scanning the [`projects` directory]
[config.projects_dir]. Adjusting this setting can be necessary when the
configuration files are located in subdirectories of projects, e.g.
`docs/mkdocs.yml`:
``` yaml
plugins:
- projects:
projects_config_files: "**/mkdocs.yml" # (1)!
```
1. If all projects share the same location for their configuration files, e.g.,
`docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
to resolve than a `**` glob pattern.
``` yaml
plugins:
- projects:
projects_config_files: "*/docs/mkdocs.yml"
```
This configuration fits the following directory structure, which is quite
common for projects using git submodules:
``` { .sh .no-copy }
.
├─ docs/
├─ projects/
│ ├─ git-submodule-a/
│ │ └─ docs/
│ │ └─ mkdocs.yml
│ └─ git-submodule-b/
│ └─ docs/
│ └─ mkdocs.yml
└─ mkdocs.yml
```
The provided path is resolved from the [`projects` directory]
[config.projects_dir].
---
#### <!-- md:setting config.projects_config_transform -->
<!-- md:sponsors -->
<!-- md:version insiders-4.42.0 -->
<!-- md:default none -->
Use this setting to transform the configuration of each project as read from
`mkdocs.yml` before it is built, which allows for adjusting the configuration
of each project when building them together, but leave them untouched when
building them individually:
``` yaml
plugins:
- projects:
projects_config_transform: !!python/name:projects.transform
```
The provided module and function name are looked up in Python's [module search
path]. You need to add your root directory to the search path when building
your site, so Python can resolve it. The easiest way is to add the working
directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
``` .sh
export PYTHONPATH=.
```
!!! tip "How to define a configuration transformation function"
The [`python/name`][python-name] tag is provided by [PyYAML] and must point
to a valid module and function name within Python's [module search path].
The plugin passes the `project` and top-level `config` objects to the
function.
As an example, we can inherit the [`use_directory_urls`]
[mkdocs.use_directory_urls] setting for all projects from the top-level
configuration:
``` py title="projects/__init__.py"
from mkdocs.config.defaults import MkDocsConfig
# Transform project configuration
def transform(project: MkDocsConfig, config: MkDocsConfig):
project.use_directory_urls = config.use_directory_urls
```
[module search path]: https://docs.python.org/3/library/sys_path_init.html
[PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
[python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
[PyYAML]: https://pyyaml.org/
### Hoisting
The following settings are available for hoisting:
---
#### <!-- md:setting config.hoisting -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable hoisting of themes files to the main
project. If you disable this setting, each project receives a copy of the
theme's files, which can be considered redundant:
``` yaml
plugins:
- projects:
hoisting: false
```
It's generally advisable to enable hoisting, as it yields faster deployments
and faster loading of your project's sites, because the files are the same for
all projects and can be deduplicated.
### Limitations
The plugin is one of the latest additions to Material for MkDocs, which means it
is rather young and has some limitations. We're working hard to remove them, and
we're happy to receive feedback and learn about your requirements in ?5800.
Current limitations are:
- __Basic multi-language support only__: we'll be investigating how to provide
better support for multi-language projects, allowing to easier interlink
projects and switch between them.
- __Separate search indexes and sitemaps__: currently, the projects are entirely
separate, which means they will have separate search indexes and sitemaps.

35
docs/plugins/requirements/caching.md Normal file
View File

@@ -0,0 +1,35 @@
---
icon: material/database-outline
---
# Caching
Some of the [built-in plugins] implement intelligent caching mechanisms, which
massively speed up consecutive builds by reducing the amount of work that needs
to be done. This guide explains how to configure caching in different
environments.
## Prerequisites
Caching is entirely optional but enabled by default. It can be disabled per
plugin. If not configured otherwise, plugins will cache their data in the
`.cache` folder in the root of your project. For this reason it's recommended
to create a `.gitignore` file in the root of your project:
``` title=".gitignore"
.cache
```
This ensures that cached files are not added to your git repository – something
that is generally not recommended to do unless absolutely necessary. In some
cases, you might need to check in cached files, e.g. when you need to
pre-generate [social cards] locally, e.g., when you're not be able to install
the image processing dependencies in your continuous integration (CI)
environment.
In this case, we recommend changing the `cache_dir` setting – something that all
plugins that implement caching share – to a folder which you add to your git
repository.
[built-in plugins]: ../index.md
[social cards]: ../../setup/setting-up-social-cards.md

52
docs/setup/dependencies/image-processing.md → docs/plugins/requirements/image-processing.md
View File

@@ -1,21 +1,38 @@
---
icon: material/image-sync-outline
---
# Image processing
Material for MkDocs depends on several libraries to allow for image processing
as part of the build pipeline, including [social cards] and [image optimization].
For this reason, a few external libraries must be installed on the host system.
This section explains how to install them.
Some of the [built-in plugins] depend on external libraries for efficient image
processing, most notably the [social] plugin to generate [social cards], and the
[optimize] plugin for applying [image optimization]. This guide explains how to
install those libraries in different environments.
[social cards]: ../setting-up-social-cards.md
[image optimization]: ../building-an-optimized-site.md
[built-in plugins]: ../index.md
[social]: ../social.md
[social cards]: ../../setup/setting-up-social-cards.md
[optimize]: ../optimize.md
[image optimization]: ../../setup/building-an-optimized-site.md
## Dependencies
Install the Python dependencies for image processing with:
The libraries for image processing are entirely optional, and only need to be
installed if you want to use the [social] plugin or the [optimize] plugin. The
libraries are listed under the `imaging` extra:
```
pip install pillow cairosvg
pip install "mkdocs-material[imaging]"
```
This will install compatible versions of the following packages:
- [Pillow]
- [CairoSVG]
[Pillow]: https://pillow.readthedocs.io/
[CairoSVG]: https://cairosvg.org/
### Cairo Graphics
[Cairo Graphics] is a graphics library and dependency of [Pillow], which
@@ -36,9 +53,8 @@ Material for MkDocs makes use of for generating [social cards] and performing
=== ":fontawesome-brands-windows: Windows"
As stated in the [installation guide], the easiest way to get up and running
with the [Cairo Graphics] library on Windows is by installing [GTK+], since
it has Cairo as a dependency. You can also download and install a
precompiled [GTK runtime].
with the [Cairo Graphics] library on Windows is by installing [GTK+]. You
can also download a precompiled [GTK runtime].
=== ":material-linux: Linux"
@@ -70,8 +86,6 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
- [x] No installation needed in [GitHub Actions] (Ubuntu)
[Cairo Graphics]: https://www.cairographics.org/
[Pillow]: https://pillow.readthedocs.io/
[CairoSVG]: https://cairosvg.org/
[Homebrew]: https://brew.sh/
[installation guide]: https://www.cairographics.org/download/
[GTK+]: https://www.gtk.org/docs/installations/windows/
@@ -82,7 +96,7 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
### pngquant
[pngquant] is an excellent library for lossy PNG compression, and a direct
dependency of the [built-in optimize plugin]. See the following section which
dependency of the [built-in optimize plugin]. See the following section which
explains how to install [pngquant] system:
=== ":material-apple: macOS"
@@ -97,8 +111,8 @@ explains how to install [pngquant] system:
=== ":fontawesome-brands-windows: Windows"
Installing [pngquant] on Windows is a little more involved. The
[pngquant-winbuild] repository contains a guide on how to set up an
Installing [pngquant] on Windows is a little more involved. The
[pngquant-winbuild] repository contains a guide on how to set up an
environment for building [pngquant] on Windows.
=== ":material-linux: Linux"
@@ -113,6 +127,10 @@ explains how to install [pngquant] system:
The same is true for `yum` and `zypper`.
The following environments come with a preinstalled version of [pngquant]:
- [x] No installation needed in [Docker image]
[pngquant]: https://pngquant.org/
[built-in optimize plugin]: ../building-an-optimized-site.md#built-in-optimize-plugin
[built-in optimize plugin]: ../../plugins/optimize.md
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild

427
docs/plugins/search.md Normal file
View File

@@ -0,0 +1,427 @@
---
title: Built-in search plugin
icon: material/magnify
---
# Built-in search plugin
The search plugin adds a search bar to the header, allowing users to search your
documentation. It's powered by [lunr.js], a lightweight full-text search engine
for the browser, elimininating the need for external services, and even works
when building [offline-capable documentation].
[lunr.js]: https://lunrjs.com/
[offline-capable documentation]: ../setup/building-for-offline-usage.md
## Objective
### How it works
The plugin scans the generated HTML and builds a search index from all pages and
sections by extracting the section titles and contents. It preserves some inline
formatting like code blocks and lists, but removes all other formatting, so the
search index is as small as possible.
When a user visits your site, the search index is shipped to the browser,
indexed with [lunr.js] and made available for fast and simple querying – no
server needed. This ensures that the search index is always up to date with
your documentation, yielding accurate results.
### When to use it
It's generally recommended to use the plugin, as interactive search functionality
is a vital part of every good documentation. Additionally, the plugin integrates
perfectly with several of the other [built-in plugins] that Material for MkDocs
offers:
<div class="grid cards" markdown>
- :material-connection: &nbsp; __[Built-in offline plugin][offline]__
---
The offline plugin adds support for building offline-capable documentation,
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
file that can be downloaded.
---
__Your documentation can work without connectivity to the internet__
- :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
---
The meta plugin makes it easy to [boost][meta.search.boost] specific
sections in search results or to [exclude][meta.search.exclude] them
entirely from being indexed, giving more granular control over search.
---
__Simpler organization and management of search in different subsections__
</div>
[offline]: offline.md
[meta]: meta.md
[built-in plugins]: index.md
## Configuration
<!-- md:version 9.0.0 -->
<!-- md:plugin [search] – built-in -->
As with all [built-in plugins], getting started with the search plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and your users
will be able to search your documentation:
``` yaml
plugins:
- search
```
The search plugin is built into Material for MkDocs and doesn't need to be
installed.
[search]: search.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.2.9 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
It's normally not necessary to specify this setting, but if you want to disable
the plugin, use:
``` yaml
plugins:
- search:
enabled: false
```
[building your project]: ../creating-your-site.md#building-your-site
### Search
The following settings are available for search:
---
#### <!-- md:setting config.lang -->
<!-- md:version 9.0.0 -->
<!-- md:default computed -->
Use this setting to specify the language of the search index, enabling [stemming]
support for other languages than English. The default value is automatically
computed from the [site language], but can be explicitly set to another language
or even multiple languages with:
=== "Set language"
``` yaml
plugins:
- search:
lang: en
```
=== "Add further languages"
``` yaml
plugins:
- search:
lang: # (1)!
- en
- de
```
1. Be aware that including support for further languages increases the
base JavaScript payload by around 20kb and by another 15-30kb per
language, all before `gzip`.
[stemming]: https://en.wikipedia.org/wiki/Stemming
[site language]: ../setup/changing-the-language.md#site-language
[lunr languages]: https://github.com/MihaiValentin/lunr-languages
Language support is provided by [lunr languages], a collection of
language-specific stemmers and stop words for [lunr.js] maintained by the
Open Source community.
---
The following languages are currently supported by [lunr languages]:
<div class="mdx-columns" markdown>
- `ar` – Arabic
- `da` – Danish
- `de` – German
- `du` – Dutch
- `en` – English
- `es` – Spanish
- `fi` – Finnish
- `fr` – French
- `hi` – Hindi
- `hu` – Hungarian
- `hy` – Armenian
- `it` – Italian
- `ja` – Japanese
- `kn` - Kannada
- `ko` – Korean
- `no` – Norwegian
- `pt` – Portuguese
- `ro` – Romanian
- `ru` – Russian
- `sa` – Sanskrit
- `sv` – Swedish
- `ta` – Tamil
- `te` – Telugu
- `th` – Thai
- `tr` – Turkish
- `vi` – Vietnamese
- `zh` – Chinese
</div>
If [lunr languages] doesn't provide support for the selected [site language],
the plugin falls back to another language that yields the best stemming results.
If you discover that the search results are not satisfactory, you can contribute
to [lunr languages] by adding support for your language.
---
#### <!-- md:setting config.separator -->
<!-- md:version 9.0.0 -->
<!-- md:default computed -->
Use this setting to specify the separator used to split words when building the
search index on the client side. The default value is automatically computed
from the [site language], but can also be explicitly set to another value with:
``` yaml
plugins:
- search:
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
```
Separators support [positive and negative lookahead assertions], which allows
for rather complex expressions that yield precise control over how words are
split when building the search index.
Broken into its parts, this separator induces the following behavior:
=== "Special characters"
```
[\s\-,:!=\[\]()"/]+
```
The first part of the expression inserts token boundaries for each
document before and after whitespace, hyphens, commas, brackets and
other special characters. If several of those special characters are
adjacent, they are treated as one.
=== "Case changes"
```
(?!\b)(?=[A-Z][a-z])
```
Many programming languages have naming conventions like `PascalCase` or
`camelCase`. By adding this subexpression to the separator,
[words are split at case changes], tokenizing the word `PascalCase`
into `Pascal` and `Case`.
=== "Version strings"
```
\.(?!\d)
```
When adding `.` to the separator, version strings like `1.2.3` are split
into `1`, `2` and `3`, which makes them undiscoverable via search. When
using this subexpression, a small lookahead is introduced which will
[preserve version strings] and keep them discoverable.
=== "HTML/XML tags"
```
&[lg]t;
```
If your documentation includes HTML/XML code examples, you may want to allow
users to find [specific tag names]. Unfortunately, the `<` and `>` control
characters are encoded in code blocks as `&lt;` and `&gt;`. Adding this
subexpression to the separator allows for just that.
[positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
[words are split at case changes]: ?q=searchHighlight
[preserve version strings]: ?q=9.0.0
[specific tag names]: ?q=script
---
#### <!-- md:setting config.pipeline -->
<!-- md:version 9.0.0 -->
<!-- md:default computed -->
<!-- md:flag experimental -->
Use this setting to specify the [pipeline functions] that are used to filter and
expand tokens after tokenizing them with the [`separator`][config.separator] and
before adding them to the search index. The default value is automatically
computed from the [site language], but can also be explicitly set with:
``` yaml
plugins:
- search:
pipeline:
- stemmer
- stopWordFilter
- trimmer
```
The following pipeline functions can be used:
- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
- `trimmer` – Trim whitespace from tokens
[pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
### Segmentation
The plugin supports text segmentation of Chinese via [jieba], a popular
Chinese text segmentation library. Other languages like Japanese and Korean are
currently segmented on the client side, but we're considering to move this
functionality into the plugin in the future.
The following settings are available for segmentation:
[jieba]: https://pypi.org/project/jieba/
---
#### <!-- md:setting config.jieba_dict -->
<!-- md:version 9.2.0 -->
<!-- md:default none -->
<!-- md:flag experimental -->
Use this setting to specify a [custom dictionary] to be used by [jieba] for
segmenting text, replacing the default dictionary. [jieba] comes with
several dictionaries, which can be used with:
``` yaml
plugins:
- search:
jieba_dict: dict.txt
```
The following dictionaries are provided by [jieba]:
- [dict.txt.small] – 占用内存较小的词典文件
- [dict.txt.big] – 支持繁体分词更好的词典文件
The provided path is resolved from the root directory.
[custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
[dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
[dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
---
#### <!-- md:setting config.jieba_dict_user -->
<!-- md:version 9.2.0 -->
<!-- md:default none -->
<!-- md:flag experimental -->
Use this setting to specify an additional [user dictionary] to be used by
[jieba] for segmenting text, augmenting the default dictionary. User
dictionaries are ideal for tuning the segmenter:
``` yaml
plugins:
- search:
jieba_dict_user: user_dict.txt
```
The provided path is resolved from the root directory.
[user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
## Usage
### Metadata
The following properties are available:
---
#### <!-- md:setting meta.search.boost -->
<!-- md:version 8.3.0 -->
<!-- md:flag metadata -->
<!-- md:default none -->
Use this property to increase or decrease the relevance of a page in the search
results, giving more weight to them. Use values above `1` to rank up and values
below `1` to rank down:
=== ":material-arrow-up-circle: Rank up"
``` yaml
---
search:
boost: 2 # (1)!
---
# Page title
...
```
1. When boosting pages, always start with low values.
=== ":material-arrow-down-circle: Rank down"
``` yaml
---
search:
boost: 0.5
---
# Page title
...
```
---
#### <!-- md:setting meta.search.exclude -->
<!-- md:version 9.0.0 -->
<!-- md:flag metadata -->
<!-- md:default none -->
Use this property to exclude a page from the search results. Note that this will
not only remove the page, but also all subsections of the page from the search
results:
``` yaml
---
search:
exclude: true
---
# Page title
...
```

1059
docs/plugins/social.md Normal file
View File

File diff suppressed because it is too large Load Diff

376
docs/plugins/tags.md Normal file
View File

@@ -0,0 +1,376 @@
---
title: Built-in tags plugin
icon: material/tag-text
---
# Built-in tags plugin
The tags plugin adds first-class support for categorizing pages with the use
of tags, adding the possibility to group related pages and make them
discoverable via search and dedicated tags indexes. If your documentation is
large, tags can help to discover relevant information faster.
## Objective
### How it works
The plugin scans all pages for the [`tags`][meta.tags] metadata property and
generates a tags index, which is an inverted list of tags and the pages they
appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
allowing for maximum flexibility when adding tags to your project.
### When to use it
If you want to add one or multiple tags indexes to your project, the tags
plugin is a perfect choice as it makes this process ridiculously simple.
Additionally, it integrates perfectly with several of the other
[built-in plugins] that Material for MkDocs offers:
<div class="grid cards" markdown>
- :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
---
The meta plugin makes it possible to ensure that subsections of your
project are annotated with [specific tags][meta.tags], so they can't be
forgotten when adding pages.
---
__Simpler organization and management of tags in different subsections__
- :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
---
The tags plugin allows to categorize posts alongside with pages in your
project, to improve their discoverability and connect posts to your
documentation.
---
__Your documentation's tag system integrates with your blog__
</div>
[meta]: meta.md
[blog]: blog.md
[built-in plugins]: index.md
## Configuration
<!-- md:version 8.2.0 -->
<!-- md:plugin [tags] – built-in -->
<!-- md:flag multiple -->
As with all [built-in plugins], getting started with the tags plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start using
[tags][meta.tags] to categorize your pages:
``` yaml
plugins:
- tags
```
The tags plugin is built into Material for MkDocs and doesn't need to be
installed.
[tags]: tags.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.1.7 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
It's normally not necessary to specify this setting, but if you want to disable
the plugin, use:
``` yaml
plugins:
- tags:
enabled: false
```
[building your project]: ../creating-your-site.md#building-your-site
### Tags
The following settings are available for tags:
---
#### <!-- md:setting config.tags -->
<!-- md:version 9.2.9 -->
<!-- md:default `true` -->
Use this setting to enable or disable handling of tags. Currently, the plugin's
sole purpose is to process tags, so it's equivalent to the [`enabled`]
[config.enabled] setting, but in the future, other features might be added.
If you want to disable handling of tags, use:
``` yaml
plugins:
- tags:
tags: false
```
---
#### <!-- md:setting config.tags_file -->
<!-- md:version 8.2.0 -->
<!-- md:default none -->
Use this setting to specify the location of the tags index, which is the page
used to render a list of all tags and their associated pages. If this setting is
specified, tags become clickable, pointing to the corresponding section in the
tags index:
``` yaml
plugins:
- tags:
tags_file: tags.md
```
The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
section of `mkdocs.yml`. This setting is not required – you should only use it
if you want to have a tags index.
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
---
#### <!-- md:setting config.tags_extra_files -->
<!-- md:sponsors -->
<!-- md:version insiders-4.20.0 -->
<!-- md:default none -->
Use this setting to specify the locations of additional tags indexes, which are
pages that render a subset of the tags index, in order to provide scoped tags
indexes for specific sections:
``` yaml
plugins:
- tags:
tags_extra_files:
extra-1.md: [tag-id-1, tag-id-2, ...]
extra-2.md: [tag-id-3, tag-id-4, ...]
...
```
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
---
#### <!-- md:setting config.tags_slugify -->
<!-- md:sponsors -->
<!-- md:version insiders-4.25.0 -->
<!-- md:default [`toc.slugify`][toc.slugify] -->
Use this setting to change the function to use for generating URL-compatible
slugs from tags. [Python Markdown Extensions] comes with a Unicode-aware
[`slugify`][pymdownx.slugs.slugify] function:
=== "Unicode"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
When your project features non-European languages, it's advisable to use this
configuration. Of course, you can also provide a custom slugification function
for more granular control.
[toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
[pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
---
#### <!-- md:setting config.tags_slugify_separator -->
<!-- md:sponsors -->
<!-- md:version insiders-4.25.0 -->
<!-- md:default `-` -->
Use this setting to change the separator that is passed to the slugification
function set as part of [`tags_slugify`][config.tags_slugify]. While the default
is a hyphen, it can be set to any string, e.g., `_`:
``` yaml
plugins:
- tags:
tags_slugify_separator: _
```
---
#### <!-- md:setting config.tags_compare -->
<!-- md:sponsors -->
<!-- md:version insiders-4.26.2 -->
<!-- md:default none -->
Use this setting to specify a custom function for comparing tags. By default,
tag comparison is case-sensitive, but you can use the `casefold` function
for case-insensitive comparison:
``` yaml
plugins:
- tags:
tags_compare: !!python/name:material.plugins.tags.casefold
```
You can also define your own comparison function, which must return a string
representing the tag, that is used for sorting, and reference it in
[`tags_compare`][config.tags_compare].
---
#### <!-- md:setting config.tags_compare_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.26.2 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which tags are sorted when comparing
them. By default, tags are sorted in ascending order, but you can reverse
ordering as follows:
``` yaml
plugins:
- tags:
tags_compare_reverse: true
```
---
#### <!-- md:setting config.tags_pages_compare -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default none -->
Use this setting to specify a custom function for comparing pages. By default,
pages occur in order of appearance, but you can sort them by using the following
configuration:
=== "Sort by page title"
``` yaml
plugins:
- tags:
tags_pages_compare: !!python/name:material.plugins.tags.page_title
```
=== "Sort by page URL"
``` yaml
plugins:
- tags:
tags_pages_compare: !!python/name:material.plugins.tags.page_url
```
You can also define your own comparison function, which must return a string
representing the page, that is used for sorting, and reference it in
[`tags_pages_compare`][config.tags_pages_compare].
---
#### <!-- md:setting config.tags_pages_compare_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which pages are sorted when comparing
them. By default, pages are sorted in ascending order, but you can reverse
ordering as follows:
``` yaml
plugins:
- tags:
tags_pages_compare_reverse: true
```
---
#### <!-- md:setting config.tags_allowed -->
<!-- md:sponsors -->
<!-- md:version insiders-4.25.0 -->
<!-- md:default none -->
The plugin allows to check tags against a predefined list, in order to catch
typos or make sure that tags are not arbitrarily added. Specify the tags you
want to allow with:
``` yaml
plugins:
- tags:
tags_allowed:
- HTML5
- JavaScript
- CSS
```
The plugin stops the build if a page references a tag that is not part of
this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
metadata property.
## Usage
### Metadata
The following properties are available:
---
#### <!-- md:setting meta.tags -->
<!-- md:version 8.2.0 -->
<!-- md:flag metadata -->
<!-- md:default none -->
Use this property to associate a page with one or more tags, making the page
appear in the generated tags index. Tags are defined as a list of strings
(whitespaces are allowed):
``` yaml
---
tags:
- HTML5
- JavaScript
- CSS
---
# Page title
...
```
If you want to prevent accidental typos when assigning tags to pages, you can
set a predefined list of allowed tags in `mkdocs.yml` by using the
[`tags_allowed`][config.tags_allowed] setting.

82
docs/plugins/typeset.md Normal file
View File

@@ -0,0 +1,82 @@
---
title: Built-in typeset plugin
icon: material/format-title
---
# Built-in typeset plugin
The typeset plugin allows to preserve the enriched presentation of titles and
headlines within the navigation and table of contents. This means that code
blocks, icons, emojis and any other inline formatting can be rendered exactly
as defined in the page's content.
## Objective
### How it works
When [building your project], MkDocs extracts the plain text from headlines and
drops the original formatting. This is generally useful and a good idea, since
this information is made available to other plugins that might have problems
when being passed HTML instead of plain text.
However, it also means that the entire formatting is lost.
The plugin hooks into the rendering process, extracts the original headlines,
and makes them available to be used in templates and plugins. The templates of
Material for MkDocs use this information to render an enriched version of the
navigation and table of contents.
[building your project]: ../creating-your-site.md#building-your-site
### When to use it
It's generally recommended to use the plugin, because it is a drop-in solution
that doesn't require any configuration and is designed to work out of the box.
Since it doesn't overwrite but only adds information, it's not expected to
interfere with other plugins.
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.27.0 -->
<!-- md:plugin [typeset] – built-in -->
<!-- md:flag experimental -->
As with all [built-in plugins], getting started with the typeset plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and observe the
enriched navigation and table of contents:
``` yaml
plugins:
- typeset
```
The typeset plugin is built into Material for MkDocs and doesn't need to be
installed.
[typeset]: typeset.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.27.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
It's normally not necessary to specify this setting, but if you want to disable
the plugin, use:
``` yaml
plugins:
- typeset:
enabled: false
```
[building your project]: ../creating-your-site.md#building-your-site

19
docs/publishing-your-site.md
View File

@@ -34,7 +34,7 @@ contents:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: 3.x
@@ -49,7 +49,7 @@ contents:
- run: mkdocs gh-deploy --force
```
1. You can change the name to your liking.
1. You can change the name to your liking.
2. At some point, GitHub renamed `master` to `main`. If your default branch
is named `master`, you can safely remove `main`, vice versa.
@@ -58,8 +58,8 @@ contents:
`key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
- The `--utc` option makes sure that each workflow runner uses the same time zone.
- The `%V` format assures a cache update once a week.
- You can change the format to `%F` to have daily cache updates.
- The `%V` format assures a cache update once a week.
- You can change the format to `%F` to have daily cache updates.
You can read the [manual page] to learn more about the formatting options of the `date` command.
@@ -89,7 +89,7 @@ contents:
runs-on: ubuntu-latest
if: github.event.repository.fork == false
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: 3.x
@@ -128,7 +128,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[Insiders]: insiders/index.md
[built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin
[built-in optimize plugin]: plugins/optimize.md
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
[publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
[manual page]: https://man7.org/linux/man-pages/man1/date.1.html
@@ -207,13 +207,6 @@ other providers:
</div>
!!! note "Enterprise support"
If you're using Material for MkDocs in your organization and need
assistance, e.g., to __reduce build times__, __improve performance__ or
ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
to discuss our __enterprise support__ offerings. We're happy to help!
[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

37
docs/reference/admonitions.md
View File

@@ -34,7 +34,7 @@ See additional configuration options:
### Admonition icons
[:octicons-tag-24: 8.3.0][Admonition icons support]
<!-- md:version 8.3.0 -->
Each of the supported admonition types has a distinct icon, which can be changed
to any icon bundled with the theme, or even a [custom icon]. Add the following
@@ -101,7 +101,6 @@ theme:
quote: fontawesome/solid/quote-left
```
[Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[supported types]: #supported-types
[icon search]: icons-emojis.md#search
@@ -243,7 +242,7 @@ only the `inline` modifier:
``` markdown
!!! info inline end "Lorem ipsum"
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat
@@ -291,7 +290,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
type qualifiers are now all deprecated and will be removed in the next major
version. This will also be mentioned in the upgrade guide.
[`note`](#type:note){ #type:note }
<!-- md:option type:note -->
: !!! note
@@ -299,7 +298,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`abstract`](#type:abstract){ #type:abstract }
<!-- md:option type:abstract -->
: !!! abstract
@@ -307,7 +306,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`info`](#type:info){ #type:info }
<!-- md:option type:info -->
: !!! info
@@ -315,7 +314,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`tip`](#type:tip){ #type:tip }
<!-- md:option type:tip -->
: !!! tip
@@ -323,7 +322,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`success`](#type:success){ #type:success }
<!-- md:option type:success -->
: !!! success
@@ -331,7 +330,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`question`](#type:question){ #type:question }
<!-- md:option type:question -->
: !!! question
@@ -339,7 +338,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`warning`](#type:warning){ #type:warning }
<!-- md:option type:warning -->
: !!! warning
@@ -347,7 +346,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`failure`](#type:failure){ #type:failure }
<!-- md:option type:failure -->
: !!! failure
@@ -355,7 +354,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`danger`](#type:danger){ #type:danger }
<!-- md:option type:danger -->
: !!! danger
@@ -363,7 +362,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`bug`](#type:bug){ #type:bug }
<!-- md:option type:bug -->
: !!! bug
@@ -371,7 +370,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`example`](#type:example){ #type:example }
<!-- md:option type:example -->
: !!! example
@@ -379,7 +378,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
[`quote`](#type:quote){ #type:quote }
<!-- md:option type:quote -->
: !!! quote
@@ -391,8 +390,8 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
### Classic admonitions
Prior to version [:octicons-tag-24: 8.5.6][Admonition modern], admonitions had
a slightly different appearance:
Prior to version <!-- md:version 8.5.6 -->, admonitions had a slightly
different appearance:
!!! classic "Note"
@@ -427,8 +426,6 @@ If you want to restore this appearance, add the following CSS to an
- stylesheets/extra.css
```
[Admonition modern]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.6
### Custom admonitions
If you want to add a custom admonition type, all you need is a color and an
@@ -504,5 +501,5 @@ After applying the customization, you can use the custom admonition type:
</div>
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
[additional style sheet]: ../customization.md#additional-css

47
docs/reference/annotations.md
View File

@@ -31,12 +31,51 @@ See additional configuration options:
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
### Annotation icons
<!-- md:version 9.2.0 -->
The annotation icon can be changed to any icon bundled with the theme, or even
a [custom icon], e.g. to material/arrow-right-circle:. Simply add the following
lines to `mkdocs.yml`:
``` yaml
theme:
icon:
annotation: material/arrow-right-circle # (1)!
```
1. Enter a few keywords to find the perfect icon using our [icon search] and
click on the shortcode to copy it to your clipboard:
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
<input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material circle" />
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
<div class="mdx-iconsearch-result__meta"></div>
<ol class="mdx-iconsearch-result__list"></ol>
</div>
</div>
Some popular choices:
- :material-plus-circle: - `material/plus-circle`
- :material-circle-medium: - `material/circle-medium`
- :material-record-circle: - `material/record-circle`
- :material-arrow-right-circle: - `material/arrow-right-circle`
- :material-arrow-right-circle-outline: - `material/arrow-right-circle-outline`
- :material-chevron-right-circle: - `material/chevron-right-circle`
- :material-star-four-points-circle: - `material/star-four-points-circle`
- :material-plus-circle-outline: - `material/plus-circle-outline`
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[icon search]: icons-emojis.md#search
## Usage
### Using annotations
[:octicons-tag-24: 9.2.0b0][Annotation support] ·
:octicons-beaker-24: Experimental
<!-- md:version 9.2.0 -->
<!-- md:flag 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
@@ -64,8 +103,6 @@ Note that the `annotate` class must only be added to the outermost block. All
nested elements can use the same list to define annotations, except when
annotations are nested themselves.
[Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
#### in annotations
When [SuperFences] is enabled, annotations can be nested inside annotations by
@@ -168,7 +205,7 @@ of a dedicated content tab (and not to the container, which is not supported):
#### in everything else
The [Attribute Lists] extension is the key ingredient for adding annotations to
The [Attribute Lists] extension is the key ingredient for adding annotations to
most elements, but it has some [limitations]. However, it's always possible to
leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
`div` with the `annotate` class:

82
docs/reference/code-blocks.md
View File

@@ -13,8 +13,8 @@ during runtime using a JavaScript syntax highlighter.
## Configuration
This configuration enables syntax highlighting on code blocks and inline code
blocks, and allows to include source code directly from other files. Add the
This configuration enables syntax highlighting on code blocks and inline code
blocks, and allows to include source code directly from other files. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -46,8 +46,8 @@ See additional configuration options:
### Code copy button
[:octicons-tag-24: 9.0.0][Code copy button support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 9.0.0 -->
<!-- md:feature -->
Code blocks can automatically render a button on the right side to allow the
user to copy a code block's contents to the clipboard. Add the following to
@@ -59,8 +59,6 @@ theme:
- content.code.copy
```
[Code copy button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
??? info "Enabling or disabling code copy buttons for a specific code block"
If you don't want to enable code copy buttons globally, you can enable them
@@ -73,7 +71,7 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the copy button can also be disabled for a
specific code block:
@@ -85,9 +83,9 @@ theme:
### Code selection button
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.32.0 -->
<!-- md:flag experimental -->
Code blocks can include a button to allow for the selection of line ranges by
the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
@@ -101,8 +99,8 @@ theme:
??? info "Enabling or disabling code selection buttons for a specific code block"
If you don't want to enable code selection buttons globally, you can enable
them for a specific code block by using a slightly different syntax based on
If you don't want to enable code selection buttons globally, you can enable
them for a specific code block by using a slightly different syntax based on
the [Attribute Lists] extension:
```` yaml
@@ -111,7 +109,7 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
Note that the language shortcode which has to come first must now also be
prefixed by a `.`. Similarly, the selection button can also be disabled for
a specific code block:
@@ -121,13 +119,12 @@ theme:
```
````
[Insiders]: ../insiders/index.md
[line highlighting]: #highlighting-specific-lines
### Code annotations
[:octicons-tag-24: 8.0.0][Code annotations support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 8.0.0 -->
<!-- md:feature -->
Code annotations offer a comfortable and friendly way to attach arbitrary
content to specific sections of code blocks by adding numeric markers in block
@@ -156,21 +153,20 @@ theme:
```
````
Note that the language shortcode which has to come first must now also be
Note that the language shortcode which has to come first must now also be
prefixed by a `.`.
[Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
#### Custom selectors
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.32.0 -->
<!-- md:flag experimental -->
Normally, code annotations can only be [placed in comments], as comments can be
considered safe for placement. However, sometimes it might be necessary to place
annotations in parts of the code block where comments are not allowed, e.g. in
annotations in parts of the code block where comments are not allowed, e.g. in
strings.
Additional selectors can be set per-language:
@@ -292,8 +288,8 @@ theme:
#### Stripping comments
[:octicons-tag-24: 8.5.0][Stripping comments support] ·
:octicons-beaker-24: Experimental
<!-- md:version 8.5.0 -->
<!-- md:flag experimental -->
If you wish to strip the comment characters surrounding a code annotation,
simply add an `!` after the closing parenthesis of the code annotation:
@@ -320,8 +316,6 @@ Note that this only allows for a single code annotation to be rendered per
comment. If you want to add multiple code annotations, comments cannot be
stripped for technical reasons.
[Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
### Adding line numbers
Line numbers can be added to a code block by using the `linenums="<start>"`
@@ -511,11 +505,11 @@ override it as part of your [additional style sheet]:
- stylesheets/extra.css
```
[colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
[color schemes]: ../setup/changing-the-colors.md#color-scheme
[types of string tokens]: https://pygments.org/docs/tokens/#literals
[additional style sheet]: ../customization.md#additional-css
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
### Annotation tooltip width
@@ -549,35 +543,3 @@ This will render annotations with a larger width:
1. Muuuuuuuuuuuuuuuch more space for content
</div>
### 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

18
docs/reference/content-tabs.md
View File

@@ -12,14 +12,14 @@ grouping code blocks and other content.
## Configuration
This configuration enables content tabs, and allows to nest arbitrary content
inside content tabs, including code blocks and ... more content tabs! Add the
inside content tabs, including code blocks and ... more content tabs! Add the
following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
alternate_style: true
```
See additional configuration options:
@@ -32,9 +32,9 @@ See additional configuration options:
### Anchor links
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.17.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.17.0 -->
<!-- md:flag experimental -->
In order to link to content tabs and share them more easily, [Insiders] adds
an anchor link to each content tab automatically, which you can copy via right
@@ -66,7 +66,6 @@ or to the [publishing guide for Insiders][tab_2].
Fore more information, please [see the extension guide][slugification].
[Insiders]: ../insiders/index.md
[tab_1]: #-or-even-me
[tab_2]: ../publishing-your-site.md#insiders
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
@@ -74,11 +73,11 @@ or to the [publishing guide for Insiders][tab_2].
### Linked content tabs
[:octicons-tag-24: 8.3.0][Linked content tabs support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 8.3.0 -->
<!-- md:feature -->
When enabled, all content tabs across the whole documentation site will be
linked and switch to the same label when the user clicks on a tab. Add the
linked and switch to the same label when the user clicks on a tab. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -100,7 +99,6 @@ integrated with [instant loading] and persisted across page loads.
[![Linked content tabs disabled]][Linked content tabs disabled]
[Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
[Linked content tabs disabled]: ../assets/screenshots/content-tabs.png

148
docs/reference/data-tables.md
View File

@@ -10,7 +10,7 @@ like [sortable tables] can be achieved with a third-party library and some
[additional JavaScript].
[sortable tables]: #sortable-tables
[additional JavaScript]: ../customization.md#additional-javascript
[additional JavaScript]: ../customization.md#additional-javascript
## Configuration
@@ -185,147 +185,7 @@ numbers, filesizes, dates and month names. See the [tablesort documentation]
### Import table from file
[:octicons-cpu-24: Plugin][table-reader-docs]
The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
import data from a CSV or Excel file.
You can also import data from a CSV or Excel file using the plugin [`mkdocs-table-reader-plugin`][table-reader-docs].
First, you will need to install it with `pip`:
```sh
pip install mkdocs-table-reader-plugin
```
Then extend the `mkdocs.yml` file like this:
```yaml
plugins:
- table-reader
```
Then, it is a simple process to import the data in to the Markdown files.
=== "Import data from :fontawesome-solid-file-csv: CSV file"
Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this:
```csv title="./data.csv"
col1,col2,col3
r1c1,r1c2,r1c3
r2c1,r2c2,r2c3
r3c1,r3c2,r3c3
```
You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
```md title="./markdown.md"
...
{{ read_csv('./data.csv') }}
...
```
<div class="result" markdown>
...
col1|col2|col3
----|----|----
r1c1|r1c2|r1c3
r2c1|r2c2|r2c3
r3c1|r3c2|r3c3
...
</div>
=== "Import data from :fontawesome-solid-file-excel: Excel file"
Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this:
![][excel-file]{width="300px"}
[excel-file]: https://i.stack.imgur.com/f32ks.png
And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
```md title="./markdown.md"
...
{{ read_excel('./Book1.xlsx', engine='openpyxl') }}
...
```
<div class="result" markdown>
It will then return a result like this:
col1|col2|col3
----|----|----
r1c1|r1c2|r1c3
r2c1|r2c2|r2c3
r3c1|r3c2|r3c3
</div>
!!! warning "Warning"
You may receive an error if you use `engine='openpyxl'`.
If this happens, you can resolve it by installing it using `pip`:
```sh
pip install openpyxl
```
Read more here: [pandas.read_excel][pandas-read_excel-engine]
[pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None
!!! tip "Pro Tip: Multiple Sheets"
If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter.
It would look like this:
```md title="./markdown.md"
...
{{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }}
...
```
By default, Pandas will grab the first sheet in the workbook.
Read more here: [pandas.read_excel][pandas-read_excel-sheet_name]
[pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200
=== "Import data from other file types"
The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats:
<div class="mdx-columns" markdown>
- [`read_csv`][table-reader-read_csv]
- [`read_fwf`][table-reader-read_fwf]
- [`read_yaml`][table-reader-read_yaml]
- [`read_table`][table-reader-read_table]
- [`read_json`][table-reader-read_json]
- [`read_excel`][table-reader-read_excel]
- [`read_raw`][table-reader-read_raw]
</div>
You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs]
[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
[table-reader-read_csv]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_csv
[table-reader-read_fwf]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_fwf
[table-reader-read_yaml]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_yaml
[table-reader-read_table]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_table
[table-reader-read_json]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_json
[table-reader-read_excel]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_excel
[table-reader-read_raw]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_raw
[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/

3
docs/reference/diagrams.md
View File

@@ -13,7 +13,7 @@ popular and flexible solution for drawing diagrams.
## Configuration
[:octicons-tag-24: 8.2.0][Diagrams support]
<!-- md:version 8.2.0 -->
This configuration enables native support for [Mermaid.js] diagrams. Material
for MkDocs will automatically initialize the JavaScript runtime when a page
@@ -42,7 +42,6 @@ No further configuration is necessary. Advantages over a custom integration:
diagrams. See the section on [other diagrams] for more information why this
is currently not implemented for all diagrams.
[Diagrams support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[additional style sheets]: ../customization.md#additional-css
[other diagrams]: #other-diagram-types

25
docs/reference/grids.md
View File

@@ -45,15 +45,14 @@ elements in a rectangular shape.
### Using card grids
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.12.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.12.0 -->
<!-- md:flag experimental -->
Card grids wrap each grid item with a beautiful hover card that levitates on
hover. They come in two slightly different syntaxes: [list] and [block syntax],
adding support for distinct use cases.
[Insiders]: ../insiders/index.md
[list]: #list-syntax
[block syntax]: #block-syntax
@@ -98,7 +97,7 @@ includes icons and links:
Install [`mkdocs-material`](#) with [`pip`](#) and get up
and running in minutes
[:octicons-arrow-right-24: Getting started](#)
- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -106,7 +105,7 @@ includes icons and links:
---
Focus on your content and generate a responsive and searchable static site
[:octicons-arrow-right-24: Reference](#)
- :material-format-font:{ .lg .middle } __Made to measure__
@@ -114,7 +113,7 @@ includes icons and links:
---
Change the colors, fonts, language, icons, logo and more with a few lines
[:octicons-arrow-right-24: Customization](#)
- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -137,7 +136,7 @@ includes icons and links:
Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
and running in minutes
[:octicons-arrow-right-24: Getting started][getting started]
- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -145,7 +144,7 @@ includes icons and links:
---
Focus on your content and generate a responsive and searchable static site
[:octicons-arrow-right-24: Reference][reference]
- :material-format-font:{ .lg .middle } __Made to measure__
@@ -153,7 +152,7 @@ includes icons and links:
---
Change the colors, fonts, language, icons, logo and more with a few lines
[:octicons-arrow-right-24: Customization][customization]
- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -227,9 +226,9 @@ to the grid.
### Using generic grids
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.12.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.12.0 -->
<!-- md:flag 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

17
docs/reference/icons-emojis.md
View File

@@ -5,11 +5,12 @@ icon: material/emoticon-happy-outline
# Icons, Emojis
One of the best features of Material for MkDocs is the possibility to use [more
than 10,000 icons][icon search] and thousands of emojis in your project
documentation with practically zero additional effort. Moreover, custom icons
can be added and used in `mkdocs.yml`, documents and templates.
than 10,000 icons][icon search] and thousands of emojis in your project
documentation with practically zero additional effort. Moreover, [custom icons
can be added] and used in `mkdocs.yml`, documents and templates.
[icon search]: #search
[custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
## Search
@@ -40,8 +41,8 @@ lines to `mkdocs.yml`:
markdown_extensions:
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
```
The following icon sets are bundled with Material for MkDocs:
@@ -74,7 +75,7 @@ between two colons. If you're using [Twemoji] (recommended), you can look up
the shortcodes at [Emojipedia]:
``` title="Emoji"
:smile:
:smile:
```
<div class="result" markdown>
@@ -102,7 +103,7 @@ a valid path to any icon bundled with the theme, which are located in the
</div>
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
#### with colors
@@ -198,7 +199,7 @@ With the help of the [built-in typeset plugin], you can use icons and emojis
in headings, which will then be rendered in the sidebars. The plugin preserves
Markdown and HTML formatting.
[built-in typeset plugin]: ./index.md#built-in-typeset-plugin
[built-in typeset plugin]: ../plugins/typeset.md
## Customization

14
docs/reference/images.md
View File

@@ -4,8 +4,8 @@ icon: material/image-frame
# Images
While images are first-class citizens of Markdown and part of the core syntax,
it can be difficult to work with them. Material for MkDocs makes working with
While images are first-class citizens of Markdown and part of the core syntax,
it can be difficult to work with them. Material for MkDocs makes working with
images more comfortable, providing styles for image alignment and image
captions.
@@ -31,10 +31,10 @@ See additional configuration options:
### Lightbox
[:octicons-tag-24: 0.1.0][Lightbox support] ·
[:octicons-cpu-24: Plugin][glightbox]
<!-- md:version 0.1.0 -->
<!-- md:plugin [glightbox] -->
If you want to add image zoom functionality to your documentation, the
If you want to add image zoom functionality to your documentation, the
[glightbox] plugin is an excellent choice, as it integrates perfectly
with Material for MkDocs. Install it with `pip`:
@@ -52,7 +52,6 @@ plugins:
We recommend checking out the available
[configuration options][glightbox options].
[Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[glightbox]: https://github.com/blueswen/mkdocs-glightbox
[glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
@@ -154,7 +153,7 @@ browsers without support:
### Light and dark mode
[:octicons-tag-24: 8.1.1][Light and dark mode support]
<!-- md:version 8.1.1 -->
If you added a [color palette toggle] and want to show different images for
light and dark color schemes, you can append a `#only-light` or `#only-dark`
@@ -200,7 +199,6 @@ hash fragment to the image URL:
Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
name of your scheme.
[Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
[color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
[Zelda light world]: ../assets/images/zelda-light-world.png#only-light
[Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark

107
docs/reference/index.md
View File

@@ -7,75 +7,13 @@ within Markdown files.
## Configuration
### Built-in <u>typeset</u> plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.27.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
The built-in typeset plugin __preserves HTML formatting__ in the navigation and
table of contents. This means that now, code blocks, icons, emojis and other
inline formatting will be preserved, which allows for a richer editing
experience. Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- typeset
```
For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: – code blocks and icons are preserved from the
section headlines; even [highlighting inline code blocks] is supported :tada:
[highlighting inline code blocks]: code-blocks.md#highlighting-inline-code-blocks
### Built-in meta plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.21.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
The built-in meta plugin allows to __set front matter per folder__, which is
especially handy to ensure that all pages in a folder use specific templates or
tags. Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- meta
```
> If you need to be able to build your documentation with and without
> [Insiders], please refer to the [built-in plugins] section to learn how
> shared configurations help to achieve this.
The following configuration options are available:
[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
: :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the
name of the meta files that the plugin should look for. The default setting
assumes that meta files are called `.meta.yml`:
``` yaml
plugins:
- meta:
meta_file: '**/.meta.yml' # (1)!
```
1. Note that it's strongly recommended to prefix meta files with a `.`,
since otherwise they would be included in the build output.
[built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
## Usage
### Setting the page `title`
Each page has a designated title, which is used in the navigation sidebar, for
[social cards] and in other places. While MkDocs attempts to automatically
determine the title of a page in a [four step process], the title can also be
Each page has a designated title, which is used in the navigation sidebar, for
[social cards] and in other places. While MkDocs attempts to automatically
determine the title of a page in a [four step process], the title can also be
explicitly set with the front matter `title` property:
``` yaml
@@ -83,7 +21,7 @@ explicitly set with the front matter `title` property:
title: Lorem ipsum dolor sit amet # (1)!
---
# Document title
# Page title
...
```
@@ -101,7 +39,7 @@ title: Lorem ipsum dolor sit amet # (1)!
### Setting the page `description`
A Markdown file can include a description that is added to the `meta` tags of
a page, and is also used for [social cards]. It's a good idea to set a
a page, and is also used for [social cards]. It's a good idea to set a
[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
the author does not explicitly define a description for a Markdown file:
@@ -110,7 +48,7 @@ the author does not explicitly define a description for a Markdown file:
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
---
# Document title
# Page title
...
```
@@ -121,8 +59,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
### Setting the page `icon`
[:octicons-tag-24: 9.2.0b0][Page icon support] ·
:octicons-beaker-24: Experimental
<!-- md:version 9.2.0 -->
<!-- md:flag experimental -->
An icon can be assigned to each page, which is then rendered as part of the
navigation sidebar, as well as [navigation tabs], if enabled. Use the front
@@ -134,7 +72,7 @@ top of a Markdown file:
icon: material/emoticon-happy # (1)!
---
# Document title
# Page title
...
```
@@ -149,18 +87,17 @@ icon: material/emoticon-happy # (1)!
</div>
</div>
[Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Insiders]: ../insiders/index.md
[icon search]: icons-emojis.md#search
[navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
### Setting the page `status`
[:octicons-tag-24: 9.2.0b0][Page status support] ·
:octicons-beaker-24: Experimental
<!-- md:version 9.2.0 -->
<!-- md:flag experimental -->
A status can be assigned to each page, which is then displayed as part of the
navigation sidebar. First, associate a status identifier with a description by
navigation sidebar. First, associate a status identifier with a description by
adding the following to `mkdocs.yml`:
``` yaml
@@ -180,7 +117,7 @@ extra:
```
The page status can now be set with the front matter `status` property. For
example, you can mark a page as `new` with the following lines at the top of a
example, you can mark a page as `new` with the following lines at the top of a
Markdown file:
``` yaml
@@ -188,7 +125,7 @@ Markdown file:
status: new
---
# Document title
# Page title
...
```
@@ -197,13 +134,11 @@ The following status identifiers are currently supported:
- :material-alert-decagram: – `new`
- :material-trash-can: – `deprecated`
[Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
### Setting the page `subtitle`
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.25.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.25.0 -->
<!-- md:flag experimental -->
Each page can define a subtitle, which is then rendered below the title as part
of the navigation sidebar by using the front matter `subtitle` property, and
@@ -214,14 +149,14 @@ adding the following lines:
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---
# Document title
# Page title
...
```
### Setting the page `template`
If you're using [theme extension] and created a new page template in the
`overrides` directory, you can enable it for a specific page. Add the following
`overrides` directory, you can enable it for a specific page. Add the following
lines at the top of a Markdown file:
``` yaml
@@ -229,7 +164,7 @@ lines at the top of a Markdown file:
template: custom.html
---
# Document title
# Page title
...
```
@@ -244,7 +179,7 @@ template: custom.html
```
[theme extension]: ../customization.md#extending-the-theme
[built-in meta plugin]: #built-in-meta-plugin
[built-in meta plugin]: ../plugins/meta.md
## Customization

14
docs/reference/tooltips.md
View File

@@ -35,9 +35,9 @@ See additional configuration options:
### Improved tooltips
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.15.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.15.0 -->
<!-- md:flag experimental -->
When improved tooltips are enabled, Material for MkDocs replaces the browser's
rendering logic for `title` attribute with beautiful little tooltips.
@@ -55,14 +55,12 @@ Now, tooltips will be rendered for the following elements:
- __Header__ – home button, header title, color palette switch and repository link
- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
[Insiders]: ../insiders/index.md
## Usage
### Adding tooltips
The [Markdown syntax] allows to specify a `title` for each link, which will
render as a beautiful tooltip when [improved tooltips] are enabled. Add a
render as a beautiful tooltip when [improved tooltips] are enabled. Add a
tooltip to a link with the following lines:
``` markdown title="Link with tooltip, inline syntax"
@@ -107,7 +105,7 @@ extension:
### Adding abbreviations
Abbreviations can be defined by using a special syntax similar to URLs and
Abbreviations can be defined by using a special syntax similar to URLs and
[footnotes], starting with a `*` and immediately followed by the term or
acronym to be associated in square brackets:
@@ -137,7 +135,7 @@ pages with the following configuration:
[^1]:
It's highly recommended to put the Markdown file containing the
abbreviations outside of the `docs` folder (here, a folder with the name
abbreviations outside of the `docs` folder (here, a folder with the name
`includes` is used), as MkDocs might otherwise complain about an
unreferenced file.

117
docs/schema/assets/icons.json
View File

@@ -104,6 +104,7 @@
"fontawesome/brands/d-and-d",
"fontawesome/brands/dailymotion",
"fontawesome/brands/dashcube",
"fontawesome/brands/debian",
"fontawesome/brands/deezer",
"fontawesome/brands/delicious",
"fontawesome/brands/deploydog",
@@ -375,11 +376,13 @@
"fontawesome/brands/square-reddit",
"fontawesome/brands/square-snapchat",
"fontawesome/brands/square-steam",
"fontawesome/brands/square-threads",
"fontawesome/brands/square-tumblr",
"fontawesome/brands/square-twitter",
"fontawesome/brands/square-viadeo",
"fontawesome/brands/square-vimeo",
"fontawesome/brands/square-whatsapp",
"fontawesome/brands/square-x-twitter",
"fontawesome/brands/square-xing",
"fontawesome/brands/square-youtube",
"fontawesome/brands/squarespace",
@@ -409,6 +412,7 @@
"fontawesome/brands/themeco",
"fontawesome/brands/themeisle",
"fontawesome/brands/think-peaks",
"fontawesome/brands/threads",
"fontawesome/brands/tiktok",
"fontawesome/brands/trade-federation",
"fontawesome/brands/trello",
@@ -459,6 +463,7 @@
"fontawesome/brands/wpexplorer",
"fontawesome/brands/wpforms",
"fontawesome/brands/wpressr",
"fontawesome/brands/x-twitter",
"fontawesome/brands/xbox",
"fontawesome/brands/xing",
"fontawesome/brands/y-combinator",
@@ -9503,8 +9508,17 @@
"octicons/feed-discussion-16",
"octicons/feed-forked-16",
"octicons/feed-heart-16",
"octicons/feed-issue-closed-16",
"octicons/feed-issue-draft-16",
"octicons/feed-issue-open-16",
"octicons/feed-issue-reopen-16",
"octicons/feed-merged-16",
"octicons/feed-person-16",
"octicons/feed-plus-16",
"octicons/feed-public-16",
"octicons/feed-pull-request-closed-16",
"octicons/feed-pull-request-draft-16",
"octicons/feed-pull-request-open-16",
"octicons/feed-repo-16",
"octicons/feed-rocket-16",
"octicons/feed-star-16",
@@ -9992,8 +10006,10 @@
"simple/airtable",
"simple/ajv",
"simple/akamai",
"simple/akaunting",
"simple/alacritty",
"simple/albertheijn",
"simple/alby",
"simple/alchemy",
"simple/aldinord",
"simple/aldisud",
@@ -10003,6 +10019,7 @@
"simple/algorand",
"simple/alibabacloud",
"simple/alibabadotcom",
"simple/alienware",
"simple/aliexpress",
"simple/alipay",
"simple/allegro",
@@ -10019,6 +10036,7 @@
"simple/amazonapigateway",
"simple/amazonaws",
"simple/amazoncloudwatch",
"simple/amazondocumentdb",
"simple/amazondynamodb",
"simple/amazonec2",
"simple/amazonecs",
@@ -10032,7 +10050,9 @@
"simple/amazonprime",
"simple/amazonrds",
"simple/amazonredshift",
"simple/amazonroute53",
"simple/amazons3",
"simple/amazonsimpleemailservice",
"simple/amazonsqs",
"simple/amd",
"simple/ameba",
@@ -10120,6 +10140,7 @@
"simple/arkecosystem",
"simple/arlo",
"simple/arm",
"simple/armkeil",
"simple/arstechnica",
"simple/artifacthub",
"simple/artixlinux",
@@ -10157,11 +10178,13 @@
"simple/autoprefixer",
"simple/avajs",
"simple/avast",
"simple/avira",
"simple/awesomelists",
"simple/awesomewm",
"simple/awsamplify",
"simple/awsfargate",
"simple/awslambda",
"simple/awsorganizations",
"simple/axios",
"simple/azureartifacts",
"simple/azuredataexplorer",
@@ -10259,6 +10282,7 @@
"simple/brevo",
"simple/britishairways",
"simple/broadcom",
"simple/bsd",
"simple/bspwm",
"simple/bt",
"simple/buddy",
@@ -10295,6 +10319,7 @@
"simple/canva",
"simple/capacitor",
"simple/cardano",
"simple/carrd",
"simple/carrefour",
"simple/carthrottle",
"simple/carto",
@@ -10329,6 +10354,7 @@
"simple/chinaeasternairlines",
"simple/chinasouthernairlines",
"simple/chocolatey",
"simple/chromatic",
"simple/chromecast",
"simple/chrysler",
"simple/chupachups",
@@ -10346,6 +10372,7 @@
"simple/ckeditor4",
"simple/clarifai",
"simple/claris",
"simple/clarivate",
"simple/clickhouse",
"simple/clickup",
"simple/clion",
@@ -10409,6 +10436,7 @@
"simple/commonworkflowlanguage",
"simple/compilerexplorer",
"simple/composer",
"simple/comptia",
"simple/comsol",
"simple/conan",
"simple/concourse",
@@ -10436,7 +10464,9 @@
"simple/coveralls",
"simple/cpanel",
"simple/cplusplus",
"simple/cplusplusbuilder",
"simple/craftcms",
"simple/craftsman",
"simple/cratedb",
"simple/crayon",
"simple/creality",
@@ -10461,6 +10491,7 @@
"simple/cultura",
"simple/curl",
"simple/curseforge",
"simple/cyberdefenders",
"simple/cycling74",
"simple/cypress",
"simple/cytoscapedotjs",
@@ -10495,6 +10526,7 @@
"simple/dbt",
"simple/dcentertainment",
"simple/debian",
"simple/decapcms",
"simple/dedge",
"simple/deepin",
"simple/deepnote",
@@ -10533,12 +10565,15 @@
"simple/discover",
"simple/disqus",
"simple/disroot",
"simple/distrokid",
"simple/django",
"simple/dlib",
"simple/dlna",
"simple/dm",
"simple/docker",
"simple/docsdotrs",
"simple/docsify",
"simple/docusaurus",
"simple/docusign",
"simple/dogecoin",
"simple/doi",
@@ -10625,6 +10660,7 @@
"simple/epicgames",
"simple/epson",
"simple/equinixmetal",
"simple/ericsson",
"simple/erlang",
"simple/esbuild",
"simple/esea",
@@ -10657,6 +10693,7 @@
"simple/facebooklive",
"simple/faceit",
"simple/facepunch",
"simple/falco",
"simple/falcon",
"simple/fampay",
"simple/fandango",
@@ -10693,6 +10730,7 @@
"simple/filezilla",
"simple/fing",
"simple/firebase",
"simple/firefish",
"simple/fireflyiii",
"simple/firefox",
"simple/firefoxbrowser",
@@ -10709,13 +10747,16 @@
"simple/flatpak",
"simple/flattr",
"simple/flickr",
"simple/flightaware",
"simple/flipboard",
"simple/flipkart",
"simple/floatplane",
"simple/flood",
"simple/fluentbit",
"simple/fluentd",
"simple/fluke",
"simple/flutter",
"simple/flux",
"simple/fluxus",
"simple/flyway",
"simple/fmod",
@@ -10763,8 +10804,10 @@
"simple/g2",
"simple/g2a",
"simple/gameandwatch",
"simple/gamebanana",
"simple/gamedeveloper",
"simple/gamejolt",
"simple/gamemaker",
"simple/garmin",
"simple/gatling",
"simple/gatsby",
@@ -10824,18 +10867,23 @@
"simple/googleanalytics",
"simple/googleappsscript",
"simple/googleassistant",
"simple/googlebard",
"simple/googlebigquery",
"simple/googlecalendar",
"simple/googlecardboard",
"simple/googlechat",
"simple/googlechrome",
"simple/googleclassroom",
"simple/googlecloud",
"simple/googlecloudcomposer",
"simple/googlecolab",
"simple/googlecontaineroptimizedos",
"simple/googledatastudio",
"simple/googledocs",
"simple/googledomains",
"simple/googledrive",
"simple/googleearth",
"simple/googleearthengine",
"simple/googlefit",
"simple/googlefonts",
"simple/googleforms",
@@ -10858,12 +10906,14 @@
"simple/googlescholar",
"simple/googlesearchconsole",
"simple/googlesheets",
"simple/googleslides",
"simple/googlestreetview",
"simple/googletagmanager",
"simple/googletranslate",
"simple/gotomeeting",
"simple/grab",
"simple/gradle",
"simple/gradleplaypublisher",
"simple/grafana",
"simple/grammarly",
"simple/grandfrais",
@@ -10900,7 +10950,9 @@
"simple/hackerrank",
"simple/hackster",
"simple/hackthebox",
"simple/hal",
"simple/handlebarsdotjs",
"simple/handm",
"simple/handshake",
"simple/handshake_protocol",
"simple/happycow",
@@ -10917,6 +10969,7 @@
"simple/hcl",
"simple/headlessui",
"simple/headspace",
"simple/hearth",
"simple/hearthisdotat",
"simple/hedera",
"simple/hellofresh",
@@ -10927,6 +10980,7 @@
"simple/here",
"simple/heroku",
"simple/hetzner",
"simple/hexlet",
"simple/hexo",
"simple/hey",
"simple/hibernate",
@@ -10943,6 +10997,7 @@
"simple/homify",
"simple/honda",
"simple/honey",
"simple/honor",
"simple/hootsuite",
"simple/hoppscotch",
"simple/hotelsdotcom",
@@ -10954,6 +11009,7 @@
"simple/hsbc",
"simple/html5",
"simple/htmlacademy",
"simple/htop",
"simple/httpie",
"simple/huawei",
"simple/hubspot",
@@ -10968,6 +11024,7 @@
"simple/hypothesis",
"simple/hyundai",
"simple/i18next",
"simple/i3",
"simple/iata",
"simple/ibeacon",
"simple/ibm",
@@ -10988,6 +11045,7 @@
"simple/ifixit",
"simple/ifood",
"simple/ifttt",
"simple/igdb",
"simple/iheartradio",
"simple/ikea",
"simple/iledefrancemobilites",
@@ -10997,10 +11055,13 @@
"simple/immer",
"simple/immich",
"simple/imou",
"simple/improvmx",
"simple/indeed",
"simple/indigo",
"simple/inertia",
"simple/infiniti",
"simple/influxdb",
"simple/infoq",
"simple/informatica",
"simple/infosys",
"simple/infracost",
@@ -11019,9 +11080,11 @@
"simple/intellijidea",
"simple/interactiondesignfoundation",
"simple/interactjs",
"simple/interbase",
"simple/intercom",
"simple/intermarche",
"simple/internetarchive",
"simple/internetcomputer",
"simple/internetexplorer",
"simple/intigriti",
"simple/intuit",
@@ -11034,6 +11097,8 @@
"simple/iota",
"simple/ipfs",
"simple/iris",
"simple/isc2",
"simple/iscsquared",
"simple/issuu",
"simple/istio",
"simple/itchdotio",
@@ -11057,6 +11122,7 @@
"simple/jenkinsx",
"simple/jest",
"simple/jet",
"simple/jetblue",
"simple/jetbrains",
"simple/jetpackcompose",
"simple/jfrog",
@@ -11107,6 +11173,7 @@
"simple/kaufland",
"simple/kde",
"simple/kdenlive",
"simple/kedro",
"simple/keepachangelog",
"simple/keepassxc",
"simple/kentico",
@@ -11172,6 +11239,7 @@
"simple/lbry",
"simple/leaderprice",
"simple/leaflet",
"simple/leagueoflegends",
"simple/leanpub",
"simple/leetcode",
"simple/legacygames",
@@ -11197,6 +11265,7 @@
"simple/lichess",
"simple/lidl",
"simple/lifx",
"simple/lightburn",
"simple/lighthouse",
"simple/lightning",
"simple/line",
@@ -11220,6 +11289,7 @@
"simple/livewire",
"simple/llvm",
"simple/lmms",
"simple/local",
"simple/lodash",
"simple/logitech",
"simple/logmein",
@@ -11238,6 +11308,7 @@
"simple/lufthansa",
"simple/lumen",
"simple/lunacy",
"simple/lutris",
"simple/lydia",
"simple/lyft",
"simple/maas",
@@ -11258,6 +11329,7 @@
"simple/man",
"simple/manageiq",
"simple/manjaro",
"simple/mantine",
"simple/mapbox",
"simple/maplibre",
"simple/mariadb",
@@ -11266,12 +11338,14 @@
"simple/marketo",
"simple/marko",
"simple/marriott",
"simple/marvelapp",
"simple/maserati",
"simple/mastercard",
"simple/mastercomfig",
"simple/mastodon",
"simple/materialdesign",
"simple/materialdesignicons",
"simple/matillion",
"simple/matomo",
"simple/matrix",
"simple/matterdotjs",
@@ -11296,6 +11370,7 @@
"simple/medium",
"simple/meetup",
"simple/mega",
"simple/meilisearch",
"simple/mendeley",
"simple/mercadopago",
"simple/mercedes",
@@ -11340,10 +11415,12 @@
"simple/microstrategy",
"simple/midi",
"simple/mikrotik",
"simple/milvus",
"simple/minds",
"simple/minecraft",
"simple/minetest",
"simple/mini",
"simple/minio",
"simple/minutemailer",
"simple/miraheze",
"simple/miro",
@@ -11351,6 +11428,7 @@
"simple/mitsubishi",
"simple/mix",
"simple/mixcloud",
"simple/mixpanel",
"simple/mlb",
"simple/mlflow",
"simple/mobx",
@@ -11405,11 +11483,13 @@
"simple/nasa",
"simple/nationalgrid",
"simple/nativescript",
"simple/natsdotio",
"simple/naver",
"simple/nba",
"simple/nbb",
"simple/nbc",
"simple/ndr",
"simple/near",
"simple/nec",
"simple/neo4j",
"simple/neovim",
@@ -11482,6 +11562,7 @@
"simple/ocaml",
"simple/octanerender",
"simple/octave",
"simple/octobercms",
"simple/octoprint",
"simple/octopusdeploy",
"simple/oculus",
@@ -11524,6 +11605,7 @@
"simple/openstreetmap",
"simple/opensuse",
"simple/opentelemetry",
"simple/opentf",
"simple/openverse",
"simple/openvpn",
"simple/openwrt",
@@ -11564,6 +11646,7 @@
"simple/palantir",
"simple/paloaltonetworks",
"simple/paloaltosoftware",
"simple/panasonic",
"simple/pandas",
"simple/pandora",
"simple/pantheon",
@@ -11581,6 +11664,7 @@
"simple/pcgamingwiki",
"simple/peakdesign",
"simple/pearson",
"simple/peerlist",
"simple/peertube",
"simple/pegasusairlines",
"simple/pelican",
@@ -11607,6 +11691,7 @@
"simple/php",
"simple/phpmyadmin",
"simple/phpstorm",
"simple/piaggiogroup",
"simple/picardsurgeles",
"simple/picartodottv",
"simple/picnic",
@@ -11776,6 +11861,7 @@
"simple/radar",
"simple/radiopublic",
"simple/radixui",
"simple/radstudio",
"simple/railway",
"simple/rainmeter",
"simple/rakuten",
@@ -11830,6 +11916,7 @@
"simple/researchgate",
"simple/resharper",
"simple/resurrectionremixos",
"simple/retool",
"simple/retroarch",
"simple/retropie",
"simple/revanced",
@@ -11850,6 +11937,7 @@
"simple/riseup",
"simple/roadmapdotsh",
"simple/roamresearch",
"simple/robinhood",
"simple/roblox",
"simple/robloxstudio",
"simple/robotframework",
@@ -11860,6 +11948,7 @@
"simple/rollsroyce",
"simple/rollupdotjs",
"simple/rome",
"simple/rootme",
"simple/roots",
"simple/rootsbedrock",
"simple/rootssage",
@@ -11880,6 +11969,7 @@
"simple/rubyonrails",
"simple/rubysinatra",
"simple/ruff",
"simple/rumble",
"simple/rundeck",
"simple/runkeeper",
"simple/runkit",
@@ -11892,12 +11982,14 @@
"simple/sage",
"simple/sahibinden",
"simple/sailfishos",
"simple/sailsdotjs",
"simple/salesforce",
"simple/saltproject",
"simple/samsung",
"simple/samsungpay",
"simple/sandisk",
"simple/sanfranciscomunicipalrailway",
"simple/sanic",
"simple/sanity",
"simple/saopaulometro",
"simple/sap",
@@ -11913,6 +12005,7 @@
"simple/scipy",
"simple/scopus",
"simple/scpfoundation",
"simple/scrapbox",
"simple/scratch",
"simple/screencastify",
"simple/scribd",
@@ -11920,7 +12013,9 @@
"simple/scrollreveal",
"simple/scrumalliance",
"simple/scrutinizerci",
"simple/scylladb",
"simple/seagate",
"simple/searxng",
"simple/seat",
"simple/securityscorecard",
"simple/sefaria",
@@ -11959,11 +12054,13 @@
"simple/shopee",
"simple/shopify",
"simple/shopware",
"simple/shortcut",
"simple/shotcut",
"simple/showpad",
"simple/showtime",
"simple/shutterstock",
"simple/siemens",
"simple/sifive",
"simple/signal",
"simple/similarweb",
"simple/simkl",
@@ -11971,6 +12068,7 @@
"simple/simpleicons",
"simple/simplenote",
"simple/sinaweibo",
"simple/singaporeairlines",
"simple/singlestore",
"simple/sitecore",
"simple/sitepoint",
@@ -12016,6 +12114,7 @@
"simple/sonarlint",
"simple/sonarqube",
"simple/sonarsource",
"simple/sonatype",
"simple/songkick",
"simple/songoda",
"simple/sonicwall",
@@ -12041,6 +12140,8 @@
"simple/spectrum",
"simple/speedtest",
"simple/speedypage",
"simple/sphinx",
"simple/spigotmc",
"simple/spinnaker",
"simple/spinrilla",
"simple/splunk",
@@ -12135,6 +12236,7 @@
"simple/swift",
"simple/swiggy",
"simple/swiper",
"simple/swr",
"simple/symantec",
"simple/symbolab",
"simple/symfony",
@@ -12162,6 +12264,7 @@
"simple/tata",
"simple/tauri",
"simple/taxbuzz",
"simple/tcs",
"simple/teamcity",
"simple/teamspeak",
"simple/teamviewer",
@@ -12236,6 +12339,7 @@
"simple/torbrowser",
"simple/torproject",
"simple/toshiba",
"simple/tourbox",
"simple/toyota",
"simple/tplink",
"simple/tqdm",
@@ -12289,11 +12393,13 @@
"simple/ubisoft",
"simple/ublockorigin",
"simple/ubuntu",
"simple/ubuntumate",
"simple/udacity",
"simple/udemy",
"simple/ufc",
"simple/uikit",
"simple/ulule",
"simple/umami",
"simple/umbraco",
"simple/uml",
"simple/unacademy",
@@ -12303,8 +12409,10 @@
"simple/unicode",
"simple/unilever",
"simple/unitedairlines",
"simple/unitednations",
"simple/unity",
"simple/unlicense",
"simple/uno",
"simple/unocss",
"simple/unraid",
"simple/unrealengine",
@@ -12320,6 +12428,7 @@
"simple/uptobox",
"simple/upwork",
"simple/usps",
"simple/utorrent",
"simple/v",
"simple/v2ex",
"simple/v8",
@@ -12330,6 +12439,7 @@
"simple/valve",
"simple/vapor",
"simple/vault",
"simple/vaultwarden",
"simple/vauxhall",
"simple/vbulletin",
"simple/vectorlogozone",
@@ -12343,9 +12453,11 @@
"simple/verdaccio",
"simple/veritas",
"simple/verizon",
"simple/vespa",
"simple/vexxhost",
"simple/vfairs",
"simple/viadeo",
"simple/viaplay",
"simple/viber",
"simple/vim",
"simple/vimeo",
@@ -12382,6 +12494,7 @@
"simple/vuetify",
"simple/vulkan",
"simple/vultr",
"simple/vyond",
"simple/w3c",
"simple/wacom",
"simple/wagtail",
@@ -12423,6 +12536,7 @@
"simple/wegame",
"simple/weightsandbiases",
"simple/welcometothejungle",
"simple/wellfound",
"simple/wemo",
"simple/westerndigital",
"simple/wetransfer",
@@ -12470,6 +12584,7 @@
"simple/writedotas",
"simple/wwe",
"simple/wwise",
"simple/x",
"simple/xamarin",
"simple/xaml",
"simple/xampp",
@@ -12496,6 +12611,7 @@
"simple/yarn",
"simple/ycombinator",
"simple/yelp",
"simple/yeti",
"simple/yoast",
"simple/yolo",
"simple/yourtraveldottv",
@@ -12520,6 +12636,7 @@
"simple/zendframework",
"simple/zenn",
"simple/zenodo",
"simple/zensar",
"simple/zerodha",
"simple/zeromq",
"simple/zerply",

32
docs/schema/extensions/pymdownx.json
View File

@@ -168,11 +168,11 @@
"properties": {
"emoji_generator": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator",
"default": "!!python/name:materialx.emoji.to_svg"
"default": "!!python/name:material.extensions.emoji.to_svg"
},
"emoji_index": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index",
"default": "!!python/name:materialx.emoji.twemoji"
"default": "!!python/name:material.extensions.emoji.twemoji"
},
"options": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons",
@@ -224,6 +224,10 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.use_pygments",
"type": "boolean"
},
"pygments_lang_class": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.pygments_lang_class",
"type": "boolean"
},
"auto_title": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.auto_title",
"type": "boolean"
@@ -247,6 +251,10 @@
"anchor_linenums": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums",
"type": "boolean"
},
"line_spans": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.line_spans",
"type": "string"
}
},
"additionalProperties": false
@@ -536,6 +544,21 @@
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
"type": "boolean",
"default": false
},
"url_max_size": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
"type": "integer",
"default": 33554432
},
"url_timeout": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
"type": "number",
"default": 10.0
},
"url_request_headers": {
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
"type": "object",
"default": {}
}
},
"additionalProperties": false
@@ -617,6 +640,11 @@
],
"default": true
},
"combine_header_slug": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.combine_header_slug",
"type": "boolean",
"default": true
},
"slugify": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"

16
docs/schema/extra.json
View File

@@ -132,6 +132,22 @@
}
]
},
"annotate": {
"title": "Custom selectors for annotations",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
"type": "object",
"patternProperties": {
".*": {
"title": "Custom selector",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
"type": "array",
"items": {
"type": "string",
"pattern": "^\\.\\w+"
}
}
}
},
"consent": {
"title": "Cookie consent",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",

5
docs/schema/plugins.json
View File

@@ -25,6 +25,9 @@
{
"$ref": "plugins/blog.json"
},
{
"$ref": "plugins/group.json"
},
{
"$ref": "plugins/info.json"
},
@@ -90,7 +93,7 @@
]
},
"external-community": {
"description": "External plugins, schema provided by the community",
"description": "External plugins, schema provided by our community",
"anyOf": [
{
"$ref": "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/schema.json"

92
docs/schema/plugins/blog.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in blog plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
"enum": [
"blog"
]
@@ -12,30 +12,37 @@
"type": "object",
"properties": {
"blog": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.enabled",
"type": "boolean",
"default": true
},
"blog_dir": {
"title": "Blog directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_dir",
"type": "string",
"default": "blog"
},
"blog_toc": {
"title": "Blog table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_toc",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_toc",
"type": "boolean",
"default": false
},
"post_dir": {
"title": "Blog posts directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_dir",
"type": "string",
"default": "\"{blog\\}/posts\""
},
"post_date_format": {
"title": "Format string for post dates",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_date_format",
"default": "long",
"oneOf": [
{
"enum": [
@@ -48,12 +55,11 @@
{
"type": "string"
}
],
"default": "long"
]
},
"post_url_date_format": {
"title": "Format string for post dates in URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_date_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_date_format",
"oneOf": [
{
"enum": [
@@ -70,7 +76,7 @@
},
"post_url_format": {
"title": "Format string for post URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_format",
"oneOf": [
{
"enum": [
@@ -87,24 +93,24 @@
},
"post_url_max_categories": {
"title": "Number of categories in post URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_max_categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_max_categories",
"type": "number",
"default": 1
},
"post_slugify": {
"title": "Post slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"post_slugify_separator": {
"title": "Post slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify_separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify_separator",
"type": "string",
"default": "\"-\""
},
"post_excerpt": {
"title": "Post excerpts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt",
"oneOf": [
{
"title": "Post excerpts are optional",
@@ -123,49 +129,49 @@
},
"post_excerpt_max_authors": {
"title": "Number of authors to render in post excerpts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_authors",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_authors",
"type": "number",
"default": 1
},
"post_excerpt_max_categories": {
"title": "Number of categories to render in post excerpts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_categories",
"type": "number",
"default": 5
},
"post_excerpt_separator": {
"title": "Post excerpt separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_separator",
"type": "string",
"default": "<!-- more -->"
},
"post_readtime": {
"title": "Post reading time computation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime",
"type": "boolean",
"default": true
},
"post_readtime_words_per_minute": {
"title": "Post reading time words per minute",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime_words_per_minute",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime_words_per_minute",
"type": "number",
"default": 265
},
"archive": {
"title": "Archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive",
"type": "boolean",
"default": true
},
"archive_name": {
"title": "Archive name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_name",
"type": "string",
"default": "Archive"
},
"archive_date_format": {
"title": "Format string for archive dates",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_date_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_date_format",
"oneOf": [
{
"enum": [
@@ -181,7 +187,7 @@
},
"archive_url_date_format": {
"title": "Format string for archive dates in URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_date_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_date_format",
"oneOf": [
{
"enum": [
@@ -197,7 +203,7 @@
},
"archive_url_format": {
"title": "Format string for archive URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_format",
"oneOf": [
{
"enum": [
@@ -211,25 +217,25 @@
},
"archive_toc": {
"title": "Archive table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_toc",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_toc",
"type": "boolean",
"default": false
},
"categories": {
"title": "Categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories",
"type": "boolean",
"default": true
},
"categories_name": {
"title": "Categories name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_name",
"type": "string",
"default": "Categories"
},
"categories_url_format": {
"title": "Format string for category URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_url_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_url_format",
"oneOf": [
{
"enum": [
@@ -244,18 +250,18 @@
},
"categories_slugify": {
"title": "Categories slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"categories_slugify_separator": {
"title": "Categories slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify_separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify_separator",
"type": "string",
"default": "\"-\""
},
"categories_allowed": {
"title": "Categories allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_allowed",
"type": "array",
"items": {
"type": "string"
@@ -265,25 +271,25 @@
},
"categories_toc": {
"title": "Categories table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_toc",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_toc",
"type": "boolean",
"default": false
},
"pagination": {
"title": "Pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination",
"type": "boolean",
"default": true
},
"pagination_per_page": {
"title": "Posts per page",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_per_page",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_per_page",
"type": "number",
"default": 10
},
"pagination_url_format": {
"title": "Format string for pagination URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_url_format",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_url_format",
"oneOf": [
{
"enum": [
@@ -298,7 +304,7 @@
},
"pagination_template": {
"title": "Template string for pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_template",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_template",
"oneOf": [
{
"enum": [
@@ -315,37 +321,37 @@
},
"pagination_keep_content": {
"title": "Paginated indexes inherit content",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_keep_content",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_keep_content",
"type": "boolean",
"default": false
},
"authors": {
"title": "Author info",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors",
"type": "boolean",
"default": true
},
"authors_file": {
"title": "Authors file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_file",
"type": "string",
"default": ".authors.yml"
"default": "\"{blog\\}/.authors.yml\""
},
"draft": {
"title": "Render posts marked as drafts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft",
"type": "boolean",
"default": false
},
"draft_on_serve": {
"title": "Render posts marked as drafts when previewing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_on_serve",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_on_serve",
"type": "boolean",
"default": true
},
"draft_if_future_date": {
"title": "Automatically mark posts with future dates as drafts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_if_future_date",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_if_future_date",
"type": "boolean",
"default": false
}

29
docs/schema/plugins/group.json Normal file
View File

@@ -0,0 +1,29 @@
{
"$schema": "https://json-schema.org/draft-07/schema",
"title": "Built-in group plugin",
"oneOf": [
{
"type": "object",
"properties": {
"group": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.enabled",
"type": "boolean",
"default": true
},
"plugins": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.plugins",
"$ref": "../plugins.json"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}

24
docs/schema/plugins/info.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in info plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
"enum": [
"info"
]
@@ -12,12 +12,30 @@
"type": "object",
"properties": {
"info": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled",
"type": "boolean",
"default": true
},
"enabled_on_serve": {
"title": "Enable plugin when previewing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled_on_serve",
"type": "boolean",
"default": false
},
"archive": {
"title": "Enable creation of archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive",
"type": "boolean",
"default": true
},
"archive_stop_on_violation": {
"title": "Stop creation of archive on violation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive_stop_on_violation",
"type": "boolean",
"default": true
}

12
docs/schema/plugins/meta.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in meta plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
"enum": [
"meta"
]
@@ -12,12 +12,18 @@
"type": "object",
"properties": {
"meta": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.enabled",
"type": "boolean",
"default": true
},
"meta_file": {
"title": "Meta file name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+meta.meta_file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.meta_file",
"pattern": "\\.yml$",
"default": "\"**/.meta.yml\""
}

6
docs/schema/plugins/offline.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in offline plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
"enum": [
"offline"
]
@@ -12,12 +12,12 @@
"type": "object",
"properties": {
"offline": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#+offline.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/#config.enabled",
"type": "boolean",
"default": true
}

52
docs/schema/plugins/optimize.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in optimize plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-optimize-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
"enum": [
"optimize"
]
@@ -12,75 +12,101 @@
"type": "object",
"properties": {
"optimize": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-optimize-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.concurrency",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.concurrency",
"type": "number"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.cache",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.cache_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache_dir",
"type": "string",
"default": ".cache/plugins/social"
"default": ".cache/plugins/optimize"
},
"optimize_png": {
"title": "Optimization of PNGs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png",
"type": "boolean",
"default": true
},
"optimize_png_speed": {
"title": "Speed/quality tradeoff [1,10]",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png_speed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_speed",
"type": "number",
"default": 4
},
"optimize_png_strip": {
"title": "Strip unnecessary metadata from PNGs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png_strip",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_strip",
"type": "boolean",
"default": true
},
"optimize_jpg": {
"title": "Optimization of JPGs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg",
"type": "boolean",
"default": true
},
"optimize_jpg_quality": {
"title": "Speed/quality tradeoff for pngquant [0,10]",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg_quality",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_quality",
"type": "number",
"default": 60
},
"optimize_jpg_progressive": {
"title": "Progressive encoding (faster rendering)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg_progressive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_progressive",
"type": "boolean",
"default": true
},
"optimize_include": {
"title": "Files or folders to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
"type": "array",
"items": {
"title": "Files or folders matching this pattern will be included",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"optimize_exclude": {
"title": "Files or folders to exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
"type": "array",
"items": {
"title": "Files or folders matching this pattern will be excluded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
"pattern": ".*"
},
"uniqueItems": true,
"minItems": 1
},
"print_gain": {
"title": "Print optimization gain",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain",
"type": "boolean",
"default": true
},
"print_gain_summary": {
"title": "Print optimization gain summary",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain_summary",
"type": "boolean",
"default": true
}

40
docs/schema/plugins/privacy.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in privacy plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
"enum": [
"privacy"
]
@@ -12,45 +12,57 @@
"type": "object",
"properties": {
"privacy": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.concurrency",
"type": "number"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache_dir",
"type": "string",
"default": ".cache/plugins/privacy"
},
"assets": {
"title": "Process external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets",
"type": "boolean",
"default": true
},
"assets_fetch": {
"title": "Download external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch",
"type": "boolean",
"default": true
},
"assets_fetch_dir": {
"title": "Download external assets to this directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch_dir",
"type": "string",
"default": "assets/external"
},
"assets_include": {
"title": "External assets to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
"type": "array",
"items": {
"title": "External assets matching this pattern will be downloaded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
"pattern": ".*"
},
"uniqueItems": true,
@@ -58,11 +70,11 @@
},
"assets_exclude": {
"title": "External assets to exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
"type": "array",
"items": {
"title": "External assets matching this pattern will not be downloaded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
"pattern": ".*"
},
"uniqueItems": true,
@@ -70,13 +82,13 @@
},
"links": {
"title": "Process external links",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links",
"type": "boolean",
"default": true
},
"links_attr_map": {
"title": "Custom attributes to add to external links",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_attr_map",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_attr_map",
"type": "object",
"patternProperties": {
"^[\\w_]+$": {
@@ -86,7 +98,7 @@
},
"links_noopener": {
"title": "Behavior for external links that open in new windows",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_noopener",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_noopener",
"type": "boolean",
"default": true
}

46
docs/schema/plugins/projects.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in projects plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
"enum": [
"projects"
]
@@ -12,31 +12,65 @@
"type": "object",
"properties": {
"projects": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.concurrency",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.concurrency",
"type": "number"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache_dir",
"type": "string",
"default": ".cache/plugins/projects"
},
"projects": {
"title": "Enable projects",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects",
"type": "boolean",
"default": true
},
"projects_dir": {
"title": "Projects directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_dir",
"type": "string",
"default": "projects"
},
"projects_config_files": {
"title": "Projects configuration files",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_files",
"type": "string",
"default": "\"*/mkdocs.yml\""
},
"projects_config_transform": {
"title": "Projects configuration transform",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_transform",
"type": "string",
"defaultSnippets": [
{
"body": "!!python/name:${1:module}.${2:function}"
}
]
},
"hosting": {
"title": "Enable hoisting",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.hoisting",
"type": "boolean",
"default": true
}
},
"additionalProperties": false

14
docs/schema/plugins/search.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in search plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
"enum": [
"search"
]
@@ -12,7 +12,7 @@
"type": "object",
"properties": {
"search": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
"type": "object",
"properties": {
"lang": {
@@ -33,12 +33,12 @@
},
"separator": {
"title": "Separator for indexing and query tokenization",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.separator",
"type": "string"
},
"pipeline": {
"title": "Text processing pipeline for indexing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.pipeline",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.pipeline",
"type": "array",
"items": {
"enum": [
@@ -51,12 +51,12 @@
},
"jieba_dict": {
"title": "Jieba dictionary replacement",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict",
"type": "string"
},
"jieba_dict_user": {
"title": "Jieba dictionary augmentation",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict_user",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict_user",
"type": "string"
}
},
@@ -69,7 +69,7 @@
"definitions": {
"lang": {
"title": "Site search language",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.lang",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.lang",
"oneOf": [
{
"title": "Site search language: Arabic",

77
docs/schema/plugins/social.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in social plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
"enum": [
"social"
]
@@ -12,61 +12,80 @@
"type": "object",
"properties": {
"social": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.enabled",
"type": "boolean",
"default": true
},
"concurrency": {
"title": "Concurrency (number of CPUs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.concurrency",
"type": "number"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache_dir",
"type": "string",
"default": ".cache/plugins/social"
},
"cards": {
"title": "Social cards",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards",
"type": "boolean",
"default": true
},
"cards_dir": {
"title": "Social cards directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir",
"type": "string",
"default": "assets/images/social"
},
"cards_layout_dir": {
"title": "Social cards layout directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_dir",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_dir",
"type": "string",
"default": "layouts"
},
"cards_layout": {
"title": "Social cards layout",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout",
"default": "default",
"enum": [
"default",
"default/accent",
"default/invert",
"default/variant"
"oneOf": [
{
"enum": [
"default",
"default/accent",
"default/invert",
"default/variant"
]
},
{
"type": "string"
}
]
},
"cards_layout_options": {
"title": "Social cards layout options",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_options",
"type": "object"
},
"cards_include": {
"title": "Pages or folders to include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
"type": "array",
"items": {
"title": "Pages or folders matching this pattern will be included",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
"pattern": ".*"
},
"uniqueItems": true,
@@ -74,11 +93,11 @@
},
"cards_exclude": {
"title": "Pages or folders to exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
"type": "array",
"items": {
"title": "Pages or folders matching this pattern will be excluded",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
"pattern": ".*"
},
"uniqueItems": true,
@@ -86,45 +105,33 @@
},
"debug": {
"title": "Debug mode",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug",
"type": "boolean",
"default": true
},
"debug_on_build": {
"title": "Always disable debug mode on build",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_on_build",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_on_build",
"type": "boolean",
"default": false
},
"debug_grid": {
"title": "Debug grid",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid",
"type": "boolean",
"default": true
},
"debug_grid_step": {
"title": "Debug grid step size",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid_step",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid_step",
"type": "number",
"default": 32
},
"debug_color": {
"title": "Debug color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_color",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_color",
"type": "string",
"default": "yellow"
},
"cache": {
"title": "Enable caching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache",
"type": "boolean",
"default": true
},
"cache_dir": {
"title": "Cache directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache_dir",
"type": "string",
"default": ".cache/plugins/social"
}
},
"additionalProperties": false

36
docs/schema/plugins/tags.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in tags plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
"enum": [
"tags"
]
@@ -12,24 +12,24 @@
"type": "object",
"properties": {
"tags": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.enabled",
"type": "boolean",
"default": true
},
"tags_file": {
"title": "Markdown file to render tags index",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_file",
"pattern": "\\.md$",
"default": "tags.md"
},
"tags_extra_files": {
"title": "Markdown files to render additional tags indexes",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_extra_files",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_extra_files",
"type": "object",
"patternProperties": {
"\\.md$": {
@@ -44,18 +44,38 @@
},
"tags_slugify": {
"title": "Tags slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"tags_slugify_separator": {
"title": "Tags slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify_separator",
"type": "string",
"default": "\"-\""
},
"tags_compare": {
"title": "Sort tags by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare",
"default": "!!python/name:material.plugins.tags.casefold"
},
"tags_compare_reverse": {
"title": "Soft tags in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare_reverse",
"default": false
},
"tags_pages_compare": {
"title": "Sort tags pages by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare",
"default": "!!python/name:material.plugins.tags.page_title"
},
"tags_pages_compare_reverse": {
"title": "Soft tags pages in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare_reverse",
"default": false
},
"tags_allowed": {
"title": "Tags allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_allowed",
"type": "array",
"items": {
"type": "string"

6
docs/schema/plugins/typeset.json
View File

@@ -3,7 +3,7 @@
"title": "Built-in typeset plugin",
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-typeset-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
"enum": [
"typeset"
]
@@ -12,12 +12,12 @@
"type": "object",
"properties": {
"typeset": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-typeset-plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+typeset.enabled",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/#config.enabled",
"type": "boolean",
"default": true
}

7
docs/schema/theme.json
View File

@@ -629,6 +629,13 @@
"content.code.copy"
]
},
{
"title": "Code selection button",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-selection-button",
"enum": [
"content.code.select"
]
},
{
"title": "Linked content tabs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs",

22
docs/setup/adding-a-comment-system.md
View File

@@ -51,22 +51,28 @@ and [override the `comments.html` partial][overriding partials] with:
<script>
var giscus = document.querySelector("script[src*=giscus]")
/* Set palette on initial load */
// Set palette on initial load
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
var theme = palette.color.scheme === "slate" ? "dark" : "light"
var theme = palette.color.scheme === "slate"
? "transparent_dark"
: "light"
// Instruct Giscus to set theme
giscus.setAttribute("data-theme", theme) // (1)!
}
/* Register event handlers after documented loaded */
// Register event handlers after documented loaded
document.addEventListener("DOMContentLoaded", function() {
var ref = document.querySelector("[data-md-component=palette]")
ref.addEventListener("change", function() {
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
var theme = palette.color.scheme === "slate" ? "dark" : "light"
var theme = palette.color.scheme === "slate"
? "transparent_dark"
: "light"
/* Instruct Giscus to change theme */
// Instruct Giscus to change theme
var frame = document.querySelector(".giscus-frame")
frame.contentWindow.postMessage(
{ giscus: { setConfig: { theme } } },
@@ -93,7 +99,7 @@ property to `true`:
comments: true
---
# Document title
# Page title
...
```
@@ -102,6 +108,6 @@ If you wish to enable comments for an entire folder, you can use the
[Giscus GitHub App]: https://github.com/apps/giscus
[theme extension]: ../customization.md#extending-the-theme
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
[overriding partials]: ../customization.md#overriding-partials
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
[built-in meta plugin]: ../plugins/meta.md

80
docs/setup/adding-a-git-repository.md
View File

@@ -9,8 +9,8 @@ static site, including stars and forks. Furthermore, the
### Repository
[:octicons-tag-24: 0.1.0][Repository support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 0.1.0 -->
<!-- md:default none -->
In order to display a link to the repository of your project as part of your
documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
@@ -29,20 +29,18 @@ GitHub repositories also include the tag of the latest release.[^1]
[^1]:
Unfortunately, GitHub only provides an API endpoint to obtain the [latest
release] - not the latest tag. Thus, make sure to [create a release] (not
release] - not the latest tag. Thus, make sure to [create a release] (not
pre-release) for the latest tag you want to display next to the number of
stars and forks.
[Repository support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
[latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
[create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
#### Repository name
[:octicons-tag-24: 0.1.0][Repository name support] ·
:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
`Bitbucket`
<!-- md:version 0.1.0 -->
<!-- md:default _automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` -->
MkDocs will infer the source provider by examining the URL and try to set the
_repository name_ automatically. If you wish to customize the name, set
@@ -52,14 +50,12 @@ _repository name_ automatically. If you wish to customize the name, set
repo_name: squidfunk/mkdocs-material
```
[Repository name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
#### Repository icon
[:octicons-tag-24: 5.0.0][Repository icon support] ·
:octicons-milestone-24: Default:
:fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
<!-- md:version 5.0.0 -->
<!-- md:default computed -->
While the default repository icon is a generic git icon, it can be set to
any icon bundled with the theme by referencing a valid icon path in
@@ -93,14 +89,12 @@ Some popular choices:
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
[Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[Repository icon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
[icon search]: ../reference/icons-emojis.md#search
#### Code actions
[:octicons-tag-24: 9.0.0][Code actions support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 9.0.0 -->
<!-- md:feature -->
If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
@@ -152,7 +146,6 @@ theme:
</div>
</div>
[Code actions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
[repository URL]: #repository
[GitHub]: https://github.com/
[GitLab]: https://about.gitlab.com/
@@ -172,8 +165,8 @@ links to all [contributors] or [authors] involved.
#### Document dates
[:octicons-tag-24: 4.6.0][Document dates support] ·
[:octicons-cpu-24: Plugin][git-revision-date-localized]
<!-- md:version 4.6.0 -->
<!-- md:plugin [git-revision-date-localized] -->
The [git-revision-date-localized] plugin adds support for adding the date of
last update and creation of a document at the bottom of each page. Install it
@@ -193,9 +186,9 @@ plugins:
The following configuration options are supported:
[`enabled`](#+git-revision-date-localized.enabled){ #+git-revision-date-localized.enabled }
<!-- md:option git-revision-date-localized.enabled -->
: :octicons-milestone-24: Default: `true` – This option specifies whether
: <!-- md:default `true` --> This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, e.g. for local builds, use an [environment variable]:
@@ -205,9 +198,9 @@ The following configuration options are supported:
enabled: !ENV [CI, false]
```
[`type`](#+git-revision-date-localized.type){ #+git-revision-date-localized.type }
<!-- md:option git-revision-date-localized.type -->
: :octicons-milestone-24: Default: `date` – The format of the date to be
: <!-- md:default `date` --> The format of the date to be
displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
and `timeago`:
@@ -217,9 +210,9 @@ The following configuration options are supported:
type: date
```
[`enable_creation_date`](#+git-revision-date-localized.enable_creation_date){ #+git-revision-date-localized.enable_creation_date }
<!-- md:option git-revision-date-localized.enable_creation_date -->
: :octicons-milestone-24: Default: `false` – Enables the display of the
: <!-- md:default `false` --> Enables the display of the
creation date of the file associated with the page next to the last updated
date at the bottom of the page:
@@ -229,9 +222,15 @@ The following configuration options are supported:
enable_creation_date: true
```
[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date }
!!! note "When using build environments"
: :octicons-milestone-24: Default: `false` – Enables falling back to
If you are deploying through a CI system, you might need to adjust your
CI settings when fetching the code. For more information, see
[git-revision-date-localized].
<!-- md:option git-revision-date-localized.fallback_to_build_date -->
: <!-- md:default `false` --> Enables falling back to
the time when `mkdocs build` was executed. Can be used as a fallback when
the build is performed outside of a git repository:
@@ -245,15 +244,14 @@ The other configuration options of this extension are not officially supported
by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
[Document dates support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
#### Document contributors
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.19.0][Insiders] ·
[:octicons-cpu-24: Plugin][git-committers] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.19.0 -->
<!-- md:plugin [git-committers] -->
<!-- md:flag experimental -->
The [git-committers][^2] plugin renders the GitHub avatars of all contributors,
linking to their GitHub profiles at the bottom of each page. As always, it can
@@ -280,9 +278,9 @@ plugins:
The following configuration options are supported:
[`enabled`](#+git-committers.enabled){ #+git-committers.enabled }
<!-- md:option git-committers.enabled -->
: :octicons-milestone-24: Default: `true` – This option specifies whether
: <!-- md:default `true` --> This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, e.g. for local builds, use an [environment variable]:
@@ -292,9 +290,9 @@ The following configuration options are supported:
enabled: !ENV [CI, false]
```
[`repository`](#+git-committers.repository){ #+git-committers.repository }
<!-- md:option git-committers.repository -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property must be set to the slug of the repository that contains your
documentation. The slug must follow the pattern `<username>/<repository>`:
@@ -304,9 +302,9 @@ The following configuration options are supported:
repository: squidfunk/mkdocs-material
```
[`branch`](#+git-committers.branch){ #+git-committers.branch }
<!-- md:option git-committers.branch -->
: :octicons-milestone-24: Default: `master` – This property should be set to
: <!-- md:default `master` --> This property should be set to
the branch of the repository from which to retrieve the contributors. To use the `main` branch:
``` yaml
@@ -326,10 +324,10 @@ them at your own risk.
#### Document authors
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.19.0][Insiders] ·
[:octicons-cpu-24: Plugin][git-authors] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.19.0 -->
<!-- md:plugin [git-authors] -->
<!-- md:flag experimental -->
The [git-authors] plugin is a lightweight alternative to the
[git-committers] plugin and extracts the authors of a document from git to display

275
docs/setup/building-an-optimized-site.md
View File

@@ -11,10 +11,10 @@ further useful automatic optimization techniques.
### Built-in projects plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.38.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:plugin [projects] – built-in -->
<!-- md:flag experimental -->
The built-in projects plugin allows to split your documentation into multiple
distinct MkDocs projects, __build them concurrently__ and
@@ -25,31 +25,10 @@ plugins:
- projects
```
Next, create a folder called `projects` in your root directory which will
contain all projects. For example, if we want to build a project with two
additional languages, we can use:
For a list of all settings, please consult the [plugin documentation].
``` { .sh .no-copy }
.
├─ projects/
│ ├─ de/
│ │ ├─ docs/
│ │ └─ mkdocs.yml
│ └─ fr/
│ ├─ docs/
│ └─ mkdocs.yml
└─ mkdocs.yml
```
If you now invoke `mkdocs serve` and change a file in one of the projects,
the projects plugin makes sure that MkDocs will also reload those files. Note
that the projects are currently entirely separate, which means they will have
separate search indexes and sitemaps. We're happy to receive feedback on this
plugin and learn about your requirements to make it better, as we plan to add
support for merging and hoisting files.
[Create a discussion to share your thoughts!][discussion]
[discussion]: https://github.com/squidfunk/mkdocs-material/discussions
[projects]: ../plugins/projects.md
[plugin documentation]: ../plugins/projects.md
??? info "Use cases for the projects plugin"
@@ -63,67 +42,12 @@ support for merging and hoisting files.
so that we can improve it together with our users and make it even more
powerful as we discover new use cases.
The following configuration options are available:
[`enabled`](#+projects.enabled){ #+projects.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
``` yaml
plugins:
- projects:
enabled: !ENV [CI, false]
```
[`concurrency`](#+projects.concurrency){ #+projects.concurrency }
: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
how many CPUs the plugin is allowed to use when building projects.
With more CPUs, the plugin can do more work in the same time, thus complete
optimization faster. Concurrent processing can be disabled with:
``` yaml
plugins:
- projects:
concurrency: 1
```
#### Projects
The following configuration options are available for projects:
[`projects`](#+projects.projects){ #+projects.projects }
: :octicons-milestone-24: Default: `true` – This option specifies whether
to build nested projects. If you want to switch the plugin off, e.g.
for local builds, you can use an [environment variable]:
``` yaml
plugins:
- projects:
projects: !ENV [CI, false]
```
[`projects_dir`](#+projects.projects_dir){ #+projects.projects_dir }
: :octicons-milestone-24: Default: `projects` – This option specifies the
name of the folder the plugin expects your projects to be stored. While it's
usually not necessary to change this option, change it with:
``` yaml
plugins:
- projects:
projects_dir: path/to/folder
```
### Built-in optimize plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.29.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.29.0 -->
<!-- md:plugin [optimize] – built-in -->
<!-- md:flag experimental -->
The built-in optimize plugin automatically identifies and optimizes all media
files as part of the build using compression and conversion techniques. Add
@@ -131,180 +55,9 @@ the following lines to `mkdocs.yml`:
``` yaml
plugins:
- optimize # (1)!
- optimize
```
1. Please ensure that all [dependencies for image processing] are installed,
or the plugin will not work properly.
For a list of all settings, please consult the [plugin documentation][optimize].
> If you need to be able to build your documentation with and without
> [Insiders], please refer to the [built-in plugins] section to learn how
> shared configurations help to achieve this.
The following configuration options are available:
[`enabled`](#+optimize.enabled){ #+optimize.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
``` yaml
plugins:
- optimize:
enabled: !ENV [CI, false]
```
[`concurrency`](#+optimize.concurrency){ #+optimize.concurrency }
: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
how many CPUs the plugin is allowed to use when optimizing media files.
With more CPUs, the plugin can do more work in the same time, thus complete
optimization faster. Concurrent processing can be disabled with:
``` yaml
plugins:
- optimize:
concurrency: 1
```
#### Optimization
Technical documentation often includes screenshots or diagrams, both of which
are prime candidates for compression. The [built-in optimize plugin] allows to
automatically compress images using [pngquant] (for PNGs), and [Pillow]
(for JPGs).
The following configuration options are available for optimization:
[`optimize_png`](#+optimize.optimize_png){ #+optimize.optimize_png }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin should optimize PNG files using [pngquant], which must be
installed on the system. PNG optimization can be disabled with:
``` yaml
plugins:
- optimize:
optimize_png: false
```
[`optimize_png_speed`](#+optimize.optimize_png_speed){ #+optimize.optimize_png_speed }
: :octicons-milestone-24: Default: `4` of `[1,10]` – This option specifies the
speed/quality tradeoff that [pngquant] applies when compressing. The lower
the number, the more time will be spent optimizing:
=== "Slower <small>small</small>"
``` yaml
plugins:
- optimize:
optimize_png_speed: 1
```
=== "Faster <small>rough</small>"
``` yaml
plugins:
- optimize:
optimize_png_speed: 10
```
A factor of `10` has 5% lower quality, but is 8x faster than the default `4`.
[`optimize_png_strip`](#+optimize.optimize_png_strip){ #+optimize.optimize_png_strip }
: :octicons-milestone-24: Default: `true` – This option specifies whether
[pngquant] should remove all non-optional metadata that is not necessary
for rendering images in a browser:
``` yaml
plugins:
- optimize:
optimize_png_strip: false
```
[`optimize_jpg`](#+optimize.optimize_jpg){ #+optimize.optimize_jpg }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin should optimize JPG files using [Pillow], a Python image
processing library. JPG optimization can be disabled with:
``` yaml
plugins:
- optimize:
optimize_jpg: false
```
[`optimize_jpg_quality`](#+optimize.optimize_jpg_quality){ #+optimize.optimize_jpg_quality }
: :octicons-milestone-24: Default: `60` of `[0,100]` – This option specifies
the image quality that [Pillow] uses when compressing. If the images look
blurry, it's a good idea to tune and change this setting:
``` yaml
plugins:
- optimize:
optimize_jpg_quality: 75
```
[`optimize_jpg_progressive`](#+optimize.optimize_jpg_progressive){ #+optimize.optimize_jpg_progressive }
: :octicons-milestone-24: Default: `true` – This option specifies whether
[Pillow] should use [progressive encoding] (faster rendering) when
compressing JPGs. Progressive encoding can be disabled with:
``` yaml
plugins:
- optimize:
optimize_jpg_progressive: false
```
[Insiders]: ../insiders/index.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[dependencies for image processing]: dependencies/image-processing.md
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[pngquant]: https://pngquant.org/
[Pillow]: https://pillow.readthedocs.io/
[progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
#### Caching
The [built-in optimize plugin] implements an intelligent caching mechanism,
ensuring that media files are only pushed through the optimization pipeline when
their contents change. If you swap out or update an image, the plugin will
detect it and update the optimized version.
The following configuration options are available for caching:
[`cache`](#+optimize.cache){ #+optimize.cache }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin queries its cache for an existing artifact before starting an
optimization job. It's normally not necessary to change this setting,
except for when debugging the plugin itself. Caching can be disabled with:
``` yaml
plugins:
- optimize:
cache: false
```
[`cache_dir`](#+optimize.cache_dir){ #+optimize.cache_dir }
: :octicons-milestone-24: Default: `.cache/plugins/optimize` – This option
specifies the file system location of the plugin's cache. It's normally not
necessary to change this setting, except for when debugging the plugin
itself. The cache directory can be changed with:
``` yaml
plugins:
- optimize:
cache_dir: .cache/plugins/optimize
```
By default, all built-in plugins that implement caching will create a
`.cache` directory in the same folder your `mkdocs.yml` resides, and create
subfolders to not interfere with each other. If you use multiple instances
of this plugin, it could be necessary to change this setting.
[optimize]: ../plugins/optimize.md

32
docs/setup/building-for-offline-usage.md
View File

@@ -11,8 +11,8 @@ support for many of its features.
### Built-in offline plugin
[:octicons-tag-24: 9.0.0][offline support] ·
:octicons-cpu-24: Plugin
<!-- md:version 9.0.0 -->
<!-- md:plugin [offline] – built-in -->
The built-in offline plugin makes sure that the [site search] works when you
distribute the contents of your [site directory] as a download. Simply add
@@ -23,27 +23,10 @@ plugins:
- offline
```
The plugin will automatically disable the [`use_directory_urls`][use_directory_urls]
setting, ensuring that users can open your documentation directly from the local
file system.
For a list of all settings, please consult the [plugin documentation].
The following configuration options are available:
[`enabled`](#+offline.enabled){ #+offline.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, e.g. for local builds, use an [environment variable]:
``` yaml
plugins:
- offline:
enabled: !ENV [OFFLINE, false]
```
Now, after invoking `mkdocs build`, you can open `site/index.html` directly
in your browser and the [site search] will work as if the documentation was
hosted on a regular server.
[offline]: ../plugins/offline.md
[plugin documentation]: ../plugins/offline.md
!!! tip "Automatically bundle all external assets"
@@ -51,12 +34,9 @@ hosted on a regular server.
while building documentation for offline usage, as it will automatically
download all external assets to distribute them with your documentation.
[offline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
[site search]: setting-up-site-search.md
[site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
[use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
[built-in privacy plugin]:../plugins/privacy.md
#### Limitations

53
docs/setup/changing-the-colors.md
View File

@@ -1,7 +1,7 @@
# Changing the colors
As any proper Material Design implementation, Material for MkDocs supports
Google's original [color palette], which can be easily configured through
Google's original [color palette], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][custom colors].
@@ -14,8 +14,8 @@ fit your brand's identity by using [CSS variables][custom colors].
#### Color scheme
[:octicons-tag-24: 5.2.0][Color scheme support] ·
:octicons-milestone-24: Default: `default`
<!-- md:version 5.2.0 -->
<!-- md:default `default` -->
Material for MkDocs supports two color schemes: a __light mode__, which is just
called `default`, and a __dark mode__, which is called `slate`. The color scheme
@@ -50,12 +50,10 @@ Click on a tile to change the color scheme:
})
</script>
[Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color
[:octicons-tag-24: 0.2.0][Primary color support] ·
:octicons-milestone-24: Default: `indigo`
<!-- md:version 0.2.0 -->
<!-- md:default `indigo` -->
The primary color is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
@@ -107,12 +105,10 @@ Click on a tile to change the primary color:
See our guide below to learn how to set [custom colors].
[Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color
[:octicons-tag-24: 0.2.0][Accent color support] ·
:octicons-milestone-24: Default: `indigo`
<!-- md:version 0.2.0 -->
<!-- md:default `indigo` -->
The accent color is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
@@ -166,12 +162,11 @@ Click on a tile to change the accent color:
See our guide below to learn how to set [custom colors].
[Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
### Color palette toggle
[:octicons-tag-24: 7.1.0][Color palette toggle support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 7.1.0 -->
<!-- md:default none -->
<!-- md:example color-palette-toggle -->
Offering a light _and_ dark color palette makes your documentation pleasant to
read at different times of the day, so the user can choose accordingly. Add the
@@ -213,9 +208,9 @@ and [`accent`][palette.accent] per color palette.
The following properties must be set for each toggle:
[`icon`](#+palette.toggle.icon){ #+palette.toggle.icon }
<!-- md:option palette.toggle.icon -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property must point to a valid icon path referencing any icon bundled
with the theme, or the build will not succeed. Some popular combinations:
@@ -225,13 +220,12 @@ The following properties must be set for each toggle:
* :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
* :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
[`name`](#+palette.toggle.name){ #+palette.toggle.name }
<!-- md:option palette.toggle.name -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property is used as the toggle's `title` attribute and should be set to
a discernable name to improve accessibility. It's rendered as a [tooltip].
[Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[palette.scheme]: #color-scheme
[palette.primary]: #primary-color
[palette.accent]: #accent-color
@@ -240,8 +234,9 @@ The following properties must be set for each toggle:
### System preference
[:octicons-tag-24: 7.1.0][System preference support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 7.1.0 -->
<!-- md:default none -->
<!-- md:example color-palette-system-preference -->
Each color palette can be linked to the user's system preference for light and
dark appearance by using a media query. Simply add a `media` property next to
@@ -270,13 +265,12 @@ When the user first visits your site, the media queries are evaluated in the
order of their definition. The first media query that matches selects the
default color palette.
[System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
#### Automatic light / dark mode
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.18.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.18.0 -->
<!-- md:flag experimental -->
<!-- md:example color-palette-system-preference -->
Newer operating system allow to automatically switch between light and dark
appearance during day and night times. [Insiders] adds support for automatic
@@ -322,6 +316,9 @@ reload the site.
### Custom colors
<!-- md:version 5.0.0 -->
<!-- md:example custom-colors -->
Material for MkDocs implements colors using [CSS variables] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional style sheet] and
@@ -361,7 +358,7 @@ add:
See the file containing the [color definitions] for a list of all CSS variables.
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
[additional style sheet]: ../customization.md#additional-css

18
docs/setup/changing-the-fonts.md
View File

@@ -11,8 +11,8 @@ or another destination should be used.
### Regular font
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto`][Roboto]
<!-- md:version 0.1.2 -->
<!-- md:default [`Roboto`][Roboto] -->
The regular font is used for all body copy, headlines, and essentially
everything that does not need to be monospaced. It can be set to any
@@ -27,12 +27,11 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[Roboto]: https://fonts.google.com/specimen/Roboto
[Font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font
[:octicons-tag-24: 0.1.2][Font support] ·
:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
<!-- md:version 0.1.2 -->
<!-- md:default [`Roboto Mono`][Roboto Mono] -->
The _monospaced font_ is used for code blocks and can be configured separately.
Just like the regular font, it can be set to any valid [Google Font]
@@ -50,8 +49,8 @@ The typeface will be loaded in 400.
### Autoloading
[:octicons-tag-24: 1.0.0][Autoloading support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 1.0.0 -->
<!-- md:default none -->
If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
to adhere to [data privacy] regulations, and fall back to system fonts, add the
@@ -69,8 +68,7 @@ theme:
by automatically downloading and self-hosting the web font files.
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
[Autoloading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
[built-in privacy plugin]:../plugins/privacy.md
## Customization
@@ -96,7 +94,7 @@ corresponding `@font-face` definition:
- stylesheets/extra.css
```
The font can then be applied to specific elements, e.g. only headlines, or
The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or monospaced font:
=== "Regular font"

38
docs/setup/changing-the-language.md
View File

@@ -9,8 +9,8 @@ available.
### Site language
[:octicons-tag-24: 1.12.0][Site language support] ·
:octicons-milestone-24: Default: `en`
<!-- md:version 1.12.0 -->
<!-- md:default `en` -->
You can set the site language in `mkdocs.yml` with:
@@ -37,11 +37,10 @@ the default slug function works. Consider using a [Unicode-aware slug function].
!!! tip "Translations missing? Help us out, it takes only 5 minutes"
Material for MkDocs relies on outside contributions for adding and updating
translations for the almost 60 languages it supports. If your language shows
that some translations are missing, click on the link to add them. If your
language is not in the list, click here to [add a new language].
translations for the more than 60 languages it supports. If your language
shows that some translations are missing, click on the link to add them. If
your language is not in the list, click here to [add a new language].
[Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
[language selector]: #site-language-selector
[Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify
@@ -49,8 +48,8 @@ the default slug function works. Consider using a [Unicode-aware slug function].
### Site language selector
[:octicons-tag-24: 7.0.0][Site language selector support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 7.0.0 -->
<!-- md:default none -->
If your documentation is available in multiple languages, a language selector
pointing to those languages can be added to the header. Alternate languages
@@ -73,36 +72,35 @@ extra:
The following properties are available for each alternate language:
[`name`](#+alternate.name){ #+alternate.name }
<!-- md:option alternate.name -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This value of this property is used inside the language selector as the
name of the language and must be set to a non-empty string.
[`link`](#+alternate.link){ #+alternate.link }
<!-- md:option alternate.link -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs.
[`lang`](#+alternate.lang){ #+alternate.lang }
<!-- md:option alternate.lang -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property must contain an [ISO 639-1 language code] and is used for
the `hreflang` attribute of the link, improving discoverability via search
engines.
[![Language selector preview]][Language selector preview]
[Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[Language selector preview]: ../assets/screenshots/language-selection.png
### Directionality
[:octicons-tag-24: 2.5.0][Directionality support] ·
:octicons-milestone-24: Default: _automatically set_
<!-- md:version 2.5.0 -->
<!-- md:default computed -->
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) directionality which is deduced from the
@@ -132,8 +130,6 @@ Click on a tile to change the directionality:
})
</script>
[Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
## Customization
### Custom translations
@@ -176,5 +172,5 @@ adjust the ones you want to override:
```
[theme extension]: ../customization.md#extending-the-theme
[translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
[list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
[translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
[list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/

55
docs/setup/changing-the-logo-and-icons.md
View File

@@ -1,7 +1,7 @@
# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 8,000
icons_ ready to be used for customization of specific parts of the theme and/or
When installing Material for MkDocs, you immediately get access to _over 8,000
icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also add
[additional icons] with minimal effort.
@@ -11,8 +11,8 @@ when writing your documentation in Markdown. Not enough? You can also add
### Logo
[:octicons-tag-24: 0.1.0][Logo support] ·
:octicons-milestone-24: Default: :material-library: – `material/library`
<!-- md:version 0.1.0 -->
<!-- md:default `material/library` -->
The logo can be changed to a user-provided image (any type, incl. `*.png` and
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
@@ -44,7 +44,6 @@ Add the following lines to `mkdocs.yml`:
</div>
</div>
[Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
Normally, the logo in the header and sidebar links to the homepage of the
@@ -58,10 +57,10 @@ extra:
### Favicon
[:octicons-tag-24: 0.1.0][Favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
<!-- md:version 0.1.0 -->
<!-- md:default [`assets/images/favicon.png`][Favicon default] -->
The favicon can be changed to a path pointing to a user-provided image, which
The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml
@@ -69,9 +68,43 @@ theme:
favicon: images/favicon.png
```
[Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
### Site icons
[:octicons-tag-24: 9.2.0][Site icon support]
Most icons you see on your site, such as navigation icons, can also be changed. For example,
to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
```yaml
theme:
icon:
previous: fontawesome/solid/angle-left
next: fontawesome/solid/angle-right
```
The following is a complete list of customizable icons used by the theme:
| Icon name | Purpose |
|:-------------|:------------------------------------------------------------------------------|
| `logo` | See [Logo](#logo) |
| `menu` | Open drawer |
| `alternate` | Change language |
| `search` | Search icon |
| `share` | Share search |
| `close` | Reset search, dismiss announcements |
| `top` | Back-to-top button |
| `edit` | Edit current page |
| `view` | View page source |
| `repo` | Repository icon |
| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons) |
| `tag` | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
| `previous` | Previous page in footer, hide search on mobile |
| `next` | Next page in footer |
[Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
## Customization
### Additional icons
@@ -96,8 +129,8 @@ Then, add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
options:
custom_icons:
- overrides/.icons

352
docs/setup/ensuring-data-privacy.md
View File

@@ -1,6 +1,6 @@
# Ensuring data privacy
Material for MkDocs makes compliance with data privacy regulations very easy,
Material for MkDocs makes compliance with data privacy regulations very easy,
as it offers a native [cookie consent] solution to seek explicit consent from
users before setting up [analytics]. Additionally, external assets can be
automatically downloaded for [self-hosting].
@@ -13,9 +13,10 @@ automatically downloaded for [self-hosting].
### Cookie consent
[:octicons-tag-24: 8.4.0][Cookie consent support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
<!-- md:version 8.4.0 -->
<!-- md:default none -->
<!-- md:flag experimental -->
<!-- md:example cookie-consent -->
Material for MkDocs ships a native and extensible cookie consent form which
asks the user for consent prior to sending requests to third parties. Add the
@@ -37,21 +38,21 @@ extra:
The following properties are available:
[`title`](#+consent.title){ #+consent.title }
<!-- md:option consent.title -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
This property sets the title of the cookie consent, which is rendered at the
: <!-- md:default none --> <!-- md:flag required -->
This property sets the title of the cookie consent, which is rendered at the
top of the form and must be set to a non-empty string.
[`description`](#+consent.description){ #+consent.description }
<!-- md:option consent.description -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
: <!-- md:default none --> <!-- md:flag required -->
This property sets the description of the cookie consent, is rendered below
the title, and may include raw HTML (e.g. a links to the terms of service).
[`cookies`](#+consent.cookies){ #+consent.cookies }
<!-- md:option consent.cookies -->
: :octicons-milestone-24: Default: _none_ – This property allows to add custom
: <!-- md:default none --> This property allows to add custom
cookies or change the initial `checked` state and name of built-in cookies.
Currently, the following cookies are built-in:
@@ -100,10 +101,10 @@ The following properties are available:
automatically include a setting for the user to disable it. [Custom cookies]
can be used from JavaScript.
[`actions`](#+consent.actions){ #+consent.actions }
<!-- md:option consent.actions -->
: :octicons-milestone-24: Default: `[accept, manage]` – This property defines
which buttons are shown and in which order, e.g. to allow the user to accept
: <!-- md:default `[accept, manage]` --> This property defines
which buttons are shown and in which order, e.g. to allow the user to accept
cookies and manage settings:
``` yaml
@@ -128,13 +129,12 @@ When a user first visits your site, a cookie consent form is rendered:
[![Cookie consent enabled]][Cookie consent enabled]
[Custom cookies]: #custom-cookies
[Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[Cookie consent enabled]: ../assets/screenshots/consent.png
#### Change cookie settings
In order to comply with GDPR, users must be able to change their cookie settings
at any time. This can be done by adding a simple link to your [copyright notice]
at any time. This can be done by adding a simple link to your [copyright notice]
in `mkdocs.yml`:
``` yaml
@@ -147,12 +147,12 @@ copyright: >
### Built-in privacy plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.9.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.9.0 -->
<!-- md:plugin [privacy][built-in privacy plugin] -->
<!-- md:flag experimental -->
The built-in privacy plugin automatically identifies [external assets] as part
The built-in privacy plugin automatically identifies external assets as part
of the build process and downloads all assets for very simple self-hosting. Add
the following lines to `mkdocs.yml`:
@@ -161,254 +161,52 @@ plugins:
- privacy
```
> If you need to be able to build your documentation with and without
> [Insiders], please refer to the [built-in plugins] section to learn how
> shared configurations help to achieve this.
For a list of all settings, please consult the [plugin documentation].
The following configuration options are available:
[plugin documentation]: ../plugins/privacy.md
[`enabled`](#+privacy.enabled){ #+privacy.enabled }
!!! tip "Hosting images externally and optimizing them automatically"
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
This option makes the [built-in privacy plugin] an excellent choice for
when you want to host assets like images outside of your git repository
in another location to keep them fresh and your repository lean.
``` yaml
plugins:
- privacy:
enabled: !ENV [CI, false]
```
Additionally, as of <!-- md:version insiders-4.30.0 -->, the
built-in privacy plugin was entirely rewritten and now works perfectly
with the [built-in optimize plugin], which means that external assets
can be passed through the same optimization pipeline as the rest of your
documentation. This means you can store and edit unoptimized files
outside of your repository, and let both plugins built a highly
optimized site for you.
[`concurrency`](#+privacy.concurrency){ #+privacy.concurrency }
: :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
how many CPUs the plugin is allowed to use when downloading external assets.
With more CPUs, the plugin can do more work in the same time, thus complete
its work faster. Concurrent processing can be disabled with:
``` yaml
plugins:
- privacy:
concurrency: 1
```
[Insiders]: ../insiders/index.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
#### External assets
The following configuration options are available for external assets:
[`assets`](#+privacy.assets){ #+privacy.assets }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should scan the HTML output to detect and process external assets:
``` yaml
plugins:
- privacy:
assets: true
```
If you've removed all external assets from your project via [customization],
it's still a good idea to enable the plugin, as the plugin will make sure
that there are no hidden external links in any Markdown files that were
unintentionally added.
Using `assets` in [strict mode] will make the build fail when external
assets are detected.
[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should download external assets it encountered and bundle them with
your documentation:
``` yaml
plugins:
- privacy:
assets_fetch: true
```
[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
: :octicons-milestone-24: Default: `assets/external` – This option
specifies where the downloaded [external assets] will be stored. It's
normally not necessary to change this option:
``` yaml
plugins:
- privacy:
assets_fetch_dir: assets/external
```
The path must be defined relative to [`docs_dir`][docs_dir].
[`assets_include`](#+privacy.assets_include){ #+privacy.assets_include }
: :octicons-milestone-24: Default: _none_ – This option allows to only include
certain external assets for processing by the privacy plugin, so they will
be downloaded and bundled during the build:
``` yaml
plugins:
- privacy:
assets_include:
- unsplash.com/*
```
!!! tip "Hosting images externally and optimizing them automatically"
This option makes the [built-in privacy plugin] an excellent choice for
when you want to host assets like images outside of your git repository
in another location to keep them fresh and your repository lean.
Additionally, as of [:octicons-tag-24: insiders-4.30.0][Insiders], the
built-in privacy plugin was entirely rewritten and now works perfectly
with the [built-in optimize plugin], which means that external assets
can be passed through the same optimization pipeline as the rest of your
documentation. This means you can store and edit unoptimized files
outside of your repository, and let both plugins built a highly
optimized site for you.
If you want to implement separate pipelines, i.e., optimize some images
differently from others or exclude some images from downloading, you can
use multiple instances of the [built-in privacy plugin].
[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
: :octicons-milestone-24: Default: _none_ – This option allows to exclude
certain external assets from processing by the privacy plugin, so they will
not be downloaded and bundled during the build:
``` yaml
plugins:
- privacy:
assets_exclude: # (1)!
- cdn.jsdelivr.net/npm/mathjax@3/*
- giscus.app/*
```
1. [MathJax] loads web fonts for typesetting of mathematical content
through relative URLs, and thus cannot be automatically bundled by the
privacy plugin. [MathJax can be self-hosted].
Giscus, which we recommend to use as a [comment system], uses a technique
called code-splitting to load only the code that is necessary, which
is implemented via relative URLs. [Giscus can be self-hosted] as well.
Excluding specific external assets can be necessary if they contain
dynamically created or relative URLs, which can't be resolved by the privacy
plugin due to [technical limitations].
If you want to implement separate pipelines, i.e., optimize some images
differently from others or exclude some images from downloading, you can
use multiple instances of the [built-in privacy plugin].
!!! question "Why can't Material for MkDocs bundle all assets by design?"
The primary reason why Material for MkDocs can't just bundle all of its own
assets is the integration with [Google Fonts], which offers over a thousand
different fonts that can be used to render your documentation. Most of the
fonts include several weights and are split up into different character sets
fonts include several weights and are split up into different character sets
to keep the download size small, so the browser only downloads what is
really needed. For Roboto, our default [regular font], this results in [42
`*.woff2` files in total][example].
If Material for MkDocs would bundle all font files, the download size would
be in the hundreds of megabytes, slowing down automated builds. Furthermore,
authors might add external assets like third-party scripts or style sheets
be in the hundreds of megabytes, slowing down automated builds. Furthermore,
authors might add external assets like third-party scripts or style sheets
that would need to be remembered to be defined as further local assets.
This is the very reason the [built-in privacy plugin] exists — it automates
the process of downloading all external assets manually to ensure compliance
with GDPR with some some [technical limitations].
[customization]: ../customization.md
[strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[MathJax]: ../reference/math.md
[MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
[Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
[comment system]: adding-a-comment-system.md
[external assets]: #how-it-works
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[Google Fonts]: changing-the-fonts.md
[regular font]: changing-the-fonts.md#regular-font
[example]: #example
[technical limitations]: #limitations
[built-in optimize plugin]: building-an-optimized-site.md#built-in-optimize-plugin
[built-in optimize plugin]: ../plugins/optimize.md
#### External links
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.26.0][Insiders] ·
:octicons-beaker-24: Experimental
The following configuration options are available for external links:
[`links`](#+privacy.links){ #+privacy.links }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should parse and process external links. If you want to speed up
local builds, you can use an [environment variable]:
``` yaml
plugins:
- privacy:
links: !ENV [CI, false]
```
[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
: :octicons-milestone-24: Default: _None_ – This option specifies custom
attributes that should be added to external links, like for example
`target="_blank"` so all external links open in a new window:
``` yaml
plugins:
- privacy:
links_attr_map:
target: _blank
```
[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
: :octicons-milestone-24: Default: `true` – This option specifies whether the
plugin should automatically add [`rel="noopener"`][noopener] to all links
with `target="_blank"` for security reasons:
``` yaml
plugins:
- privacy:
links_noopener: true
```
[noopener]: https://mathiasbynens.github.io/rel-noopener/
#### How it works
The [built-in privacy plugin] scans the resulting HTML for links to external
resources, including external scripts, style sheets, images and web fonts, and
downloads them to bundle them with your documentation site. Every URL referring
to an external resource, no matter if part of a template or Markdown file, is
then replaced with the URL to the local copy. An example:
``` html
<script src="https://example.com/script.js"></script>
```
The external script is downloaded, and the link is replaced with:
``` html
<script src="assets/external/example.com/script.js"></script>
```
Style sheets are scanned for external `url(...)` references, e.g. images and
web fonts, which are then also downloaded and bundled with your documentation
site. This means that [Google Fonts] can be configured in `mkdocs.yml` as usual,
as the [built-in privacy plugin] automatically downloads and bundles all
dependent resources.
As a third measure, [`preconnect`][preconnect] hints used for DNS pre-fetching
which might also leak the visitors IP address to a third party are automatically
removed during the build process.
??? example "Expand to inspect example"
@@ -480,72 +278,16 @@ removed during the build process.
└─ polyfill.io/v3/polyfill.min.js
```
[built-in privacy plugin]: #built-in-privacy-plugin
[built-in privacy plugin]: ../plugins/privacy.md
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
All downloaded files are written to the `.cache` directory, significantly
reducing the duration of subsequent builds as only replacements need to be
carried out. You might want to:
1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
2. When building your site for publishing, use a build cache to save the
`.cache` directory in between builds. Taking the example from the
[publishing guide], add the following lines:
``` yaml hl_lines="15-21"
name: ci
on:
push:
branches:
- master
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v3
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
```
[publishing guide]: ../publishing-your-site.md#with-github-actions
#### Limitations
Note that dynamically created URLs as part of scripts are not detected, and thus
cannot be automatically downloaded. The [built-in privacy plugin] does not
execute scripts – it can only detect fully qualified URLs to download and
replace.
In short, don't do this:
``` js
const cdn = "https://polyfill.io"
const url = `${cdn}/v3/polyfill.min.js`
```
Instead, always use fully qualified URLs:
``` js
const url ="https://polyfill.io/v3/polyfill.min.js"
```
## Customization
### Custom cookies
<!-- md:version 8.4.0 -->
<!-- md:example custom-cookies -->
If you've customized the [cookie consent] and added a `custom` cookie, the user
will be prompted to accept or reject your custom cookie. Once the user accepts
or rejects the cookie consent, or [changes the settings], the page reloads[^1].

10
docs/setup/extensions/index.md
View File

@@ -15,7 +15,7 @@ syntax extensions for technical writing.
## Supported extensions
The following extensions are all supported by Material for MkDocs and therefore
The following extensions are all supported by Material for MkDocs and therefore
strongly recommended. Click on each extension to learn about its purpose and
configuration:
@@ -77,8 +77,8 @@ your documentation project.
### Minimal configuration
This configuration is a good starting point for when you're using Material for
MkDocs for the first time. The best idea is to explore the [reference], and
This configuration is a good starting point for when you're using Material for
MkDocs for the first time. The best idea is to explore the [reference], and
gradually add what you want to use:
``` yaml
@@ -121,8 +121,8 @@ markdown_extensions:
- pymdownx.caret
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys

197
docs/setup/extensions/python-markdown-extensions.md
View File

@@ -15,8 +15,8 @@ are natively supported, meaning they work without any further adjustments.
### Arithmatex
[:octicons-tag-24: 1.0.0][Arithmatex support] ·
[:octicons-workflow-24: Extension][Arithmatex]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.arithmatex][Arithmatex] -->
The [Arithmatex] extension allows for rendering of block and inline block
equations and integrates seamlessly with [MathJax][^1] – a library for
@@ -33,7 +33,7 @@ markdown_extensions:
generic: true
```
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with a few lines
of [additional JavaScript]:
@@ -77,7 +77,6 @@ See reference for usage:
- [Using inline block syntax]
[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
[MathJax]: https://www.mathjax.org/
[KaTeX]: https://github.com/Khan/KaTeX
@@ -87,8 +86,8 @@ See reference for usage:
### BetterEm
[:octicons-tag-24: 0.1.0][BetterEm support] ·
[:octicons-workflow-24: Extension][BetterEm]
<!-- md:version 0.1.0 -->
<!-- md:extension [pymdownx.betterem][BetterEm] -->
The [BetterEm] extension improves the detection of Markup to emphasize text
in Markdown using special characters, i.e. for `**bold**` and `_italic_`
@@ -100,16 +99,15 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
documentation][BetterEm] for more information.
[BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
[BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Caret, Mark & Tilde
[:octicons-tag-24: 1.0.0][Caret support] ·
[:octicons-workflow-24: Extension][Caret]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.caret][Caret] -->
The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
and define sub- and superscript using a simple syntax. Enable them together
@@ -132,7 +130,6 @@ See reference for usage:
- [Sub- and superscripts]
[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
[Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
[Highlighting text]: ../../reference/formatting.md#highlighting-text
@@ -140,8 +137,8 @@ See reference for usage:
### Critic
[:octicons-tag-24: 1.0.0][Critic support] ·
[:octicons-workflow-24: Extension][Critic]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.critic][Critic] -->
The [Critic] extension allows for the usage of [Critic Markup] to highlight
added, deleted or updated sections in a document, i.e. for tracking changes in
@@ -154,9 +151,9 @@ markdown_extensions:
The following configuration options are supported:
[`mode`](#+pymdownx.critic.mode){ #+pymdownx.critic.mode }
<!-- md:option pymdownx.critic.mode -->
: :octicons-milestone-24: Default: `view` – This option defines how the markup
: <!-- md:default `view` --> This option defines how the markup
should be parsed, i.e. whether to just `view` all suggested changes, or
alternatively `accept` or `reject` them:
@@ -189,14 +186,13 @@ See reference for usage:
- [Highlighting changes]
[Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
[Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
[Highlighting changes]: ../../reference/formatting.md#highlighting-changes
### Details
[:octicons-tag-24: 1.9.0][Details support] ·
[:octicons-workflow-24: Extension][Details]
<!-- md:version 1.9.0 -->
<!-- md:extension [pymdownx.details][Details] -->
The [Details] extension supercharges the [Admonition] extension, making the
resulting _call-outs_ collapsible, allowing them to be opened and closed by the
@@ -212,14 +208,13 @@ No configuration options are available. See reference for usage:
- [Collapsible blocks]
[Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
[Admonition]: python-markdown.md#admonition
[Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
### Emoji
[:octicons-tag-24: 1.0.0][Emoji support] ·
[:octicons-workflow-24: Extension][Emoji]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.emoji][Emoji] -->
The [Emoji] extension automatically inlines bundled and custom icons and emojis
in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
@@ -227,8 +222,8 @@ in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji # (1)!
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
emoji_generator: !!python/name:material.extensions.emoji.to_svg
```
1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
@@ -237,41 +232,41 @@ markdown_extensions:
The following configuration options are supported:
[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index }
<!-- md:option pymdownx.emoji.emoji_index -->
: :octicons-milestone-24: Default: `emojione` – This option defines which set
: <!-- md:default `emojione` --> This option defines which set
of emojis is used for rendering. Note that the use of `emojione` is not
recommended due to [restrictions in licensing][Emoji index]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_index: !!python/name:material.extensions.emoji.twemoji
```
[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator }
<!-- md:option pymdownx.emoji.emoji_generator -->
: :octicons-milestone-24: Default: `to_png` – This option defines how the
: <!-- md:default `to_png` --> This option defines how the
resolved emoji or icon shortcode is render. Note that icons can only be
used together with the `to_svg` configuration:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_generator: !!python/name:material.extensions.emoji.to_svg
```
[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons }
<!-- md:option pymdownx.emoji.options.custom_icons -->
: :octicons-milestone-24: Default: _none_ – This option allows to list folders
with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
: <!-- md:default none --> This option allows to list folders
with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
explained in more detail in the [icon customization guide]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
options:
custom_icons:
- overrides/.icons
@@ -288,7 +283,6 @@ See reference for usage:
- [Using icons in templates]
[Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
[icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
[Using emojis]: ../../reference/icons-emojis.md#using-emojis
@@ -297,9 +291,8 @@ See reference for usage:
### Highlight
[:octicons-tag-24: 5.0.0][Highlight support] ·
[:octicons-workflow-24: Extension][Highlight] ·
:octicons-zap-24: Supersedes [CodeHilite]
<!-- md:version 5.0.0 -->
<!-- md:extension [pymdownx.highlight][Highlight] -->
The [Highlight] extension adds support for syntax highlighting of code blocks
(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
@@ -319,9 +312,9 @@ markdown_extensions:
The following configuration options are supported:
[`use_pygments`](#+pymdownx.highlight.use_pygments){ #+pymdownx.highlight.use_pygments }
<!-- md:option pymdownx.highlight.use_pygments -->
: :octicons-milestone-24: Default: `true` – This option allows to control
: <!-- md:default `true` --> This option allows to control
whether highlighting should be carried out during build time using
[Pygments] or in the browser with a JavaScript syntax highlighter:
@@ -342,7 +335,7 @@ The following configuration options are supported:
use_pygments: false
```
As an example, [Highlight.js], a JavaScript syntax highlighter, can be
As an example, [Highlight.js], a JavaScript syntax highlighter, can be
integrated with some [additional JavaScript] and an [additional style
sheet] in `mkdocs.yml`:
@@ -371,9 +364,9 @@ The following configuration options are supported:
syntax highlighting using [Pygments], so they don't apply if `use_pygments`
is set to `false`.
[`pygments_lang_class`](#+pymdownx.highlight.pygments_lang_class){ #+pymdownx.highlight.pygments_lang_class }
<!-- md:option pymdownx.highlight.pygments_lang_class -->
: :octicons-milestone-24: Default: `false` – This option instructs [Pygments]
: <!-- md:default `false` --> This option instructs [Pygments]
to add a CSS class to identify the language of the code block, which is
essential for custom annotation markers to function:
@@ -383,9 +376,9 @@ markdown_extensions:
pygments_lang_class: true
```
[`auto_title`](#+pymdownx.highlight.auto_title){ #+pymdownx.highlight.auto_title }
<!-- md:option pymdownx.highlight.auto_title -->
: :octicons-milestone-24: Default: `false` – This option will automatically
: <!-- md:default `false` --> This option will automatically
add a [title] to all code blocks that shows the name of the language being
used, e.g. `Python` is printed for a `py` block:
@@ -395,9 +388,9 @@ markdown_extensions:
auto_title: true
```
[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums }
<!-- md:option pymdownx.highlight.linenums -->
: :octicons-milestone-24: Default: `false` – This option will add line numbers
: <!-- md: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][Adding line
numbers] in the code block reference, which also contains some tips on
@@ -409,9 +402,9 @@ markdown_extensions:
linenums: true
```
[`linenums_style`](#+pymdownx.highlight.linenums_style){ #+pymdownx.highlight.linenums_style }
<!-- md:option pymdownx.highlight.linenums_style -->
: :octicons-milestone-24: Default: `table` – The [Highlight] extension
: <!-- md:default `table` --> The [Highlight] extension
provides three ways to add line numbers, two of which are supported by
Material for MkDocs. While `table` wraps a code block in a `<table>`
element, `pymdownx-inline` renders line numbers as part of the line itself:
@@ -423,13 +416,13 @@ markdown_extensions:
```
Note that `inline` will put line numbers next to the actual code, which
means that they will be included when selecting text with the cursor or
means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of either `table`
or `pymdownx-inline` is recommended.
[`anchor_linenums`](#+pymdownx.highlight.anchor_linenums){ #+pymdownx.highlight.anchor_linenums }
<!-- md:option pymdownx.highlight.anchor_linenums -->
: [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24:
: <!-- md:version 8.1.0 --> :octicons-milestone-24:
Default: `false` – If a code blocks contains line numbers, enabling this
setting will wrap them with anchor links, so they can be hyperlinked and
shared more easily:
@@ -440,9 +433,9 @@ markdown_extensions:
anchor_linenums: true
```
[`line_spans`](#+pymdownx.highlight.line_spans){ #+pymdownx.highlight.line_spans }
<!-- md:option pymdownx.highlight.line_spans -->
: :octicons-milestone-24: Default: _none_ – When this option is set, each
: <!-- md:default none --> When this option is set, each
line of a code block is wrapped in a `span`, which is essential for features
like line highlighting to work correctly:
@@ -465,7 +458,6 @@ See reference for usage:
- [Custom syntax theme]
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[CodeHilite]: python-markdown.md#codehilite
[pymdownx.superfences]: #superfences
[pymdownx.inlinehilite]: #inlinehilite
@@ -473,7 +465,6 @@ See reference for usage:
[additional style sheet]: ../../customization.md#additional-css
[Highlight.js]: https://highlightjs.org/
[title]: ../../reference/code-blocks.md#adding-a-title
[anchor_linenums support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
[Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
[Using code blocks]: ../../reference/code-blocks.md#usage
[Adding a title]: ../../reference/code-blocks.md#adding-a-title
@@ -482,10 +473,10 @@ See reference for usage:
### InlineHilite
[:octicons-tag-24: 5.0.0][InlineHilite support] ·
[:octicons-workflow-24: Extension][InlineHilite]
<!-- md:version 5.0.0 -->
<!-- md:extension [pymdownx.inlinehilite][InlineHilite] -->
The [InlineHilite] extension add support for syntax highlighting of inline code
The [InlineHilite] extension add support for syntax highlighting of inline code
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
which it sources its configuration. Enable it via `mkdocs.yml`:
@@ -497,7 +488,7 @@ markdown_extensions:
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
the [`css_class`][InlineHilite options] option, which must not be changed. See the
the [`css_class`][InlineHilite options] option, which must not be changed. See the
[InlineHilite documentation][InlineHilite] for guidance.
See reference for usage:
@@ -505,17 +496,16 @@ See reference for usage:
- [Highlighting inline code blocks]
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
[pymdownx.highlight]: #highlight
[Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
### Keys
[:octicons-tag-24: 1.0.0][Keys support] ·
[:octicons-workflow-24: Extension][Keys]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.keys][Keys] -->
The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
``` yaml
@@ -525,7 +515,7 @@ markdown_extensions:
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. The only exception is
the [`class`][Keys options] option, which must not be changed. See the
the [`class`][Keys options] option, which must not be changed. See the
[Keys documentation][Keys] for more information.
See reference for usage:
@@ -533,16 +523,15 @@ See reference for usage:
- [Adding keyboard keys]
[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
[Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
[Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
### SmartSymbols
[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
[:octicons-workflow-24: Extension][SmartSymbols]
<!-- md:version 0.1.0 -->
<!-- md:extension [pymdownx.smartsymbols][SmartSymbols] -->
The [SmartSymbols] extension converts some sequences of characters into their
The [SmartSymbols] extension converts some sequences of characters into their
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
`mkdocs.yml`:
@@ -552,16 +541,15 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
documentation][SmartSymbols] for guidance.
[SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
[SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Snippets
[:octicons-tag-24: 0.1.0][Snippets support] ·
[:octicons-workflow-24: Extension][Snippets]
<!-- md:version 0.1.0 -->
<!-- md:extension [pymdownx.snippets][Snippets] -->
The [Snippets] extension adds the ability to embed content from arbitrary files
into a document, including other documents or source files, by using a simple
@@ -573,7 +561,7 @@ markdown_extensions:
```
The configuration options of this extension are not specific to Material for
MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
documentation][Snippets] for more information.
See reference for usage:
@@ -582,15 +570,13 @@ See reference for usage:
- [Embedding external files]
[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
[Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
### SuperFences
[:octicons-tag-24: 0.1.0][SuperFences support] ·
[:octicons-workflow-24: Extension][SuperFences] ·
:octicons-zap-24: Supersedes [Fenced Code Blocks]
<!-- md:version 0.1.0 -->
<!-- md:extension [pymdownx.superfences][SuperFences] -->
The [SuperFences] extension allows for arbitrary nesting of code and content
blocks inside each other, including admonitions, tabs, lists and all other
@@ -603,9 +589,9 @@ markdown_extensions:
The following configuration options are supported:
[`custom_fences`](#+pymdownx.superfences.custom_fences){ #+pymdownx.superfences.custom_fences }
<!-- md:option pymdownx.superfences.custom_fences -->
: :octicons-milestone-24: Default: _none_ – This option allows to define a
: <!-- md:default none --> This option allows to define a
handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
diagrams to be interpreted in the browser:
@@ -638,7 +624,6 @@ See reference for usage:
- [Using entity-relationship diagrams]
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
[diagrams]: ../../reference/diagrams.md
@@ -652,8 +637,8 @@ See reference for usage:
### Tabbed
[:octicons-tag-24: 5.0.0][Tabbed support] ·
[:octicons-workflow-24: Extension][Tabbed]
<!-- md:version 5.0.0 -->
<!-- md:extension [pymdownx.tabbed][Tabbed] -->
The [Tabbed] extension allows the usage of content tabs, a simple way to group
related content and code blocks under accessible tabs. Enable it via
@@ -667,12 +652,12 @@ markdown_extensions:
The following configuration options are supported:
[`alternate_style`](#+pymdownx.tabbed.alternate_style){ #+pymdownx.tabbed.alternate_style }
<!-- md:option pymdownx.tabbed.alternate_style -->
: [:octicons-tag-24: 7.3.1][Tabbed alternate support] ·
:octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__
– This option enables the content tabs [alternate style], which has
[better behavior on mobile viewports], and is the only supported style:
: <!-- md:version 7.3.1 --> <!-- md:default `false` -->
<!-- md:flag required --> This option enables the content tabs
[alternate style], which has [better behavior on mobile viewports], and is
the only supported style:
``` yaml
markdown_extensions:
@@ -680,9 +665,21 @@ The following configuration options are supported:
alternate_style: true
```
[`slugify`](#+pymdownx.tabbed.slugify){ #+pymdownx.tabbed.slugify }
<!-- md:option pymdownx.tabbed.combine_header_slug -->
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
: <!-- md:default `false` --> This option enables the content tabs
[combine_header_slug style] flag, which prepends the id of the header to
the id of the tab:
``` yaml
markdown_extensions:
- pymdownx.tabbed:
combine_header_slug: true
```
<!-- md:option pymdownx.tabbed.slugify -->
: <!-- md:default `toc.slugify` --> This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][Slugs]:
@@ -716,9 +713,8 @@ See reference for usage:
- [Embedded content]
[Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
[combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
[Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
@@ -727,8 +723,8 @@ See reference for usage:
### Tasklist
[:octicons-tag-24: 1.0.0][Tasklist support] ·
[:octicons-workflow-24: Extension][Tasklist]
<!-- md:version 1.0.0 -->
<!-- md:extension [pymdownx.tasklist][Tasklist] -->
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Tasklist specification], following the same syntactical
@@ -742,10 +738,10 @@ markdown_extensions:
The following configuration options are supported:
[`custom_checkbox`](#+pymdownx.tasklist.custom_checkbox){ #+pymdownx.tasklist.custom_checkbox }
<!-- md:option pymdownx.tasklist.custom_checkbox -->
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
: <!-- md:default `false` --> This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore recommended:
``` yaml
@@ -754,10 +750,10 @@ The following configuration options are supported:
custom_checkbox: true
```
[`clickable_checkbox`](#+pymdownx.tasklist.clickable_checkbox){ #+pymdownx.tasklist.clickable_checkbox }
<!-- md:option pymdownx.tasklist.clickable_checkbox -->
: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
: <!-- md:default `false` --> This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:
``` yaml
@@ -775,7 +771,6 @@ See reference for usage:
- [Using task lists]
[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[GitHub Flavored Markdown]: https://github.github.com/gfm/
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists

Some files were not shown because too many files have changed in this diff Show More