1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Restructured documentation (#5692)

This commit is contained in:
Martin Donath 2023-09-14 19:09:18 +02:00 committed by GitHub
parent 19437db8fc
commit cd008fdf29
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
83 changed files with 6877 additions and 3354 deletions

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

View File

@ -60,11 +60,8 @@ RUN \
pip install --no-cache-dir . \
&& \
if [ "${WITH_PLUGINS}" = "true" ]; then \
pip install --no-cache-dir \
"mkdocs-minify-plugin~=0.7" \
"mkdocs-redirects~=1.2" \
"pillow~=9.4" \
"cairosvg~=2.6"; \
pip install --no-cache-dir mkdocs-material[recommended] \
pip install --no-cache-dir mkdocs-material[imaging]; \
fi \
&& \
if [ -e user-requirements.txt ]; then \

View File

@ -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.

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.
@ -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].

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

View File

@ -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.

View File

@ -64,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 -->.

View File

@ -148,7 +148,7 @@ 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
@ -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 }
---
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
@ -259,7 +259,7 @@ automatically upload it to GitHub.
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.
@ -301,7 +301,7 @@ only relevant when the bug you are reporting does not involve a crash when
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
and have worked to the best of your knowledge to provide us with everything we
need to know to help you.
__We'll take it from here.__

67
docs/conventions.md Normal file
View File

