Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-23 23:21:00 +01:00
Code Issues Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-10 17:39:53 +02:00
parent 1809b6c013
commit 43cdb91472
23 changed files with 502 additions and 581 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG
View File

@ -138,7 +138,7 @@ mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20)
mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18)
* Improved Mermaid.js intergration, now stable
* Improved Mermaid.js integration, now stable
* Added support for sequence diagrams
* Added support for entity relationship diagrams
* Added support for cookie consent configuration

2
docs/data-privacy.md
View File

@ -19,7 +19,7 @@ CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
disabled][3] via `mkdocs.yml`.
[2]: setup/changing-the-fonts.md
[3]: setup/changing-the-fonts.md#disabling-font-loading
[3]: setup/changing-the-fonts.md#autoloading
### Google Analytics and Disqus

14
docs/reference/admonitions.md
View File

@ -35,10 +35,11 @@ See additional configuration options:
### Admonition icons
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.4.0][Insiders]
Each of the supported admonition types has a distinct icon, which can be changed
to any icon bundled with the theme. Add the following lines to `mkdocs.yml`:
to any icon bundled with the theme, or even a [custom icon]. Add the following
lines to `mkdocs.yml`:
``` yaml
theme:
@ -106,6 +107,7 @@ theme:
[![FontAwesome]][FontAwesome]
[Insiders]: ../insiders/index.md
[custom icon]: icons-emojis.md#additional-icons
[supported types]: #supported-types
[icon search]: icons-emojis.md#search
[Octicons]: ../assets/screenshots/admonition-octicons.png
@ -234,8 +236,8 @@ _Result_:
### Inline blocks
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.0.0 ... present][Inline support]
[:octicons-tag-24: 7.0.0][Inline support] ·
:octicons-beaker-24: Experimental
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing
them to the right using the `inline` + `end` modifiers, or to the left using
@ -441,7 +443,7 @@ _Example_:
purus auctor massa, nec semper lorem quam in massa.
```
=== ":octicons-file-code-16: docs/stylesheets/admonitions.css"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
:root {
@ -468,7 +470,7 @@ _Example_:
``` yaml
extra_css:
- stylesheets/admonitions.css
- stylesheets/extra.css
```
_Result_:

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

@ -40,9 +40,9 @@ See additional configuration options:
### Code annotations
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.2.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-2.2.0 ... present][Insiders]
:octicons-beaker-24: Experimental
Code annotations offer a comfortable and friendly way to attach arbitrary
content to specific sections of code blocks by adding numeric markers in block
@ -297,7 +297,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens], they use the same color. You can assign
a new color by using an [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/colors.css"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
:root > * {
@ -309,14 +309,14 @@ a new color by using an [additional style sheet]:
``` yaml
extra_css:
- stylesheets/colors.css
- stylesheets/extra.css
```
If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
can lookup the specific CSS class name in the [syntax theme definition], and
override it as part of your [additional style sheet]:
=== ":octicons-file-code-16: docs/stylesheets/colors.css"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.highlight .sb {
@ -328,7 +328,7 @@ override it as part of your [additional style sheet]:
``` yaml
extra_css:
- stylesheets/colors.css
- stylesheets/extra.css
```
[colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss

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

@ -33,9 +33,9 @@ See additional configuration options:
### Linked content tabs
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.9.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-2.9.0 ... present][Insiders]
:octicons-beaker-24: Experimental
When enabled, all content tabs across the whole documentation site will be
linked and switch to the same label when the user clicks on a tab. Add the
@ -54,16 +54,16 @@ integrated with [instant loading] and persisted across page loads.
=== ":octicons-check-circle-fill-16: Enabled"
[![linking enabled]][linking enabled]
[![content.tabs.link enabled]][content.tabs.link enabled]
=== ":octicons-skip-16: Disabled"
[![linking disabled]][linking disabled]
[![content.tabs.link disabled]][content.tabs.link disabled]
[Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[linking enabled]: ../assets/screenshots/content-tabs-link.png
[linking disabled]: ../assets/screenshots/content-tabs.png
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
## Usage

4
docs/reference/diagrams.md
View File

@ -14,8 +14,8 @@ popular and flexible solution for drawing diagrams.
## Configuration
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-1.15.0 ... present][Insiders]
[:octicons-tag-24: insiders-1.15.0][Insiders] ·
:octicons-beaker-24: Experimental
This configuration enables native support for [Mermaid.js] diagrams. Material
for MkDocs will automatically initialize the JavaScript runtime when a page

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

@ -57,7 +57,6 @@ See additional configuration options:
[Material Design]: https://materialdesignicons.com/
[FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
[Octicons]: https://octicons.github.com/
[additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons
[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
@ -136,7 +135,7 @@ _Example_:
- :fontawesome-brands-facebook:{ .facebook } – Facebook
```
=== ":octicons-file-code-16: docs/stylesheets/icons.css"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.medium {
@ -154,7 +153,7 @@ _Example_:
``` yaml
extra_css:
- stylesheets/icons.css
- stylesheets/extra.css
```
_Result_:
@ -181,7 +180,7 @@ _Example_:
:octicons-heart-fill-24:{ .heart }
```
=== ":octicons-file-code-16: docs/stylesheets/icons.css"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
@keyframes heart {
@ -201,7 +200,7 @@ _Example_:
``` yaml
extra_css:
- stylesheets/icons.css
- stylesheets/extra.css
```
_Result_:

15
docs/reference/meta-tags.md
View File

@ -34,9 +34,8 @@ See additional configuration options:
### Setting the page title
When [Metadata] is enabled, the page title can be overridden on a per-document
basis with custom front matter. Add the following lines at the top of a Markdown
file:
When [Metadata] is enabled, the page title can be overridden for a document with
some custom front matter. Add the following lines at the top of a Markdown file:
``` bash
---
@ -57,9 +56,9 @@ title: Lorem ipsum dolor sit amet # (1)
### Setting the page description
When [Metadata] is enabled, the page description can also be overridden on a
per-document basis with custom front matter. Add the following lines at the top
of a Markdown file:
When [Metadata] is enabled, the page description can be overridden for a
document with custom front matter. Add the following lines at the top of a
Markdown file:
``` bash
---
@ -77,8 +76,8 @@ document `head` for the current page to the provided value.
### Adding a web app manifest
[:octicons-tag-24: 3.1.0][manifest support] ·
:octicons-archive-24: Deprecated ·
[:octicons-tag-24: 3.1.0 ... present][web app manifest support] ·
:octicons-trash-24: 8.0.0
A [web app manifest] is a simple JSON file that specifies how your web
@ -94,7 +93,7 @@ extra:
can be achieved with [theme extension].
[web app manifest]: https://developers.google.com/web/fundamentals/web-app-manifest/
[web app manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
[manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
[theme extension]: ../customization.md#extending-the-theme
</div>

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

@ -5,12 +5,12 @@ template: overrides/main.html
# Changing the colors
As any proper Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], 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][2].
fit your brand's identity by using [CSS variables][custom colors].
[1]: http://www.materialui.co/colors
[2]: #custom-colors
[color palette]: http://www.materialui.co/colors
[custom colors]: #custom-colors
## Configuration
@ -18,9 +18,10 @@ fit your brand's identity by using [CSS variables][2].
#### Color scheme
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`
[:octicons-tag-24: 5.2.0][palette.scheme support] ·
:octicons-milestone-24: Default: `default`
Material for MkDocs supports two _color schemes_: a light mode, which is just
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
can be set via `mkdocs.yml`:
@ -30,7 +31,7 @@ theme:
scheme: default
```
_Click on a tile to change the color scheme_:
Click on a tile to change the color scheme:
<div class="mdx-switch">
<button data-md-color-scheme="default"><code>default</code></button>
@ -49,13 +50,14 @@ _Click on a tile to change the color scheme_:
})
</script>
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss
[palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
#### Primary color
[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`
[:octicons-tag-24: 0.2.0][palette.primary support] ·
:octicons-milestone-24: Default: `indigo`
The _primary color_ is used for the header, the sidebar, text links and several
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
in `mkdocs.yml` to a valid color name:
@ -65,7 +67,7 @@ theme:
primary: indigo
```
_Click on a tile to change the primary color_:
Click on a tile to change the primary color:
<div class="mdx-switch">
<button data-md-color-primary="red"><code>red</code></button>
@ -103,13 +105,14 @@ _Click on a tile to change the primary color_:
})
</script>
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss
[palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
#### Accent color
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`
[:octicons-tag-24: 0.2.0][palette.accent support] ·
:octicons-milestone-24: Default: `indigo`
The _accent color_ is used to denote elements that can be interacted with, e.g.
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
choosing a valid color name:
@ -119,7 +122,7 @@ theme:
accent: indigo
```
_Click on a tile to change the accent color_:
Click on a tile to change the accent color:
<style>
.md-typeset button[data-md-color-accent] > code {
@ -159,36 +162,45 @@ _Click on a tile to change the accent color_:
})
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
[palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
### Color palette toggle
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 7.1.0][palette.toggle support] ·
:octicons-milestone-24: Default: _none_
It's also possible to offer a list of color palettes to the user, each of which
can include a [`scheme`][7], [`primary`][8] and [`accent`][9] color each. The
user can toggle between those color palettes:
can include a [`scheme`][palette.scheme], [`primary`][palette.primary] and
[`accent`][palette.accent] color each. The user can toggle between those color
palettes:
``` yaml hl_lines="4-6 8-10"
``` yaml
theme:
palette:
palette: # (1)
- scheme: default
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
- scheme: slate # (2)
toggle:
icon: material/toggle-switch
name: Switch to light mode
```
The following fields must be set for each toggle:
1. Note that the `theme.palette` setting is now defined as a list.
2. With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_). Make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
`icon`{ #icon }
The following properties must be set for each toggle:
`icon`{ #toggle-icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled
with the theme][10], or the build will not succeed. Some popular
with the theme][custom icons], or the build will not succeed. Some popular
combinations:
* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
@ -196,102 +208,113 @@ The following fields must be set for each toggle:
* :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
* :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`
`name`{ #name }
`name`{ #toggle-name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field is used as the toggle's `title` attribute and should be set to a
discernable name to improve accessibility.
discernable name to improve accessibility. It will appear on mouse hover.
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[7]: #color-scheme
[8]: #primary-color
[9]: #accent-color
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[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
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### System preference
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
[:octicons-tag-24: 7.1.0][palette.media support] ·
:octicons-milestone-24: Default: _none_
In order to automatically set the color palette to the user's system preference,
a media query can be set as part of the `media` field next to the toggle
definition in `mkdocs.yml`:
``` yaml hl_lines="3 8"
``` yaml
theme:
palette:
- media: "(prefers-color-scheme: light)"
- media: "(prefers-color-scheme: light)" # (1)
scheme: default
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
- media: "(prefers-color-scheme: dark)" # (2)
scheme: slate
toggle:
icon: material/toggle-switch
name: Switch to light mode
```
1. This media query is __checked first__. It's also the __fallback__ when no
media query matches.
2. This media query is __checked second__. If it doesn't match, the first one
is automatically used.
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.
!!! warning "Accessibility – not all color combinations work well"
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_). Make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
[palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Customization
### Custom colors
[:octicons-file-code-24: Source][11] ·
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs implements colors using [CSS variables][12] (custom
Material for MkDocs implements colors using [CSS variables] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional style sheet][13] and
use your brand-specific colors), you can add an [additional style sheet] and
tweak the values of the CSS variables.
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__YouTube__, and want to set the primary color to your brand's palette. Just
add:
``` css
:root {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
See the file containing the [color definitions][11] for a list of all CSS
variables.
``` css
:root {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[12]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[13]: ../customization.md#additional-css
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
See the file containing the [color definitions] for a list of all CSS variables.
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[additional style sheet]: ../customization.md#additional-css
### Custom color schemes
[:octicons-file-code-24: Source][11] ·
:octicons-mortar-board-24: Difficulty: _easy_
Besides overriding specific colors, you can create your own, named color scheme
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
[attribute selector][14], which you can then set via `mkdocs.yml` as described
in the [color schemes][7] section:
by wrapping the definitions in a `[data-md-color-scheme="..."]`
[attribute selector], which you can then set via `mkdocs.yml` as described
in the [color schemes][palette.scheme] section:
``` css
[data-md-color-scheme="youtube"] {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
[data-md-color-scheme="youtube"] {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
Additionally, the `slate` color scheme defines all of it's colors via `hsla`
color functions and deduces its colors from the `--md-hue` CSS variable. You
@ -299,8 +322,10 @@ can tune the `slate` theme with:
``` css
[data-md-color-scheme="slate"] {
--md-hue: 210; /* [0, 360] */
--md-hue: 210; /* (1) */
}
```
[14]: https://www.w3.org/TR/selectors-4/#attribute-selectors
1. The `hue` value must be in the range of `[0, 360]`
[attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors

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

@ -5,22 +5,22 @@ template: overrides/main.html
# Changing the fonts
Material for MkDocs makes it easy to change the typeface of your project
documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
documentation, as it directly integrates with [Google Fonts]. Alternatively,
fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
or another destination should be used.
[1]: https://fonts.google.com
[Google Fonts]: https://fonts.google.com
## Configuration
### Regular font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto`][3]
[:octicons-tag-24: 0.1.2][font support] ·
:octicons-milestone-24: Default: [`Roboto`][Roboto]
The _regular font_ is used for all body copy, headlines, and essentially
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
valid [Google Font][1] with:
valid [Google Font][Google Fonts] via `mkdocs.yml`:
``` yaml
theme:
@ -30,17 +30,17 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[3]: https://fonts.google.com/specimen/Roboto
[Roboto]: https://fonts.google.com/specimen/Roboto
[font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto Mono`][4]
[:octicons-tag-24: 0.1.2][font support] ·
:octicons-milestone-24: 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][1] via
`mkdocs.yml` with:
Just like the regular font, it can be set to any valid [Google Font]
[Google Fonts] via `mkdocs.yml`:
``` yaml
theme:
@ -50,55 +50,63 @@ theme:
The typeface will be loaded in 400.
[4]: https://fonts.google.com/specimen/Roboto+Mono
[Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
## Customization
### Autoloading
If you want to load fonts from other destinations or don't want to use Google
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
font loading as described below.
[:octicons-tag-24: 1.0.0][font=false support] ·
:octicons-milestone-24: Default: _none_
### Disabling font loading
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to prevent typefaces from being loaded from Google Fonts and fall
back to system fonts, add the following lines to `mkdocs.yml`:
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
following lines to `mkdocs.yml`:
``` yaml
theme:
font: false
```
[data privacy]: ../data-privacy.md
[font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
## Customization
### Additional fonts
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to load an (additional) font from another or override
the fallback font, you can use an [additional style sheet][8] to add the
If you want to load an (additional) font from another destination or override
the system font, you can use an [additional style sheet] to add the
corresponding `@font-face` definition:
``` css
@font-face {
font-family: "<font>";
src: "...";
}
```
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
@font-face {
font-family: "<font>";
src: "...";
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
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 (with fallback
fonts being added automatically):
globally to be used as the site-wide regular or monospaced font:
=== "Regular font"
``` css
:root {
--md-text-font-family: "<font>";
--md-text-font-family: "<font>"; /* (1) */
}
```
1. Always define fonts through CSS variables and not `font-family`, as
this would disable the system font fallback.
=== "Monospaced font"
``` css
@ -107,7 +115,4 @@ fonts being added automatically):
}
```
[5]: ../data-privacy.md
[6]: ../customization.md#extending-the-theme
[7]: ../customization.md#overriding-blocks-recommended
[8]: ../customization.md#additional-stylesheets
[additional style sheet]: ../customization.md#additional-css

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

@ -6,16 +6,17 @@ template: overrides/main.html
Material for MkDocs supports internationalization (i18n) and provides
translations for template variables and labels in 40+ languages. Additionally,
the site search can be configured to use a language-specific stemmer (if
available).
the site search can be configured to use a language-specific stemmer, if
available.
## Configuration
### Site language
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
[:octicons-tag-24: 1.12.0][language support] ·
:octicons-milestone-24: Default: `en`
You can set the _site language_ in `mkdocs.yml` with:
You can set the site language in `mkdocs.yml` with:
``` yaml
theme:
@ -79,70 +80,72 @@ The following languages are supported:
</div>
_Note that some languages will produce unreadable anchor links, due to the way
the default slug function works. Consider using a Unicode-aware slug function,
as [documented here][2]._
Note that some languages will produce unreadable anchor links due to the way
the default slug function works. Consider using a [Unicode-aware slug function].
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/en.html
[2]: setting-up-navigation.md#slugify
[language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[Unicode-aware slug function]: setting-up-navigation.md#slugify
### Site language selector
[:octicons-file-code-24: Source][3] ·
[:octicons-tag-24: 7.0.0][alternate support] ·
:octicons-milestone-24: Default: _none_ ·
:octicons-beaker-24: Experimental
If your documentation is available in multiple languages, a _language selector_
can be added to the header next to the search bar. Alternate languages can be
defined via `mkdocs.yml`:
If your documentation is available in multiple languages, a language selector
pointing to those languages can be added to the header. Alternate languages
can be defined via `mkdocs.yml`.
``` yaml
extra:
alternate:
# Switch to English
- name: English
link: <your-site>/en/
link: /en/ # (1)
lang: en
# Switch to German
- name: Deutsch
link: <your-site>/de/
link: /de/
lang: de
# Switch to Japanese
- name: 日本語
link: <your-site>/ja/
lang: ja
```
This will render a language selector in the header next to the search bar:
1. Note that this must be an absolute link. If it includes a domain part, it's
used as defined. Otherwise the domain part of the [`site_url`][site_url] as
set in `mkdocs.yml` is prepended to the link.
[![Language selection][4]][4]
The following properties must be set for each alternate language:
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[4]: ../assets/screenshots/language-selection.png
`name`{ #language-name }
### Site search language
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field is used inside the language selector as the name of the language
and must be set to a non-empty string.
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _automatically set_
`link`{ #language-link }
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
functionality. See the guide detailing how to [set up site search][7] for
more information.
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must be set to an absolute link, which might also point to
another domain or subdomain not necessarily generated with MkDocs.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts
[6]: https://github.com/MihaiValentin/lunr-languages
[7]: setting-up-site-search.md
`lang`{ #language-lang }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must contain a valid [ISO 639-1 language code] and is used for
the `hreflang` attribute of the link, improving discoverability via search
engines.
[![Language selector]][Language selector]
[alternate 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]: ../assets/screenshots/language-selection.png
### Directionality
[:octicons-file-code-24: Source][8] ·
[:octicons-tag-24: 2.5.0][direction support] ·
:octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) _directionality_ which is inferred from the
supports `rtl` (right-to-left) directionality which is deduced from the
selected language, but can also be set with:
``` yaml
@ -163,44 +166,46 @@ Click on a tile to change the directionality:
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir")
document.body.dir = attr
var name = document.querySelector("#__code_1 code span:nth-child(5)")
var name = document.querySelector("#__code_3 code span:nth-child(5)")
name.textContent = attr
})
})
</script>
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
## Customization
### Custom translations
[:octicons-file-code-24: Source][1] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to customize some of the translations for a language, just follow
the guide on [theme extension][9] and create a new partial in
`partials/languages`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial.
the guide on [theme extension] and create a new partial in the `overrides`
folder. Then import the [translations] of your language as a fallback and only
adjust the ones you want to override:
Let's say you want to change "__Table of contents__" to "__On this page__":
=== ":octicons-file-code-16: partials/languages/custom.html"
``` html
<!-- Use en language as fallback -->
{% import "partials/languages/en.html" as fallback %}
{% macro override(key) %}{{ {
"toc.title": "On this page"
}[key] }}{% endmacro %}
``` html
<!-- Import translations for your language as fallback -->
{% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %}
{% macro override(key) %}{{ {
"toc.title": "On this page" <!-- (1) -->
}[key] }}{% endmacro %}
<!-- Re-export the translation macro for mkbuild-material to use -->
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
```
<!-- Re-export translations -->
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}
```
Then, add the following lines to `mkdocs.yml`:
1. Check the [list of available languages], pick the translation you want
to override for your language and add them here.
``` yaml
theme:
language: en-custom
```
=== ":octicons-file-code-16: mkdocs.yml"
[9]: ../customization.md#extending-the-theme
``` yaml
theme:
language: custom
```
[theme extension]: ../customization.md#extending-the-theme
[translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
[list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/

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

@ -4,32 +4,32 @@ template: overrides/main.html
# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 7.000
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][1] with minimal effort.
when writing your documentation in Markdown. Not enough? You can also add
[additional icons] with minimal effort.
[1]: #additional-icons
[additional icons]: #additional-icons
## Configuration
### Logo
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`material/library`][3]
[:octicons-tag-24: 0.1.0][logo support] ·
:octicons-milestone-24: Default: [`material/library`][logo default]
The _logo_ can be changed to a user-provided image (any type, incl. `*.png` and
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.
Add the following lines to `mkdocs.yml`:
=== "Image"
=== ":octicons-image-16: Image"
``` yaml
theme:
logo: assets/logo.png
```
=== "Icon, bundled"
=== ":octicons-package-16: Icon, bundled"
``` yaml
theme:
@ -37,9 +37,8 @@ Add the following lines to `mkdocs.yml`:
logo: material/library
```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
Normally, the logo in the header and sidebar links to the homepage of the
documentation, which is the same as `site_url`. This behavior can be changed
@ -52,60 +51,28 @@ extra:
### Favicon
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: `assets/images/favicon.png`
[:octicons-tag-24: 0.1.0][favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][favicon default]
The _favicon_ can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. It can be set via `mkdocs.yml`:
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
theme:
favicon: images/favicon.png
```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
### Icons
[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][6]
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
adds the ability to __integrate icons__ in the `*.svg` file format, which are
inlined when [building your site][8]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
```
The following icon sets are bundled with Material for MkDocs:
- :material-material-design: – [Material Design][9]
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
- :octicons-mark-github-16: – [Octicons][11]
If you want to add [additional icons][1], read on.
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: ../creating-your-site.md#building-your-site
[9]: https://materialdesignicons.com/
[10]: https://fontawesome.com/icons?d=gallery&m=free
[11]: https://octicons.github.com/
[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
## Customization
### Additional icons
[:octicons-file-code-24: Source][4] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to add additional icons, [extend the theme][12], and create a folder
named `.icons` in the [`custom_dir`][13] you want to use for overrides. Next,
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
downloaded and unpacked the [Bootstrap][14] icon set, and want to add it to
In order to use custom icons, [extend the theme] and create a new folder named
`.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
your project documentation. The structure of your project should look like this:
``` sh
@ -129,9 +96,8 @@ markdown_extensions:
- overrides/.icons
```
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
icons.
You can now use all :fontawesome-brands-bootstrap: Bootstrap icons.
[12]: ../customization.md#extending-the-theme
[13]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[14]: https://icons.getbootstrap.com/
[extend the theme]: ../customization.md#extending-the-theme
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[Bootstrap]: https://icons.getbootstrap.com/

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

@ -11,8 +11,8 @@ are two packages that enhance the Markdown writing experience, adding useful
syntax extensions for technical writing.
[John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
[Python Markdown]: #python-markdown.md
[Python Markdown Extensions]: #python-markdown-extensions.md
[Python Markdown]: python-markdown.md
[Python Markdown Extensions]: python-markdown-extensions.md
## Supported extensions

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

@ -15,8 +15,8 @@ installed with a supported version.
### Arithmatex
[:octicons-workflow-24: Extension][Arithmatex] ·
[:octicons-tag-24: 1.0.0 ... present][Arithmatex support]
[:octicons-tag-24: 1.0.0][Arithmatex support] ·
[:octicons-workflow-24: Extension][Arithmatex]
The [Arithmatex] extension allows for rendering of block and inline block
equations and integrates seamlessly with [MathJax][^1] – a library for
@ -87,8 +87,8 @@ See reference for usage:
### BetterEm
[:octicons-workflow-24: Extension][BetterEm] ·
[:octicons-tag-24: 0.1.0 ... present][BetterEm support]
[:octicons-tag-24: 0.1.0][BetterEm support] ·
[:octicons-workflow-24: Extension][BetterEm]
The [BetterEm] extension improves the detection of Markup to emphasize text
in Markdown using special characters, i.e. for `**bold**` and `_italic_`
@ -108,8 +108,8 @@ documentation][BetterEm] for more information.
### Caret, Mark & Tilde
[:octicons-workflow-24: Extension][Caret] ·
[:octicons-tag-24: 1.0.0 ... present][Caret support]
[:octicons-tag-24: 1.0.0][Caret support] ·
[:octicons-workflow-24: Extension][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
@ -140,8 +140,8 @@ See reference for usage:
### Critic
[:octicons-workflow-24: Extension][Critic] ·
[:octicons-tag-24: 1.0.0 ... present][Critic support]
[:octicons-tag-24: 1.0.0][Critic support] ·
[:octicons-workflow-24: Extension][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
@ -195,8 +195,8 @@ See reference for usage:
### Details
[:octicons-workflow-24: Extension][Details] ·
[:octicons-tag-24: 1.9.0 ... present][Details support]
[:octicons-tag-24: 1.9.0][Details support] ·
[:octicons-workflow-24: Extension][Details]
The [Details] extension supercharges the [Admonition] extension, making the
resulting _call-outs_ collapsible, allowing them to be opened and closed by the
@ -218,8 +218,8 @@ No configuration options are available. See reference for usage:
### Emoji
[:octicons-workflow-24: Extension][Emoji] ·
[:octicons-tag-24: 1.0.0 ... present][Emoji support]
[:octicons-tag-24: 1.0.0][Emoji support] ·
[:octicons-workflow-24: Extension][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`:
@ -297,13 +297,14 @@ See reference for usage:
### Highlight
[:octicons-tag-24: 5.0.0][Highlight support] ·
[:octicons-workflow-24: Extension][Highlight] ·
[:octicons-tag-24: 5.0.0 ... present][Highlight support] ·
:octicons-zap-24: Supersedes [CodeHilite]
The [Highlight] extension adds support for syntax highlighting of code blocks
(with the help of [SuperFences][SuperFences #]) and inline code blocks (with
the help of [InlineHilite][InlineHilite #]). Enable it via `mkdocs.yml`:
(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
`mkdocs.yml`:
``` yaml
markdown_extensions:
@ -311,7 +312,7 @@ markdown_extensions:
- pymdownx.superfences # (1)
```
1. [Highlight] is used by the [SuperFences][SuperFences #] extension to
1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
perform syntax highlighting on code blocks, not the other way round, which
is why this extension also needs to be enabled.
@ -410,8 +411,8 @@ See reference for usage:
[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
[SuperFences #]: #superfences
[InlineHilite #]: #inlinehilite
[pymdownx.superfences]: #superfences
[pymdownx.inlinehilite]: #inlinehilite
[Pygments]: https://pygments.org
[additional CSS]: ../../customization.md#additional-css
[Highlight.js]: https://highlightjs.org/
@ -422,12 +423,12 @@ See reference for usage:
### InlineHilite
[:octicons-workflow-24: Extension][InlineHilite] ·
[:octicons-tag-24: 5.0.0 ... present][InlineHilite support]
[:octicons-tag-24: 5.0.0][InlineHilite support] ·
[:octicons-workflow-24: Extension][InlineHilite]
The [InlineHilite] extension add support for syntax highlighting of inline code
blocks. It's built on top of the [Highlight][Highlight #] extension, from which
it sources its configuration. Enable it via `mkdocs.yml`:
blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
which it sources its configuration. Enable it via `mkdocs.yml`:
``` yaml
markdown_extensions:
@ -447,13 +448,13 @@ See reference for usage:
[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
[Highlight #]: #highlight
[pymdownx.highlight]: #highlight
[Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
### Keys
[:octicons-workflow-24: Extension][Keys] ·
[:octicons-tag-24: 1.0.0 ... present][Keys support]
[:octicons-tag-24: 1.0.0][Keys support] ·
[:octicons-workflow-24: Extension][Keys]
The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
@ -479,8 +480,8 @@ See reference for usage:
### SmartSymbols
[:octicons-workflow-24: Extension][SmartSymbols] ·
[:octicons-tag-24: 0.1.0 ... present][SmartSymbols support]
[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
[:octicons-workflow-24: Extension][SmartSymbols]
The [SmartSymbols] extension converts some sequences of characters into their
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
@ -500,8 +501,8 @@ documentation][SmartSymbols] for guidance.
### Snippets
[:octicons-workflow-24: Extension][Snippets] ·
[:octicons-tag-24: 0.1.0 ... present][Snippets support]
[:octicons-tag-24: 0.1.0][Snippets support] ·
[:octicons-workflow-24: Extension][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
@ -528,8 +529,8 @@ See reference for usage:
### SuperFences
[:octicons-tag-24: 0.1.0][SuperFences support] ·
[:octicons-workflow-24: Extension][SuperFences] ·
[:octicons-tag-24: 0.1.0 ... present][SuperFences support] ·
:octicons-zap-24: Supersedes [Fenced Code Blocks]
The [SuperFences] extension allows for arbitrary nesting of code and content
@ -587,8 +588,8 @@ See reference for usage:
### Tabbed
[:octicons-workflow-24: Extension][Tabbed] ·
[:octicons-tag-24: 5.0.0 ... present][Tabbed support]
[:octicons-tag-24: 5.0.0][Tabbed support] ·
[:octicons-workflow-24: Extension][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
@ -636,8 +637,8 @@ See reference for usage:
### Tasklist
[:octicons-workflow-24: Extension][Tasklist] ·
[:octicons-tag-24: 1.0.0 ... present][Tasklist support]
[:octicons-tag-24: 1.0.0][Tasklist support] ·
[:octicons-workflow-24: Extension][Tasklist]
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Tasklist specification], following the same syntactical
@ -686,6 +687,5 @@ See reference for usage:
[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 #]: #tasklist
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists

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

@ -15,8 +15,8 @@ reference for which features they need to be enabled.
### Abbreviations
[:octicons-workflow-24: Extension][Abbreviations] ·
[:octicons-tag-24: 1.0.0 ... present][Abbreviations support]
[:octicons-tag-24: 1.0.0][Abbreviations support] ·
[:octicons-workflow-24: Extension][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
@ -39,8 +39,8 @@ No configuration options are available. See reference for usage:
### Admonition
[:octicons-workflow-24: Extension][Admonition] ·
[:octicons-tag-24: 0.1.0 ... present][Admonition support]
[:octicons-tag-24: 0.1.0][Admonition support] ·
[:octicons-workflow-24: Extension][Admonition]
The [Admonition] extension adds support for admonitions, more commonly known as
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
@ -67,8 +67,8 @@ No configuration options are available. See reference for usage:
### Attribute Lists
[:octicons-workflow-24: Extension][Attribute Lists] ·
[:octicons-tag-24: 0.1.0 ... present][Attribute Lists support]
[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
[:octicons-workflow-24: Extension][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
@ -96,8 +96,8 @@ No configuration options are available. See reference for usage:
### Definition Lists
[:octicons-workflow-24: Extension][Definition Lists] ·
[:octicons-tag-24: 1.1.0 ... present][Definition Lists support]
[:octicons-tag-24: 1.1.0][Definition Lists support] ·
[:octicons-workflow-24: Extension][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
@ -119,8 +119,8 @@ No configuration options are available. See reference for usage:
### Footnotes
[:octicons-workflow-24: Extension][Footnotes] ·
[:octicons-tag-24: 1.0.0 ... present][Footnotes support]
[:octicons-tag-24: 1.0.0][Footnotes support] ·
[:octicons-workflow-24: Extension][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`:
@ -142,8 +142,8 @@ No configuration options are supported. See reference for usage:
### Metadata
[:octicons-workflow-24: Extension][Metadata] ·
[:octicons-tag-24: 1.0.0 ... present][Metadata support]
[:octicons-tag-24: 1.0.0][Metadata support] ·
[:octicons-workflow-24: Extension][Metadata]
The [Metadata] extension adds the ability to attach arbitrary key-value pairs
to a document via front matter written in YAML syntax before the Markdown.
@ -170,8 +170,8 @@ No configuration options are available. See reference for usage:
### Markdown in HTML
[:octicons-workflow-24: Extension][Markdown in HTML] ·
[:octicons-tag-24: 0.1.0 ... present][Markdown in HTML support]
[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
[:octicons-workflow-24: Extension][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
@ -198,8 +198,8 @@ No configuration options are available. See reference for usage:
### Table of Contents
[:octicons-workflow-24: Extension][Table of Contents] ·
[:octicons-tag-24: 0.1.0 ... present][Table of Contents support]
[:octicons-tag-24: 0.1.0][Table of Contents support] ·
[:octicons-workflow-24: Extension][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
@ -292,8 +292,8 @@ own risk.
### Tables
[:octicons-workflow-24: Extension][Tables] ·
[:octicons-tag-24: 0.1.0 ... present][Tables support]
[:octicons-tag-24: 0.1.0][Tables support] ·
[:octicons-workflow-24: Extension][Tables]
The [Tables] extension adds the ability to create tables in Markdown by using a
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
@ -322,8 +322,8 @@ should be considered.
### Fenced Code Blocks
[:octicons-workflow-24: Extension][Fenced Code Blocks] ·
[:octicons-tag-24: 0.1.0 ... present][Fenced Code Blocks support]
[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
[:octicons-workflow-24: Extension][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
@ -335,8 +335,8 @@ nesting, and is therefore recommended.
### CodeHilite
[:octicons-workflow-24: Extension][CodeHilite] ·
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support]
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
[:octicons-workflow-24: Extension][CodeHilite]
Superseded by [Highlight]. Support for CodeHilite was dropped in
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other

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

@ -6,22 +6,23 @@ template: overrides/main.html
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][1] and [sections][2],
and its flag-ship feature: [instant loading][3].
the behavior of navigational elements, including [tabs][navigation.tabs] and
[sections][navigation.sections], and its flag-ship feature: [instant loading]
[navigation.instant].
[1]: #navigation-tabs
[2]: #navigation-sections
[3]: #instant-loading
[navigation.tabs]: #navigation-tabs
[navigation.sections]: #navigation-sections
[navigation.instant]: #instant-loading
## Configuration
### Instant loading
[:octicons-file-code-24: Source][4] ·
[:octicons-tag-24: 5.0.0][navigation.instant support] ·
:octicons-unlock-24: Feature flag
When _instant loading_ is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR][5] without fully reloading the page. Add
When instant loading is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR] without fully reloading the page. Add
the following lines to `mkdocs.yml`:
``` yaml
@ -31,23 +32,21 @@ theme:
```
The resulting page is parsed and injected and all event handlers and components
are rebound automatically. This means that __Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation
sites that come with a massive search index, as the search index will now
remain intact in-between document switches.
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.
_Material for MkDocs is the only MkDocs theme offering this feature._
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
[navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Anchor tracking
[:octicons-file-code-24: Source][6] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.1.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][6]{ .mdx-insiders }
:octicons-beaker-24: Experimental
When _anchor tracking_ is enabled, the URL in the address bar is automatically
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
following lines to `mkdocs.yml`:
@ -57,24 +56,25 @@ theme:
- navigation.tracking
```
[6]: ../insiders/index.md
[Insiders]: ../insiders/index.md
### Navigation tabs
[:octicons-file-code-24: Source][7] · :octicons-unlock-24: Feature flag
[:octicons-tag-24: 1.1.0][navigation.tabs support] ·
:octicons-unlock-24: Feature flag
When _tabs_ are enabled, top-level sections are rendered in a menu layer below
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 version 6.2, navigation tabs had a slightly different behavior.
All top-level pages (i.e. all top-level entries that directly refer to an
`*.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 version 6.2 on, navigation tabs
include all top-level pages and sections.
Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
behavior. All top-level pages (i.e. all top-level entries directly
refefring 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
on, navigation tabs include all top-level pages and sections.
``` yaml
theme:
@ -84,23 +84,23 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![With tabs][8]][8]
[![navigation.tabs enabled]][navigation.tabs enabled]
=== ":octicons-skip-16: Disabled"
[![Without tabs][9]][9]
[![navigation.tabs disabled]][navigation.tabs disabled]
[7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[8]: ../assets/screenshots/navigation-tabs.png
[9]: ../assets/screenshots/navigation.png
[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-file-code-24: Source][10] ·
[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When _sticky tabs_ are enabled, navigation tabs will lock below the header and
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
flags to `mkdocs.yml`:
@ -113,22 +113,22 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![With sticky tabs][11]][11]
[![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
=== ":octicons-skip-16: Disabled"
[![Without sticky tabs][12]][12]
[![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled]
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
[11]: ../assets/screenshots/navigation-tabs-sticky.png
[12]: ../assets/screenshots/navigation-tabs-collapsed.png
[navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs.png
[navigation.tabs.sticky disabled]: ../assets/screenshots/navigation.png
### Navigation sections
[:octicons-file-code-24: Source][13] ·
[:octicons-tag-24: 6.2.0][navigation.sections support] ·
:octicons-unlock-24: Feature flag
When _sections_ are enabled, top-level sections are rendered as groups in the
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
following lines to `mkdocs.yml`:
@ -140,25 +140,27 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![With sections][14]][14]
[![navigation.sections enabled]][navigation.sections enabled]
=== ":octicons-skip-16: Disabled"
[![Without sections][9]][9]
[![navigation.sections disabled]][navigation.sections disabled]
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[14]: ../assets/screenshots/navigation-sections.png
[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
Both feature flags, _tabs_ and _sections_, can be combined with each other. If
both feature flags are enabled, sections are rendered for level 2 navigation
Both feature flags, [`navigation.tabs`][navigation.tabs] and
[`navigation.sections`][navigation.sections], can be combined with each other.
If both feature flags are enabled, sections are rendered for level 2 navigation
items.
### Navigation expansion
[:octicons-file-code-24: Source][13] ·
[:octicons-tag-24: 6.2.0][navigation.expand support] ·
:octicons-unlock-24: Feature flag
When _expansion_ is enabled, the left sidebar will expand all collapsible
When expansion is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually.
Add the following lines to `mkdocs.yml`:
@ -170,21 +172,23 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![With expansion][15]][15]
[![navigation.expand enabled]][navigation.expand enabled]
=== ":octicons-skip-16: Disabled"
[![Without expansion][9]][9]
[![navigation.expand disabled]][navigation.expand disabled]
[15]: ../assets/screenshots/navigation-expand.png
[navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[navigation.expand enabled]: ../assets/screenshots/navigation-expand.png
[navigation.expand disabled]: ../assets/screenshots/navigation.png
### Section index pages
[:octicons-file-code-24: Source][16] ·
[:octicons-tag-24: 7.3.0][navigation.indexes support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When _section index pages_ are enabled, documents can be directly attached to
When section index pages are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. Add the
following lines to `mkdocs.yml`:
@ -196,11 +200,11 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![With expansion][17]][17]
[![navigation.indexes enabled]][navigation.indexes enabled]
=== ":octicons-skip-16: Disabled"
[![Without expansion][18]][18]
[![navigation.indexes disabled]][navigation.indexes disabled]
In order to link a page to a section, create a new document with the name
`index.md` in the respective folder, and add it to the beginning of your
@ -215,128 +219,21 @@ nav:
- Page n: section/page-n.md
```
_This feature flag can be combined with all other feature flags, e.g. [tabs][1]
and [sections][2], except for table of contents [navigation integration][19]._
This feature flag is not compatible with [`toc.integrate`][toc.integrate].
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[17]: ../assets/screenshots/navigation-index-on.png
[18]: ../assets/screenshots/navigation-index-off.png
[19]: #navigation-integration
[navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
[navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
[toc.integrate]: #integrated-table-of-contents
### Back-to-top button
### Integrated table of contents
[:octicons-file-code-24: Source][20] ·
[:octicons-tag-24: 6.2.0][toc.integrate support] ·
:octicons-unlock-24: Feature flag
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
following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- navigation.top
```
[![back-to-top button][21]][21]
[20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss
[21]: ../assets/screenshots/back-to-top.png
### Table of contents
[:octicons-file-code-24: Source][22] · [:octicons-workflow-24: Extension][23]
The [Table of contents][24] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance:
`permalink`{ #permalink }
: :octicons-milestone-24: 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:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
`slugify`{ #slugify }
: :octicons-milestone-24: Default: `headerid.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][25]:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify
```
=== "Unicode, case-sensitive"
``` yaml
markdown_extensions:
- toc:
slugify: !!python/name:pymdownx.slugs.uslugify_cased
```
`toc_depth`{ #toc-depth }
: :octicons-milestone-24: 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:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but might yield unexpected results.
Use them at your own risk._
[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[23]: https://python-markdown.github.io/extensions/toc/
[24]: https://python-markdown.github.io/extensions/toc/#usage
[25]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
#### Navigation integration
[:octicons-file-code-24: Source][26] ·
:octicons-unlock-24: Feature flag
When _integration_ is enabled, the table of contents is rendered as part of
the navigation for viewports above `1220px`, but remains as-is on mobile. Add
the following lines to `mkdocs.yml`:
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
to `mkdocs.yml`:
``` yaml
theme:
@ -346,29 +243,44 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled"
[![Integrate table of contents][27]][27]
[![toc.integrate enabled]][toc.integrate enabled]
=== ":octicons-skip-16: Disabled"
[![Separate table of contents][8]][8]
[![toc.integrate disabled]][toc.integrate disabled]
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
[27]: ../assets/screenshots/toc-integrate.png
This feature flag is not compatible with [`navigation.indexes`]
[navigation.indexes].
The content section will now always stretch to the right side, resulting in
more space for your content. This feature flag can be combined with all other
feature flags, e.g. [tabs][1] and [sections][2].
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
[navigation.indexes]: #section-index-pages
### Back-to-top button
[:octicons-tag-24: 7.1.0][navigation.top support] ·
:octicons-unlock-24: Feature flag
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
following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- navigation.top
```
[navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
## Usage
### Hiding the sidebars
[:octicons-file-code-24: Source][28] ·
:octicons-note-24: Metadata
Sometimes it's desirable to hide the navigation and/or table of contents
sidebar, especially when there's a single navigation item. This can be done for
any page using the [Metadata][29] extension:
When [Metadata] is enabled, the navigation and/or table of contents sidebars
can be hidden for a document with custom front matter. Add the following lines
at the top of a Markdown file:
``` bash
---
@ -383,29 +295,25 @@ hide:
=== "Hide navigation"
[![Hide navigation][30]][30]
[![hide.navigation enabled]][hide.navigation enabled]
=== "Hide table of contents"
[![Hide table of contents][31]][31]
[![hide.toc enabled]][hide.toc enabled]
=== "Hide both"
[![Hide navigation and table of contents][32]][32]
[![hide.* enabled]][hide.* enabled]
[28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[29]: ../../reference/meta-tags/#metadata
[30]: ../assets/screenshots/hide-navigation.png
[31]: ../assets/screenshots/hide-toc.png
[32]: ../assets/screenshots/hide-navigation-toc.png
[Metadata]: extensions/python-markdown.md#metadata
[hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
[hide.toc enabled]: ../assets/screenshots/hide-toc.png
[hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
## Customization
### Keyboard shortcuts
[:octicons-file-code-24: Source][33] ·
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There're two modes:
@ -429,54 +337,66 @@ to navigate your project documentation via keyboard. There're two modes:
* ++n++ , ++period++ : go to next page
Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript][34], you can subscribe to the `keyboard$` observable and attach
JavaScript], you can subscribe to the `keyboard$` observable and attach
your custom event listener:
``` js
keyboard$.subscribe(function(key) {
if (key.mode === "global" && key.type === "x") {
/* Add custom keyboard handler here */
key.claim()
}
})
```
=== ":octicons-file-code-16: docs/javascripts/shortcuts.js"
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
on the underlying event, so the keypress will not propagate further and touch
other event listeners.
``` js
keyboard$.subscribe(function(key) {
if (key.mode === "global" && key.type === "x") {
/* Add custom keyboard handler here */
key.claim() // (1)
}
})
```
[33]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[34]: ../customization.md#additional-javascript
1. The call to `key.claim()` will execute `preventDefault()` on the
underlying event, so the keypress will not propagate further and
touch other event listeners.
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_javascript:
- javascripts/shortcuts.js
```
[additional JavaScript]: ../customization.md#additional-javascript
### Content area width
[:octicons-file-code-24: Source][35] ·
:octicons-mortar-board-24: Difficulty: _easy_
The width of the content area is set so the length of each line doesn't exceed
80-100 characters, depending on the width of the characters. While this
is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it
stretch to the entire available space.
This can easily be achieved with an [additional style sheet][36] and a few lines
This can easily be achieved with an [additional style sheet] and a few lines
of CSS:
=== "Increase width"
=== ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css
.md-grid {
max-width: 1440px;
max-width: 1440px; /* (1) */
}
```
=== "Stretch to fit"
1. If you want the content area to always stretch to the available screen
space, reset `max-width` with the following CSS:
``` css
.md-grid {
max-width: initial;
}
``` css
.md-grid {
max-width: initial;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/extra.css
```
[35]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
[36]: ../customization.md#additional-css
[additional style sheet]: ../customization.md#additional-css

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

@ -18,7 +18,7 @@ and extendable [cookie consent][2].
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: 7.1.8 ... present][Google Analytics support]
[:octicons-tag-24: 7.1.8][Google Analytics support]
Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
out Universal Analytics (`UA-*`). Depending on the prefix of the property, add
@ -68,7 +68,7 @@ yourself, [this tutorial][4] might be a good start._
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: insiders-2.10.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.10.0][Insiders]
Material for MkDocs ships a native and extensible cookie consent form, which
asks the user for his consent prior to setting up analytics. Add the following

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

@ -39,7 +39,7 @@ The following options are supported:
`lang`{ #lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows
: :octicons-milestone-24: Default: _auto_ – This option allows
to include the language-specific stemmers provided by [lunr-languages][5].
Note that Material for MkDocs will set this automatically based on the
[site language][6], but it may be overridden, e.g. to support multiple
@ -100,7 +100,7 @@ The following options are supported:
`separator`{ #separator }
: :octicons-milestone-24: Default: _automatically set_ – The separator for
: :octicons-milestone-24: Default: _auto_ – 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 `.`:
@ -148,7 +148,7 @@ Use them at your own risk._
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0 ... present][Search suggestions support]
[:octicons-tag-24: 7.2.0][Search suggestions support]
When _search suggestions_ are enabled, the search will display the likeliest
completion for the last word, saving the user many key strokes by accepting the
@ -175,7 +175,7 @@ Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0 ... present][Search highlighting support]
[:octicons-tag-24: 7.2.0][Search highlighting support]
When _search highlighting_ is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
@ -200,7 +200,7 @@ Searching for [:octicons-search-24: code blocks][12] yields:
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: 7.2.0 ... present][Search highlighting support]
[:octicons-tag-24: 7.2.0][Search highlighting support]
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
@ -250,7 +250,7 @@ For setup instructions, refer to the [official documentation][19].
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata ·
[:octicons-tag-24: insiders-2.8.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.8.0][Insiders]
In order to give specific pages a higher relevance in search, [lunr][4] supports
page-specific boosts, which can be defined for each page by leveraging the
@ -275,7 +275,7 @@ search:
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-3.1.0 ... present][Insiders]
[:octicons-tag-24: insiders-3.1.0][Insiders]
#### Excluding pages

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

@ -26,7 +26,7 @@ MkDocs can generate beautiful social cards automatically, using the [colors][1],
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-2.12.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.12.0][Insiders]
The [built-in social cards plugin][4] generates a social card image for every
page and adds the necessary meta tags, so it's displayed on social media when
@ -57,8 +57,8 @@ are available:
`cards_color`{ #cards-color } :material-new-box:
: :octicons-milestone-24: Default: _automatically set based on [primary
color][8]_ – This option specifies which colors to use for the background
: :octicons-milestone-24: Default: [`primary
color`][8]_ – This option specifies which colors to use for the background
`fill` and foreground `text` when generating the social card.
``` yaml

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

@ -16,7 +16,7 @@ can help to discover relevant information faster.
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-2.7.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.7.0][Insiders]
The [built-in tags plugin][1] 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

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

@ -17,7 +17,7 @@ configured via `mkdocs.yml`.
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: 1.0.0 ... present][Social links support]
[:octicons-tag-24: 1.0.0][Social links support]
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`
@ -30,7 +30,7 @@ extra:
link: https://twitter.com/squidfunk
```
For each entry, the following fields are available:
For each entry, the following settings are available:
`icon`{ #icon }
@ -95,7 +95,7 @@ For each entry, the following fields are available:
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ ·
[:octicons-tag-24: 0.1.0 ... present][Copyright notice support]
[:octicons-tag-24: 0.1.0][Copyright notice support]
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`:
@ -111,7 +111,7 @@ copyright: Copyright &copy; 2016 - 2020 Martin Donath
:octicons-hash-24: Setting ·
:octicons-milestone-24: Default: `true` ·
[:octicons-tag-24: 7.3.0 ... present][Generator notice support]
[:octicons-tag-24: 7.3.0][Generator notice support]
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 setting

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

@ -17,7 +17,7 @@ It also includes the [search bar][1] and a place to display your project's
### Automatic hiding
:octicons-unlock-24: Feature flag ·
[:octicons-tag-24: 6.2.0 ... present][Automatic hiding support]
[:octicons-tag-24: 6.2.0][Automatic hiding support]
When _autohiding_ is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the
@ -36,7 +36,7 @@ theme:
### Announcement bar
:octicons-file-symlink-file-24: Customization ·
[:octicons-tag-24: 5.0.0 ... present][Announcement bar support]
[:octicons-tag-24: 5.0.0][Announcement bar support]
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

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

@ -70,7 +70,7 @@ Material for MkDocs._
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-file-symlink-file-24: Customization ·
[:octicons-tag-24: insiders-2.5.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.5.0][Insiders]
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][8],
@ -119,7 +119,7 @@ Make sure that this matches the [default version][11].
### Stay on page
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-2.6.0 ... present][Insiders]
[:octicons-tag-24: insiders-2.6.0][Insiders]
Insiders improves the user experience when switching between versions: if
version A and B contain a page with the same path name, the user will stay on