mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-14 10:57:41 +01:00
Merge branch 'master' of https://github.com/mendax1234/mkdocs-material
This commit is contained in:
Daniel Webber
commit
6f2ee54c52
@ -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
|
||||
|
||||
@ -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 \
|
||||
|
||||
@ -9,7 +9,7 @@ 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
|
||||
---
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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 -->.
|
||||
|
||||
@ -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: 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
|
||||
|
||||
88
docs/conventions.md
Normal file
88
docs/conventions.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Conventions
|
||||
|
||||
This section explains several conventions used in this documentation.
|
||||
|
||||
## Symbols
|
||||
|
||||
This documentation use some symbols for illustration purposes. Before you read
|
||||
on, please make sure you've made yourself familiar with the following list of
|
||||
conventions:
|
||||
|
||||
### <!-- md:sponsors --> – Sponsors only { data-toc-label="Sponsors only" }
|
||||
|
||||
The pumping heart symbol denotes that a specific feature or behavior is only
|
||||
available to sponsors via [Insiders]. Make sure that you have access to
|
||||
[Insiders] if you want to use the feature.
|
||||
|
||||
### <!-- md:version --> – Version { data-toc-label="Version" }
|
||||
|
||||
The tag symbol in conjunction with a version number denotes when a specific
|
||||
feature or behavior was added. Make sure you're at least on this version
|
||||
if you want to use it.
|
||||
|
||||
### <!-- md:version insiders- --> – Version (Insiders) { data-toc-label="Version (Insiders)" }
|
||||
|
||||
The tag symbol with a heart in conjunction with a version number denotes that a
|
||||
specific feature or behavior was added to the [Insiders] version of Material for
|
||||
MkDocs.
|
||||
|
||||
### <!-- md:default --> – Default value { #default data-toc-label="Default value" }
|
||||
|
||||
Some properties in `mkdocs.yml` have default values for when the author does not
|
||||
explicitly define them. The default value of the property is always included.
|
||||
|
||||
#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
|
||||
|
||||
Some default values are not set to static values but computed form other values,
|
||||
like the site language, repository provider, or other settings.
|
||||
|
||||
#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }
|
||||
|
||||
Some properties do not contain default values. This means that the functionality
|
||||
that is associated with them is not available unless explicitly enabled.
|
||||
|
||||
### <!-- md:flag metadata --> – Metadata property { #metadata data-toc-label="Metadata property" }
|
||||
|
||||
This symbol denotes that the thing described is a metadata property, which can
|
||||
be used in Markdown documents as part of the front matter definition.
|
||||
|
||||
### <!-- md: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:extension --> – Markdown extension { data-toc-label="Markdown extension" }
|
||||
|
||||
This symbol denotes that the thing described is a Markdown extension, which can
|
||||
be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
|
||||
parser.
|
||||
|
||||
### <!-- md:flag required --> – Required value { #required data-toc-label="Required value" }
|
||||
|
||||
Some (very few in fact) properties or settings are required, which means the
|
||||
authors must explicitly define them.
|
||||
|
||||
### <!-- md:flag customization --> – Customization { #customization data-toc-label="Customization" }
|
||||
|
||||
This symbol denotes that the thing described is a customization that must be
|
||||
added by the author.
|
||||
|
||||
### <!-- md:utility --> – Utility { data-toc-label="Utility" }
|
||||
|
||||
Besides plugins, there are some utilities that build on top of MkDocs in order
|
||||
to provide extended functionality, like for example support for versioning.
|
||||
|
||||
[Insiders]: insiders/index.md
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 } Insiders][Insiders]{ .mdx-insiders }
|
||||
|
||||
: Some features are not yet available in the community edition, but only as
|
||||
part of the Insiders build of Material for MkDocs. Please consult the
|
||||
[Insiders] guide to learn how to get access.
|
||||
|
||||
:octicons-tag-24: __{x.x.x}__
|
||||
|
||||
: The tag icon in conjunction with a version number denotes when a specific
|
||||
feature or behavior was added. Make sure you're at least on this version
|
||||
if you want to use it.
|
||||
|
||||
:octicons-file-code-24: __{file.ext}__
|
||||
|
||||
: The source file icon together with a file name is sometimes used in code
|
||||
examples which span multiple files. The file name (or path) always starts
|
||||
from the location of `mkdocs.yml`.
|
||||
|
||||
:octicons-milestone-24: __Default__: _value_
|
||||
|
||||
: Some properties in `mkdocs.yml` have default values for when the author
|
||||
does not explicitly define them. The default value of the property is always
|
||||
included.
|
||||
|
||||
:octicons-unlock-24: __Feature flag__
|
||||
|
||||
: Most of the features are hidden behind feature flags, which means they must
|
||||
be explicitly enabled via `mkdocs.yml`. This allows for the existence of
|
||||
potentially orthogonal features.
|
||||
|
||||
:octicons-beaker-24: __Experimental__
|
||||
|
||||
: Some newer features are still considered experimental, which means they
|
||||
might (although rarely) change at any time, including their complete removal
|
||||
(which hasn't happened yet).
|
||||
|
||||
|
||||
:octicons-cpu-24: __Plugin__
|
||||
|
||||
: Several features are implemented through MkDocs excellent plugin
|
||||
architecture, some of which are built-in and distributed with Material for
|
||||
MkDocs, so no installation is required.
|
||||
|
||||
:octicons-package-24: __Utility__
|
||||
|
||||
: Besides plugins, there are some utilities that build on top of MkDocs in
|
||||
order to provide extended functionality, like for example support for
|
||||
versioning.
|
||||
|
||||
[Insiders]: insiders/index.md
|
||||
|
||||
1460
docs/plugins/blog.md
Normal file
1460
docs/plugins/blog.md
Normal file
File diff suppressed because it is too large
Load Diff
121
docs/plugins/group.md
Normal file
121
docs/plugins/group.md
Normal 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
246
docs/plugins/index.md
Normal 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: __[Built-in group plugin][group]__
|
||||
|
||||
---
|
||||
|
||||
The group plugin allows to group plugins into logical units to conditionally
|
||||
enable or disable them for specific environments with the use of
|
||||
[environment variables][mkdocs.env].
|
||||
|
||||
---
|
||||
|
||||
__Optimal management of plugins when building in different environments__
|
||||
|
||||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to manage metadata (front matter) for all
|
||||
pages in a folder, so a certain subset of pages uses specific tags or a
|
||||
custom template.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization, categorization and management of metadata__
|
||||
|
||||
- :material-folder-open: __[Built-in projects plugin][projects]__
|
||||
|
||||
---
|
||||
|
||||
The projects plugin allows to split your main project into multiple distinct
|
||||
projects, build them concurrently and preview them together as one.
|
||||
|
||||
---
|
||||
|
||||
__Connect multiple projects together, and build them separately or as one__
|
||||
|
||||
- :material-information: __[Built-in info plugin][info]__
|
||||
|
||||
---
|
||||
|
||||
The info plugin is a small and useful utility that helps to create
|
||||
self-contained minimal reproductions, so we maintainers can fix reported
|
||||
bugs more quickly.
|
||||
|
||||
---
|
||||
|
||||
__Your bug reports are of the highest quality, so we can fix them as fast as
|
||||
possible__
|
||||
|
||||
|
||||
</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: __[Built-in social plugin][social]__
|
||||
|
||||
---
|
||||
|
||||
The social plugin automatically generates beautiful and customizable
|
||||
social cards for each page of your documentation, showing as previews on
|
||||
social media.
|
||||
|
||||
---
|
||||
|
||||
__Links to your site render beautiful social cards when shared on social
|
||||
media__
|
||||
|
||||
- :material-rabbit: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin automatically identifies and optimizes all media files
|
||||
that you reference in your project by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__Your site loads faster as smaller images are served to your users__
|
||||
|
||||
- :material-shield-account: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin downloads external assets automatically for easy
|
||||
self-hosting, allowing for GDPR compliance with a single line of
|
||||
configuration.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be made GDPR compliant with minimal effort__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building [offline-capable documentation],
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
</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: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The blog plugin adds first-class support for blogging to Material for
|
||||
MkDocs, either as a sidecar to your documentation or as a standalone
|
||||
installation.
|
||||
|
||||
---
|
||||
|
||||
__Your blog is built with the same powerful engine as your documentation__
|
||||
|
||||
- :material-magnify: __[Built-in search plugin][search]__
|
||||
|
||||
---
|
||||
|
||||
The search plugin adds a search bar to the header, allowing users to search
|
||||
the entire documentation, so it's easier for them to find what they're
|
||||
looking for.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation is searchable without any external services, even
|
||||
offline__
|
||||
|
||||
- :material-tag-text: __[Built-in tags plugin][tags]__
|
||||
|
||||
---
|
||||
|
||||
The tags plugin adds first-class support for categorizing pages with tags,
|
||||
adding the ability to group related pages to improve the discovery of
|
||||
related content.
|
||||
|
||||
---
|
||||
|
||||
__Your pages are categorized with tags, yielding additional context__
|
||||
|
||||
- :material-format-title: __[Built-in typeset plugin][typeset]__
|
||||
|
||||
---
|
||||
|
||||
The typeset plugin allows to preserve the enriched presentation of titles
|
||||
and headlines within the navigation and table of contents.
|
||||
|
||||
---
|
||||
|
||||
__Sidebars preserve the same formatting as section titles in pages__
|
||||
|
||||
</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
155
docs/plugins/info.md
Normal 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
195
docs/plugins/meta.md
Normal 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: __[Built-in social plugin][social]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin can be used to [change the layout] for social cards or
|
||||
[change specific layout options] like [background] or [color]
|
||||
for a subset of pages.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
social:
|
||||
cards_layout: default/variant
|
||||
```
|
||||
|
||||
- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin allows to automatically associate blog posts with specific
|
||||
[authors] and [categories], ensuring that blog posts are always correctly
|
||||
annotated.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
authors:
|
||||
- squidfunk
|
||||
```
|
||||
|
||||
- :material-tag-text: __[Built-in tags plugin][tags]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it possible to ensure that subsections of your
|
||||
project are annotated with [specific tags], so they can't be forgotten when
|
||||
adding pages.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
tags:
|
||||
- Example
|
||||
```
|
||||
|
||||
- :material-magnify: __[Built-in search plugin][search]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to [boost] specific sections in search results
|
||||
or to [exclude] them entirely from being indexed, giving more granular
|
||||
control over search.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
search:
|
||||
exclude: true
|
||||
```
|
||||
|
||||
</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
153
docs/plugins/offline.md
Normal 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: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin makes it easy to use external assets when building for
|
||||
offline usage, as it automatically downloads them for distribution with
|
||||
your documentation.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet[^1]__
|
||||
|
||||
- :material-rabbit: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin automatically identifies and optimizes all media files
|
||||
that you reference in your project by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be distributed as a smaller `.zip` download__
|
||||
|
||||
</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
443
docs/plugins/optimize.md
Normal 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: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin makes it easy to use unoptimized external assets, passing
|
||||
them to the optimize plugin before copying them to the [`site` directory]
|
||||
[mkdocs.site_dir].
|
||||
|
||||
---
|
||||
|
||||
__External media files can be automatically downloaded and optimized__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building offline-capable documentation,
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be distributed as a smaller `.zip` download__
|
||||
|
||||
</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
416
docs/plugins/privacy.md
Normal 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: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin allows to optimize all downloaded external assets
|
||||
detected by the privacy plugin by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__External media files are automatically downloaded and optimized__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building [offline-capable documentation],
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
</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
264
docs/plugins/projects.md
Normal 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.
|
||||
35
docs/plugins/requirements/caching.md
Normal file
35
docs/plugins/requirements/caching.md
Normal 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
|
||||
@ -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/
|
||||
@ -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
427
docs/plugins/search.md
Normal 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: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building offline-capable documentation,
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to [boost][meta.search.boost] specific
|
||||
sections in search results or to [exclude][meta.search.exclude] them
|
||||
entirely from being indexed, giving more granular control over search.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization and management of search in different subsections__
|
||||
|
||||
</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 `<` and `>`. Adding this
|
||||
subexpression to the separator allows for just that.
|
||||
|
||||
[positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
|
||||
[words are split at case changes]: ?q=searchHighlight
|
||||
[preserve version strings]: ?q=9.0.0
|
||||
[specific tag names]: ?q=script
|
||||
|
||||
---
|
||||
|
||||
#### <!-- 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
1059
docs/plugins/social.md
Normal file
File diff suppressed because it is too large
Load Diff
376
docs/plugins/tags.md
Normal file
376
docs/plugins/tags.md
Normal 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: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it possible to ensure that subsections of your
|
||||
project are annotated with [specific tags][meta.tags], so they can't be
|
||||
forgotten when adding pages.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization and management of tags in different subsections__
|
||||
|
||||
- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The tags plugin allows to categorize posts alongside with pages in your
|
||||
project, to improve their discoverability and connect posts to your
|
||||
documentation.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation's tag system integrates with your blog__
|
||||
|
||||
</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
82
docs/plugins/typeset.md
Normal 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
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -159,14 +156,13 @@ theme:
|
||||
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
|
||||
@ -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
|
||||
|
||||
@ -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,8 +73,8 @@ 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
|
||||
@ -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
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -31,8 +31,8 @@ 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
|
||||
[glightbox] plugin is an excellent choice, as it integrates perfectly
|
||||
@ -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
|
||||
|
||||
@ -7,68 +7,6 @@ within Markdown files.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in <u>typeset</u> plugin
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.27.0][Insiders] ·
|
||||
:octicons-cpu-24: Plugin ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
The built-in typeset plugin __preserves HTML formatting__ in the navigation and
|
||||
table of contents. This means that now, code blocks, icons, emojis and other
|
||||
inline formatting will be preserved, which allows for a richer editing
|
||||
experience. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- typeset
|
||||
```
|
||||
|
||||
For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: – code blocks and icons are preserved from the
|
||||
section headlines; even [highlighting inline code blocks] is supported :tada:
|
||||
|
||||
[highlighting inline code blocks]: code-blocks.md#highlighting-inline-code-blocks
|
||||
|
||||
### Built-in meta plugin
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.21.0][Insiders] ·
|
||||
:octicons-cpu-24: Plugin ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
The built-in meta plugin allows to __set front matter per folder__, which is
|
||||
especially handy to ensure that all pages in a folder use specific templates or
|
||||
tags. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta
|
||||
```
|
||||
|
||||
> If you need to be able to build your documentation with and without
|
||||
> [Insiders], please refer to the [built-in plugins] section to learn how
|
||||
> shared configurations help to achieve this.
|
||||
|
||||
The following configuration options are available:
|
||||
|
||||
[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
|
||||
|
||||
: :octicons-milestone-24: Default: `.meta.yml` – This option specifies the
|
||||
name of the meta files that the plugin should look for. The default setting
|
||||
assumes that meta files are called `.meta.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta:
|
||||
meta_file: .meta.yml # (1)!
|
||||
```
|
||||
|
||||
1. Note that it's strongly recommended to prefix meta files with a `.`,
|
||||
since otherwise they would be included in the build output.
|
||||
|
||||
[built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin
|
||||
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
|
||||
|
||||
## Usage
|
||||
|
||||
### Setting the page `title`
|
||||
@ -83,7 +21,7 @@ explicitly set with the front matter `title` property:
|
||||
title: Lorem ipsum dolor sit amet # (1)!
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -110,7 +48,7 @@ the author does not explicitly define a description for a Markdown file:
|
||||
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -121,8 +59,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
|
||||
|
||||
### Setting the page `icon`
|
||||
|
||||
[:octicons-tag-24: 9.2.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 +72,7 @@ top of a Markdown file:
|
||||
icon: material/emoticon-happy # (1)!
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -149,15 +87,14 @@ 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
|
||||
@ -188,7 +125,7 @@ Markdown file:
|
||||
status: new
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -197,13 +134,11 @@ The following status identifiers are currently supported:
|
||||
- :material-alert-decagram: – `new`
|
||||
- :material-trash-can: – `deprecated`
|
||||
|
||||
[Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.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,7 +149,7 @@ adding the following lines:
|
||||
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -229,7 +164,7 @@ lines at the top of a Markdown file:
|
||||
template: custom.html
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -244,7 +179,7 @@ template: custom.html
|
||||
```
|
||||
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[built-in meta plugin]: #built-in-meta-plugin
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
## Customization
|
||||
|
||||
|
||||
@ -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,8 +55,6 @@ 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
|
||||
|
||||
@ -93,7 +93,7 @@ property to `true`:
|
||||
comments: true
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
@ -33,16 +33,14 @@ GitHub repositories also include the tag of the latest release.[^1]
|
||||
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,12 +222,9 @@ The following configuration options are supported:
|
||||
enable_creation_date: true
|
||||
```
|
||||
|
||||
!!! note
|
||||
If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code. For more information, see [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments).
|
||||
<!-- md:option git-revision-date-localized.fallback_to_build_date -->
|
||||
|
||||
[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+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:
|
||||
|
||||
@ -248,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
|
||||
@ -283,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]:
|
||||
|
||||
@ -295,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>`:
|
||||
|
||||
@ -307,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
|
||||
@ -329,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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,8 +57,8 @@ 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
|
||||
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
|
||||
@ -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
|
||||
|
||||
@ -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__ –
|
||||
: <!-- 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,9 +100,9 @@ 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
|
||||
: <!-- 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:
|
||||
|
||||
@ -128,7 +128,6 @@ 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
|
||||
@ -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,109 +160,17 @@ 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 }
|
||||
|
||||
: :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:
|
||||
- privacy:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
[`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"
|
||||
!!! 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
|
||||
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
|
||||
@ -275,32 +182,6 @@ The following configuration options are available for external assets:
|
||||
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].
|
||||
|
||||
!!! 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
|
||||
@ -320,95 +201,11 @@ The following configuration options are available for external assets:
|
||||
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
|
||||
|
||||
@ -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
|
||||
@ -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_`
|
||||
@ -104,12 +103,11 @@ 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,9 +256,9 @@ 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
|
||||
: <!-- 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]:
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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:
|
||||
@ -427,9 +420,9 @@ markdown_extensions:
|
||||
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,8 +473,8 @@ 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
|
||||
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
|
||||
@ -505,15 +496,14 @@ 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
|
||||
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
|
||||
@ -533,14 +523,13 @@ 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
|
||||
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
|
||||
@ -556,12 +545,11 @@ 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
|
||||
@ -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,9 +725,9 @@ 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
|
||||
: <!-- md:default `false` --> This option toggles the rendering
|
||||
style of checkboxes, replacing native checkbox styles with beautiful icons,
|
||||
and is therefore recommended:
|
||||
|
||||
@ -754,9 +737,9 @@ 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
|
||||
: <!-- 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:
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,14 +29,13 @@ 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
|
||||
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
|
||||
@ -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,15 +165,14 @@ 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
|
||||
@ -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,9 +222,9 @@ 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
|
||||
discernable name, stating that the anchor links to the section itself:
|
||||
@ -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,15 +288,13 @@ 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
|
||||
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
|
||||
@ -320,7 +311,6 @@ 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
|
||||
|
||||
@ -332,24 +322,23 @@ 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
|
||||
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/
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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,8 +216,9 @@ 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
|
||||
@ -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,12 +352,13 @@ 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
|
||||
Markdown file:
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
@ -16,8 +16,8 @@ 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
|
||||
@ -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 `<` and `>`. 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,16 +130,15 @@ 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
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
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,472 +65,9 @@ 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,
|
||||
@ -551,8 +75,8 @@ you can set the front matter [`title`][Changing the title] and
|
||||
[`description`][Changing the description] properties, which take precedence over
|
||||
the defaults, or use:
|
||||
|
||||
- [`cards_layout_options.title`](#+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
|
||||
|
||||
@ -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,
|
||||
@ -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
|
||||
|
||||
@ -378,6 +185,6 @@ hide:
|
||||
- tags
|
||||
---
|
||||
|
||||
# Document title
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
@ -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,12 +22,10 @@ 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`
|
||||
@ -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,9 +70,9 @@ 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__ –
|
||||
: <!-- 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`:
|
||||
|
||||
@ -96,9 +94,9 @@ 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_ –
|
||||
: <!-- 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:
|
||||
|
||||
@ -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 © 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
|
||||
@ -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
|
||||
|
||||
@ -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]: #
|
||||
|
||||
@ -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],
|
||||
@ -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
|
||||
|
||||
11
includes/mkdocs.md
Normal file
11
includes/mkdocs.md
Normal 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
|
||||
1
material/.overrides/assets/stylesheets/custom.024fa163.min.css
vendored
Normal file
1
material/.overrides/assets/stylesheets/custom.024fa163.min.css
vendored
Normal file
File diff suppressed because one or more lines are too long
@ -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
@ -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"}
|
||||
256
material/.overrides/hooks/shortcodes.py
Normal file
256
material/.overrides/hooks/shortcodes.py
Normal 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')"
|
||||
)
|
||||
@ -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
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -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 }}">
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
@ -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 = [])
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
31
mkdocs.yml
31
mkdocs.yml
@ -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
|
||||
|
||||
@ -49,6 +49,21 @@ classifiers = [
|
||||
"Topic :: Text Processing :: Markup :: HTML",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
recommended = [
|
||||
"mkdocs-minify-plugin~=0.7",
|
||||
"mkdocs-redirects~=1.2",
|
||||
"mkdocs-rss-plugin~=1.6"
|
||||
]
|
||||
git = [
|
||||
"mkdocs-git-committers-plugin-2~=1.1",
|
||||
"mkdocs-git-revision-date-localized-plugin~=1.2"
|
||||
]
|
||||
imaging = [
|
||||
"pillow~=9.4",
|
||||
"cairosvg~=2.6"
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Documentation = "https://squidfunk.github.io/mkdocs-material/"
|
||||
Source = "https://github.com/squidfunk/mkdocs-material"
|
||||
|
||||
@ -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;
|
||||
|
||||
256
src/.overrides/hooks/shortcodes.py
Normal file
256
src/.overrides/hooks/shortcodes.py
Normal 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')"
|
||||
)
|
||||
@ -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);
|
||||
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
@ -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 = [])
|
||||
|
||||
@ -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")
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user