@ -0,0 +1,67 @@
# 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: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 the ymight
(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: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

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:

View File

@ -225,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

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
@ -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

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
@ -155,7 +155,33 @@ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-materi
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.
that allows to conditionally load plugins:
``` yaml
plugins:
- search
- social
# CI=1 mkdocs build
- group:
enabled: !ENV CI
plugins:
- git-revision-date-localized
- git-committers
# INSIDERS=1 mkdocs build
- group:
enabled: !ENV INSIDERS
plugins:
- optimize
- privacy
```
Of course, you can also enable both groups with:
```
CI=1 INSIDERS=1 mkdocs build
```
[^1]:
Previously we recommended to use [configuration inheritance] to work around
@ -164,63 +190,5 @@ that allows to conditionally load plugins.
your project with the community edition and Insiders version of Material
for MkDocs.
[built-in group plugin]: #built-in-group-plugin
[built-in group plugin]: ../plugins/group.md
[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
### Built-in group plugin
[:octicons-tag-24: 9.3.0][Group plugin support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
The built-in group plugin adds support for conditionally loading plugins based
on environments. This makes enabling and disabling of multiple plugins much
simpler, as you can group them into logical units and enable or disable them
with an [environment variable]:
``` yaml
plugins:
- group:
enabled: !ENV CI
plugins:
- optimize
- minify
```
[`enabled`](#+group.enabled){ #+group.enabled }
: :octicons-milestone-24: Default: `false` This option specifies whether
the plugin is enabled when building your project. By default, the plugin is
disabled, so you can use an [environment variable]:
``` yaml
plugins:
- group:
enabled: !ENV CI
```
Now, If you invoke MkDocs with that environment variable (or export the
environment variable before invoking MkDocs), the plugin will be enabled:
``` sh
CI=true mkdocs build
```
[`plugins`](#+group.plugins){ #+group.plugins }
: :octicons-milestone-24: Default: _none_ This option specifies the plugins
that the group plugin should load when enabled. Note that the plugins must
be specified as a list, even if there's only one plugin:
``` yaml
plugins:
- group:
plugins:
- optimize
- minify
```
The syntax is exactly the same as for all other plugins.
[Group plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.3.0
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables

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

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 file 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"
```

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

@ -0,0 +1,264 @@
---
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.
### 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.

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

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]: ../../setup/building-an-optimized-site.md#built-in-optimize-plugin
[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

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

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
@ -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

View File

@ -33,7 +33,7 @@ See additional configuration options:
### Annotation icons
[:octicons-tag-24: 9.2.0][Annotation icons support]
<!-- 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
@ -67,7 +67,6 @@ Some popular choices:
- :material-star-four-points-circle: - `material/star-four-points-circle`
- :material-plus-circle-outline: - `material/plus-circle-outline`
[Annotation icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
[icon search]: icons-emojis.md#search
@ -75,8 +74,8 @@ Some popular choices:
### Using annotations
[:octicons-tag-24: 9.2.0][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
@ -104,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.0
#### in annotations
When [SuperFences] is enabled, annotations can be nested inside annotations by
@ -208,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:

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>"`
@ -552,12 +546,11 @@ This will render annotations with a larger width:
### 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.
Prior to <!-- md:version 8.1.0 -->, 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:
@ -579,5 +572,3 @@ you can add an [additional style sheet] and copy and paste the following CSS:
extra_css:
- stylesheets/extra.css
```
[code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0

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

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/

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

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

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

View File

@ -9,10 +9,10 @@ within Markdown files.
### 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
<!-- md:sponsors -->
<!-- md:version insiders-4.27.0 -->
<!-- md:plugin -->
<!-- md:flag 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
@ -31,13 +31,13 @@ section headlines; even [highlighting inline code blocks] is supported :tada:
### 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
<!-- md:sponsors -->
<!-- md:version insiders-4.21.0 -->
<!-- md:plugin -->
<!-- md:flag 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
especially handy to ensure that all pages in a folder use specific templates or
tags. Add the following lines to `mkdocs.yml`:
``` yaml
@ -51,9 +51,9 @@ plugins:
The following configuration options are available:
[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
<!-- md:option meta.meta_file -->
: :octicons-milestone-24: Default: `.meta.yml` This option specifies the
: <!-- md: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`:
@ -73,9 +73,9 @@ The following configuration options are available:
### 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 +83,7 @@ explicitly set with the front matter `title` property:
title: Lorem ipsum dolor sit amet # (1)!
---
# Document title
# Page title
...
```
@ -101,7 +101,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 +110,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 +121,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
### Setting the page `icon`
[:octicons-tag-24: 9.2.0][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 +134,7 @@ top of a Markdown file:
icon: material/emoticon-happy # (1)!
---
# Document title
# Page title
...
```
@ -149,18 +149,17 @@ icon: material/emoticon-happy # (1)!
</div>
</div>
[Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[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.0][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 +179,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 +187,7 @@ Markdown file:
status: new
---
# Document title
# Page title
...
```
@ -197,13 +196,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.0
### 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 +211,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 +226,7 @@ lines at the top of a Markdown file:
template: custom.html
---
# Document title
# Page title
...
```

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.

View File

@ -93,7 +93,7 @@ property to `true`:
comments: true
---
# Document title
# Page title
...
```

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,9 @@ 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 }
<!-- md:option git-revision-date-localized.fallback_to_build_date -->
: :octicons-milestone-24: Default: `false` Enables falling back to
: <!-- 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 +238,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 +272,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 +284,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 +296,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 +318,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

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,89 +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
```
#### Hoisting
The following configuration options are available for hoisting:
[`hoisting`](#+projects.hoisting){ #+projects.hoisting }
: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
Default: `true` This option specifies whether the plugin should hoist all
themes files to the top-level project. If you disable this setting, each
project will have a copy of the themes files, which in general, can be
considered redundant:
``` yaml
plugins:
- projects:
hoisting: false
```
It's generally advisable to enable hoisting, as it leads to faster
deployments and faster loading of your project's sites, because the files
are the same for all projects.
### 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
@ -156,177 +58,6 @@ plugins:
- optimize # (1)!
```
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

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,11 +34,8 @@ 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
#### Limitations

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,10 @@ 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 -->
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 +207,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 +219,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 +233,8 @@ 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 -->
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 +263,11 @@ 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 -->
Newer operating system allow to automatically switch between light and dark
appearance during day and night times. [Insiders] adds support for automatic

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,7 +68,6 @@ 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
## 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"

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:
@ -41,7 +41,6 @@ the default slug function works. Consider using a [Unicode-aware slug function].
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

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,7 +68,6 @@ 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

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,9 @@ 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 -->
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 +37,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 +100,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 +128,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 +146,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 +160,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,68 +277,9 @@ 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

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`:
@ -237,9 +232,9 @@ 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]:
@ -249,9 +244,9 @@ The following configuration options are supported:
emoji_index: !!python/name:materialx.emoji.twemoji
```
[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator }
<!-- 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:
@ -261,10 +256,10 @@ The following configuration options are supported:
emoji_generator: !!python/name:materialx.emoji.to_svg
```
[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons }
<!-- 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
@ -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,9 @@ The following configuration options are supported:
alternate_style: true
```
[`slugify`](#+pymdownx.tabbed.slugify){ #+pymdownx.tabbed.slugify }
<!-- md:option pymdownx.tabbed.slugify -->
: :octicons-milestone-24: Default: `headerid.slugify` This option allows for
: <!-- 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,8 +701,6 @@ 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
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
@ -727,8 +710,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 +725,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 +737,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 +758,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

View File

@ -11,8 +11,8 @@ reference for which features they need to be enabled.
### Abbreviations
[:octicons-tag-24: 1.0.0][Abbreviations support] ·
[:octicons-workflow-24: Extension][Abbreviations]
<!-- md:version 1.0.0 -->
<!-- md:extension [abbr][Abbreviations] -->
The [Abbreviations] extension adds the ability to add a small tooltip to an
element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
@ -29,16 +29,15 @@ No configuration options are available. See reference for usage:
- [Adding a glossary]
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
[Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
### Admonition
[:octicons-tag-24: 0.1.0][Admonition support] ·
[:octicons-workflow-24: Extension][Admonition]
<!-- md:version 0.1.0 -->
<!-- md:extension [admonition][Admonition] -->
The [Admonition] extension adds support for admonitions, more commonly known as
The [Admonition] extension adds support for admonitions, more commonly known as
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
it via `mkdocs.yml`:
@ -55,7 +54,6 @@ No configuration options are available. See reference for usage:
- [Supported types]
[Admonition]: https://python-markdown.github.io/extensions/admonition/
[Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding admonitions]: ../../reference/admonitions.md#usage
[Changing the title]: ../../reference/admonitions.md#changing-the-title
[Removing the title]: ../../reference/admonitions.md#removing-the-title
@ -63,8 +61,8 @@ No configuration options are available. See reference for usage:
### Attribute Lists
[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
[:octicons-workflow-24: Extension][Attribute Lists]
<!-- md:version 0.1.0 -->
<!-- md:extension [attr_list][Attribute Lists] -->
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
@ -87,7 +85,6 @@ No configuration options are available. See reference for usage:
- [Image lazy-loading]
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
[Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
[Using grids]: ../../reference/grids.md#using-grids
[Adding buttons]: ../../reference/buttons.md#adding-buttons
@ -99,8 +96,8 @@ No configuration options are available. See reference for usage:
### Definition Lists
[:octicons-tag-24: 1.1.0][Definition Lists support] ·
[:octicons-workflow-24: Extension][Definition Lists]
<!-- md:version 1.1.0 -->
<!-- md:extension [def_list][Definition Lists] -->
The [Definition Lists] extension adds the ability to add definition lists (more
commonly known as [description lists] `dl` in HTML) via Markdown to a
@ -116,14 +113,13 @@ No configuration options are available. See reference for usage:
- [Using definition lists]
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
[Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[Using definition lists]: ../../reference/lists.md#using-definition-lists
### Footnotes
[:octicons-tag-24: 1.0.0][Footnotes support] ·
[:octicons-workflow-24: Extension][Footnotes]
<!-- md:version 1.0.0 -->
<!-- md:extension [footnotes][Footnotes] -->
The [Footnotes] extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
@ -139,14 +135,13 @@ No configuration options are supported. See reference for usage:
- [Adding footnote content]
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
[Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
[Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
### Markdown in HTML
[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
[:octicons-workflow-24: Extension][Markdown in HTML]
<!-- md:version 0.1.0 -->
<!-- md:extension [md_in_html][Markdown in HTML] -->
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
which is useful for wrapping Markdown content with custom elements. Enable it
@ -170,18 +165,17 @@ No configuration options are available. See reference for usage:
- [Image captions]
[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
[Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using annotations]: ../../reference/annotations.md#usage
[Using grids]: ../../reference/grids.md#usage
[Image captions]: ../../reference/images.md#image-captions
### Table of Contents
[:octicons-tag-24: 0.1.0][Table of Contents support] ·
[:octicons-workflow-24: Extension][Table of Contents]
<!-- md:version 0.1.0 -->
<!-- md:extension [toc][Table of Contents] -->
The [Table of Contents] extension automatically generates a table of contents
from a document, which Material for MkDocs will render as part of the resulting
from a document, which Material for MkDocs will render as part of the resulting
page. Enable it via `mkdocs.yml`:
``` yaml
@ -192,13 +186,12 @@ markdown_extensions:
The following configuration options are supported:
[`title`](#+toc.title){ #+toc.title }
<!-- md:option toc.title -->
: [:octicons-tag-24: 7.3.5][title support] ·
:octicons-milestone-24: Default: _automatically set_ This option sets the
title of the table of contents in the right navigation sidebar, which is
normally automatically sourced from the translations for the [site language]
as set in `mkdocs.yml`:
: <!-- md:version 7.3.5 --> <!-- md:default computed -->
This option sets the title of the table of contents in the right navigation
sidebar, which is normally automatically sourced from the translations for
the [site language] as set in `mkdocs.yml`:
``` yaml
markdown_extensions:
@ -206,9 +199,9 @@ The following configuration options are supported:
title: On this page
```
[`permalink`](#+toc.permalink){ #+toc.permalink }
<!-- md:option toc.permalink -->
: :octicons-milestone-24: Default: `false` This option adds an anchor link
: <!-- md:default `false` --> This option adds an anchor link
containing the paragraph symbol `¶` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
@ -229,11 +222,11 @@ The following configuration options are supported:
permalink: ⚓︎
```
[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
<!-- md:option toc.permalink_title -->
: :octicons-milestone-24: Default: `Permanent link` This option sets the
: <!-- md:default `Permanent link` --> This option sets the
title of the anchor link which is shown on hover and read by screen readers.
For accessibility reasons, it might be beneficial to change it to a more
For accessibility reasons, it might be beneficial to change it to a more
discernable name, stating that the anchor links to the section itself:
``` yaml
@ -242,9 +235,9 @@ The following configuration options are supported:
permalink_title: Anchor link to this section for reference
```
[`slugify`](#+toc.slugify){ #+toc.slugify }
<!-- md:option toc.slugify -->
: :octicons-milestone-24: Default: `headerid.slugify` This option allows for
: <!-- 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]:
@ -267,9 +260,9 @@ The following configuration options are supported:
slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
<!-- md:option toc.toc_depth -->
: :octicons-milestone-24: Default: `6` Define the range of levels to be
: <!-- md:default `6` --> Define the range of levels to be
included in the table of contents. This may be useful for project
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
@ -295,17 +288,15 @@ by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
[Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.5
[site language]: ../changing-the-language.md#site-language
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
### Tables
[:octicons-tag-24: 0.1.0][Tables support] ·
[:octicons-workflow-24: Extension][Tables]
<!-- md:version 0.1.0 -->
<!-- md:extension [tables][Tables] -->
The [Tables] extension adds the ability to create tables in Markdown by using a
The [Tables] extension adds the ability to create tables in Markdown by using a
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
default):
@ -320,36 +311,34 @@ No configuration options are available. See reference for usage:
- [Column alignment]
[Tables]: https://python-markdown.github.io/extensions/tables/
[Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using data tables]: ../../reference/data-tables.md#usage
[Column alignment]: ../../reference/data-tables.md#column-alignment
## Superseded extensions
The following [Python Markdown] extensions are not (or might not be) supported
The following [Python Markdown] extensions are not (or might not be) supported
anymore, and are therefore not recommended for use. Instead, the alternatives
should be considered.
### Fenced Code Blocks
[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
[:octicons-workflow-24: Extension][Fenced Code Blocks]
<!-- md:version 0.1.0 -->
<!-- md:extension [fenced_code_blocks][Fenced Code Blocks] -->
Superseded by [SuperFences]. This extension might still work, but the
[SuperFences] extension is superior in many ways, as it allows for arbitrary
[SuperFences] extension is superior in many ways, as it allows for arbitrary
nesting, and is therefore recommended.
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### CodeHilite
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
[:octicons-workflow-24: Extension][CodeHilite]
<!-- md:version 0.1.0 -->
<!-- md:extension [codehilite][CodeHilite] -->
Superseded by [Highlight]. Support for CodeHilite was dropped in
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other
<!-- md:version 6.0.0 -->, as [Highlight] has a better integration with other
essential extensions like [SuperFences] and [InlineHilite].
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/

View File

@ -16,7 +16,7 @@ setting up site search, and more.
- :fontawesome-solid-earth-americas: __[Language]__ Choose out of the 60+ supported languages or add a new one
- :material-page-layout-sidebar-left: __[Navigation]__ Create a clear, concise, and comprehensive navigation structure
- :material-page-layout-header: __[Header]__ Customize the behavior of the header, add an announcement bar
- :material-page-layout-footer: __[Footer]__ Add links to your social media profiles or websites in the footer
- :material-page-layout-footer: __[Footer]__ Add links to your social media profiles or websites in the footer
- :material-tab-search: __[Search]__ Set up and configure search, running entirely in the user's browser
- :material-tag-plus-outline: __[Tags]__ Categorize your pages with tags and group related pages
@ -66,7 +66,7 @@ versioned documentation that matches your project's versioning methodology.
[Blog]: setting-up-a-blog.md
[Comment System]: adding-a-comment-system.md
[Versioning]: setting-up-versioning.md
[Versioning]: setting-up-versioning.md
[Repository]: adding-a-git-repository.md
## Optimization

File diff suppressed because it is too large Load Diff

View File

@ -1,6 +1,6 @@
# Setting up navigation
A clear and concise navigation structure is an important aspect of good project
A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs] and [sections], and one
of its flagship features: [instant loading].
@ -13,8 +13,8 @@ of its flagship features: [instant loading].
### Instant loading
[:octicons-tag-24: 5.0.0][Instant loading support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 5.0.0 -->
<!-- md:feature -->
When instant loading is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR] without fully reloading the page. Add
@ -31,14 +31,14 @@ are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
Page Application__. Now, the search index survives navigation, which is
especially useful for large documentation sites.
[Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
#### Instant prefetching :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.36.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.36.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
Instant prefetching is a new experimental feature that will start to fetch a
page once the user hovers over a link. This will reduce the perceived loading
@ -52,12 +52,10 @@ theme:
- navigation.instant.prefetch
```
[Insiders]: ../insiders/index.md
### Anchor tracking
[:octicons-tag-24: 8.0.0][Anchor tracking support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 8.0.0 -->
<!-- md:feature -->
When anchor tracking is enabled, the URL in the address bar is automatically
updated with the active anchor as highlighted in the table of contents. Add the
@ -69,24 +67,22 @@ theme:
- navigation.tracking
```
[Anchor tracking support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
### Navigation tabs
[:octicons-tag-24: 1.1.0][Navigation tabs support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 1.1.0 -->
<!-- md:feature -->
When tabs are enabled, top-level sections are rendered in a menu layer below
the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
the following lines to `mkdocs.yml`:
[^1]:
Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
Prior to <!-- md:version 6.2.0 -->, navigation tabs had a slightly different
behavior. All top-level pages (i.e. all top-level entries directly
referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
were grouped under the first tab which received the title of the first page.
This made it impossible to include a top-level page (or external link) as a
tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
tab item, as was reported in #1884 and #2072. From <!-- md:version 6.2.0 -->
on, navigation tabs include all top-level pages and sections.
``` yaml
@ -103,14 +99,13 @@ theme:
[![Navigation tabs disabled]][Navigation tabs disabled]
[Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
[Navigation tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs
[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 7.3.0 -->
<!-- md:feature -->
When sticky tabs are enabled, navigation tabs will lock below the header and
always remain visible when scrolling down. Just add the following two feature
@ -131,14 +126,13 @@ theme:
[![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
[Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
[Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections
[:octicons-tag-24: 6.2.0][Navigation sections support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 6.2.0 -->
<!-- md:feature -->
When sections are enabled, top-level sections are rendered as groups in the
sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
@ -158,7 +152,6 @@ theme:
[![Navigation sections disabled]][Navigation sections disabled]
[Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
[Navigation sections disabled]: ../assets/screenshots/navigation.png
@ -168,8 +161,8 @@ feature flags are enabled, sections are rendered for level 2 navigation items.
### Navigation expansion
[:octicons-tag-24: 6.2.0][Navigation expansion support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 6.2.0 -->
<!-- md:feature -->
When expansion is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually.
@ -189,15 +182,15 @@ theme:
[![Navigation expansion disabled]][Navigation expansion disabled]
[Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
[Navigation expansion disabled]: ../assets/screenshots/navigation.png
### Navigation path <small>Breadcrumbs</small> { id=navigation-path }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.28.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.28.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
When navigation paths are activated, a breadcrumb navigation is rendered above
the title of each page, which might make orientation easier for users visiting your
@ -223,11 +216,12 @@ theme:
### Navigation pruning
[:octicons-tag-24: 9.2.0][Navigation pruning support] ·
:octicons-beaker-24: Experimental
<!-- md:version 9.2.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
When pruning is enabled, only the visible navigation items are included in the
rendered HTML, __reducing the size of the built site by 33% or more__. Add the
When pruning is enabled, only the visible navigation items are included in the
rendered HTML, __reducing the size of the built site by 33% or more__. Add the
following lines to `mkdocs.yml`:
``` yaml
@ -245,13 +239,12 @@ This feature flag is especially useful for documentation sites with 100+ or even
Navigation pruning will replace all expandable sections with links to the first
page in that section (or the section index page).
[Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[navigation.expand]: #navigation-expansion
### Section index pages
[:octicons-tag-24: 7.3.0][Section index pages support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 7.3.0 -->
<!-- md:feature -->
When section index pages are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. Add the
@ -289,7 +282,6 @@ nav:
1. MkDocs also considers files called `README.md` as [index pages].
[Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
[Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #navigation-integration
@ -299,8 +291,9 @@ nav:
#### Anchor following
[:octicons-tag-24: 8.5.0][Anchor following support] ·
:octicons-beaker-24: Experimental
<!-- md:version 8.5.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
When anchor following for the [table of contents] is enabled, the sidebar is
automatically scrolled so that the active anchor is always visible. Add the
@ -312,12 +305,10 @@ theme:
- toc.follow
```
[Anchor following support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
#### Navigation integration
[:octicons-tag-24: 6.2.0][Navigation integration support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 6.2.0 -->
<!-- md:feature -->
When navigation integration for the [table of contents] is enabled, it is always
rendered as part of the navigation sidebar on the left. Add the following lines
@ -342,15 +333,14 @@ theme:
[![Navigation integration disabled]][Navigation integration disabled]
[table of contents]: extensions/python-markdown.md#table-of-contents
[Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
[navigation.indexes]: #section-index-pages
### Back-to-top button
[:octicons-tag-24: 7.1.0][Back-to-top button support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 7.1.0 -->
<!-- md:feature -->
A back-to-top button can be shown when the user, after scrolling down, starts
to scroll up again. It's rendered centered and just below the header. Add the
@ -362,14 +352,15 @@ theme:
- navigation.top
```
[Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Usage
### Hiding the sidebars
<!-- md:version 6.2.0 -->
<!-- md:flag metadata -->
The navigation and/or table of contents sidebars can be hidden for a document
with the front matter `hide` property. Add the following lines at the top of a
with the front matter `hide` property. Add the following lines at the top of a
Markdown file:
``` yaml
@ -379,7 +370,7 @@ hide:
- toc
---
# Document title
# Page title
...
```
@ -401,6 +392,10 @@ hide:
### Hiding the navigation path
<!-- md:sponsors -->
<!-- md:version insiders-4.28.0 -->
<!-- md:flag metadata -->
While the [navigation path] is rendered above the main headline, sometimes, it
might be desirable to hide it for a specific page, which can be achieved with
the front matter `hide` property:
@ -411,7 +406,7 @@ hide:
- path
---
# Document title
# Page title
...
```
@ -424,7 +419,7 @@ hide:
Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There are two modes:
[`search`](#mode:search){ #mode:search }
<!-- md:option mode:search -->
: This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard:
@ -433,7 +428,7 @@ to navigate your project documentation via keyboard. There are two modes:
* ++esc++ , ++tab++ : close search dialog
* ++enter++ : follow selected result
[`global`](#mode:global){ #mode:global }
<!-- md:option mode:global -->
: This mode is active when _search is not focussed_ and when there's no other
focussed element that is susceptible to keyboard input. The following keys

View File

@ -13,8 +13,8 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable
### Google Analytics
[:octicons-tag-24: 7.1.8][Google Analytics support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 7.1.8 -->
<!-- md:default none -->
Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
already set up Google Analytics and have a property, enable it by adding the
@ -32,8 +32,6 @@ extra:
property: G-XXXXXXXXXX
```
[Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
??? question "How to measure site search usage?"
Besides page views and events, [site search] can be tracked to better
@ -50,8 +48,8 @@ extra:
### Was this page helpful?
[:octicons-tag-24: 8.4.0][Was this page helpful? support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 8.4.0 -->
<!-- md:default none -->
A simple [feedback widget] can be included at the bottom of each page,
encouraging users to give instant feedback whether a page was helpful or not.
@ -85,7 +83,7 @@ extra:
Both properties, `title` and `ratings`, are required. Note that it's allowed to
define more than two ratings, e.g. to implement a 1-5 star rating. Since the
feedback widget sends data to a third-party service, it is, of course, natively
feedback widget sends data to a third-party service, it is, of course, natively
integrated with the [cookie consent] feature[^2].
[^2]:
@ -103,7 +101,7 @@ integrated with the [cookie consent] feature[^2].
2. Go to the __configure__ page on the left hand menu, then select
__custom definitions__
3. Click the __custom metrics__ tab and then __create custom metrics__,
3. Click the __custom metrics__ tab and then __create custom metrics__,
enter the following values:
* Metric name: Page helpful
@ -121,7 +119,7 @@ integrated with the [cookie consent] feature[^2].
(the custom metric created in step 3)
* Rows: `Page location`
* Values: Drag in both `Event count` and `Page helpful`
* Filters: Add a new filter for
* Filters: Add a new filter for
`Event name / exactly matches / feedback`
!!! warning "Delay in data availability"
@ -143,9 +141,9 @@ integrated with the [cookie consent] feature[^2].
The following properties are available for each rating:
[`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon }
<!-- md:option analytics.feedback.ratings.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][custom icons], or the build will not succeed. Some popular
combinations:
@ -154,24 +152,24 @@ The following properties are available for each rating:
* :material-thumb-up-outline: + :material-thumb-down-outline: `material/thumb-up-outline` + `material/thumb-down-outline`
* :material-heart: + :material-heart-broken: `material/heart` + `material/heart-broken`
[`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name }
<!-- md:option analytics.feedback.ratings.name -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__
: <!-- md:default none --> <!-- md:flag required -->
The value of this property is shown on user interaction (i.e. keyboard focus
or mouse hover), explaining the meaning of the rating behind the icon.
[`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data }
<!-- md:option analytics.feedback.ratings.data -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__
: <!-- md:default none --> <!-- md:flag required -->
The value of this property is sent as a data value with the custom event
that is transmitted to Google Analytics[^3] (or any custom integration).
[^3]:
Note that for Google Analytics, the data value must be an integer.
[`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note }
<!-- md:option analytics.feedback.ratings.note -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__
: <!-- md:default none --> <!-- md:flag required -->
The value of this property is shown after the user selected the rating.
It may contain arbitrary HTML tags, which is especially useful to ask the
user to provide more detailed feedback for the current page through a form.
@ -185,7 +183,7 @@ The following properties are available for each rating:
https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
```
In this example, when clicking the link, the user is redirected to the "new
In this example, when clicking the link, the user is redirected to the "new
issue" form of your repository, with a pre-filled title including the path
of the current document, e.g.:
@ -195,7 +193,6 @@ The following properties are available for each rating:
An alternative to GitHub issues is [Google Forms].
[Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[feedback widget]: #feedback
[analytics]: #google-analytics
[feedback report]: ../assets/screenshots/feedback-report.png
@ -216,7 +213,7 @@ hide:
- feedback
---
# Document title
# Page title
...
```
@ -224,7 +221,7 @@ hide:
### Custom site analytics
In order to integrate another analytics service provider offering a
In order to integrate another analytics service provider offering a
JavaScript-based tracking solution, just follow the guide on [theme extension]
and create a new partial in the `overrides` folder. The name of the partial is
used to configure the custom integration via `mkdocs.yml`:

View File

@ -16,11 +16,11 @@ not be compliant with privacy regulations. Moreover, search even works
### Built-in search plugin
[:octicons-tag-24: 0.1.0][Search support] ·
:octicons-cpu-24: Plugin
<!-- md:version 0.1.0 -->
<!-- md:plugin -->
The built-in search plugin integrates seamlessly with Material for MkDocs,
adding multilingual client-side search with [lunr] and [lunr-languages]. It's
adding multilingual client-side search with [lunr] and [lunr-languages]. It's
enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used:
@ -29,227 +29,18 @@ plugins:
- search
```
The following configuration options are supported:
For a list of all settings, please consult the [plugin documentation].
[`lang`](#+search.lang){ #+search.lang }
[plugin documentation]: ../plugins/search.md
: :octicons-milestone-24: Default: _automatically set_ This option allows
to include the language-specific stemmers provided by [lunr-languages].
Note that Material for MkDocs will set this automatically based on the
[site language], but it may be overridden, e.g. to support multiple
languages:
=== "A single language"
``` yaml
plugins:
- search:
lang: en
```
=== "Multiple languages"
``` yaml
plugins:
- search:
lang: # (1)!
- en
- de
```
1. Be aware that including support for other languages increases the
general JavaScript payload by around 20kb (before `gzip`) and by
another 15-30kb per language.
The following languages are supported by [lunr-languages]:
<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>
Material for MkDocs goes to great lengths to support languages that are not
part of this list by automatically falling back to the stemmer yielding the
best result.
[`separator`](#+search.separator){ #+search.separator }
: :octicons-milestone-24: Default: _automatically set_ The separator for
indexing and query tokenization can be customized, making it possible to
index parts of words separated by other characters than whitespace and `-`,
e.g. by including `.`:
``` yaml
plugins:
- search:
separator: '[\s\-\.]+'
```
With :octicons-tag-24: 9.0.0, a faster and more flexible tokenizer method
is shipped, allowing for __tokenizing with lookahead__, which yields more
influence on the way documents are indexed. As a result, we use the
following separator setting for this site's search:
``` yaml
plugins:
- search:
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
```
Broken into its parts, the separator induces the following behavior:
=== "Special characters"
```
[\s\-,:!=\[\]()"/]+
```
The first part of the expression inserts token boundaries for each
document before and after whitespace, hyphens, commas, brackets and
other special characters. If several of those special characters are
adjacent, they are treated as one.
=== "Case changes"
```
(?!\b)(?=[A-Z][a-z])
```
Many programming languages have naming conventions like `PascalCase` or
`camelCase`. By adding this subexpression to the separator,
[words are split at case changes], tokenizing the word `PascalCase`
into `Pascal` and `Case`.
[:octicons-arrow-right-24: Read more on tokenizing case changes]
[tokenize case changes]
=== "Version strings"
```
\.(?!\d)
```
When adding `.` to the separator, version strings like `1.2.3` are split
into `1`, `2` and `3`, which makes them undiscoverable via search. When
using this subexpression, a small lookahead is introduced which will
[preserve version strings] and keep them discoverable.
[:octicons-arrow-right-24: Read more on tokenizing version numbers]
[tokenize version numbers]
=== "HTML/XML tags"
```
&[lg]t;
```
If your documentation includes HTML/XML code examples, you may want to allow
users to find specific tag names. Unfortunately, the `<` and `>` control
characters are encoded in code blocks as `&lt;` and `&gt;`. Adding this
subexpression to the separator allows for just that.
[:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
[tokenize html-xml tags]
[Search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[lunr]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
[lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
[site language]: changing-the-language.md#site-language
[words are split at case changes]: ?q=searchHighlight
[preserve version strings]: ?q=9.0.0
[tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
#### Chinese language support
[:octicons-tag-24: 9.2.0][Chinese language support] ·
:octicons-beaker-24: Experimental
In order to add support for Chinese languages to the [built-in search plugin],
install the text segmentation library [jieba] via `pip`, and the plugin will
run all text through the segmenter:
``` sh
pip install jieba
```
The following configuration options are available:
[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
: :octicons-milestone-24: Default: _none_ This option allows for specifying
a [custom dictionary] to be used by [jieba] for segmenting text, replacing
the default dictionary:
``` yaml
plugins:
- search:
jieba_dict: dict.txt # (1)!
```
1. The following alternative dictionaries are provided by [jieba]:
- [dict.txt.small] 占用内存较小的词典文件
- [dict.txt.big] 支持繁体分词更好的词典文件
[`jieba_dict_user`](#+search.jieba_dict_user){ #+search.jieba_dict_user }
: :octicons-milestone-24: Default: _none_ This option allows for specifying
an additional [user dictionary] to be used by [jieba] for segmenting text,
augmenting the default dictionary:
``` yaml
plugins:
- search:
jieba_dict_user: user_dict.txt
```
User dictionaries can be used for tuning the segmenter to preserve
technical terms.
[Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[chinese search]: ../blog/posts/chinese-search-support.md
[jieba]: https://pypi.org/project/jieba/
[built-in search plugin]: #built-in-search-plugin
[custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
[dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
[dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
[user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
### Search suggestions
[:octicons-tag-24: 7.2.0][Search suggestions support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
<!-- md:version 7.2.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
When search suggestions are enabled, the search will display the likeliest
completion for the last word which can be accepted with the ++arrow-right++ key.
@ -264,14 +55,13 @@ theme:
Searching for [:octicons-search-24: search su][Search suggestions example]
yields ^^search suggestions^^ as a suggestion.
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search suggestions example]: ?q=search+su
### Search highlighting
[:octicons-tag-24: 7.2.0][Search highlighting support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
<!-- md:version 7.2.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
When search highlighting is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
@ -286,13 +76,12 @@ theme:
Searching for [:octicons-search-24: code blocks][Search highlighting example]
highlights all occurrences of both terms.
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
### Search sharing
[:octicons-tag-24: 7.2.0][Search sharing support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 7.2.0 -->
<!-- md:feature -->
When search sharing is activated, a :material-share-variant: share button is
rendered next to the reset button, which allows to deep link to the current
@ -307,13 +96,12 @@ theme:
When a user clicks the share button, the URL is automatically copied to the
clipboard.
[Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
## Usage
### Search boosting
[:octicons-tag-24: 8.3.0][boost support]
<!-- md:version 8.3.0 -->
<!-- md:flag metadata -->
Pages can be boosted in search with the front matter `search.boost` property,
which will make them rank higher. Add the following lines at the top of a
@ -327,7 +115,7 @@ Markdown file:
boost: 2 # (1)!
---
# Document title
# Page title
...
```
@ -342,19 +130,18 @@ Markdown file:
boost: 0.5
---
# Document title
# Page title
...
```
[boost support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
### Search exclusion
[:octicons-tag-24: 9.0.0][exclusion support] ·
:octicons-beaker-24: Experimental
<!-- md:version 9.0.0 -->
<!-- md:flag metadata -->
<!-- md:flag experimental -->
Pages can be excluded from search with the front matter `search.exclude`
property, removing them from the index. Add the following lines at the top of a
property, removing them from the index. Add the following lines at the top of a
Markdown file:
``` yaml
@ -363,12 +150,10 @@ search:
exclude: true
---
# Document title
# Page title
...
```
[exclusion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
#### Excluding sections
When [Attribute Lists] is enabled, specific sections of pages can be excluded
@ -378,7 +163,7 @@ heading:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
# Page title
## Section 1
@ -420,7 +205,7 @@ inline- or block-level element:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
# Page title
The content of this block is included

View File

@ -4,8 +4,8 @@ status: new
# Setting up social cards
Material for MkDocs can automatically create beautiful social cards for your
documentation, which appear as link previews on social media platforms. You
Material for MkDocs can automatically create beautiful social cards for your
documentation, which appear as link previews on social media platforms. You
can select from several [pre-designed layouts][default layouts] or create
[custom layouts] to match your unique style and branding.
@ -36,35 +36,22 @@ Social card of our [formatting] reference
### Built-in social plugin
[:octicons-tag-24: 8.5.0][Social cards support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
<!-- md:version 8.5.0 -->
<!-- md:plugin -->
<!-- md:flag experimental -->
The built-in social plugin automatically generate a custom preview image for
each page. Install all [dependencies for image processing][^1] and add the
The built-in social plugin automatically generate a custom preview image for
each page. Install all [dependencies for image processing] and add the
following lines to `mkdocs.yml`:
[^1]:
The awesome thing about social cards is that they are generated during
build time and directly distributed with your documentation, no external
services involved. While it would technically be simpler to generate
social cards using a web browser and an automation framework like
[Puppeteer], it would add further liabilities to the toolchain, with the
potential to make build pipelines more complex and resource intense.
For this reason, Material for MkDocs again follows its core principle of
making it as simple and powerful as possible, providing an easy-to-use
framework for building [custom layouts] using Python image processing
libraries.
``` yaml
plugins:
- social
```
> Note that [Insiders] contains a ground up rewrite of the social plugin that
> generates images much more efficiently in parallel and allows to build
> entirely [custom layouts].
For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/blog.md
!!! info "The [`site_url`][site_url] setting must be set"
@ -78,481 +65,18 @@ plugins:
site_url: https://example.com
```
[dependencies for image processing]: ../plugins/requirements/image-processing.md
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
The following configuration options are available:
[`enabled`](#+social.enabled){ #+social.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:
- social:
enabled: !ENV [CI, false]
```
[`concurrency`](#+social.concurrency){ #+social.concurrency }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: _number of CPUs_ How many CPUs the plugin is allowed to use when
generating social cards. With more CPUs, the plugin can do more work in the
same time, thus complete generation faster. Concurrent processing can be
disabled with:
``` yaml
plugins:
- social:
concurrency: 1
```
[Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[dependencies for image processing]: dependencies/image-processing.md
[Puppeteer]: https://github.com/puppeteer/puppeteer
[Insiders]: ../insiders/index.md
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
#### Social cards
The following configuration options are available for card generation:
[`cards`](#+social.cards){ #+social.cards }
: :octicons-milestone-24: Default: `true` This option specifies whether
to generate social card images. If you want to switch the plugin off, e.g.
for local builds, you can use an [environment variable]:
``` yaml
plugins:
- social:
cards: !ENV [CI, false]
```
[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
: :octicons-milestone-24: Default: `assets/images/social` This option
specifies where the generated social cards will be stored. While it's
usually not necessary to change this option, change it with:
``` yaml
plugins:
- social:
cards_dir: assets/images/social
```
<div class="mdx-deprecated" markdown>
[`cards_color`](#+social.cards_color){ #+social.cards_color } <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
: :octicons-milestone-24: Default: [`theme.palette.primary`][primary color]
This option specifies the colors for the background `fill` and foreground
`text` when generating the social card:
``` yaml
plugins:
- social:
cards_color:
fill: "#0FF1CE"
text: "#FFFFFF"
```
[`cards_font`](#+social.cards_font){ #+social.cards_font } <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
: :octicons-milestone-24: Default: [`theme.font.text`][font] This option
specifies which font to use for rendering the social card, which can be
any font hosted on [Google Fonts]:
``` yaml
plugins:
- social:
cards_font: Ubuntu
```
</div>
[`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: _none_ This option specifies where the social plugin should try
to resolve [custom layouts] from, taking precedence over the included
layouts:
``` yaml
plugins:
- social:
cards_layout_dir: layouts
```
[`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `default` Layout specification the social card should use. The
plugin includes the following layouts which make use of the [color palette]
and [font]:
=== "`default`"
``` yaml
plugins:
- social:
cards_layout: default
```
This layout uses the configured [primary color] as a background:
[![Layout default]][Layout default]
=== "`default/variant`"
``` yaml
plugins:
- social:
cards_layout: default/variant
```
This layout includes the [page icon] as a watermark, if defined:
[![Layout default variant]][Layout default variant]
=== "`default/accent`"
``` yaml
plugins:
- social:
cards_layout: default/accent
```
This layout uses the configured [accent color] as a background:
[![Layout default accent]][Layout default accent]
=== "`default/invert`"
``` yaml
plugins:
- social:
cards_layout: default/invert
```
This layout inverts the background and foreground colors:
[![Layout default invert]][Layout default invert]
=== "`default/only/image`"
``` yaml
plugins:
- social:
cards_layout: default/only/image
cards_layout_options:
background_image: layouts/background.png
```
This layout will only show the given background image and scale to fit:
[![Layer background image]][Layer background image]
All [`default`][default layouts] layouts make use of the following
[template variables]:
- :material-page-layout-header: `config.site_name`
- :material-page-layout-body: `page.meta.title` or `page.title`
- :material-page-layout-footer: `page.meta.description` or `config.site_description`
- :material-page-layout-sidebar-right: `theme.logo` or `theme.icon.logo`
[`cards_layout_options`](#+social.cards_layout_options){ #+social.cards_layout_options }
: [:octicons-tag-24: 9.1.10][Layout options support] · :octicons-milestone-24:
Default: _none_ This option allows to set [parameters] as provided by
the layout specification. For [custom layouts], this key can be used to
provide layout-specific options, making layouts entirely configurable.
---
All [`default`][default layouts] layouts expose the following parameters:
[`background_color`](#+social.cards_layout_options.background_color){ #+social.cards_layout_options.background_color }
: Set a background color, which can be a [CSS color keyword], or a 3, 4, 6
or 8 letter HEX color code. Alpha channels are supported as well:
``` yaml
plugins:
- social:
cards_layout_options:
background_color: "#0FF1CE"
```
[`background_image`](#+social.cards_layout_options.background_image){ #+social.cards_layout_options.background_image }
: [:octicons-tag-24: insiders-4.33.0][Insiders] Set a background image.
If a `background_color` is set, like for the
[`default`][default layouts] layouts, the image is tinted (overlayed)
with the color. Thus, the background color must be (partially)
transparent for the image to become visible:
``` yaml
plugins:
- social:
cards_layout_options:
background_color: "#00000000"
background_image: layouts/background.png
```
The path of the image must be defined relative to the project root.
[`color`](#+social.cards_layout_options.color){ #+social.cards_layout_options.color }
: Set a foreground color, which can be a [CSS color keyword], or a 3, 4, 6
or 8 letter HEX color code. The color is primarily used to tint text and
icons:
``` yaml
plugins:
- social:
cards_layout_options:
color: "#0FF1CE"
```
[`font_family`](#+social.cards_layout_options.font_family){ #+social.cards_layout_options.font_family }
: Set a font family. This overrides the [font] that is set as part of the
theme configuration. The [built-in social plugin] will automatically
download the font from [Google Fonts]:
``` yaml
plugins:
- social:
cards_layout_options:
font_family: Ubuntu
```
[`title`](#+social.cards_layout_options.title){ #+social.cards_layout_options.title }
: [:octicons-tag-24: insiders-4.40.0][Insiders] Set the social card
title, which takes precedence over `page.title` and `page.meta.title`:
``` yaml
plugins:
- social:
cards_layout_options:
title: Social card title
```
[`description`](#+social.cards_layout_options.description){ #+social.cards_layout_options.description }
: [:octicons-tag-24: insiders-4.40.0][Insiders] Set the social card
description, which takes precedence over `site_description` and
`page.meta.description`:
``` yaml
plugins:
- social:
cards_layout_options:
description: Social card description
```
[`logo`](#+social.cards_layout_options.logo){ #+social.cards_layout_options.logo }
: [:octicons-tag-24: insiders-4.40.0][Insiders] Set the logo used as
part of the social card, overriding the `theme.logo` or
`theme.icon.logo` settings which are used as defaults:
``` yaml
plugins:
- social:
cards_layout_options:
logo: layouts/logo.png
```
The path of the image must be defined relative to the project root.
[`cards_include`](#+privacy.cards_include){ #+privacy.cards_include }
: [:octicons-tag-24: insiders-4.35.0][Insiders] · :octicons-milestone-24:
Default: _none_ This option allows to only generate social cards for
certain subsections of your documentation, e.g. to generate different
cards for different subfolders with multiple instances of the plugin:
``` yaml
plugins:
- social:
cards_include:
- blog/*
```
[`cards_exclude`](#+privacy.cards_exclude){ #+privacy.cards_exclude }
: :octicons-milestone-24: Default: _none_ This option allows to exclude
certain subsections of your documentation from generating social cards:
``` yaml
plugins:
- social:
cards_exclude:
- changelog/*.md
```
[color palette]: ./changing-the-colors.md#color-palette
[primary color]: ./changing-the-colors.md#primary-color
[accent color]: ./changing-the-colors.md#accent-color
[font]: ./changing-the-fonts.md#regular-font
[Google Fonts]: https://fonts.google.com/
[layout options]: #+social.cards_layout_options
[page icon]: ../reference/index.md#setting-the-page-icon
[Layout default]: ../assets/screenshots/social-cards.png
[Layout default variant]: ../assets/screenshots/social-cards-variant.png
[Layout default accent]: ../assets/screenshots/social-cards-accent.png
[Layout default invert]: ../assets/screenshots/social-cards-invert.png
[template variables]: https://www.mkdocs.org/dev-guide/themes/#template-variables
[parameters]: #parameters
[default layouts]: #+social.cards_layout
[CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
[Layout options support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.1.10
#### Debugging
The following configuration options are available for debugging:
[`debug`](#+social.debug){ #+social.debug }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `false` This option enables a special debug mode, which renders
each layer with an outline and its `x` and `y` offset in order to understand
how the layout is composed, and optionally renders a grid for easier
alignment:
``` yaml
plugins:
- social:
debug: true
```
=== "With debug mode"
[![Debug mode enabled]][Debug mode enabled]
=== "Without"
[![Debug mode disabled]][Debug mode disabled]
[Debug mode enabled]: ../assets/screenshots/social-cards-debug.png
[Debug mode disabled]: ../assets/screenshots/social-cards-variant.png
[`debug_on_build`](#+social.debug_on_build){ #+social.debug_on_build }
: [:octicons-tag-24: insiders-4.34.1][Insiders] · :octicons-milestone-24:
Default: `false` Whether debug mode should be automatically disabled
[when building your site] with `mkdocs build`. It can be changed with:
``` yaml
plugins:
- social:
debug_on_build: true
```
This setting is just intended to be a safety net, so that when building
your site social cards definitely won't contain the dot grid or layer
outlines by accident.
[`debug_grid`](#+social.debug_grid){ #+social.debug_grid }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `true` This option enables the rendering of a dot grid when
[`debug`][debug] is enabled (see screenshot above). The grid can be switched
off with:
``` yaml
plugins:
- social:
debug_grid: false
```
[`debug_grid_step`](#+social.debug_grid_step){ #+social.debug_grid_step }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `32` This option specifies the step size of the grid in pixels,
if enabled, which can be used to align elements. It can be changed with:
``` yaml
plugins:
- social:
debug_grid_step: 64
```
[`debug_color`](#+social.debug_color){ #+social.debug_color }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `grey` This option sets the color of the layer outlines and
the grid which are rendered when [`debug`][debug] is enabled. It can be
changed with:
``` yaml
plugins:
- social:
debug_color: yellow
```
[debug]: #+social.debug
[when building your site]: ../creating-your-site.md#building-your-site
#### Caching
The [built-in social plugin] implements an intelligent caching mechanism,
ensuring that social cards are only re-generated when they're not contained in
the cache or their contents change. If any of the variables used in a layout
changes, the plugin will detect it and re-generate the card.
The following configuration options are available for caching:
[`cache`](#+social.cache){ #+social.cache }
: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
Default: `true` Whether the plugin queries its cache for an existing
artifact before starting a generation job. It's normally not necessary to
change this setting, except for when debugging the plugin itself. Caching
can be disabled with:
``` yaml
plugins:
- social:
cache: false
```
[`cache_dir`](#+social.cache_dir){ #+social.cache_dir }
: :octicons-milestone-24: Default: `.cache/plugins/social` 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:
- social:
cache_dir: .cache/plugins/social
```
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.
[built-in social plugin]: #built-in-social-plugin
[publishing guide]: ../publishing-your-site.md#with-github-actions
## Usage
If you want to adjust the title or set a custom description for the social card,
you can set the front matter [`title`][Changing the title] and
[`description`][Changing the description] properties, which take precedence over
[`description`][Changing the description] properties, which take precedence over
the defaults, or use:
- [`cards_layout_options.title`](#+social.cards_layout_options.title)
- [`cards_layout_options.description`](#+social.cards_layout_options.description)
- [`cards_layout_options.title`](../plugins/social.md#option.title)
- [`cards_layout_options.description`](../plugins/social.md#option.description)
[Changing the title]: ../reference/index.md#setting-the-page-title
[Changing the description]: ../reference/index.md#setting-the-page-description
@ -602,12 +126,14 @@ comes with CJK characters, e.g. one from the `Noto Sans` font family:
### Changing the layout
[:octicons-tag-24: insiders-4.37.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:version insiders-4.37.0 -->
<!-- md:flag metadata -->
<!-- md:flag experimental -->
If you want to use a different layout for a single page (e.g. your landing
page), you can use the `social` front matter property together with the
[`cards_layout`](#+social.cards_layout) key, exactly as in `mkdocs.yml`:
[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
in `mkdocs.yml`:
``` yaml
---
@ -615,7 +141,7 @@ social:
cards_layout: custom
---
# Headline
# Page title
...
```
@ -623,17 +149,18 @@ You can apply those changes for entire subtrees of your documentation, e.g.,
to generate different social cards for your blog and API reference, by using
the [built-in meta plugin].
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
[built-in meta plugin]: ../plugins/meta.md
### Parametrizing the layout
[:octicons-tag-24: insiders-4.37.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:version insiders-4.37.0 -->
<!-- md:flag metadata -->
<!-- md:flag experimental -->
Besides changing the entire layout, you can override all options that a layout
exposes. This means you can parametrize social cards with custom front matter
properties, such as `tags`, `date`, `author` or anything you can think of.
Simply define [`cards_layout_options`](#+social.cards_layout_options):
Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
``` yaml
---
@ -643,7 +170,7 @@ social:
background_image: null # Remove background image
---
# Headline
# Page title
...
```
@ -653,8 +180,9 @@ the [built-in meta plugin].
### Disabling social cards
[:octicons-tag-24: insiders-4.37.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:version insiders-4.37.0 -->
<!-- md:flag metadata -->
<!-- md:flag experimental -->
If you wish to disable social cards for a page, simply add the following to the
front matter of the Markdown document:
@ -665,15 +193,15 @@ social:
cards: false
---
# Headline
# Page title
...
```
## Customization
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.33.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.33.0 -->
<!-- md:flag experimental -->
[Insiders] ships a ground up rewrite of the [built-in social plugin] and
introduces a brand new layout system based on a combination of YAML and
@ -755,6 +283,9 @@ haven't defined any layers, the cards are transparent.
The following sections explain how to create custom layouts.
[Insiders]: ../insiders/index.md
[built-in social plugin]: ../plugins/social.md
[Google Fonts]: https://fonts.google.com/
[Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
[study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material-insiders/tree/master/src/plugins/social/layouts
@ -785,8 +316,8 @@ useful for alignment and composition.
#### Origin
[:octicons-tag-24: insiders-4.35.0][Insiders] ·
:octicons-beaker-24: Experimental
<!-- md:version insiders-4.35.0 -->
<!-- md:flag experimental -->
The `origin` for the `x` and `y` values can be changed, so that the layer is
aligned to one of the edges or corners of the layout, e.g., to the bottom right
@ -934,7 +465,7 @@ automatically scaled down to fit the layer:
![Layer typography shrink]
While truncating with an ellipsis is the default, auto-shrinking can be enabled
While truncating with an ellipsis is the default, auto-shrinking can be enabled
by setting `overflow` to `shrink`:
``` yaml hl_lines="7"

View File

@ -11,8 +11,8 @@ can help to discover relevant information faster.
### Built-in tags plugin
[:octicons-tag-24: 8.2.0][Tags support] ·
:octicons-cpu-24: Plugin
<!-- md:version 8.2.0 -->
<!-- md:plugin -->
The built-in tags plugin adds the ability to categorize any page with tags
as part of the front matter of the page. In order to add support for tags, add
@ -23,206 +23,14 @@ plugins:
- tags
```
The following configuration options are available:
For a list of all settings, please consult the [plugin documentation].
[`enabled`](#+tags.enabled){ #+tags.enabled }
: :octicons-milestone-24: Default: `true` This option specifies whether
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
``` yaml
plugins:
- tags:
enabled: !ENV [CI, false]
```
[`tags_file`](#+tags.tags_file){ #+tags.tags_file }
: :octicons-milestone-24: Default: _none_ This option specifies which page
should be used to render the tags index. See the section on [adding a tags
index][tags index] for more information. If this option is specified, tags
become clickable, pointing to the corresponding section in the tags index:
``` yaml
plugins:
- tags:
tags_file: tags.md
```
The page holding the tags index can be linked anywhere in the `nav` section
of `mkdocs.yml`. Note, however, that this options is not required only use
it if you want a tags index page.
[`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files }
: [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24:
Default: _none_ This option specifies additional pages, i.e. to render
subsets of the [tags index], in order to provide scoped tags indexes for
specific sections:
``` yaml
plugins:
- tags:
tags_extra_files:
compatibility.md:
- compat # (1)!
web.md:
- html
- js
- css
```
1. Each page can be assigned a list of [tag identifiers], which must be
defined as part of `extra.tags` in `mkdocs.yml`:
``` yaml
extra:
tags:
Compatibility: compat
HTML5: html
JavaScript: js
CSS: css
```
In this example, all pages with the tag `Compatibility` will be included
in the additional tags index on `compatibility.md`, all pages defining
at least one of the tags `HTML5`, `JavaScript` or `CSS` will be included
in the additional tags index on `web.md`.
Note that the values listed under each tags extra file must be alphanumeric
[tag identifiers], not tags themselves. See #3864 for more information.
[`tags_slugify`](#+tags.tags_slugify){ #+tags.tags_slugify }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: `headerid.slugify` This option specifies which function to use for
generating URL-compatible slugs from tags. [Python Markdown Extensions]
includes several Unicode-aware slug functions which are a good choice for
non-ASCII languages:
=== "Unicode"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`tags_slugify_separator`](#+tags.tags_slugify_separator){ #+tags.tags_slugify_separator }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: `-` This option specifies the separator which is used by the slug function. By default, a hyphen is used, but it can
be changed to any string:
``` yaml
plugins:
- tags:
tags_slugify_separator: "-"
```
[`tags_compare`](#+tags.tags_compare){ #+tags.tags_compare }
: [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
Default: `None` This option specifies which function to use when
comparing tag values for sorting. If you wish to compare tags irregardless
of casing, use:
``` yaml
plugins:
- tags:
tags_compare: !!python/name:material.plugins.tags.casefold
```
You can also define your own comparison function which must return a tag
value (as a string) that is used for sorting, and reference it accordingly.
[`tags_compare_reverse`](#+tags.tags_compare_reverse){ #+tags.tags_compare_reverse }
: [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
Default: `false` This option specifies whether tags are sorted in reverse
order. It is mainly provided for completeness. To change direction, use:
``` yaml
plugins:
- tags:
tags_compare_reverse: true
```
[`tags_pages_compare`](#+tags.tags_pages_compare){ #+tags.tags_pages_compare }
: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
Default: `None` This option specifies which function to use when
comparing pages for sorting. If you wish to sort pages, use:
=== "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 page
value (as a string) that is used for sorting, and reference it accordingly.
[`tags_pages_compare_reverse`](#+tags.tags_pages_compare_reverse){ #+tags.tags_pages_compare_reverse }
: [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
Default: `false` This option specifies whether pages are sorted in reverse
order. It is mainly provided for completeness. To change direction, use:
``` yaml
plugins:
- tags:
tags_pages_compare_reverse: true
```
[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: _none_ This option allows the author to define explicitly which
tags are allowed to be used on pages. If this setting is omitted, the
[built-in tags plugin] won't check tag names. Use this option to define a
list of tags in order to catch typos:
``` yaml
plugins:
- tags:
tags_allowed:
- HTML5
- JavaScript
- CSS
```
[Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[Insiders]: ../insiders/index.md
[tag identifiers]: #tag-icons-and-identifiers
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
[plugin documentation]: ../plugins/tags.md
### Tag icons and identifiers
[:octicons-tag-24: 8.5.0][Tag icons support] ·
:octicons-beaker-24: Experimental
<!-- md:version 8.5.0 -->
<!-- md:flag experimental -->
Each tag can be associated with an icon, which is then rendered inside the tag.
Before assigning icons to tags, associate each tag with a unique identifier,
@ -248,7 +56,7 @@ extra:
associated will use the default tag icon which is :material-pound:
Next, each identifier can be associated with an icon, even a [custom icon], by
adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
setting:
=== "Tag icon"
@ -296,7 +104,6 @@ setting:
CSS: css
```
[Tag icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
[custom icon]: changing-the-logo-and-icons.md#additional-icons
[icon search]: ../reference/icons-emojis.md#search
@ -305,7 +112,7 @@ setting:
### Adding tags
When the [built-in tags plugin] is enabled, tags can be added for a document
with the front matter `tags` property. Add the following lines at the top of a
with the front matter `tags` property. Add the following lines at the top of a
Markdown file:
``` sh
@ -378,6 +185,6 @@ hide:
- tags
---
# Document title
# Page title
...
```

View File

@ -1,7 +1,7 @@
# Setting up the footer
The footer of your project documentation is a great place to add links to
websites or platforms you or your company are using as additional marketing
websites or platforms you or your company are using as additional marketing
channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
configure via `mkdocs.yml`.
@ -10,8 +10,8 @@ configure via `mkdocs.yml`.
### Navigation
[:octicons-tag-24: 9.0.0][Navigation footer support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 9.0.0 -->
<!-- md:feature -->
The footer can include links to the previous and next page of the current page.
If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
@ -22,15 +22,13 @@ theme:
- navigation.footer
```
[Navigation footer support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
### Social links
[:octicons-tag-24: 1.0.0][Social links support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 1.0.0 -->
<!-- md:default none -->
Social links are rendered next to the copyright notice as part of the
footer of your project documentation. Add a list of social links in `mkdocs.yml`
Social links are rendered next to the copyright notice as part of the
footer of your project documentation. Add a list of social links in `mkdocs.yml`
with:
``` yaml
@ -53,9 +51,9 @@ extra:
The following properties are available for each link:
[`icon`](#+social.icon){ #+social.icon }
<!-- md:option social.icon -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__
: <!-- md:default none --> <!-- md:flag required -->
This property must contain a valid path to any icon bundled with the theme,
or the build will not succeed. Some popular choices:
@ -72,10 +70,10 @@ The following properties are available for each link:
* :fontawesome-brands-slack: `fontawesome/brands/slack`
* :fontawesome-brands-discord: `fontawesome/brands/discord`
[`link`](#+social.link){ #+social.link }
<!-- md:option social.link -->
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__
This property must be set to a relative or absolute URL including the URI
: <!-- md:default none --> <!-- md:flag required -->
This property must be set to a relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== ":fontawesome-brands-mastodon: Mastodon"
@ -96,10 +94,10 @@ The following properties are available for each link:
link: mailto:<email-address>
```
[`name`](#+social.name){ #+social.name }
<!-- md:option social.name -->
: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_
This property is used as the link's `title` attribute and can be set to a
: <!-- md:default _domain name from_ `link`_, if available_ -->
This property is used as the link's `title` attribute and can be set to a
discernable name to improve accessibility:
``` yaml
@ -111,13 +109,12 @@ The following properties are available for each link:
```
[icon search]: ../reference/icons-emojis.md#search
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[rel=me]: https://docs.joinmastodon.org/user/profile/#verification
### Copyright notice
[:octicons-tag-24: 0.1.0][Copyright notice support] ·
:octicons-milestone-24: Default: _none_
<!-- md:version 0.1.0 -->
<!-- md:default none -->
A custom copyright banner can be rendered as part of the footer, which is
displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@ -126,12 +123,10 @@ displayed next to the social links. It can be defined as part of `mkdocs.yml`:
copyright: Copyright &copy; 2016 - 2020 Martin Donath
```
[Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
### Generator notice
[:octicons-tag-24: 7.3.0][Generator notice support] ·
:octicons-milestone-24: Default: `true`
<!-- md:version 7.3.0 -->
<!-- md:default `true` -->
The footer displays a _Made with Material for MkDocs_ notice to denote how
the site was generated. The notice can be removed with the following option
@ -155,7 +150,6 @@ extra:
Thus, if you remove this notice, please consider [sponsoring][Insiders] the
project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
[Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[Insiders]: ../insiders/index.md
## Usage
@ -163,7 +157,7 @@ extra:
### Hiding prev/next links
The footer navigation showing links to the previous and next page can be hidden
with the front matter `hide` property. Add the following lines at the top of a
with the front matter `hide` property. Add the following lines at the top of a
Markdown file:
``` yaml
@ -172,7 +166,7 @@ hide:
- footer
---
# Document title
# Page title
...
```
@ -180,14 +174,13 @@ hide:
### Custom copyright
[:octicons-tag-24: 8.0.0][Custom copyright support] ·
:octicons-file-symlink-file-24: Customization
<!-- md:version 8.0.0 -->
<!-- md:flag customization -->
In order to customize and override the [copyright notice], [extend the theme]
and [override the `copyright.html` partial][overriding partials], which normally
includes the `copyright` property set in `mkdocs.yml`.
[Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[copyright notice]: #copyright-notice
[generator notice]: #generator-notice
[extend the theme]: ../customization.md#extending-the-theme

View File

@ -1,6 +1,6 @@
# Setting up the header
Material for MkDocs' header can be customized to show an announcement bar that
Material for MkDocs' header can be customized to show an announcement bar that
disappears upon scrolling, and provides some options for further configuration.
It also includes the [search bar] and a place to display your project's
[git repository], as explained in those dedicated guides.
@ -12,8 +12,8 @@ It also includes the [search bar] and a place to display your project's
### Automatic hiding
[:octicons-tag-24: 6.2.0][Automatic hiding support] ·
:octicons-unlock-24: Feature flag
<!-- md:version 6.2.0 -->
<!-- md:feature -->
When autohiding is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the
@ -25,12 +25,10 @@ theme:
- header.autohide
```
[Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
### Announcement bar
[:octicons-tag-24: 5.0.0][Announcement bar support] ·
:octicons-file-symlink-file-24: Customization
<!-- md:version 5.0.0 -->
<!-- md:flag customization -->
Material for MkDocs includes an announcement bar, which is the perfect place to
display project news or other important information to the user. When the user
@ -46,15 +44,14 @@ block][overriding blocks], which is empty by default:
{% endblock %}
```
[Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[extend the theme]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
#### Mark as read
[:octicons-tag-24: 8.4.0][dismiss support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
<!-- md:version 8.4.0 -->
<!-- md:feature -->
<!-- md:flag experimental -->
In order to render temporary announcements that can be marked as read by the
user, a button to dismiss the current announcement can be included. Add the
@ -72,5 +69,4 @@ automatically.
[Scroll to the top of this page][top] to see it in action.
[dismiss support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
[top]: #

View File

@ -11,8 +11,8 @@ documentation remain untouched.
### Versioning
[:octicons-tag-24: 7.0.0][Versioning support] ·
[:octicons-package-24: Utility][mike]
<!-- md:version 7.0.0 -->
<!-- md:utility [mike] -->
[mike] makes it easy to deploy multiple versions of your project documentation.
It integrates natively with Material for MkDocs and can be enabled via
@ -51,15 +51,14 @@ Check out the versioning example to see it in action
to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to.
[Versioning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
[Version selector preview]: ../assets/screenshots/versioning.png
[version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike
### Version warning
[:octicons-tag-24: 8.0.0][Version warning support] ·
:octicons-file-symlink-file-24: Customization
<!-- md:version 8.0.0 -->
<!-- md:flag customization -->
If you're using versioning, you might want to display a warning when the user
visits any other version than the latest version. Using [theme extension],
@ -76,7 +75,7 @@ you can [override the `outdated` block][overriding blocks]:
{% endblock %}
```
1. Given this value for the `href` attribute, the link will always redirect to
1. Given this value for the `href` attribute, the link will always redirect to
the root of your site, which will then redirect to the latest version. This
ensures that older versions of your site do not depend on a specific alias,
e.g. `latest`, to allow for changing the alias later on without breaking
@ -113,7 +112,6 @@ extra:
Make sure one alias matches the [default version], as this is where users are
redirected to.
[Version warning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
[theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
[Version warning preview]: ../assets/screenshots/version-warning.png
@ -121,7 +119,7 @@ redirected to.
## Usage
While this section outlines the basic workflow for publishing new versions,
While this section outlines the basic workflow for publishing new versions,
it's best to check out [mike's documentation][mike] to make yourself familiar
with its mechanics.

11
includes/mkdocs.md Normal file
View File

@ -0,0 +1,11 @@
[mkdocs]: https://www.mkdocs.org
[mkdocs.dotfiles]: https://www.mkdocs.org/dev-guide/themes/#dot-files
[mkdocs.metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
[mkdocs.env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[mkdocs.docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[mkdocs.site_dir]: https://www.mkdocs.org/user-guide/configuration/#site_dir
[mkdocs.site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
[mkdocs.nav]: https://www.mkdocs.org/user-guide/configuration/#nav
[mkdocs.plugins]: https://www.mkdocs.org/user-guide/configuration/#plugins
[mkdocs.strict]: https://www.mkdocs.org/user-guide/configuration/#strict
[mkdocs.use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1 @@
{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"AA2BA,iBACE,cAIE,kBC7BF,CDgCA,QAEE,qBC/BF,CACF,CD0CE,qBACE,aCxCJ,CD6CE,sBACE,aC3CJ,CD+CE,uBACE,UC7CJ,CDgDI,8BAGE,QAAA,CACA,sBAAA,CAHA,iBAAA,CACA,UC5CN,CDkDI,8BAOE,WAAA,CAFA,WAAA,CAFA,MAAA,CAGA,eAAA,CALA,iBAAA,CACA,KAAA,CAEA,UC7CN,CDqDE,uBACE,2BCnDJ,CDuDE,0BACE,aCrDJ,CD2DE,uBACE,eCzDJ,CD4DI,8BACE,4BAAA,CACA,4BAAA,CACA,2CC1DN,CD6DM,uCACE,2BC3DR,CDgEI,uCAGE,4BC7DN,CD0DI,uCAGE,6BC7DN,CD0DI,uCAIE,+BC9DN,CD0DI,uCAIE,gCC9DN,CD0DI,6BAEE,iDAAA,CADA,aC3DN,CDiEM,wCACE,mBC/DR,CDoEI,uCAEE,6BChEN,CD8DI,uCAEE,4BChEN,CD8DI,uCAGE,gCCjEN,CD8DI,uCAGE,+BCjEN,CD8DI,6BAIE,iEAAA,CAHA,mBC/DN,CDyEE,+BACE,cAAA,CACA,uBCvEJ,CD0EI,0EACE,WCxEN,CD4EI,oCAGE,2CAAA,CADA,gCAAA,CADA,aCxEN,CDkFI,wDAEE,cAAA,CAAA,cChFN,CCqII,wCFvDA,wDAMI,oBAAA,CAAA,eC/EN,CACF,CDmFI,4BACE,8BAAA,CAAA,kBCjFN,CDsFE,uBACE,eCpFJ,CDuFI,0BACE,eCrFN,CDwFM,6BACE,iBCtFR,CD2FI,6BACE,YAAA,CACA,SCzFN,CD6FI,gCACE,YAAA,CACA,MAAA,CACA,qBC3FN,CD8FM,qCAEE,oBAAA,CADA,mBAAA,CAEA,6BC5FR,CDgGM,kDACE,aC9FR,CDkGM,qCACE,WChGR,CDsGE,wBAEE,sBAAA,CADA,iBCnGJ,CDuGI,iDACE,0BCrGN,CDyGI,+BAEE,eAAA,CADA,iBAAA,CAGA,2BAAA,CADA,uCCtGN,CD6GQ,wDACE,SC3GV,CD+GQ,wDACE,0BC7GV,CDiHQ,wDACE,SC/GV,CDqHI,+BACE,yCACE,CAGF,oDAAA,CADA,mBCpHN,CDwHM,mCACE,aCtHR,CD2HI,+BAKE,kDAAA,CADA,gCAAA,CAFA,aAAA,CAIA,SAAA,CAHA,mBAAA,CAFA,iBAAA,CAMA,mBCzHN,CD8HM,8DACE,2BC5HR,CD2HM,8DACE,2BCzHR,CDwHM,8DACE,2BCtHR,CDqHM,8DACE,uBCnHR,CDkHM,8DACE,0BChHR,CD+GM,6DACE,0BC7GR,CD4GM,8DACE,0BC1GR,CEtJA,WACE,wCFyJF,CEtJE,kBAEE,kBFwJJ,CErJE,+BAJE,+BF4JJ,CErJI,sCAEE,kBFsJN,CEpJM,wDACE,0CAAA,CACA,eFsJR,CEjJE,oBAME,kBAAA,CACA,0CAAA,CANA,oBAAA,CAEA,aAAA,CACA,cAAA,CAIA,mBAAA,CAHA,qBAAA,CAHA,YFyJJ,CEjJI,wBACE,aAAA,CACA,eFmJN,CGtLA,eAEE,uYACE,CAFF,gBH0LF,CG/KE,4CACE,yYHiLJ,CGrKA,UAEE,gCAAA,CADA,cHyKF,CGrKE,aAEE,kBAAA,CACA,eAAA,CAFA,kBHyKJ,CCfI,wCE3JF,aAOI,gBHuKJ,CACF,CGnKE,mBACE,mBHqKJ,CC1CI,mCE7IJ,UAwBI,mBAAA,CADA,YHqKF,CGjKE,mBAEE,iBAAA,CADA,eAAA,CAEA,mBHmKJ,CG/JE,iBACE,OAAA,CAEA,0BAAA,CADA,WHkKJ,CACF,CC1DI,sCEhGA,iBACE,0BH6JJ,CACF,CGzJE,qBAGE,gCAAA,CADA,kBAAA,CADA,gBH6JJ,CGxJI,sDAEE,0CAAA,CACA,sCAAA,CAFA,+BH4JN,CGtJI,8BAEE,2CAAA,CACA,uCAAA,CAFA,aH0JN,CIjPE,4BAEE,2CAAA,CACA,mBAAA,CACA,8BAAA,CAHA,iBAAA,CAIA,2BJoPJ,CIjPI,2EACE,8BJmPN,CI/OI,sCACE,qCAAA,CACA,eJiPN,CI9OM,mEACE,kCJgPR,CI1OE,mCAIE,kCAAA,CAAA,0BAAA,CAHA,eAAA,CACA,eAAA,CAKA,yDAAA,CADA,oBAAA,CADA,kBJ6OJ,CIxOI,+CACE,mBJ0ON,CItOI,sDAEE,YAAA,CADA,WJyON,CIpOI,4DACE,oDJsON,CInOM,kEACE,0CJqOR,CIhOI,yCAIE,yCAAA,CACA,gBAAA,CAJA,iBAAA,CAEA,WAAA,CADA,SJqON,CI9NI,mDAIE,aJgON,CIpOI,mDAIE,cJgON,CIpOI,yCAME,eAAA,CALA,QAAA,CAIA,SJ+NN,CI1NI,mDAIE,aJ4NN,CIhOI,mDAIE,cJ4NN,CIhOI,yCAME,+DAAA,CALA,QAAA,CAIA,mBJ2NN,CIvNM,oDACE,kBJyNR,CIrNM,2CACE,kBJuNR,CInNM,6CAEE,YAAA,CADA,WJsNR,CIlNQ,0FACE,gBJoNV,CKrTI,2BACE,YAAA,CACA,iBLwTN,CKpTI,6BACE,cLsTN,CKlTI,sCACE,YAAA,CACA,cAAA,CACA,sBLoTN,CKjTM,wCACE,aAAA,CACA,aLmTR,CK1SI,mCACE,YL4SN,CKzSM,yCAEE,UAAA,CACA,UAAA,CAFA,aL6SR,CKtSI,6CAEE,UL+SN,CKjTI,6CAEE,WL+SN,CKjTI,mCAOE,kBAAA,CANA,aAAA,CAGA,aAAA,CACA,YAAA,CACA,eAAA,CAEA,kBAAA,CACA,sCACE,CAPF,YL8SN,CKnSM,kFACE,oBLqSR,CKlSQ,0FACE,mBLoSV,CK/RM,4CAME,+CAAA,CALA,yCAAA,CAEA,eAAA,CADA,eAAA,CAEA,kBAAA,CACA,iBLkSR,CK7RM,uCACE,aAAA,CAGA,mCAAA,CADA,WAAA,CAEA,uBAAA,CAHA,ULkSR,CKzRE,oCACE,eL2RJ,CKvRE,sEAEE,eLyRJ","file":"custom.css"}

File diff suppressed because one or more lines are too long

View File

@ -1 +0,0 @@
{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"AA2BA,iBACE,cAIE,kBC7BF,CDgCA,QAEE,qBC/BF,CACF,CD0CE,qBACE,aCxCJ,CD6CE,sBACE,aC3CJ,CD+CE,uBACE,UC7CJ,CDgDI,8BAGE,QAAA,CACA,sBAAA,CAHA,iBAAA,CACA,UC5CN,CDkDI,8BAOE,WAAA,CAFA,WAAA,CAFA,MAAA,CAGA,eAAA,CALA,iBAAA,CACA,KAAA,CAEA,UC7CN,CDqDE,uBACE,2BCnDJ,CDuDE,0BACE,aCrDJ,CDyDE,+BACE,cAAA,CACA,uBCvDJ,CD0DI,0EACE,WCxDN,CD4DI,oCAGE,2CAAA,CADA,gCAAA,CADA,aCxDN,CD+DE,4BACE,UAAA,CACA,uBC7DJ,CDgEI,2EACE,SC9DN,CDsEI,wDAEE,cAAA,CAAA,cCpEN,CCwJI,wCFtFA,wDAMI,oBAAA,CAAA,eCnEN,CACF,CDuEI,4BACE,8BAAA,CAAA,kBCrEN,CD0EE,uBACE,eCxEJ,CD2EI,0BACE,eCzEN,CD4EM,6BACE,iBC1ER,CD+EI,6BACE,YAAA,CACA,SC7EN,CDiFI,gCACE,YAAA,CACA,MAAA,CACA,qBC/EN,CDkFM,qCAEE,oBAAA,CADA,mBAAA,CAEA,6BChFR,CDoFM,kDACE,aClFR,CDsFM,qCACE,WCpFR,CD0FE,wBACE,YAAA,CACA,gBCxFJ,CD2FI,4BAEE,kBAAA,CADA,WCxFN,CDgGM,sCACE,aAAA,CACA,kBC9FR,CDkGM,+BACE,aChGR,CDsGE,wBAEE,sBAAA,CADA,iBCnGJ,CDuGI,iDACE,0BCrGN,CDyGI,+BAEE,eAAA,CADA,iBAAA,CAGA,2BAAA,CADA,uCCtGN,CD6GQ,wDACE,SC3GV,CD+GQ,wDACE,0BC7GV,CDiHQ,wDACE,SC/GV,CDqHI,+BACE,yCACE,CAGF,oDAAA,CADA,mBCpHN,CDwHM,mCACE,aCtHR,CD2HI,+BAKE,kDAAA,CADA,gCAAA,CAFA,aAAA,CAIA,SAAA,CAHA,mBAAA,CAFA,iBAAA,CAMA,mBCzHN,CD8HM,8DACE,2BC5HR,CD2HM,8DACE,2BCzHR,CDwHM,8DACE,2BCtHR,CDqHM,8DACE,uBCnHR,CDkHM,8DACE,0BChHR,CD+GM,6DACE,0BC7GR,CD4GM,8DACE,0BC1GR,CElJA,WACE,wCFqJF,CElJE,kBAEE,kBFoJJ,CEjJE,+BAJE,+BFwJJ,CEjJI,sCAEE,kBFkJN,CEhJM,wDACE,0CAAA,CACA,eFkJR,CE7IE,oBAME,kBAAA,CACA,0CAAA,CANA,oBAAA,CAEA,aAAA,CACA,cAAA,CAIA,mBAAA,CAHA,qBAAA,CAHA,YFqJJ,CE7II,wBACE,aAAA,CACA,eF+IN,CGlLA,eAEE,uYACE,CAFF,gBHsLF,CG3KE,4CACE,yYH6KJ,CGjKA,UAEE,gCAAA,CADA,cHqKF,CGjKE,aAEE,kBAAA,CACA,eAAA,CAFA,kBHqKJ,CCXI,wCE3JF,aAOI,gBHmKJ,CACF,CG/JE,mBACE,mBHiKJ,CCtCI,mCE7IJ,UAwBI,mBAAA,CADA,YHiKF,CG7JE,mBAEE,iBAAA,CADA,eAAA,CAEA,mBH+JJ,CG3JE,iBACE,OAAA,CAEA,0BAAA,CADA,WH8JJ,CACF,CCtDI,sCEhGA,iBACE,0BHyJJ,CACF,CGrJE,qBAGE,gCAAA,CADA,kBAAA,CADA,gBHyJJ,CGpJI,sDAEE,0CAAA,CACA,sCAAA,CAFA,+BHwJN,CGlJI,8BAEE,2CAAA,CACA,uCAAA,CAFA,aHsJN,CI7OE,4BAEE,2CAAA,CACA,mBAAA,CACA,8BAAA,CAHA,iBAAA,CAIA,2BJgPJ,CI7OI,2EACE,8BJ+ON,CI3OI,sCACE,qCAAA,CACA,eJ6ON,CI1OM,mEACE,kCJ4OR,CItOE,mCAIE,kCAAA,CAAA,0BAAA,CAHA,eAAA,CACA,eAAA,CAKA,yDAAA,CADA,oBAAA,CADA,kBJyOJ,CIpOI,+CACE,mBJsON,CIlOI,sDAEE,YAAA,CADA,WJqON,CIhOI,4DACE,oDJkON,CI/NM,kEACE,0CJiOR,CI5NI,yCAIE,yCAAA,CACA,gBAAA,CAJA,iBAAA,CAEA,WAAA,CADA,SJiON,CI1NI,mDAIE,aJ4NN,CIhOI,mDAIE,cJ4NN,CIhOI,yCAME,eAAA,CALA,QAAA,CAIA,SJ2NN,CItNI,mDAIE,aJwNN,CI5NI,mDAIE,cJwNN,CI5NI,yCAME,+DAAA,CALA,QAAA,CAIA,mBJuNN,CInNM,oDACE,kBJqNR,CIjNM,2CACE,kBJmNR,CI/MM,6CAEE,YAAA,CADA,WJkNR,CI9MQ,0FACE,gBJgNV,CKjTI,2BACE,YAAA,CACA,iBLoTN,CKhTI,6BACE,cLkTN,CK9SI,sCACE,YAAA,CACA,cAAA,CACA,sBLgTN,CK7SM,wCACE,aAAA,CACA,aL+SR,CKtSI,mCACE,YLwSN,CKrSM,yCAEE,UAAA,CACA,UAAA,CAFA,aLySR,CKlSI,6CAEE,UL2SN,CK7SI,6CAEE,WL2SN,CK7SI,mCAOE,kBAAA,CANA,aAAA,CAGA,aAAA,CACA,YAAA,CACA,eAAA,CAEA,kBAAA,CACA,sCACE,CAPF,YL0SN,CK/RM,kFACE,oBLiSR,CK9RQ,0FACE,mBLgSV,CK3RM,4CAME,+CAAA,CALA,yCAAA,CAEA,eAAA,CADA,eAAA,CAEA,kBAAA,CACA,iBL8RR,CKzRM,uCACE,aAAA,CAGA,mCAAA,CADA,WAAA,CAEA,uBAAA,CAHA,UL8RR,CKrRE,oCACE,eLuRJ,CKnRE,sEAEE,eLqRJ","file":"custom.css"}

View File

@ -0,0 +1,256 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
from __future__ import annotations
import posixpath
import re
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import File, Files
from mkdocs.structure.pages import Page
from re import Match
# -----------------------------------------------------------------------------
# Hooks
# -----------------------------------------------------------------------------
# @todo
def on_page_markdown(
markdown: str, *, page: Page, config: MkDocsConfig, files: Files
):
# Replace callback
def replace(match: Match):
type, args = match.groups()
args = args.strip()
if type == "version":
if args.startswith("insiders-"):
return _badge_for_version_insiders(args, page, files)
else:
return _badge_for_version(args, page, files)
elif type == "sponsors": return _badge_for_sponsors(page, files)
elif type == "flag": return flag(args, page, files)
elif type == "option": return option(args)
elif type == "setting": return setting(args)
elif type == "feature": return _badge_for_feature(args, page, files)
elif type == "plugin": return _badge_for_plugin(args, page, files)
elif type == "extension": return _badge_for_extension(args, page, files)
elif type == "utility": return _badge_for_utility(args, page, files)
elif type == "default":
if args == "none": return _badge_for_default_none(page, files)
elif args == "computed": return _badge_for_default_computed(page, files)
else: return _badge_for_default(args, page, files)
# Otherwise, raise an error
raise RuntimeError(f"Unknown shortcode: {type}")
# Find and replace all external asset URLs in current page
return re.sub(
r"<!-- md:(\w+)(.*?) -->",
replace, markdown, flags = re.I | re.M
)
# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------
# Create a flag of a specific type
def flag(args: str, page: Page, files: Files):
type, *_ = args.split(" ", 1)
if type == "experimental": return _badge_for_experimental(page, files)
elif type == "required": return _badge_for_required(page, files)
elif type == "customization": return _badge_for_customization(page, files)
elif type == "metadata": return _badge_for_metadata(page, files)
elif type == "multiple": return _badge_for_multiple(page, files)
raise RuntimeError(f"Unknown type: {type}")
# Create a linkable option
def option(type: str):
_, *_, name = re.split(r"[.:]", type)
return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
# Create a linkable setting - @todo append them to the bottom of the page
def setting(type: str):
_, *_, name = re.split(r"[.*]", type)
return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
# -----------------------------------------------------------------------------
# Resolve path of file relative to given page - the posixpath always includes
# one additional level of `..` which we need to remove
def _resolve_path(path: str, page: Page, files: Files):
path, anchor, *_ = f"{path}#".split("#")
path = _resolve(files.get_file_from_path(path), page)
return "#".join([path, anchor]) if anchor else path
# Resolve path of file relative to given page - the posixpath always includes
# one additional level of `..` which we need to remove
def _resolve(file: File, page: Page):
path = posixpath.relpath(file.src_uri, page.file.src_uri)
return posixpath.sep.join(path.split(posixpath.sep)[1:])
# -----------------------------------------------------------------------------
# Create badge
def _badge(icon: str, text: str = "", type: str = ""):
classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
return "".join([
f"<span class=\"{classes}\">",
*([f"<span class=\"mdx-badge__icon\">{icon}</span>"] if icon else []),
*([f"<span class=\"mdx-badge__text\">{text}</span>"] if text else []),
f"</span>",
])
# Create sponsors badge
def _badge_for_sponsors(page: Page, files: Files):
icon = "material-heart"
href = _resolve_path("insiders/index.md", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Sponsors only')",
type = "heart"
)
# Create badge for version
def _badge_for_version(text: str, page: Page, files: Files):
spec = text
path = f"changelog/index.md#{spec}"
# Return badge
icon = "material-tag-outline"
href = _resolve_path("conventions.md#version", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Minimum version')",
text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
)
# Create badge for version of Insiders
def _badge_for_version_insiders(text: str, page: Page, files: Files):
spec = text.replace("insiders-", "")
path = f"insiders/changelog.md#{spec}"
# Return badge
icon = "material-tag-heart-outline"
href = _resolve_path("conventions.md#version-insiders", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Minimum version')",
text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
)
# Create badge for feature
def _badge_for_feature(text: str, page: Page, files: Files):
icon = "material-toggle-switch"
href = _resolve_path("conventions.md#feature", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Optional feature')",
text = text
)
# Create badge for plugin
def _badge_for_plugin(text: str, page: Page, files: Files):
icon = "material-floppy"
href = _resolve_path("conventions.md#plugin", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Plugin')",
text = text
)
# Create badge for extension
def _badge_for_extension(text: str, page: Page, files: Files):
icon = "material-language-markdown"
href = _resolve_path("conventions.md#extension", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Markdown extension')",
text = text
)
# Create badge for utility
def _badge_for_utility(text: str, page: Page, files: Files):
icon = "material-package-variant"
href = _resolve_path("conventions.md#utility", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Third-party utility')",
text = text
)
# Create badge for default value
def _badge_for_default(text: str, page: Page, files: Files):
icon = "material-water"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value')",
text = text
)
# Create badge for empty default value
def _badge_for_default_none(page: Page, files: Files):
icon = "material-water-outline"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value is empty')"
)
# Create badge for computed default value
def _badge_for_default_computed(page: Page, files: Files):
icon = "material-water-check"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value is computed')"
)
# Create badge for metadata property flag
def _badge_for_metadata(page: Page, files: Files):
icon = "material-list-box-outline"
href = _resolve_path("conventions.md#metadata", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Metadata property')"
)
# Create badge for required value flag
def _badge_for_required(page: Page, files: Files):
icon = "material-alert"
href = _resolve_path("conventions.md#required", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Required value')"
)
# Create badge for customization flag
def _badge_for_customization(page: Page, files: Files):
icon = "material-brush-variant"
href = _resolve_path("conventions.md#customization", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Customization')"
)
# Create badge for multiple instance flag
def _badge_for_multiple(page: Page, files: Files):
icon = "material-inbox-multiple"
href = _resolve_path("conventions.md#multiple-instances", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Multiple instances')"
)
# Create badge for experimental flag
def _badge_for_experimental(page: Page, files: Files):
icon = "material-flask-outline"
href = _resolve_path("conventions.md#experimental", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Experimental')"
)

View File

@ -3,7 +3,7 @@
-#}
{% extends "base.html" %}
{% block extrahead %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/custom.f7ec4df2.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/custom.024fa163.min.css' | url }}">
{% endblock %}
{% block announce %}
For updates follow <strong>@squidfunk</strong> on

View File

@ -44,7 +44,7 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.046329b4.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.0efb648e.min.css' | url }}">
{% if config.theme.palette %}
{% set palette = config.theme.palette %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.85d0ee34.min.css' | url }}">

View File

@ -80,6 +80,10 @@ class InfoPlugin(BasePlugin[InfoConfig]):
log.error("Please upgrade to the latest version.")
self._help_on_versions_and_exit(present, current)
# Exit if archive creation is disabled
if not self.config.archive:
sys.exit(1)
# Print message that we're creating a bug report
log.info("Started archive creation for bug report")

View File

@ -41,6 +41,9 @@ pipeline = ("stemmer", "stopWordFilter", "trimmer")
# Search plugin configuration
class SearchConfig(Config):
enabled = Type(bool, default = True)
# Settings for search
lang = Optional(LangOption())
separator = Optional(Type(str))
pipeline = ListOfItems(Choice(pipeline), default = [])

View File

@ -58,6 +58,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Initialize plugin
def on_config(self, config):
if not self.config.enabled:
return
# Retrieve default value for language
if not self.config.lang:
self.config.lang = [self._translate(
config, "search.config.lang"
@ -104,6 +108,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Add page to search index
def on_page_context(self, context, *, page, config, nav):
if not self.config.enabled:
return
# Index page
self.search_index.add_entry_from_context(page)
page.content = re.sub(
r"\s?data-search-\w+=\"[^\"]+\"",
@ -113,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Generate search index
def on_post_build(self, *, config):
if not self.config.enabled:
return
# Write search index
base = os.path.join(config.site_dir, "search")
path = os.path.join(base, "search_index.json")

View File

@ -79,7 +79,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
if "Image" not in globals():
raise PluginError(
"Required dependencies of \"social\" plugin not found. "
"Install with: pip install pillow cairosvg"
"Install with: pip install \"mkdocs-material[imaging]\""
)
# Move color options

View File

@ -86,12 +86,13 @@ theme:
plugins:
- blog
- search:
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
- minify:
minify_html: true
# Hooks
hooks:
- material/.overrides/hooks/shortcodes.py
- material/.overrides/hooks/translations.py
# Customization
@ -141,11 +142,15 @@ markdown_extensions:
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.magiclink:
normalize_issue_symbols: true
repo_url_shorthand: true
user: squidfunk
repo: mkdocs-material
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.snippets:
auto_append:
- includes/mkdocs.md
- pymdownx.superfences:
custom_fences:
- name: mermaid
@ -153,6 +158,10 @@ markdown_extensions:
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
combine_header_slug: true
slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
@ -165,6 +174,7 @@ nav:
- Creating your site: creating-your-site.md
- Publishing your site: publishing-your-site.md
- Customization: customization.md
- Conventions: conventions.md
- Browser support: browser-support.md
- Enterprise feedback: enterprise-support.md
- Philosophy: philosophy.md
@ -207,8 +217,23 @@ nav:
- setup/extensions/index.md
- Python Markdown: setup/extensions/python-markdown.md
- Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
- Dependencies:
- setup/dependencies/image-processing.md
- Plugins:
- plugins/index.md
- Blog: plugins/blog.md
- Group: plugins/group.md
- Info: plugins/info.md
- Meta: plugins/meta.md
- Offline: plugins/offline.md
- Optimize: plugins/optimize.md
- Privacy: plugins/privacy.md
- Projects: plugins/projects.md
- Search: plugins/search.md
- Social: plugins/social.md
- Tags: plugins/tags.md
- Typeset: plugins/typeset.md
- Requirements:
- Image processing: plugins/requirements/image-processing.md
- Caching: plugins/requirements/caching.md
- Reference:
- reference/index.md
- Admonitions: reference/admonitions.md

View File

@ -49,6 +49,17 @@ classifiers = [
"Topic :: Text Processing :: Markup :: HTML",
]
[project.optional-dependencies]
recommended = [
"mkdocs-minify-plugin~=0.7",
"mkdocs-redirects~=1.2",
"mkdocs-rss-plugin~=1.6"
]
imaging = [
"pillow~=9.4",
"cairosvg~=2.6"
]
[project.urls]
Documentation = "https://squidfunk.github.io/mkdocs-material/"
Source = "https://github.com/squidfunk/mkdocs-material"

View File

@ -86,11 +86,53 @@
animation: heart 1000ms infinite;
}
// Insiders color (for links, etc.)
// Insiders color (for links, etc.) // remove
.mdx-insiders {
color: $clr-pink-500;
}
// BETA #####################################################################
// Badge
.mdx-badge {
font-size: .85em;
// Badge with heart
&--heart {
--md-typeset-a-color: hsla(#{hex2hsl($clr-pink-500)}, 1);
--md-accent-fg-color: hsla(#{hex2hsl($clr-pink-a200)}, 1);
--md-accent-fg-color--transparent: hsla(#{hex2hsl($clr-pink-500)}, 0.1);
// Animate icon
.twemoji {
animation: heart 1000ms infinite;
}
}
// Badge icon
&__icon {
padding: px2rem(4px);
background: var(--md-accent-fg-color--transparent);
border-start-start-radius: px2rem(2px);
border-end-start-radius: px2rem(2px);
// If icon is alone, round corners
&:last-child {
border-radius: px2rem(2px);
}
}
// Badge text
&__text {
padding: px2rem(4px) px2rem(6px);
border-start-end-radius: px2rem(2px);
border-end-end-radius: px2rem(2px);
box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
}
}
// BETA #####################################################################
// Switch buttons
.mdx-switch button {
cursor: pointer;
@ -109,17 +151,6 @@
}
}
// Deprecation
.mdx-deprecated {
opacity: 0.5;
transition: opacity 250ms;
// Deprecation on focus/hover
&:is(:focus-within, :hover) {
opacity: 1;
}
}
// Two-column layout
.mdx-columns {
@ -185,33 +216,6 @@
}
}
// Blog author
.mdx-author {
display: flex;
font-size: px2rem(13.6px);
// Blog author image
img {
height: px2rem(40px);
border-radius: 100%;
}
// Blog author content
p {
// TODO: refactor, use dedicated classes
&:first-child {
flex-shrink: 0;
margin-right: px2rem(16px);
}
// Blog metadata
> span {
display: block;
}
}
}
// Social card
.mdx-social {
position: relative;

View File

@ -0,0 +1,256 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
from __future__ import annotations
import posixpath
import re
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import File, Files
from mkdocs.structure.pages import Page
from re import Match
# -----------------------------------------------------------------------------
# Hooks
# -----------------------------------------------------------------------------
# @todo
def on_page_markdown(
markdown: str, *, page: Page, config: MkDocsConfig, files: Files
):
# Replace callback
def replace(match: Match):
type, args = match.groups()
args = args.strip()
if type == "version":
if args.startswith("insiders-"):
return _badge_for_version_insiders(args, page, files)
else:
return _badge_for_version(args, page, files)
elif type == "sponsors": return _badge_for_sponsors(page, files)
elif type == "flag": return flag(args, page, files)
elif type == "option": return option(args)
elif type == "setting": return setting(args)
elif type == "feature": return _badge_for_feature(args, page, files)
elif type == "plugin": return _badge_for_plugin(args, page, files)
elif type == "extension": return _badge_for_extension(args, page, files)
elif type == "utility": return _badge_for_utility(args, page, files)
elif type == "default":
if args == "none": return _badge_for_default_none(page, files)
elif args == "computed": return _badge_for_default_computed(page, files)
else: return _badge_for_default(args, page, files)
# Otherwise, raise an error
raise RuntimeError(f"Unknown shortcode: {type}")
# Find and replace all external asset URLs in current page
return re.sub(
r"<!-- md:(\w+)(.*?) -->",
replace, markdown, flags = re.I | re.M
)
# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------
# Create a flag of a specific type
def flag(args: str, page: Page, files: Files):
type, *_ = args.split(" ", 1)
if type == "experimental": return _badge_for_experimental(page, files)
elif type == "required": return _badge_for_required(page, files)
elif type == "customization": return _badge_for_customization(page, files)
elif type == "metadata": return _badge_for_metadata(page, files)
elif type == "multiple": return _badge_for_multiple(page, files)
raise RuntimeError(f"Unknown type: {type}")
# Create a linkable option
def option(type: str):
_, *_, name = re.split(r"[.:]", type)
return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
# Create a linkable setting - @todo append them to the bottom of the page
def setting(type: str):
_, *_, name = re.split(r"[.*]", type)
return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
# -----------------------------------------------------------------------------
# Resolve path of file relative to given page - the posixpath always includes
# one additional level of `..` which we need to remove
def _resolve_path(path: str, page: Page, files: Files):
path, anchor, *_ = f"{path}#".split("#")
path = _resolve(files.get_file_from_path(path), page)
return "#".join([path, anchor]) if anchor else path
# Resolve path of file relative to given page - the posixpath always includes
# one additional level of `..` which we need to remove
def _resolve(file: File, page: Page):
path = posixpath.relpath(file.src_uri, page.file.src_uri)
return posixpath.sep.join(path.split(posixpath.sep)[1:])
# -----------------------------------------------------------------------------
# Create badge
def _badge(icon: str, text: str = "", type: str = ""):
classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
return "".join([
f"<span class=\"{classes}\">",
*([f"<span class=\"mdx-badge__icon\">{icon}</span>"] if icon else []),
*([f"<span class=\"mdx-badge__text\">{text}</span>"] if text else []),
f"</span>",
])
# Create sponsors badge
def _badge_for_sponsors(page: Page, files: Files):
icon = "material-heart"
href = _resolve_path("insiders/index.md", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Sponsors only')",
type = "heart"
)
# Create badge for version
def _badge_for_version(text: str, page: Page, files: Files):
spec = text
path = f"changelog/index.md#{spec}"
# Return badge
icon = "material-tag-outline"
href = _resolve_path("conventions.md#version", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Minimum version')",
text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
)
# Create badge for version of Insiders
def _badge_for_version_insiders(text: str, page: Page, files: Files):
spec = text.replace("insiders-", "")
path = f"insiders/changelog.md#{spec}"
# Return badge
icon = "material-tag-heart-outline"
href = _resolve_path("conventions.md#version-insiders", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Minimum version')",
text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
)
# Create badge for feature
def _badge_for_feature(text: str, page: Page, files: Files):
icon = "material-toggle-switch"
href = _resolve_path("conventions.md#feature", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Optional feature')",
text = text
)
# Create badge for plugin
def _badge_for_plugin(text: str, page: Page, files: Files):
icon = "material-floppy"
href = _resolve_path("conventions.md#plugin", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Plugin')",
text = text
)
# Create badge for extension
def _badge_for_extension(text: str, page: Page, files: Files):
icon = "material-language-markdown"
href = _resolve_path("conventions.md#extension", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Markdown extension')",
text = text
)
# Create badge for utility
def _badge_for_utility(text: str, page: Page, files: Files):
icon = "material-package-variant"
href = _resolve_path("conventions.md#utility", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Third-party utility')",
text = text
)
# Create badge for default value
def _badge_for_default(text: str, page: Page, files: Files):
icon = "material-water"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value')",
text = text
)
# Create badge for empty default value
def _badge_for_default_none(page: Page, files: Files):
icon = "material-water-outline"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value is empty')"
)
# Create badge for computed default value
def _badge_for_default_computed(page: Page, files: Files):
icon = "material-water-check"
href = _resolve_path("conventions.md#default", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Default value is computed')"
)
# Create badge for metadata property flag
def _badge_for_metadata(page: Page, files: Files):
icon = "material-list-box-outline"
href = _resolve_path("conventions.md#metadata", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Metadata property')"
)
# Create badge for required value flag
def _badge_for_required(page: Page, files: Files):
icon = "material-alert"
href = _resolve_path("conventions.md#required", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Required value')"
)
# Create badge for customization flag
def _badge_for_customization(page: Page, files: Files):
icon = "material-brush-variant"
href = _resolve_path("conventions.md#customization", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Customization')"
)
# Create badge for multiple instance flag
def _badge_for_multiple(page: Page, files: Files):
icon = "material-inbox-multiple"
href = _resolve_path("conventions.md#multiple-instances", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Multiple instances')"
)
# Create badge for experimental flag
def _badge_for_experimental(page: Page, files: Files):
icon = "material-flask-outline"
href = _resolve_path("conventions.md#experimental", page, files)
return _badge(
icon = f"[:{icon}:]({href} 'Experimental')"
)

View File

@ -50,7 +50,6 @@
font-weight: 700;
line-height: 1.6;
letter-spacing: initial;
vertical-align: middle;
background: var(--md-default-fg-color--lightest);
border-radius: px2rem(48px);

View File

@ -80,6 +80,10 @@ class InfoPlugin(BasePlugin[InfoConfig]):
log.error("Please upgrade to the latest version.")
self._help_on_versions_and_exit(present, current)
# Exit if archive creation is disabled
if not self.config.archive:
sys.exit(1)
# Print message that we're creating a bug report
log.info("Started archive creation for bug report")

View File

@ -41,6 +41,9 @@ pipeline = ("stemmer", "stopWordFilter", "trimmer")
# Search plugin configuration
class SearchConfig(Config):
enabled = Type(bool, default = True)
# Settings for search
lang = Optional(LangOption())
separator = Optional(Type(str))
pipeline = ListOfItems(Choice(pipeline), default = [])

View File

@ -58,6 +58,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Initialize plugin
def on_config(self, config):
if not self.config.enabled:
return
# Retrieve default value for language
if not self.config.lang:
self.config.lang = [self._translate(
config, "search.config.lang"
@ -104,6 +108,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Add page to search index
def on_page_context(self, context, *, page, config, nav):
if not self.config.enabled:
return
# Index page
self.search_index.add_entry_from_context(page)
page.content = re.sub(
r"\s?data-search-\w+=\"[^\"]+\"",
@ -113,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
# Generate search index
def on_post_build(self, *, config):
if not self.config.enabled:
return
# Write search index
base = os.path.join(config.site_dir, "search")
path = os.path.join(base, "search_index.json")

View File

@ -79,7 +79,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
if "Image" not in globals():
raise PluginError(
"Required dependencies of \"social\" plugin not found. "
"Install with: pip install pillow cairosvg"
"Install with: pip install \"mkdocs-material[imaging]\""
)
# Move color options