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

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) 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 sequence diagrams
* Added support for entity relationship diagrams * Added support for entity relationship diagrams
* Added support for cookie consent configuration * 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`. disabled][3] via `mkdocs.yml`.
[2]: setup/changing-the-fonts.md [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 ### Google Analytics and Disqus

14
docs/reference/admonitions.md
View File

@ -35,10 +35,11 @@ See additional configuration options:
### Admonition icons ### Admonition icons
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [: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 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 ``` yaml
theme: theme:
@ -106,6 +107,7 @@ theme:
[![FontAwesome]][FontAwesome] [![FontAwesome]][FontAwesome]
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[custom icon]: icons-emojis.md#additional-icons
[supported types]: #supported-types [supported types]: #supported-types
[icon search]: icons-emojis.md#search [icon search]: icons-emojis.md#search
[Octicons]: ../assets/screenshots/admonition-octicons.png [Octicons]: ../assets/screenshots/admonition-octicons.png
@ -234,8 +236,8 @@ _Result_:
### Inline blocks ### Inline blocks
:octicons-beaker-24: Experimental · [:octicons-tag-24: 7.0.0][Inline support] ·
[:octicons-tag-24: 7.0.0 ... present][Inline support] :octicons-beaker-24: Experimental
Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing 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 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. 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 ``` css
:root { :root {
@ -468,7 +470,7 @@ _Example_:
``` yaml ``` yaml
extra_css: extra_css:
- stylesheets/admonitions.css - stylesheets/extra.css
``` ```
_Result_: _Result_:

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

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

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

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

4
docs/reference/diagrams.md
View File

@ -14,8 +14,8 @@ popular and flexible solution for drawing diagrams.
## Configuration ## Configuration
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-beaker-24: Experimental · [:octicons-tag-24: insiders-1.15.0][Insiders] ·
[:octicons-tag-24: insiders-1.15.0 ... present][Insiders] :octicons-beaker-24: Experimental
This configuration enables native support for [Mermaid.js] diagrams. Material This configuration enables native support for [Mermaid.js] diagrams. Material
for MkDocs will automatically initialize the JavaScript runtime when a page 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/ [Material Design]: https://materialdesignicons.com/
[FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free [FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
[Octicons]: https://octicons.github.com/ [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]: ../setup/extensions/python-markdown-extensions.md#emoji
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
@ -136,7 +135,7 @@ _Example_:
- :fontawesome-brands-facebook:{ .facebook } – Facebook - :fontawesome-brands-facebook:{ .facebook } – Facebook
``` ```
=== ":octicons-file-code-16: docs/stylesheets/icons.css" === ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css ``` css
.medium { .medium {
@ -154,7 +153,7 @@ _Example_:
``` yaml ``` yaml
extra_css: extra_css:
- stylesheets/icons.css - stylesheets/extra.css
``` ```
_Result_: _Result_:
@ -181,7 +180,7 @@ _Example_:
:octicons-heart-fill-24:{ .heart } :octicons-heart-fill-24:{ .heart }
``` ```
=== ":octicons-file-code-16: docs/stylesheets/icons.css" === ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css ``` css
@keyframes heart { @keyframes heart {
@ -201,7 +200,7 @@ _Example_:
``` yaml ``` yaml
extra_css: extra_css:
- stylesheets/icons.css - stylesheets/extra.css
``` ```
_Result_: _Result_:

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

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

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

@ -5,12 +5,12 @@ template: overrides/main.html
# Changing the colors # Changing the colors
As any proper Material Design implementation, Material for MkDocs supports 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 `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 [color palette]: http://www.materialui.co/colors
[2]: #custom-colors [custom colors]: #custom-colors
## Configuration ## Configuration
@ -18,9 +18,10 @@ fit your brand's identity by using [CSS variables][2].
#### Color scheme #### 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 called `default`, and a dark mode, which is called `slate`. The color scheme
can be set via `mkdocs.yml`: can be set via `mkdocs.yml`:
@ -30,7 +31,7 @@ theme:
scheme: default scheme: default
``` ```
_Click on a tile to change the color scheme_: Click on a tile to change the color scheme:
<div class="mdx-switch"> <div class="mdx-switch">
<button data-md-color-scheme="default"><code>default</code></button> <button data-md-color-scheme="default"><code>default</code></button>
@ -49,13 +50,14 @@ _Click on a tile to change the color scheme_:
}) })
</script> </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 #### 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 other components. In order to change the primary color, set the following value
in `mkdocs.yml` to a valid color name: in `mkdocs.yml` to a valid color name:
@ -65,7 +67,7 @@ theme:
primary: indigo primary: indigo
``` ```
_Click on a tile to change the primary color_: Click on a tile to change the primary color:
<div class="mdx-switch"> <div class="mdx-switch">
<button data-md-color-primary="red"><code>red</code></button> <button data-md-color-primary="red"><code>red</code></button>
@ -103,13 +105,14 @@ _Click on a tile to change the primary color_:
}) })
</script> </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 #### 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 hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
choosing a valid color name: choosing a valid color name:
@ -119,7 +122,7 @@ theme:
accent: indigo accent: indigo
``` ```
_Click on a tile to change the accent color_: Click on a tile to change the accent color:
<style> <style>
.md-typeset button[data-md-color-accent] > code { .md-typeset button[data-md-color-accent] > code {
@ -159,36 +162,45 @@ _Click on a tile to change the accent color_:
}) })
</script> </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 ### 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 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 can include a [`scheme`][palette.scheme], [`primary`][palette.primary] and
user can toggle between those color palettes: [`accent`][palette.accent] color each. The user can toggle between those color
palettes:
``` yaml hl_lines="4-6 8-10" ``` yaml
theme: theme:
palette: palette: # (1)
- scheme: default - scheme: default
toggle: toggle:
icon: material/toggle-switch-off-outline icon: material/toggle-switch-off-outline
name: Switch to dark mode name: Switch to dark mode
- scheme: slate - scheme: slate # (2)
toggle: toggle:
icon: material/toggle-switch icon: material/toggle-switch
name: Switch to light mode 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 – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled 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: combinations:
* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch` * :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-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
* :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb` * :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`
`name`{ #name } `name`{ #toggle-name }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :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 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 [palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
[7]: #color-scheme [palette.scheme]: #color-scheme
[8]: #primary-color [palette.primary]: #primary-color
[9]: #accent-color [palette.accent]: #accent-color
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### System preference ### 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, 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 a media query can be set as part of the `media` field next to the toggle
definition in `mkdocs.yml`: definition in `mkdocs.yml`:
``` yaml hl_lines="3 8" ``` yaml
theme: theme:
palette: palette:
- media: "(prefers-color-scheme: light)" - media: "(prefers-color-scheme: light)" # (1)
scheme: default scheme: default
toggle: toggle:
icon: material/toggle-switch-off-outline icon: material/toggle-switch-off-outline
name: Switch to dark mode name: Switch to dark mode
- media: "(prefers-color-scheme: dark)" - media: "(prefers-color-scheme: dark)" # (2)
scheme: slate scheme: slate
toggle: toggle:
icon: material/toggle-switch icon: material/toggle-switch
name: Switch to light mode 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 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 order of their definition. The first media query that matches selects the
default color palette. default color palette.
!!! warning "Accessibility – not all color combinations work well" [palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
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.
## Customization ## Customization
### Custom colors ### Custom colors
[:octicons-file-code-24: Source][11] · Material for MkDocs implements colors using [CSS variables] (custom
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs implements colors using [CSS variables][12] (custom
properties). If you want to customize the colors beyond the palette (e.g. to 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. tweak the values of the CSS variables.
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" } 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 __YouTube__, and want to set the primary color to your brand's palette. Just
add: add:
``` css === ":octicons-file-code-16: docs/stylesheets/extra.css"
:root {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
See the file containing the [color definitions][11] for a list of all CSS ``` css
variables. :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 === ":octicons-file-code-16: mkdocs.yml"
[12]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[13]: ../customization.md#additional-css ``` 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 ### 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 Besides overriding specific colors, you can create your own, named color scheme
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]` by wrapping the definitions in a `[data-md-color-scheme="..."]`
[attribute selector][14], which you can then set via `mkdocs.yml` as described [attribute selector], which you can then set via `mkdocs.yml` as described
in the [color schemes][7] section: in the [color schemes][palette.scheme] section:
``` css === ":octicons-file-code-16: docs/stylesheets/extra.css"
[data-md-color-scheme="youtube"] {
--md-primary-fg-color: #EE0F0F; ``` css
--md-primary-fg-color--light: #ECB7B7; [data-md-color-scheme="youtube"] {
--md-primary-fg-color--dark: #90030C; --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` 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 color functions and deduces its colors from the `--md-hue` CSS variable. You
@ -299,8 +322,10 @@ can tune the `slate` theme with:
``` css ``` css
[data-md-color-scheme="slate"] { [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 # Changing the fonts
Material for MkDocs makes it easy to change the typeface of your project 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 fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
or another destination should be used. or another destination should be used.
[1]: https://fonts.google.com [Google Fonts]: https://fonts.google.com
## Configuration ## Configuration
### Regular font ### Regular font
[:octicons-file-code-24: Source][2] · [:octicons-tag-24: 0.1.2][font support] ·
:octicons-milestone-24: Default: [`Roboto`][3] :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 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 ``` yaml
theme: theme:
@ -30,17 +30,17 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__. The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html [Roboto]: https://fonts.google.com/specimen/Roboto
[3]: https://fonts.google.com/specimen/Roboto [font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
### Monospaced font ### Monospaced font
[:octicons-file-code-24: Source][2] · [:octicons-tag-24: 0.1.2][font support] ·
:octicons-milestone-24: Default: [`Roboto Mono`][4] :octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
The _monospaced font_ is used for code blocks and can be configured separately. 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 Just like the regular font, it can be set to any valid [Google Font]
`mkdocs.yml` with: [Google Fonts] via `mkdocs.yml`:
``` yaml ``` yaml
theme: theme:
@ -50,55 +50,63 @@ theme:
The typeface will be loaded in 400. 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 [:octicons-tag-24: 1.0.0][font=false support] ·
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize :octicons-milestone-24: Default: _none_
font loading as described below.
### Disabling font loading 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
[:octicons-file-code-24: Source][2] · following lines to `mkdocs.yml`:
: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`:
``` yaml ``` yaml
theme: theme:
font: false font: false
``` ```
[data privacy]: ../data-privacy.md
[font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
## Customization
### Additional fonts ### Additional fonts
[:octicons-file-code-24: Source][2] · If you want to load an (additional) font from another destination or override
:octicons-mortar-board-24: Difficulty: _easy_ the system font, you can use an [additional style sheet] to add the
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
corresponding `@font-face` definition: corresponding `@font-face` definition:
``` css === ":octicons-file-code-16: docs/stylesheets/extra.css"
@font-face {
font-family: "<font>"; ``` css
src: "..."; @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 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 globally to be used as the site-wide regular or monospaced font:
fonts being added automatically):
=== "Regular font" === "Regular font"
``` css ``` css
:root { :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" === "Monospaced font"
``` css ``` css
@ -107,7 +115,4 @@ fonts being added automatically):
} }
``` ```
[5]: ../data-privacy.md [additional style sheet]: ../customization.md#additional-css
[6]: ../customization.md#extending-the-theme
[7]: ../customization.md#overriding-blocks-recommended
[8]: ../customization.md#additional-stylesheets

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 Material for MkDocs supports internationalization (i18n) and provides
translations for template variables and labels in 40+ languages. Additionally, translations for template variables and labels in 40+ languages. Additionally,
the site search can be configured to use a language-specific stemmer (if the site search can be configured to use a language-specific stemmer, if
available). available.
## Configuration ## Configuration
### Site language ### 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 ``` yaml
theme: theme:
@ -79,70 +80,72 @@ The following languages are supported:
</div> </div>
_Note that some languages will produce unreadable anchor links, due to the way 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, the default slug function works. Consider using a [Unicode-aware slug function].
as [documented here][2]._
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/en.html [language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
[2]: setting-up-navigation.md#slugify [Unicode-aware slug function]: setting-up-navigation.md#slugify
### Site language selector ### 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 :octicons-beaker-24: Experimental
If your documentation is available in multiple languages, a _language selector_ 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 pointing to those languages can be added to the header. Alternate languages
defined via `mkdocs.yml`: can be defined via `mkdocs.yml`.
``` yaml ``` yaml
extra: extra:
alternate: alternate:
# Switch to English
- name: English - name: English
link: <your-site>/en/ link: /en/ # (1)
lang: en lang: en
# Switch to German
- name: Deutsch - name: Deutsch
link: <your-site>/de/ link: /de/
lang: 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 `name`{ #language-name }
[4]: ../assets/screenshots/language-selection.png
### 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] · `link`{ #language-link }
:octicons-milestone-24: Default: _automatically set_
Some languages, like Arabic or Japanese, need dedicated stemmers for search to : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
work properly. Material for MkDocs relies on [lunr-languages][6] to provide this This field must be set to an absolute link, which might also point to
functionality. See the guide detailing how to [set up site search][7] for another domain or subdomain not necessarily generated with MkDocs.
more information.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts `lang`{ #language-lang }
[6]: https://github.com/MihaiValentin/lunr-languages
[7]: setting-up-site-search.md : :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 ### Directionality
[:octicons-file-code-24: Source][8] · [:octicons-tag-24: 2.5.0][direction support] ·
:octicons-milestone-24: Default: _automatically set_ :octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also 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: selected language, but can also be set with:
``` yaml ``` yaml
@ -163,44 +166,46 @@ Click on a tile to change the directionality:
button.addEventListener("click", function() { button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir") var attr = this.getAttribute("data-md-dir")
document.body.dir = attr 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 name.textContent = attr
}) })
}) })
</script> </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 ## Customization
### Custom translations ### 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 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 the guide on [theme extension] and create a new partial in the `overrides`
`partials/languages`, e.g. `en-custom.html`. Next, look up the translation you folder. Then import the [translations] of your language as a fallback and only
want to change in the [base translation][1] and add it to the partial. 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 ``` html
<!-- Use en language as fallback --> <!-- Import translations for your language as fallback -->
{% import "partials/languages/en.html" as fallback %} {% import "partials/languages/" ~ config.theme.language ~ ".html" as fallback %}
{% macro override(key) %}{{ { {% macro override(key) %}{{ {
"toc.title": "On this page" "toc.title": "On this page" <!-- (1) -->
}[key] }}{% endmacro %} }[key] }}{% endmacro %}
<!-- Re-export the translation macro for mkbuild-material to use --> <!-- Re-export translations -->
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %} {% 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 === ":octicons-file-code-16: mkdocs.yml"
theme:
language: en-custom
```
[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 # 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 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 when writing your documentation in Markdown. Not enough? You can also add
additional icons][1] with minimal effort. [additional icons] with minimal effort.
[1]: #additional-icons [additional icons]: #additional-icons
## Configuration ## Configuration
### Logo ### Logo
[:octicons-file-code-24: Source][2] · [:octicons-tag-24: 0.1.0][logo support] ·
:octicons-milestone-24: Default: [`material/library`][3] :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. `*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
Add the following lines to `mkdocs.yml`: Add the following lines to `mkdocs.yml`:
=== "Image" === ":octicons-image-16: Image"
``` yaml ``` yaml
theme: theme:
logo: assets/logo.png logo: assets/logo.png
``` ```
=== "Icon, bundled" === ":octicons-package-16: Icon, bundled"
``` yaml ``` yaml
theme: theme:
@ -37,9 +37,8 @@ Add the following lines to `mkdocs.yml`:
logo: material/library logo: material/library
``` ```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html [logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg [logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
Normally, the logo in the header and sidebar links to the homepage of the 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 documentation, which is the same as `site_url`. This behavior can be changed
@ -52,60 +51,28 @@ extra:
### Favicon ### Favicon
[:octicons-file-code-24: Source][5] · [:octicons-tag-24: 0.1.0][favicon support] ·
:octicons-milestone-24: Default: `assets/images/favicon.png` :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 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`: must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml ``` yaml
theme: theme:
favicon: images/favicon.png favicon: images/favicon.png
``` ```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html [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
### 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/
## Customization ## Customization
### Additional icons ### Additional icons
[:octicons-file-code-24: Source][4] · In order to use custom icons, [extend the theme] and create a new folder named
:octicons-mortar-board-24: Difficulty: _easy_ `.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
In order to add additional icons, [extend the theme][12], and create a folder you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
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
your project documentation. The structure of your project should look like this: your project documentation. The structure of your project should look like this:
``` sh ``` sh
@ -129,9 +96,8 @@ markdown_extensions:
- overrides/.icons - overrides/.icons
``` ```
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap You can now use all :fontawesome-brands-bootstrap: Bootstrap icons.
icons.
[12]: ../customization.md#extending-the-theme [extend the theme]: ../customization.md#extending-the-theme
[13]: https://www.mkdocs.org/user-guide/configuration/#custom_dir [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[14]: https://icons.getbootstrap.com/ [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. syntax extensions for technical writing.
[John Gruber's Markdown]: https://daringfireball.net/projects/markdown/ [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
[Python Markdown]: #python-markdown.md [Python Markdown]: python-markdown.md
[Python Markdown Extensions]: #python-markdown-extensions.md [Python Markdown Extensions]: python-markdown-extensions.md
## Supported extensions ## Supported extensions

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

@ -15,8 +15,8 @@ installed with a supported version.
### Arithmatex ### Arithmatex
[:octicons-workflow-24: Extension][Arithmatex] · [:octicons-tag-24: 1.0.0][Arithmatex support] ·
[:octicons-tag-24: 1.0.0 ... present][Arithmatex support] [:octicons-workflow-24: Extension][Arithmatex]
The [Arithmatex] extension allows for rendering of block and inline block The [Arithmatex] extension allows for rendering of block and inline block
equations and integrates seamlessly with [MathJax][^1] – a library for equations and integrates seamlessly with [MathJax][^1] – a library for
@ -87,8 +87,8 @@ See reference for usage:
### BetterEm ### BetterEm
[:octicons-workflow-24: Extension][BetterEm] · [:octicons-tag-24: 0.1.0][BetterEm support] ·
[:octicons-tag-24: 0.1.0 ... present][BetterEm support] [:octicons-workflow-24: Extension][BetterEm]
The [BetterEm] extension improves the detection of Markup to emphasize text The [BetterEm] extension improves the detection of Markup to emphasize text
in Markdown using special characters, i.e. for `**bold**` and `_italic_` in Markdown using special characters, i.e. for `**bold**` and `_italic_`
@ -108,8 +108,8 @@ documentation][BetterEm] for more information.
### Caret, Mark & Tilde ### Caret, Mark & Tilde
[:octicons-workflow-24: Extension][Caret] · [:octicons-tag-24: 1.0.0][Caret support] ·
[:octicons-tag-24: 1.0.0 ... present][Caret support] [:octicons-workflow-24: Extension][Caret]
The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
and define sub- and superscript using a simple syntax. Enable them together and define sub- and superscript using a simple syntax. Enable them together
@ -140,8 +140,8 @@ See reference for usage:
### Critic ### Critic
[:octicons-workflow-24: Extension][Critic] · [:octicons-tag-24: 1.0.0][Critic support] ·
[:octicons-tag-24: 1.0.0 ... present][Critic support] [:octicons-workflow-24: Extension][Critic]
The [Critic] extension allows for the usage of [Critic Markup] to highlight 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 added, deleted or updated sections in a document, i.e. for tracking changes in
@ -195,8 +195,8 @@ See reference for usage:
### Details ### Details
[:octicons-workflow-24: Extension][Details] · [:octicons-tag-24: 1.9.0][Details support] ·
[:octicons-tag-24: 1.9.0 ... present][Details support] [:octicons-workflow-24: Extension][Details]
The [Details] extension supercharges the [Admonition] extension, making the The [Details] extension supercharges the [Admonition] extension, making the
resulting _call-outs_ collapsible, allowing them to be opened and closed by 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 ### Emoji
[:octicons-workflow-24: Extension][Emoji] · [:octicons-tag-24: 1.0.0][Emoji support] ·
[:octicons-tag-24: 1.0.0 ... present][Emoji support] [:octicons-workflow-24: Extension][Emoji]
The [Emoji] extension automatically inlines bundled and custom icons and emojis 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`: in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
@ -297,13 +297,14 @@ See reference for usage:
### Highlight ### Highlight
[:octicons-tag-24: 5.0.0][Highlight support] ·
[:octicons-workflow-24: Extension][Highlight] · [:octicons-workflow-24: Extension][Highlight] ·
[:octicons-tag-24: 5.0.0 ... present][Highlight support] ·
:octicons-zap-24: Supersedes [CodeHilite] :octicons-zap-24: Supersedes [CodeHilite]
The [Highlight] extension adds support for syntax highlighting of code blocks The [Highlight] extension adds support for syntax highlighting of code blocks
(with the help of [SuperFences][SuperFences #]) and inline code blocks (with (with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
the help of [InlineHilite][InlineHilite #]). Enable it via `mkdocs.yml`: (with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
`mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -311,7 +312,7 @@ markdown_extensions:
- pymdownx.superfences # (1) - 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 perform syntax highlighting on code blocks, not the other way round, which
is why this extension also needs to be enabled. 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]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 [Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[CodeHilite]: python-markdown.md#codehilite [CodeHilite]: python-markdown.md#codehilite
[SuperFences #]: #superfences [pymdownx.superfences]: #superfences
[InlineHilite #]: #inlinehilite [pymdownx.inlinehilite]: #inlinehilite
[Pygments]: https://pygments.org [Pygments]: https://pygments.org
[additional CSS]: ../../customization.md#additional-css [additional CSS]: ../../customization.md#additional-css
[Highlight.js]: https://highlightjs.org/ [Highlight.js]: https://highlightjs.org/
@ -422,12 +423,12 @@ See reference for usage:
### InlineHilite ### InlineHilite
[:octicons-workflow-24: Extension][InlineHilite] · [:octicons-tag-24: 5.0.0][InlineHilite support] ·
[:octicons-tag-24: 5.0.0 ... present][InlineHilite support] [:octicons-workflow-24: Extension][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][Highlight #] extension, from which blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
it sources its configuration. Enable it via `mkdocs.yml`: which it sources its configuration. Enable it via `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -447,13 +448,13 @@ See reference for usage:
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 [InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options [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 [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
### Keys ### Keys
[:octicons-workflow-24: Extension][Keys] · [:octicons-tag-24: 1.0.0][Keys support] ·
[:octicons-tag-24: 1.0.0 ... present][Keys support] [:octicons-workflow-24: Extension][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`: keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
@ -479,8 +480,8 @@ See reference for usage:
### SmartSymbols ### SmartSymbols
[:octicons-workflow-24: Extension][SmartSymbols] · [:octicons-tag-24: 0.1.0][SmartSymbols support] ·
[:octicons-tag-24: 0.1.0 ... present][SmartSymbols support] [:octicons-workflow-24: Extension][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 corresponding symbols, e.h. copyright symbols or fractions. Enable it via
@ -500,8 +501,8 @@ documentation][SmartSymbols] for guidance.
### Snippets ### Snippets
[:octicons-workflow-24: Extension][Snippets] · [:octicons-tag-24: 0.1.0][Snippets support] ·
[:octicons-tag-24: 0.1.0 ... present][Snippets support] [:octicons-workflow-24: Extension][Snippets]
The [Snippets] extension adds the ability to embed content from arbitrary files 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 into a document, including other documents or source files, by using a simple
@ -528,8 +529,8 @@ See reference for usage:
### SuperFences ### SuperFences
[:octicons-tag-24: 0.1.0][SuperFences support] ·
[:octicons-workflow-24: Extension][SuperFences] · [:octicons-workflow-24: Extension][SuperFences] ·
[:octicons-tag-24: 0.1.0 ... present][SuperFences support] ·
:octicons-zap-24: Supersedes [Fenced Code Blocks] :octicons-zap-24: Supersedes [Fenced Code Blocks]
The [SuperFences] extension allows for arbitrary nesting of code and content The [SuperFences] extension allows for arbitrary nesting of code and content
@ -587,8 +588,8 @@ See reference for usage:
### Tabbed ### Tabbed
[:octicons-workflow-24: Extension][Tabbed] · [:octicons-tag-24: 5.0.0][Tabbed support] ·
[:octicons-tag-24: 5.0.0 ... present][Tabbed support] [:octicons-workflow-24: Extension][Tabbed]
The [Tabbed] extension allows the usage of content tabs, a simple way to group 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 related content and code blocks under accessible tabs. Enable it via
@ -636,8 +637,8 @@ See reference for usage:
### Tasklist ### Tasklist
[:octicons-workflow-24: Extension][Tasklist] · [:octicons-tag-24: 1.0.0][Tasklist support] ·
[:octicons-tag-24: 1.0.0 ... present][Tasklist support] [:octicons-workflow-24: Extension][Tasklist]
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown] The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Tasklist specification], following the same syntactical 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]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[GitHub Flavored Markdown]: https://github.github.com/gfm/ [GitHub Flavored Markdown]: https://github.github.com/gfm/
[Tasklist #]: #tasklist
[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension- [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists [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 ### Abbreviations
[:octicons-workflow-24: Extension][Abbreviations] · [:octicons-tag-24: 1.0.0][Abbreviations support] ·
[:octicons-tag-24: 1.0.0 ... present][Abbreviations support] [:octicons-workflow-24: Extension][Abbreviations]
The [Abbreviations] extension adds the ability to add a small tooltip to an 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 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 ### Admonition
[:octicons-workflow-24: Extension][Admonition] · [:octicons-tag-24: 0.1.0][Admonition support] ·
[:octicons-tag-24: 0.1.0 ... present][Admonition support] [:octicons-workflow-24: Extension][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 _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 ### Attribute Lists
[:octicons-workflow-24: Extension][Attribute Lists] · [:octicons-tag-24: 0.1.0][Attribute Lists support] ·
[:octicons-tag-24: 0.1.0 ... present][Attribute Lists support] [:octicons-workflow-24: Extension][Attribute Lists]
The [Attribute Lists] extension allows to add HTML attributes and CSS classes The [Attribute Lists] extension allows to add HTML attributes and CSS classes
to [almost every][Attribute Lists limitations] Markdown inline- and block-level 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 ### Definition Lists
[:octicons-workflow-24: Extension][Definition Lists] · [:octicons-tag-24: 1.1.0][Definition Lists support] ·
[:octicons-tag-24: 1.1.0 ... present][Definition Lists support] [:octicons-workflow-24: Extension][Definition Lists]
The [Definition Lists] extension adds the ability to add definition lists (more The [Definition Lists] extension adds the ability to add definition lists (more
commonly known as [description lists] – `dl` in HTML) via Markdown to a 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 ### Footnotes
[:octicons-workflow-24: Extension][Footnotes] · [:octicons-tag-24: 1.0.0][Footnotes support] ·
[:octicons-tag-24: 1.0.0 ... present][Footnotes support] [:octicons-workflow-24: Extension][Footnotes]
The [Footnotes] extension allows to define inline footnotes, which are then The [Footnotes] extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`: 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 ### Metadata
[:octicons-workflow-24: Extension][Metadata] · [:octicons-tag-24: 1.0.0][Metadata support] ·
[:octicons-tag-24: 1.0.0 ... present][Metadata support] [:octicons-workflow-24: Extension][Metadata]
The [Metadata] extension adds the ability to attach arbitrary key-value pairs 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. 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 ### Markdown in HTML
[:octicons-workflow-24: Extension][Markdown in HTML] · [:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
[:octicons-tag-24: 0.1.0 ... present][Markdown in HTML support] [:octicons-workflow-24: Extension][Markdown in HTML]
The [Markdown in HTML] extension allows for writing Markdown inside of 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 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 ### Table of Contents
[:octicons-workflow-24: Extension][Table of Contents] · [:octicons-tag-24: 0.1.0][Table of Contents support] ·
[:octicons-tag-24: 0.1.0 ... present][Table of Contents support] [:octicons-workflow-24: Extension][Table of Contents]
The [Table of Contents] extension automatically generates a 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
@ -292,8 +292,8 @@ own risk.
### Tables ### Tables
[:octicons-workflow-24: Extension][Tables] · [:octicons-tag-24: 0.1.0][Tables support] ·
[:octicons-tag-24: 0.1.0 ... present][Tables support] [:octicons-workflow-24: Extension][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 simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
@ -322,8 +322,8 @@ should be considered.
### Fenced Code Blocks ### Fenced Code Blocks
[:octicons-workflow-24: Extension][Fenced Code Blocks] · [:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
[:octicons-tag-24: 0.1.0 ... present][Fenced Code Blocks support] [:octicons-workflow-24: Extension][Fenced Code Blocks]
Superseded by [SuperFences]. This extension might still work, but the 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
@ -335,8 +335,8 @@ nesting, and is therefore recommended.
### CodeHilite ### 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 Superseded by [Highlight]. Support for CodeHilite was dropped in
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other :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 A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides a multitude of options to configure documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs][1] and [sections][2], the behavior of navigational elements, including [tabs][navigation.tabs] and
and its flag-ship feature: [instant loading][3]. [sections][navigation.sections], and its flag-ship feature: [instant loading]
[navigation.instant].
[1]: #navigation-tabs [navigation.tabs]: #navigation-tabs
[2]: #navigation-sections [navigation.sections]: #navigation-sections
[3]: #instant-loading [navigation.instant]: #instant-loading
## Configuration ## Configuration
### Instant loading ### Instant loading
[:octicons-file-code-24: Source][4] · [:octicons-tag-24: 5.0.0][navigation.instant support] ·
:octicons-unlock-24: Feature flag :octicons-unlock-24: Feature flag
When _instant loading_ is enabled, clicks on all internal links will be When instant loading is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR][5] without fully reloading the page. Add intercepted and dispatched via [XHR] without fully reloading the page. Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
``` yaml ``` yaml
@ -31,23 +32,21 @@ theme:
``` ```
The resulting page is parsed and injected and all event handlers and components 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 are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
Single Page Application__, which is especially useful for large documentation Page Application__. Now, the search index survives navigation, which is
sites that come with a massive search index, as the search index will now especially useful for large documentation sites.
remain intact in-between document switches.
_Material for MkDocs is the only MkDocs theme offering this feature._ [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
[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
### Anchor tracking ### 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-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 updated with the active anchor as highlighted in the table of contents. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
@ -57,24 +56,25 @@ theme:
- navigation.tracking - navigation.tracking
``` ```
[6]: ../insiders/index.md [Insiders]: ../insiders/index.md
### Navigation tabs ### 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 header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
[^1]: [^1]:
Prior to version 6.2, navigation tabs had a slightly different behavior. Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
All top-level pages (i.e. all top-level entries that directly refer to an behavior. All top-level pages (i.e. all top-level entries directly
`*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped refefring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
under the first tab which received the title of the first page. This made were grouped under the first tab which received the title of the first page.
it impossible to include a top-level page (or external link) as a tab item, This made it impossible to include a top-level page (or external link) as a
as was reported in #1884 and #2072. From version 6.2 on, navigation tabs tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
include all top-level pages and sections. on, navigation tabs include all top-level pages and sections.
``` yaml ``` yaml
theme: theme:
@ -84,23 +84,23 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![With tabs][8]][8] [![navigation.tabs enabled]][navigation.tabs enabled]
=== ":octicons-skip-16: Disabled" === ":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 [navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[8]: ../assets/screenshots/navigation-tabs.png [navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png
[9]: ../assets/screenshots/navigation.png [navigation.tabs disabled]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs #### 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-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental :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 always remain visible when scrolling down. Just add the following two feature
flags to `mkdocs.yml`: flags to `mkdocs.yml`:
@ -113,22 +113,22 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![With sticky tabs][11]][11] [![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled]
=== ":octicons-skip-16: Disabled" === ":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 [navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[11]: ../assets/screenshots/navigation-tabs-sticky.png [navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs.png
[12]: ../assets/screenshots/navigation-tabs-collapsed.png [navigation.tabs.sticky disabled]: ../assets/screenshots/navigation.png
### Navigation sections ### Navigation sections
[:octicons-file-code-24: Source][13] · [:octicons-tag-24: 6.2.0][navigation.sections support] ·
:octicons-unlock-24: Feature flag :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 sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
@ -140,25 +140,27 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![With sections][14]][14] [![navigation.sections enabled]][navigation.sections enabled]
=== ":octicons-skip-16: Disabled" === ":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 [navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
[14]: ../assets/screenshots/navigation-sections.png [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, [`navigation.tabs`][navigation.tabs] and
both feature flags are enabled, sections are rendered for level 2 navigation [`navigation.sections`][navigation.sections], can be combined with each other.
If both feature flags are enabled, sections are rendered for level 2 navigation
items. items.
### Navigation expansion ### Navigation expansion
[:octicons-file-code-24: Source][13] · [:octicons-tag-24: 6.2.0][navigation.expand support] ·
:octicons-unlock-24: Feature flag :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. subsections by default, so the user doesn't have to open subsections manually.
Add the following lines to `mkdocs.yml`: Add the following lines to `mkdocs.yml`:
@ -170,21 +172,23 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![With expansion][15]][15] [![navigation.expand enabled]][navigation.expand enabled]
=== ":octicons-skip-16: Disabled" === ":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 ### Section index pages
[:octicons-file-code-24: Source][16] · [:octicons-tag-24: 7.3.0][navigation.indexes support] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental :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 sections, which is particularly useful for providing overview pages. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
@ -196,11 +200,11 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![With expansion][17]][17] [![navigation.indexes enabled]][navigation.indexes enabled]
=== ":octicons-skip-16: Disabled" === ":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 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 `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 - Page n: section/page-n.md
``` ```
_This feature flag can be combined with all other feature flags, e.g. [tabs][1] This feature flag is not compatible with [`toc.integrate`][toc.integrate].
and [sections][2], except for table of contents [navigation integration][19]._
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html [navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
[17]: ../assets/screenshots/navigation-index-on.png [navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png
[18]: ../assets/screenshots/navigation-index-off.png [navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png
[19]: #navigation-integration [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 :octicons-unlock-24: Feature flag
A _back-to-top button_ can be shown when the user, after scrolling down, starts When navigation integration for the table of contents is enabled, it is always
to scroll up again. It's rendered centered and just below the header. Add the rendered as part of the navigation sidebar on the left. Add the following lines
following lines to `mkdocs.yml`: 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`:
``` yaml ``` yaml
theme: theme:
@ -346,29 +243,44 @@ theme:
=== ":octicons-check-circle-fill-16: Enabled" === ":octicons-check-circle-fill-16: Enabled"
[![Integrate table of contents][27]][27] [![toc.integrate enabled]][toc.integrate enabled]
=== ":octicons-skip-16: Disabled" === ":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 This feature flag is not compatible with [`navigation.indexes`]
[27]: ../assets/screenshots/toc-integrate.png [navigation.indexes].
The content section will now always stretch to the right side, resulting in [toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
more space for your content. This feature flag can be combined with all other [toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
feature flags, e.g. [tabs][1] and [sections][2]. [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 ## Usage
### Hiding the sidebars ### Hiding the sidebars
[:octicons-file-code-24: Source][28] · When [Metadata] is enabled, the navigation and/or table of contents sidebars
:octicons-note-24: Metadata can be hidden for a document with custom front matter. Add the following lines
at the top of a Markdown file:
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:
``` bash ``` bash
--- ---
@ -383,29 +295,25 @@ hide:
=== "Hide navigation" === "Hide navigation"
[![Hide navigation][30]][30] [![hide.navigation enabled]][hide.navigation enabled]
=== "Hide table of contents" === "Hide table of contents"
[![Hide table of contents][31]][31] [![hide.toc enabled]][hide.toc enabled]
=== "Hide both" === "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 [Metadata]: extensions/python-markdown.md#metadata
[29]: ../../reference/meta-tags/#metadata [hide.navigation enabled]: ../assets/screenshots/hide-navigation.png
[30]: ../assets/screenshots/hide-navigation.png [hide.toc enabled]: ../assets/screenshots/hide-toc.png
[31]: ../assets/screenshots/hide-toc.png [hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png
[32]: ../assets/screenshots/hide-navigation-toc.png
## Customization ## Customization
### Keyboard shortcuts ### 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 Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There're two modes: 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 * ++n++ , ++period++ : go to next page
Let's say you want to bind some action to the ++x++ key. By using [additional 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: your custom event listener:
``` js === ":octicons-file-code-16: docs/javascripts/shortcuts.js"
keyboard$.subscribe(function(key) {
if (key.mode === "global" && key.type === "x") {
/* Add custom keyboard handler here */
key.claim()
}
})
```
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()` ``` js
on the underlying event, so the keypress will not propagate further and touch keyboard$.subscribe(function(key) {
other event listeners. 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 1. The call to `key.claim()` will execute `preventDefault()` on the
[34]: ../customization.md#additional-javascript 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 ### 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 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 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 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 desirable to increase the overall width of the content area, or even make it
stretch to the entire available space. 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: of CSS:
=== "Increase width" === ":octicons-file-code-16: docs/stylesheets/extra.css"
``` css ``` css
.md-grid { .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 ``` css
.md-grid { .md-grid {
max-width: initial; 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 [additional style sheet]: ../customization.md#additional-css
[36]: ../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-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ · :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 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 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-hash-24: Setting · :octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ · :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 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 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 } `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]. to include the language-specific stemmers provided by [lunr-languages][5].
Note that Material for MkDocs will set this automatically based on the 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 [site language][6], but it may be overridden, e.g. to support multiple
@ -100,7 +100,7 @@ The following options are supported:
`separator`{ #separator } `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 indexing and query tokenization can be customized, making it possible to
index parts of words separated by other characters than whitespace and `-`, index parts of words separated by other characters than whitespace and `-`,
e.g. by including `.`: e.g. by including `.`:
@ -148,7 +148,7 @@ Use them at your own risk._
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :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 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 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-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :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, When _search highlighting_ is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link. 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-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :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 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 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata · :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 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 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-note-24: Metadata · :octicons-note-24: Metadata ·
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-3.1.0 ... present][Insiders] [:octicons-tag-24: insiders-3.1.0][Insiders]
#### Excluding pages #### 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-cpu-24: Plugin · :octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental · :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 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 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: `cards_color`{ #cards-color } :material-new-box:
: :octicons-milestone-24: Default: _automatically set based on [primary : :octicons-milestone-24: Default: [`primary
color][8]_ – This option specifies which colors to use for the background color`][8]_ – This option specifies which colors to use for the background
`fill` and foreground `text` when generating the social card. `fill` and foreground `text` when generating the social card.
``` yaml ``` 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-cpu-24: Plugin · :octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental · :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 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 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-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ · :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 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` footer of your project documentation. Add a list of social links in `mkdocs.yml`
@ -30,7 +30,7 @@ extra:
link: https://twitter.com/squidfunk link: https://twitter.com/squidfunk
``` ```
For each entry, the following fields are available: For each entry, the following settings are available:
`icon`{ #icon } `icon`{ #icon }
@ -95,7 +95,7 @@ For each entry, the following fields are available:
:octicons-hash-24: Setting · :octicons-hash-24: Setting ·
:octicons-milestone-24: Default: _none_ · :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 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`: 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-hash-24: Setting ·
:octicons-milestone-24: Default: `true` · :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 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 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 ### Automatic hiding
:octicons-unlock-24: Feature flag · :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 When _autohiding_ is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. Add the user scrolls past a certain threshold, leaving more space for content. Add the
@ -36,7 +36,7 @@ theme:
### Announcement bar ### Announcement bar
:octicons-file-symlink-file-24: Customization · :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 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 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-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-file-symlink-file-24: Customization · :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 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], 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 ### Stay on page
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [: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 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 version A and B contain a page with the same path name, the user will stay on