starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-08-02 10:48:49 -04:00
Code Issues Packages Projects Releases Wiki Activity

Restructured documentation (#5692)

Browse Source
This commit is contained in:
Martin Donath
2023-09-14 19:09:18 +02:00
committed by GitHub
parent 19437db8fc
commit cd008fdf29
83 changed files with 6877 additions and 3354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

@@ -11,10 +11,10 @@ further useful automatic optimization techniques.
### Built-in projects plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.38.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
<!-- md:sponsors -->
<!-- md:version insiders-4.38.0 -->
<!-- md:plugin [projects] – built-in -->
<!-- md:flag experimental -->
The built-in projects plugin allows to split your documentation into multiple
distinct MkDocs projects, __build them concurrently__ and
@@ -25,31 +25,10 @@ plugins:
- projects
```
Next, create a folder called `projects` in your root directory which will
contain all projects. For example, if we want to build a project with two
additional languages, we can use:
For a list of all settings, please consult the [plugin documentation].
``` { .sh .no-copy }
.
├─ projects/
│ ├─ de/
│ │ ├─ docs/
│ │ └─ mkdocs.yml
│ └─ fr/
│ ├─ docs/
│ └─ mkdocs.yml
└─ mkdocs.yml
```
If you now invoke `mkdocs serve` and change a file in one of the projects,
the projects plugin makes sure that MkDocs will also reload those files. Note
that the projects are currently entirely separate, which means they will have
separate search indexes and sitemaps. We're happy to receive feedback on this
plugin and learn about your requirements to make it better, as we plan to add
support for merging and hoisting files.
[Create a discussion to share your thoughts!][discussion]
[discussion]: https://github.com/squidfunk/mkdocs-material/discussions
[projects]: ../plugins/projects.md
[plugin documentation]: ../plugins/projects.md
??? info "Use cases for the projects plugin"
@@ -63,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

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

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

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

@@ -1,7 +1,7 @@
# Changing the colors
As any proper Material Design implementation, Material for MkDocs supports
Google's original [color palette], which can be easily configured through
Google's original [color palette], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][custom colors].
@@ -14,8 +14,8 @@ fit your brand's identity by using [CSS variables][custom colors].
#### Color scheme
[:octicons-tag-24: 5.2.0][Color scheme support] ·
:octicons-milestone-24: Default: `default`
<!-- md:version 5.2.0 -->
<!-- md:default `default` -->
Material for MkDocs supports two color schemes: a __light mode__, which is just
called `default`, and a __dark mode__, which is called `slate`. The color scheme
@@ -50,12 +50,10 @@ Click on a tile to change the color scheme:
})
</script>
[Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color
[:octicons-tag-24: 0.2.0][Primary color support] ·
:octicons-milestone-24: Default: `indigo`
<!-- md:version 0.2.0 -->
<!-- md:default `indigo` -->
The primary color is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
@@ -107,12 +105,10 @@ Click on a tile to change the primary color:
See our guide below to learn how to set [custom colors].
[Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color
[:octicons-tag-24: 0.2.0][Accent color support] ·
:octicons-milestone-24: Default: `indigo`
<!-- md:version 0.2.0 -->
<!-- md:default `indigo` -->
The accent color is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
@@ -166,12 +162,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

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

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

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

@@ -9,8 +9,8 @@ available.
### Site language
[:octicons-tag-24: 1.12.0][Site language support] ·
:octicons-milestone-24: Default: `en`
<!-- md:version 1.12.0 -->
<!-- md:default `en` -->
You can set the site language in `mkdocs.yml` with:
@@ -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

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

@@ -1,7 +1,7 @@
# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 8,000
icons_ ready to be used for customization of specific parts of the theme and/or
When installing Material for MkDocs, you immediately get access to _over 8,000
icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also add
[additional icons] with minimal effort.
@@ -11,8 +11,8 @@ when writing your documentation in Markdown. Not enough? You can also add
### Logo
[:octicons-tag-24: 0.1.0][Logo support] ·
:octicons-milestone-24: Default: :material-library: – `material/library`
<!-- md:version 0.1.0 -->
<!-- md:default `material/library` -->
The logo can be changed to a user-provided image (any type, incl. `*.png` and
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
@@ -44,7 +44,6 @@ Add the following lines to `mkdocs.yml`:
</div>
</div>
[Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
Normally, the logo in the header and sidebar links to the homepage of the
@@ -58,10 +57,10 @@ extra:
### Favicon
[:octicons-tag-24: 0.1.0][Favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
<!-- md:version 0.1.0 -->
<!-- md:default [`assets/images/favicon.png`][Favicon default] -->
The favicon can be changed to a path pointing to a user-provided image, which
The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml
@@ -69,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

118
docs/setup/dependencies/image-processing.md
View File

@@ -1,118 +0,0 @@
# 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.
[social cards]: ../setting-up-social-cards.md
[image optimization]: ../building-an-optimized-site.md
## Dependencies
Install the Python dependencies for image processing with:
```
pip install pillow cairosvg
```
### Cairo Graphics
[Cairo Graphics] is a graphics library and dependency of [Pillow], which
Material for MkDocs makes use of for generating [social cards] and performing
[image optimization]. See the following section which explains how to install
[Cairo Graphics] and its dependencies on your system:
=== ":material-apple: macOS"
Make sure [Homebrew] is installed, which is a modern package manager for
macOS. Next, use the following command to install all necessary
dependencies:
```
brew install cairo freetype libffi libjpeg libpng zlib
```
=== ":fontawesome-brands-windows: Windows"
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].
=== ":material-linux: Linux"
There are several package managers for Linux with varying availability per
distribution. The [installation guide] explains how to install the [Cairo
Graphics] library for your distribution:
=== ":material-ubuntu: Ubuntu"
```
apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
```
=== ":material-fedora: Fedora"
```
yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
```
=== ":fontawesome-brands-suse: openSUSE"
```
zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
```
The following environments come with a preinstalled version of [Cairo Graphics]:
- [x] No installation needed in [Docker image]
- [x] No installation needed in [GitHub Actions] (Ubuntu)
[Cairo Graphics]: https://www.cairographics.org/
[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/
[GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[GitHub Actions]: ../../publishing-your-site.md#with-github-actions
### pngquant
[pngquant] is an excellent library for lossy PNG compression, and a direct
dependency of the [built-in optimize plugin]. See the following section which
explains how to install [pngquant] system:
=== ":material-apple: macOS"
Make sure [Homebrew] is installed, which is a modern package manager for
macOS. Next, use the following command to install all necessary
dependencies:
```
brew install pngquant
```
=== ":fontawesome-brands-windows: Windows"
Installing [pngquant] on Windows is a little more involved. The
[pngquant-winbuild] repository contains a guide on how to set up an
environment for building [pngquant] on Windows.
=== ":material-linux: Linux"
All popular Linux distributions, regardless of package manager, should
allow to install [pngquant] with the bundled package manager. For example,
on Ubuntu, [pngquant] can be installed with:
```
apt-get install pngquant
```
The same is true for `yum` and `zypper`.
[pngquant]: https://pngquant.org/
[built-in optimize plugin]: ../building-an-optimized-site.md#built-in-optimize-plugin
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild

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

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

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

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

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

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

4
docs/setup/index.md
View File

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

965
docs/setup/setting-up-a-blog.md
View File

File diff suppressed because it is too large Load Diff

103
docs/setup/setting-up-navigation.md
View File

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

39
docs/setup/setting-up-site-analytics.md
View File

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

263
docs/setup/setting-up-site-search.md
View File

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

547
docs/setup/setting-up-social-cards.md
View File

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

211
docs/setup/setting-up-tags.md
View File

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

53
docs/setup/setting-up-the-footer.md
View File

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

20
docs/setup/setting-up-the-header.md
View File

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

14
docs/setup/setting-up-versioning.md
View File

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