225 docs/reference/icons-emojis.md
View file
@@ -0,0 +1,225 @@
---
template: overrides/main.html
---

# Icons + Emojis

One of the best features of Material for MkDocs is the possibility to use [more
than _7.000 icons_][1] and _thousands of emojis_ in your project documentation
with practically zero additional effort. Furthermore, custom icons can be used
in `mkdocs.yml`, documents and templates.

## Configuration

### Emoji

[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]

The [Emoji][3] extension, which is part of [Python Markdown Extensions][4],
adds the ability to __integrate emojis and icons__ in the `*.svg` file format,
which are inlined when [building your site][5]:

``` 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][6]
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
* :octicons-mark-github-16: – [Octicons][8]

You can also add [additional icons][9]. When using emojis, it's recommended to
consult the official documentation of [Python Markdown Extensions][3] to learn
about configuration options.

[1]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[4]: https://facelessuser.github.io/pymdown-extensions/
[5]: ../creating-your-site.md#building-your-site
[6]: https://materialdesignicons.com/
[7]: https://fontawesome.com/icons?d=gallery&m=free
[8]: https://octicons.github.com/
[9]: ../setup/changing-the-logo-and-icons.md#additional-icons

### Attribute List

The [Attribute List][10] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`

``` yaml
markdown_extensions:
- attr_list
```

[10]: https://python-markdown.github.io/extensions/attr_list/

## Usage

### Using emojis

Emojis can be integrated in Markdown by putting the shortcode of the emoji
between two colons. If you're using [Twemoji][11] (recommended), you can look up
the shortcodes at [Emojipedia][12].

_Example_:

```
:smile:
```

_Result_:

:smile:

[11]: https://twemoji.twitter.com/
[12]: https://emojipedia.org/twitter/

### Using icons

When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing
a valid path to any icon bundled with the theme, which are located in the
[`.icons`][1] directory, and replacing `/` with `-`:

_Example_:

```
* :material-account-circle: – `.icons/material/account-circle.svg`
* :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
* :octicons-octoface-16: – `.icons/octicons/octoface-16.svg`
```

_Result_:

* :material-account-circle: – [`.icons/material/account-circle.svg`][14]
* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16]

[13]: #emoji
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg

#### with colors

When the [Attribute List][17] extension is enabled, custom CSS classes and
attributes can be added to icons by suffixing the icon with a special syntax.
While HTML and CSS allow to use [inline styles][18], it's always best to add
an [additional stylesheet][19] and put styles into dedicated CSS classes:

``` css
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
```

Then, simply add the CSS class to the icon.

<style>
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
</style>

_Example_:

``` markdown
* :fontawesome-brands-medium:{: .medium } – Medium
* :fontawesome-brands-twitter:{: .twitter } – Twitter
* :fontawesome-brands-facebook:{: .facebook } – Facebook
```

_Result_:

* :fontawesome-brands-medium:{: .medium } – Medium
* :fontawesome-brands-twitter:{: .twitter } – Twitter
* :fontawesome-brands-facebook:{: .facebook } – Facebook

[17]: #attribute-list
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
[19]: ../customization.md#additional-stylesheets

#### with animations

Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to
icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule
and adding the dedicated CSS class to the icon:

``` css
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
animation: heart 1000ms infinite;
}
```

Then, simply add the CSS class to the icon.

<style>
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
animation: heart 1000ms infinite;
}
</style>

_Example_:

``` markdown
:octicons-heart-fill-24:{: .heart }
```

_Result_:

:octicons-heart-fill-24:{: .heart }

[20]: #with-colors
[21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation

## Customization

### Using icons in templates

When you're [extending the theme][22] with partials or blocks, you can simply
reference any icon that's [bundled with the theme][1] with Jinja's
[`include`][23] function and wrap it with the `twemoji` class:

``` html
<span class="twemoji">
{% include ".icons/fontawesome/brands/twitter.svg" %}
</span>
```

This is exactly what Material for MkDocs does in its templates.

[22]: ../customization.md#extending-the-theme
[23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
89 docs/reference/images.md
View file
@@ -0,0 +1,89 @@
---
template: overrides/main.html
---

# Images

While images are first-class citizens of Markdown and part of the core syntax,
it can be difficult to work with them. Material for MkDocs makes working with
images more comfortable by providing styles for alignment and image captions.

[1]: https://www.markdownguide.org/basic-syntax/#images-1

## Configuration

### Attribute List

The [Attribute List][2] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`

``` yaml
markdown_extensions:
- attr_list
```

[2]: https://python-markdown.github.io/extensions/attr_list/

## Usage

### Image alignment

When the [Attribute List][2] extension is enabled, images can be aligned by
adding the respective alignment directions via the `align` attribute, i.e.
`align=left` or `align=right`

=== "Left"

_Example_:

``` markdown
![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=left }
```

_Result_:

![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=left width=300 }

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

=== "Right"

_Example_:

``` markdown
![Placeholder](https://dummyimage.com/600x400/eee/aaa){ align=right }
```

_Result_:

![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ align=right width=300 }

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

_If there's insufficient space to render the text next to the image, the image
will stretch to the full width of the viewport, e.g. on mobile viewports._

### Image captions

Sadly, the Markdown syntax doesn't provide native support for image captions,
but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images.

_Example_:

```html
<figure>
<img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
<figcaption>Image caption</figcaption>
</figure>
```

_Result_:
<figure>
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
<figcaption>Image caption</figcaption>
</figure>
202 docs/reference/lists.md
View file
@@ -0,0 +1,202 @@
---
template: overrides/main.html
---

# Lists

Material for MkDocs supports several flavors of lists that cater to different
use cases, including _unordered lists_ and _ordered lists_, which are supported
through standard Markdown, as well as _definition lists_ and _task lists_, which
are supported through extensions.

## Configuration

### Definition List

[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]

The [Definition List][2] extension, which is part of the standard Markdown
library, adds the ability to add definitions lists to a document and can be
enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- def_list
```

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[2]: https://python-markdown.github.io/extensions/definition_lists/

### Tasklist

[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]

The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5],
adds support for lists with styled checkboxes, and provides several options for
configuring the style:

`custom_checkbox`{: #custom-checkbox }

: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore _strongly recommended_:

``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```

`clickable_checkbox`{: #clickable-checkbox }

: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:

``` yaml
markdown_extensions:
- pymdownx.tasklist:
clickable_checkbox: true
```

[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tasklist.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[5]: https://facelessuser.github.io/pymdown-extensions/

## Usage

### Using unordered lists

An unordered list can be written by prefixing a line with a `-`, `*` or `+`
list marker, all of which can be used interchangeably. Furthermore, all flavors
of lists can be nested inside each other.

_Example_:

``` markdown
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.

* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.
```

_Result_:

* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.

* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.

### Using ordered lists

An ordered list must start with a number immediately followed by a dot. The
numbers do not need to be consecutive and can be all set to `1.`, as they will
be re-numbered when rendered.

_Example_:

``` markdown
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.

1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.

2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu
```

_Result_:

1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.

1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.

2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu

### Using definition lists

[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g.
the parameters of functions or modules, as used within this documentation to
describe extension or plugin parameters.

_Example_:

``` markdown
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
```

_Result_:

`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.

[6]: #definition-lists

### Using tasklists

When the [Tasklist][7] extension is enabled, unordered list items can be
prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
checkbox.

_Example_:

``` markdown
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
```

_Result_:

* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

[7]: #tasklist
134 docs/reference/mathjax.md
View file
@@ -0,0 +1,134 @@
---
template: overrides/main.html
---

# MathJax

[MathJax][1] is a beautiful and accessible way to display _mathematical content_
in the browser, allows for writing formulas in different notations, including
[LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with
Material for MkDocs.

[1]: https://www.mathjax.org/
[2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
[3]: https://en.wikipedia.org/wiki/MathML
[4]: http://asciimath.org/

## Configuration

### Arithmatex

[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]

The [Arithmatex][6] extension, which is part of of [Python Markdown
Extensions][7], allows the rendering of block and inline block equations, and
can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
```

Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with [additional
JavaScript][8]:

=== "docs/javascripts/config.js"

``` js
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
```

=== "mkdocs.yml"

``` yaml
extra_javascript:
- javascripts/config.js
- https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
```

_MathJax can be configured in many different ways, for which Material for MkDocs
might not provide native support. See the [official documentation][6] for more
information._

!!! tip "Using MathJax with [instant loading][9]"

There's no additional effort necessary to integrate _MathJax 3_ with
[instant loading][7] – it's expected to work straight away. However, a
previous version of this document explained how to integrate Material for
MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore
highly recommended to switch to _MathJax 3_.

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
</script>

[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_arithmatex.scss
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/
[8]: ../customization.md#additional-javascript
[9]: ../setup/setting-up-navigation.md#instant-loading

## Usage

### Using block syntax

Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]`on separate lines:

_Example_:

``` latex
$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$
```

_Result_:

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

### Using inline block syntax

Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:

_Example_:

``` latex
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
```

_Result_:

The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
134 docs/reference/meta-tags.md
View file
@@ -0,0 +1,134 @@
---
template: overrides/main.html
---

# Meta tags

In HTML, `meta` tags allow to provide additional metadata for a document, e.g.
page titles and descriptions, additional assets to be loaded, and [Open Graph]
[1] data. While metadata can always be added via [customization][2], some tags
can be configured.

[1]: https://ogp.me/
[2]: #customization

## Configuration

### Metadata

The [Metadata][3] extension, which is part of the standard Markdown library,
adds the ability to add [front matter][4] to a document and can be enabled via
`mkdocs.yml`:

``` yaml
markdown_extensions:
- meta
```

Front matter is written as a series of key-value pairs at the beginning of the
Markdown document, delimited by a blank line which ends the YAML context.

[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[4]: https://jekyllrb.com/docs/front-matter/

## Usage

### Setting the page title

If the [Metadata][5] extension is enabled, the page title can be overridden on
a per-document basis with custom front matter:

``` markdown
---
title: Lorem ipsum dolor sit amet
---
```

This will set the `title` tag inside the document `head` for the current page
to the provided value. Note that the site title is appended using a dash as a
separator, which is the default behavior.

[5]: #metadata

### Setting the page description

If the [Metadata][5] extension is enabled, the page description can also be
overridden on a per-document basis with custom front matter:

``` markdown
---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---
```

This will set the `meta` tag containing the site description inside the
document `head` for the current page to the provided value.

### Adding a web app manifest

A [web app manifest][6] is a simple JSON file that specifies how your web application should behave when installed on the user's mobile device or desktop, which can be set via `mkdocs.yml`:

``` yaml
extra:
manifest: manifest.webmanifest
```

[6]: https://developers.google.com/web/fundamentals/web-app-manifest/

## Customization

In order to add `meta` tags to your document, you can [extend the theme][7] and
simply [override the `extrahead` block][8] with the respective tags, e.g. to set
policies for search engines:

``` html
{% block extrahead %}
<meta property="robots" content="noindex, nofollow" />
{% endblock %}
```

Some further examples, including [Open Graph][1] and [Twitter Cards][9]:

=== "Open Graph"

``` html
{% block extrahead %}
{% set title = config.site_name %}
{% if page and page.meta and page.meta.title %}
{% set title = title ~ " - " ~ page.meta.title %}
{% elif page and page.title and not page.is_homepage %}
{% set title = title ~ " - " ~ page.title | striptags %}
{% endif %}
<meta property="og:type" content="website" />
<meta property="og:title" content="{{ title }}" />
<meta property="og:description" content="{{ config.site_description }}" />
<meta property="og:url" content="{{ page.canonical_url }}" />
<meta property="og:image" content="<url>" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
{% endblock %}
```

=== "Twitter Cards"

``` html
{% block extrahead %}
{% set title = config.site_name %}
{% if page and page.meta and page.meta.title %}
{% set title = title ~ " - " ~ page.meta.title %}
{% elif page and page.title and not page.is_homepage %}
{% set title = title ~ " - " ~ page.title | striptags %}
{% endif %}
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="<username>" />
<meta name="twitter:creator" content="<username>" />
<meta name="twitter:title" content="{{ title }}" />
<meta name="twitter:description" content="{{ config.site_description }}" />
<meta name="twitter:image" content="<url>" />
{% endblock %}
```

[7]: ../customization.md#extending-the-theme
[8]: ../customization.md#overriding-blocks
[9]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
30 docs/releases/4.md
View file

This file was deleted.

97 docs/setup/adding-a-comment-system.md
View file
@@ -0,0 +1,97 @@
---
template: overrides/main.html
---

# Adding a comment system

Material for MkDocs is natively integrated with [Disqus][1], a comment system
that provides a wide range of features like social integrations, user profiles,
as well as spam and moderation tools. Of course, other comment systems can be
integrated, too.

[1]: https://disqus.com/

## Configuration

### Disqus

[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: _none_

First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate
Material for MkDocs with [Disqus][1], create an account and a site giving you a
[shortname][4], and add it to `mkdocs.yml`:

``` yaml
extra:
disqus: <shortname>
```

This will insert a comment system on _every page, except the index page_.

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html
[3]: https://www.mkdocs.org/user-guide/configuration/#site_url
[4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname

### Metadata

The [Metadata][5] extension, which is part of the standard Markdown library,
adds the ability to add [front matter][6] to a document and can be enabled via
`mkdocs.yml`:

``` yaml
markdown_extensions:
- meta
```

Front matter is written as a series of key-value pairs at the beginning of the
Markdown document, delimited by a blank line which ends the YAML context.

[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[6]: https://jekyllrb.com/docs/front-matter/

## Customization

### Selective integration

[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_

If the [Metadata][7] extension is enabled, you can disable or enable Disqus for
specific pages by adding the following to the front matter of a page:

=== "Enable Disqus"

``` markdown
---
disqus: <shortname>
---
```

=== "Disable Disqus"

``` markdown
---
disqus: ""
---
```

[7]: #metadata

### Other comment systems

[:octicons-file-code-24: Source][8] ·
:octicons-mortar-board-24: Difficulty: _easy_

In order to integrate another JavaScript-based comment system provider, you can
[extend the theme][9] and [override the `disqus` block][10]:

``` html
{% block disqus %}
<!-- Add custom comment system integration here -->
{% endblock %}
```

[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L340-342
[9]: ../customization.md#extending-the-theme
[10]: ../customization.md#overriding-blocks
193 docs/setup/adding-a-git-repository.md
View file
@@ -0,0 +1,193 @@
---
template: overrides/main.html
---

# Adding a git repository

If your documentation is related to source code, Material for MkDocs provides
the ability to display information to the project's repository as part of the
static site, including statistics like stars and forks. Furthermore, individual
documents can be linked to specific source files.

## Configuration

In order to display a link to the repository of your project as part of your
documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your
repository, e.g.:

``` yaml
repo_url: https://github.com/squidfunk/mkdocs-material
```

The link to the repository will be rendered next to the search bar on big
screens and as part of the main navigation drawer on smaller screen sizes.
Additionally, for GitHub and GitLab, the number of stars and forks is
automatically requested and rendered for _public repositories_.

[1]: https://www.mkdocs.org/user-guide/configuration/#repo_url

### Repository name

[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
_automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket`

MkDocs will infer the source provider by examining the URL and try to set the
_repository name_ automatically. If you wish to customize the name, set
[`repo_name`][3] in `mkdocs.yml`:

``` yaml
repo_name: squidfunk/mkdocs-material
```

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html
[3]: https://www.mkdocs.org/user-guide/configuration/#repo_name

### Repository icon

[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
`fontawesome/brands/git-alt`

While the default _repository icon_ is a generic git icon, it can be set to
[any icon bundled with the theme][4] by referencing a valid icon path in
`mkdocs.yml`:

``` yaml
theme:
icon:
repo: fontawesome/brands/git-alt
```

Some popular choices:

* :fontawesome-brands-git: – `fontawesome/brands/git`
* :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
* :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
* :fontawesome-brands-github: – `fontawesome/brands/github`
* :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
* :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
* :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
* :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
* :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
* :fontawesome-solid-trash: – `fontawesome/solid/trash`

[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons

### Edit button

[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default:
_automatically set_

If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8]
repository, an _edit button_ is displayed at the top of each document. This
behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:

=== "Customize edit path"

``` yaml
edit_uri: edit/master/docs/
```

=== "Hide edit button"

``` yaml
edit_uri: ""
```

[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L299-L308
[6]: https://github.com/
[7]: https://about.gitlab.com/
[8]: https://bitbucket.org/
[9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri

### Revision date

[:octicons-file-code-24: Source][10] ·
[:octicons-cpu-24: Plugin][11]

The [git-revision-date][11] plugin adds support for displaying the date a
document was _last updated_ at the bottom of each page. It can be installed
with `pip`:

```
pip install mkdocs-git-revision-date-plugin
```

Then, add the following to `mkdocs.yml`:

``` yaml
plugins:
- git-revision-date
```

The following options are supported:

`enabled_if_env`{: #enabled_if_env }

: :octicons-milestone-24: Default: _none_ – This option defines whether the
date is actually extracted from git, which makes it possible to disable
extraction for cases when the repository is not available:

``` yaml
plugins:
- git-revision-date:
enabled_if_env: CI
```

_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._

[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
[11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin

### Revision date, localized

[:octicons-file-code-24: Source][10] ·
[:octicons-cpu-24: Plugin][12]

Similarly, the [git-revision-date-localized][12] plugin adds support for adding
a localized _last updated_ date at the bottom of each page. It can be installed
with `pip`:

```
pip install mkdocs-git-revision-date-localized-plugin
```

Then, add the following to `mkdocs.yml`:

``` yaml
plugins:
- git-revision-date-localized
```

The following options are supported:

`type`{: #type }

: :octicons-milestone-24: Default: `date` – This option allows to change the
format of the date to be displayed. Valid values are `date`, `datetime`,
`iso_date`, `iso_datetime` and `timeago`:

``` yaml
plugins:
- git-revision-date-localized:
type: date
```

`fallback_to_build_date`{: #fallback_to_build_date }

: :octicons-milestone-24: Default: `false` – This option specifies whether
the time when `mkdocs build` was executed should be used as a fallback when
the git repository is not available:

``` yaml
plugins:
- git-revision-date-localized:
fallback_to_build_date: true
```

_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._

[12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
104 docs/setup/adding-social-links.md
View file
@@ -0,0 +1,104 @@
---
template: overrides/main.html
---

# Adding social links

The footer of your project documentation is a great place to add links to
websites or platforms you or your company are using as additional marketing
channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" },
:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or
:fontawesome-brands-facebook:{: style="color: #4267B2" }, which can be
configured via `mkdocs.yml`.

## Configuration

### Social links

[:octicons-file-code-24: Source][1] ·
:octicons-milestone-24: Default: _none_

All _social links_ are rendered next to the copyright information as part of the
footer of your project documentation. Add a list of social links in `mkdocs.yml`
with:

``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
```

For each entry, the following fields are available:

`icon`{: #icon }

: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled
with the theme][2], or the build will not succeed. Some popular choices:

* :fontawesome-brands-behance: – `fontawesome/brands/behance`
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
* :fontawesome-brands-github: – `fontawesome/brands/github`
* :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
* :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
* :fontawesome-brands-medium: – `fontawesome/brands/medium`
* :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
* :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter`

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons

`link`{: #link }

: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must contain a valid relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:

=== "Twitter"

``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
```

=== "Email address"

``` yaml
extra:
social:
- icon: fontawesome/solid/paper-plane
link: mailto:<email-address>
```

`name`{: #name }

: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
This field is used as the link's `title` attribute and can be set to a
discernable name to improve accessibility:

``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
name: squidfunk on Twitter
```

## Customization

### Custom icons

[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _moderate_

The social links feature uses the standard [icon integration][3] of Material for
MkDocs. If you want to use custom icons, follow the guide explaining how to
add [additional icons][4].

[3]: changing-the-logo-and-icons.md#icons
[4]: changing-the-logo-and-icons.md#additional-icons
246 docs/setup/changing-the-colors.md
View file
@@ -0,0 +1,246 @@
---
template: overrides/main.html
---

# Changing the colors

As any proper Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][2].

[1]: http://www.materialui.co/colors
[2]: #custom-colors

## Configuration

### Color scheme

[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`

Material for MkDocs supports two _color schemes_: a light mode, which is just
called `default`, and a dark mode, which is called `slate`. The color scheme
can be set via `mkdocs.yml`:

``` yaml
theme:
palette:
scheme: default
```

:material-cursor-default-click-outline: Click on a tile to change the color
scheme:

<div class="tx-switch">
<button data-md-color-scheme="default"><code>default</code></button>
<button data-md-color-scheme="slate"><code>slate</code></button>
</div>

<script>
var buttons = document.querySelectorAll("button[data-md-color-scheme]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-scheme")
document.body.setAttribute("data-md-color-scheme", attr)
var name = document.querySelector("#__code_0 code span:nth-child(7)")
name.textContent = attr
})
})
</script>

The _color scheme_ can also be set based on _user preference_, which makes use
of the `prefers-color-scheme` media query, by setting the value in `mkdocs.yml`
to `preference`:

``` yaml
theme:
palette:
scheme: preference
```

[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss

### Primary color

[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`

The _primary color_ is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
in `mkdocs.yml` to a valid color name:

``` yaml
theme:
palette:
primary: indigo
```

:material-cursor-default-click-outline: Click on a tile to change the primary
color:

<div class="tx-switch">
<button data-md-color-primary="red"><code>red</code></button>
<button data-md-color-primary="pink"><code>pink</code></button>
<button data-md-color-primary="purple"><code>purple</code></button>
<button data-md-color-primary="deep-purple"><code>deep purple</code></button>
<button data-md-color-primary="indigo"><code>indigo</code></button>
<button data-md-color-primary="blue"><code>blue</code></button>
<button data-md-color-primary="light-blue"><code>light blue</code></button>
<button data-md-color-primary="cyan"><code>cyan</code></button>
<button data-md-color-primary="teal"><code>teal</code></button>
<button data-md-color-primary="green"><code>green</code></button>
<button data-md-color-primary="light-green"><code>light green</code></button>
<button data-md-color-primary="lime"><code>lime</code></button>
<button data-md-color-primary="yellow"><code>yellow</code></button>
<button data-md-color-primary="amber"><code>amber</code></button>
<button data-md-color-primary="orange"><code>orange</code></button>
<button data-md-color-primary="deep-orange"><code>deep orange</code></button>
<button data-md-color-primary="brown"><code>brown</code></button>
<button data-md-color-primary="grey"><code>grey</code></button>
<button data-md-color-primary="blue-grey"><code>blue grey</code></button>
<button data-md-color-primary="black"><code>black</code></button>
<button data-md-color-primary="white"><code>white</code></button>
</div>

<script>
var buttons = document.querySelectorAll("button[data-md-color-primary]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-primary")
document.body.setAttribute("data-md-color-primary", attr)
var name = document.querySelector("#__code_2 code span:nth-child(7)")
name.textContent = attr.replace("-", " ")
})
})
</script>

[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss

### Accent color

[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`

The _accent color_ is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
choosing a valid color name:

``` yaml
theme:
palette:
accent: indigo
```

:material-cursor-default-click-outline: Click on a tile to change the accent
color:

<style>
.md-typeset button[data-md-color-accent] > code {
background-color: var(--md-code-bg-color);
color: var(--md-accent-fg-color);
}
</style>

<div class="tx-switch">
<button data-md-color-accent="red"><code>red</code></button>
<button data-md-color-accent="pink"><code>pink</code></button>
<button data-md-color-accent="purple"><code>purple</code></button>
<button data-md-color-accent="deep-purple"><code>deep purple</code></button>
<button data-md-color-accent="indigo"><code>indigo</code></button>
<button data-md-color-accent="blue"><code>blue</code></button>
<button data-md-color-accent="light-blue"><code>light blue</code></button>
<button data-md-color-accent="cyan"><code>cyan</code></button>
<button data-md-color-accent="teal"><code>teal</code></button>
<button data-md-color-accent="green"><code>green</code></button>
<button data-md-color-accent="light-green"><code>light green</code></button>
<button data-md-color-accent="lime"><code>lime</code></button>
<button data-md-color-accent="yellow"><code>yellow</code></button>
<button data-md-color-accent="amber"><code>amber</code></button>
<button data-md-color-accent="orange"><code>orange</code></button>
<button data-md-color-accent="deep-orange"><code>deep orange</code></button>
</div>

<script>
var buttons = document.querySelectorAll("button[data-md-color-accent]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-accent")
document.body.setAttribute("data-md-color-accent", attr)
var name = document.querySelector("#__code_3 code span:nth-child(7)")
name.textContent = attr.replace("-", " ")
})
})
</script>

[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss

---

!!! warning "Accessibility – not all color combinations work well"

With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_). Make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.

## Customization

### Custom colors

[:octicons-file-code-24: Source][6] ·
:octicons-mortar-board-24: Difficulty: _easy_

Material for MkDocs implements colors using [CSS variables][7] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional stylesheet][8] and
tweak the values of the CSS variables.

Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" }
__YouTube__, and want to set the primary color to your brand's palette. Just
add:

``` css
:root {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```

See the file containing the [color definitions][6] for a list of all CSS
variables.

[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[8]: ../customization.md#additional-stylesheets


### Custom color schemes

[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _easy_

Besides overriding specific colors, you can create your own, named color scheme
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
[attribute selector][9], which you can then set via `mkdocs.yml` as described
in the [color schemes][10] section:

``` css
[data-md-color-scheme="youtube"] {
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```

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
can tune the `slate` theme with:

``` css
[data-md-color-scheme="slate"] {
--md-hue: 210; /* [0, 360] */
}
```

[9]: https://www.w3.org/TR/selectors-4/#attribute-selectors
[10]: #color-scheme
112 docs/setup/changing-the-fonts.md
View file
@@ -0,0 +1,112 @@
---
template: overrides/main.html
---

# Changing the fonts

Material for MkDocs makes it easy to change the typeface of your project
documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
or another destination should be used.

[1]: https://fonts.google.com

## Configuration

### Regular font

[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto`][3]

The _regular font_ is used for all body copy, headlines, and essentially
everything that does not need to be proportionally spaced. It can be set to any
valid [Google Font][1] with:

``` yaml
theme:
font:
text: Roboto
```

The typeface will be loaded in 300, 400, _400i_ and __700__.

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L116-L140
[3]: https://fonts.google.com/specimen/Roboto

### Proportional font

[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto Mono`][4]

The _proportional font_ is used for code blocks and can be configured separately.
Just like the regular font, it can be set to any valid [Google Font][1] via
`mkdocs.yml` with:

``` yaml
theme:
font:
code: Roboto Mono
```

The typeface will be loaded in 400.

[4]: https://fonts.google.com/specimen/Roboto+Mono

## Customization

If you want to load fonts from other destinations or don't want to use Google
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
font loading as described below.

### Disabling font loading

[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_

If you want to prevent typefaces from being loaded from Google Fonts and fall
back to system fonts, add the following lines to `mkdocs.yml`:

``` yaml
theme:
font: false
```

### Additional fonts

[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_

If you want to load an (additional) font from another or override
the fallback font, you can use an [additional stylesheet][8] to add the
corresponding `@font-face` definition:

``` css
@font-face {
font-family: "<font>";
src: "...";
}
```

The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or proportional font:

=== "Regular font"

``` css
body, input {
font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
}
```

=== "Proportional font"

``` css
pre, code, kbd {
font-family: "<font>", SFMono-Regular, Consolas, Menlo, monospace;
}
```

[5]: ../data-privacy.md
[6]: ../customization.md#extending-the-theme
[7]: ../customization.md#overriding-blocks
[8]: ../customization.md#additional-stylesheets
158 docs/setup/changing-the-language.md
View file
@@ -0,0 +1,158 @@
---
template: overrides/main.html
---

# Changing the language

Material for MkDocs supports internationalization (i18n) and provides
translations for template variables and labels in 40+ languages. Additionally,
the site search can be configured to use a language-specific stemmer (if
available).

## Configuration

### Site language

[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`

You can set the _site language_ in `mkdocs.yml` with:

``` yaml
theme:
language: en
```

The following languages are supported:

<ul class="tx-columns">
<li><code>af</code> – Afrikaans</li>
<li><code>ar</code> – Arabic</li>
<li><code>bn</code> – Bengali (Bangla)</li>
<li><code>ca</code> – Catalan</li>
<li><code>cs</code> – Czech</li>
<li><code>da</code> – Danish</li>
<li><code>de</code> – German</li>
<li><code>en</code> – English</li>
<li><code>es</code> – Spanish</li>
<li><code>et</code> – Estonian</li>
<li><code>fa</code> – Persian (Farsi)</li>
<li><code>fi</code> – Finnish</li>
<li><code>fr</code> – French</li>
<li><code>gl</code> – Galician</li>
<li><code>gr</code> – Greek</li>
<li><code>he</code> – Hebrew</li>
<li><code>hi</code> – Hindi</li>
<li><code>hr</code> – Croatian</li>
<li><code>hu</code> – Hungarian</li>
<li><code>id</code> – Indonesian</li>
<li><code>it</code> – Italian</li>
<li><code>ja</code> – Japanese</li>
<li><code>kr</code> – Korean</li>
<li><code>my</code> – Burmese</li>
<li><code>nl</code> – Dutch</li>
<li><code>nn</code> – Norwegian (Nynorsk)</li>
<li><code>no</code> – Norwegian</li>
<li><code>pl</code> – Polish</li>
<li><code>pt</code> – Portuguese</li>
<li><code>ro</code> – Romanian</li>
<li><code>ru</code> – Russian</li>
<li><code>sh</code> – Serbo-Croatian</li>
<li><code>si</code> – Slovenian</li>
<li><code>sk</code> – Slovak</li>
<li><code>sr</code> – Serbian</li>
<li><code>sv</code> – Swedish</li>
<li><code>th</code> – Thai</li>
<li><code>tr</code> – Turkish</li>
<li><code>uk</code> – Ukrainian</li>
<li><code>vi</code> – Vietnamese</li>
<li><code>zh</code> – Chinese (Simplified)</li>
<li><code>zh-Hant</code> – Chinese (Traditional)</li>
<li><code>zh-TW</code> – Chinese (Taiwanese)</li>
<li>
<a href="https://bit.ly/38F5RCa">
Add language
</a>
</li>
</ul>

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html

### Site search language

[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: _automatically set_

Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][3] to provide this
functionality. See the guide detailing how to [set up site search][4] for
more information.

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
[3]: https://github.com/MihaiValentin/lunr-languages
[4]: setting-up-site-search.md


### Directionality

[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _automatically set_

While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) _directionality_ which is inferred from the
selected language, but can also be set with:

``` yaml
theme:
direction: ltr
```

:material-cursor-default-click-outline: Click on a tile to change the
directionality:

<div class="tx-switch">
<button data-md-dir="ltr"><code>ltr</code></button>
<button data-md-dir="rtl"><code>rtl</code></button>
</div>

<script>
var buttons = document.querySelectorAll("button[data-md-dir]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir")
document.body.dir = attr
var name = document.querySelector("#__code_1 code span:nth-child(5)")
name.textContent = attr
})
})
</script>

[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L168

## Customization

### Custom translations

[:octicons-file-code-24: Source][1] ·
:octicons-mortar-board-24: Difficulty: _easy_

If you want to customize some (or all) of the translations for your language,
you may follow the guide on [theme extension][6] and create a new partial in
`partials/language`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial.

Let's say you want to change "__Table of contents__" to "__On this page__":

``` html
{% macro t(key) %}{{ {
"toc.title": "On this page"
}[key] }}{% endmacro %}
```

Then, add the following lines to `mkdocs.yml`:

``` yaml
theme:
language: en-custom
```

[6]: ../customization.md#extending-the-theme
129 docs/setup/changing-the-logo-and-icons.md
View file
@@ -0,0 +1,129 @@
---
template: overrides/main.html
---

# Changing the logo and icons

When installing Material for MkDocs, you immediately get access to _over 7.000
icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also [add
additional icons][1] with minimal effort.

[1]: #additional-icons

## Configuration

### Logo

[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: `material/library`

There're two ways to specify a _logo_: it must be a valid path to [any icon
bundled with the theme][3], or to a user-provided image located in the `docs`
folder. Both can be set via `mkdocs.yml`:

=== "Icon"

``` yaml
theme:
icon:
logo: material/library
```

=== "Image"

``` yaml
theme:
logo: assets/logo.png
```

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
[3]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons

### Favicon

[:octicons-file-code-24: Source][4] ·
:octicons-milestone-24: Default: `assets/images/favicon.png`

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`:

``` yaml
theme:
favicon: images/favicon.png
```

[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L71

### Icons

[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][5]

The [Emoji][5] extension, which is part of [Python Markdown Extensions][6],
adds the ability to __integrate icons__ in the `*.svg` file format, which are
inlined when [building your site][7]:

``` 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][8]
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][9]
* :octicons-mark-github-16: – [Octicons][10]

If you want to add [additional icons][1], read on.

[5]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[6]: https://facelessuser.github.io/pymdown-extensions/
[7]: ../creating-your-site.md#building-your-site
[8]: https://materialdesignicons.com/
[9]: https://fontawesome.com/icons?d=gallery&m=free
[10]: https://octicons.github.com/

## Customization

### Additional icons

[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _moderate_

In order to add additional icons, [extend the theme][11], and create a folder
named `.icons` in the [`custom_dir`][12] 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][13] icon set, and want to add it to
your project documentation. The structure of your project should look like this:

``` sh
.
├─ docs/
│ └─ index.md
├─ overrides/
│ └─ .icons/
│ └─ bootstrap/
│ └─ *.svg
└─ mkdocs.yml
```

Then, add the following lines to `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
options:
custom_icons:
- overrides/.icons
```

You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
icons.

[11]: ../customization.md#extending-the-theme
[12]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[13]: https://icons.getbootstrap.com/
231 docs/setup/setting-up-navigation.md
View file
@@ -0,0 +1,231 @@
---
template: overrides/main.html
---

# Setting up navigation

A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides several options to configure the
behavior of navigational elements, some of those through _feature flags_.

## Configuration

### Instant loading

[:octicons-file-code-24: Source][1] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental

When _instant loading_ is activated, clicks on all internal links will be
intercepted and dispatched via [XHR][2] without fully reloading the page. It
can be enabled via `mkdocs.yml` with:

``` yaml
theme:
features:
- instant
```

The resulting page is parsed and injected and all event handlers and components
are rebound automatically. This means that __Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation
sites that come with a massive search index, as the search index will now
remain intact in-between document switches.

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest

### Navigation tabs

[:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag

When _tabs_ are activated, top-level sections are rendered in a menu layer
below the header on big screens (but not when the sidebar is hidden). It can be
enabled via `mkdocs.yml` with:

``` yaml
theme:
features:
- tabs
```

Note that all __top-level pages__ (i.e. all top-level entries that directly
refer to an `*.md` file) defined inside the [`nav`][4] entry of `mkdocs.yml`
will be grouped under the first tab which will receive the title of the first
page.

This means that there will effectively be no collapsible subsections for the
first tab, because each subsection is rendered as another tab. If you want more
fine-grained control, _i.e. collapsible subsections for the first tab_, you can
use __top-level sections__, so that the top-level is entirely made up of
sections. This is illustrated in the following example:

=== "Top-level pages"

``` yaml
nav:
- Tab 1 + Page 1.1
- Page 1.2
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
- Page 1.3
```

=== "Top-level sections"

``` yaml
nav:
- Tab 1:
- Page 1.1
- Page 1.2
- Page 1.3
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
```

Note that tabs are only shown for larger screens, so make sure that navigation
is plausible on mobile devices. As another example, see the [`mkdocs.yml`][5]
used to render these pages.

[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[4]: https://www.mkdocs.org/user-guide/configuration/#nav
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml

### Table of contents

[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]

The [Table of contents][8] 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][9]:

=== "Unicode"

``` yaml
markdown_extensions:
- toc:
slugify: pymdownx.slugs.uslugify
```

=== "Unicode, case-sensitive"

``` yaml
markdown_extensions:
- toc:
slugify: 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 can also yield weird results. Use
them at your own risk._

[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[7]: https://python-markdown.github.io/extensions/toc/
[8]: https://python-markdown.github.io/extensions/toc/#usage
[9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/

## Customization

### Keyboard shortcuts

[:octicons-file-code-24: Source][10] ·
:octicons-mortar-board-24: Difficulty: _easy_

Material for MkDocs includes several keyboard shortcuts that make it possible
to navigate your project documentation via keyboard. There're two modes:

`search`{: #search }

: This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard:

* ++arrow-down++ , ++arrow-up++ : select next / previous result
* ++esc++ , ++tab++ : close search dialog
* ++enter++ : follow selected result

`global`{: #global }

: This mode is active when _search is not focussed_ and when there's no other
focussed element that is susceptible to keyboard input. The following keys
are bound:

* ++f++ , ++s++ , ++slash++ : open search dialog
* ++p++ , ++comma++ : go to previous page
* ++n++ , ++period++ : go to next page

Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript][11], you can subscribe to the `keyboard$` observable and attach
your custom event listener:

``` js
app.keyboard$.subscribe(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()`
on the underlying event, so the keypress will not propagate further and touch
other event listeners.

[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[11]: ../customization.md#additional-javascript
81 docs/setup/setting-up-site-analytics.md
View file
@@ -0,0 +1,81 @@
---
template: overrides/main.html
---

# Setting up site analytics

As with any other service offered on the web, understanding how your project
documentation is actually used can be an essential success factor. While
Material for MkDocs natively integrates with [Google Analytics][1], [other
analytics services][2] can be used, too.

[1]: https://developers.google.com/analytics
[2]: #using-other-analytics-services

## Configuration

### Google Analytics

[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_

After heading over to your [Google Analytics][1] account to [create a new
property][4] in order to obtain a unique tracking id of the form
`UA-XXXXXXXX-X`, add it to `mkdocs.yml`:

``` yaml
google_analytics:
- UA-XXXXXXXX-X
- auto
```

[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
[4]: https://support.google.com/analytics/answer/1042508

#### Site search tracking

Besides basic page views, _site search_ can also be tracked to understand better
how people use your documentation and what they expect to find. To enable
search tracking:

1. Go to your Google Analytics __admin settings__
2. Select the property for the respective tracking code
3. Go to the __view settings__ tab.
4. Scroll down and enable __site search settings__
5. Set the __query parameter__ to `q`.

## Customization

### Other analytics providers

[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _easy_

In order to integrate another analytics service provider offering an
asynchronous JavaScript-based tracking solution, you can [extend the theme][5]
and [override the `analytics` block][6]:

``` html
{% block analytics %}
<!-- Add custom analytics integration here -->
{% endblock %}
```

[5]: ../customization.md#extending-the-theme
[6]: ../customization.md#overriding-blocks

If you're using [instant loading][7], you may use the `location$` observable,
which will emit the current `URL` to listen for navigation events and register
a page view event with:

``` js
app.location$.subscribe(function(url) {
/* Add custom page event tracking here */
})
```

Note that this must be integrated with [additional JavaScript][8], and cannot be
included as part of the `analytics` block, as it is included in the `head` of
the document.

[7]: setting-up-navigation.md#instant-loading
[8]: ../customization.md#additional-javascript
301 docs/setup/setting-up-site-search.md
View file
@@ -0,0 +1,301 @@
---
template: overrides/main.html
---

# Setting up site search

Material for MkDocs provides an excellent, client-side search implementation,
omitting the need for the integration of third-party services, which might
violate data privacy regulations. Moreover, with some effort, search can be
made available [offline][1].

[1]: #offline-search

## Configuration

### Built-in search

[:octicons-file-code-24: Source][2] ·
[:octicons-cpu-24: Plugin][3] ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders – improved user experience][4]{: .tx-insiders }

The [built-in search plugin][3] integrates seamlessly with Material for MkDocs,
adding multilingual client-side search with [lunr][5] and [lunr-languages][6].
It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used:

``` yaml
plugins:
- search
```

The following options are supported:

`lang`{: #lang }

: :octicons-milestone-24: Default: _automatically set_ – This option allows
to include the language-specific stemmers provided by [lunr-languages][6].
Note that Material for MkDocs will set this automatically based on the
[site language][7], but it may be overridden, e.g. to support multiple
languages:

=== "A single language"

``` yaml
plugins:
- search:
lang: ru
```

=== "Multiple languages"

``` yaml
plugins:
- search:
lang:
- en
- ru
```

The following languages are supported:

<ul class="tx-columns">
<li><code>ar</code> – Arabic</li>
<li><code>da</code> – Danish</li>
<li><code>du</code> – Dutch</li>
<li><code>en</code> – English</li>
<li><code>fi</code> – Finnish</li>
<li><code>fr</code> – French</li>
<li><code>de</code> – German</li>
<li><code>hu</code> – Hungarian</li>
<li><code>it</code> – Italian</li>
<li><code>ja</code> – Japanese</li>
<li><code>no</code> – Norwegian</li>
<li><code>pt</code> – Portuguese</li>
<li><code>ro</code> – Romanian</li>
<li><code>ru</code> – Russian</li>
<li><code>es</code> – Spanish</li>
<li><code>sv</code> – Swedish</li>
<li><code>th</code> – Thai</li>
<li><code>tr</code> – Turkish</li>
<li><code>vi</code> – Vietnamese</li>
</ul>

_Material for MkDocs also tries to support languages that are not part of
this list by choosing the stemmer yielding the best result automatically_.

!!! warning "Only specify the languages you really need"

Be aware that including support for other languages increases the general
JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
per language.

`separator`{: #separator }

: :octicons-milestone-24: Default: _automatically set_ – The separator for
indexing and query tokenization can be customized, making it possible to
index parts of words separated by other characters than whitespace and `-`,
e.g. by including `.`:

``` yaml
plugins:
- search:
separator: '[\s\-\.]+'
```

`prebuild_index`{: #prebuild-index }

: :octicons-milestone-24: Default: `false` · :octicons-beaker-24:
Experimental – MkDocs can generate a [prebuilt index][8] of all pages during
build time, which provides performance improvements at the cost of more
bandwidth, as it reduces the build time of the search index:

``` yaml
plugins:
- search:
prebuild_index: true
```

This may be beneficial for large documentation projects served with
appropriate headers, i.e. `Content-Encoding: gzip`, but benchmarking before
deployment is recommended.

_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._

[2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
[3]: https://www.mkdocs.org/user-guide/configuration/#search
[4]: ../insiders.md
[5]: https://lunrjs.com
[6]: https://github.com/MihaiValentin/lunr-languages
[7]: changing-the-language.md#site-language
[8]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index

### Highlighting search

[:octicons-file-code-24: Source][4] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][4]{: .tx-insiders }

When _search highlighting_ is activated and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
It can be enabled via `mkdocs.yml` with:

``` yaml
theme:
features:
- search.highlight
```

Searching for `"code blocks"` yields:

[![Search highlighting][9]][9]

_Give this feature a try on [the official documentation][10] built with Material
for MkDocs Insiders!_

[9]: ../assets/search-highlighting.png
[10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks

### Offline search

[:octicons-file-code-24: Source][11] ·
[:octicons-cpu-24: Plugin][12] · :octicons-beaker-24: Experimental

If you distribute your documentation as `*.html` files, the built-in search
will not work out-of-the-box due to the restrictions modern browsers impose for
security reasons. This can be mitigated with the [localsearch][12] plugin in
combination with @squidfunk's [iframe-worker][13] polyfill.

For setup instructions, refer to the [official documentation][14].

[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
[12]: https://github.com/wilhelmer/mkdocs-localsearch/
[13]: https://github.com/squidfunk/iframe-worker
[14]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5

## Customization

The search implementation of Material for MkDocs is probably its most
sophisticated feature, as it tries to balance a _great typeahead experience_,
_good performance_, _accessibility_, and a result list that is _easy to scan_.
This is where Material for MkDocs deviates from other themes.

The following section explains how search can be customized to tailor it to
your needs.

### Query transformation

[:octicons-file-code-24: Source][15] ·
:octicons-mortar-board-24: Difficulty: _easy_

When a user enters a query into the search box, the query is pre-processed
before it is submitted to the search index. Material for MkDocs will apply the
following transformations, which can be customized by [extending the theme][16]:

``` ts
/**
* Default transformation function
*
* 1. Search for terms in quotation marks and prepend a `+` modifier to denote
* that the resulting document must contain all terms, converting the query
* to an `AND` query (as opposed to the default `OR` behavior). While users
* may expect terms enclosed in quotation marks to map to span queries, i.e.
* for which order is important, `lunr` doesn't support them, so the best
* we can do is to convert the terms to an `AND` query.
*
* 2. Replace control characters which are not located at the beginning of the
* query or preceded by white space, or are not followed by a non-whitespace
* character or are at the end of the query string. Furthermore, filter
* unmatched quotation marks.
*
* 3. Trim excess whitespace from left and right.
*
* 4. Append a wildcard to the end of every word to make every word a prefix
* query in order to provide a good typeahead experience, by adding an
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
* any non-control character, or a word boundary.
*
* @param query - Query value
*
* @return Transformed query value
*/
function defaultTransform(query: string): string {
return query
.split(/"([^"]+)"/g) /* => 1 */
.map((terms, i) => i & 1
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
: terms
)
.join("")
.replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */
.trim() /* => 3 */
.replace(/\s+|(?![^\x00-\x7F]|^)$|\b$/g, "* ") /* => 4 */
}
```

If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
template, both of which don't transform the query prior to submission, or
customize the `transform` function, you can do this by [overriding the
`config` block][17]:

``` html
{% block config %}
<script>
var search = {
transform: function(query) {
return query
}
}
</script>
{% endblock %}
```

The `transform` function will receive the query string as entered by the user
and must return the processed query string to be submitted to the search index.

[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[16]: ../customization.md#extending-the-theme
[17]: ../customization.md#overriding-blocks

### Custom search

[:octicons-file-code-24: Source][18] ·
:octicons-mortar-board-24: Difficulty: _challenging_

Material for MkDocs implements search as part of a [web worker][19]. If you
want to switch the web worker with your own implementation, e.g. to submit
search to an external service, you can add a custom JavaScript file to the `docs`
directory and [override the `config` block][17]:

``` html
{% block config %}
<script>
var search = {
worker: "<url>"
}
</script>
{% endblock %}
```

Communication with the search worker is implemented using a standardized
message format using _discriminated unions_, i.e. through the `type` property
of the message. See the following interface definitions to learn about the
message formats:

* [:octicons-file-code-24: `SearchMessage`][20]
* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][21]

The sequence and direction of messages is rather intuitive:

* :octicons-arrow-right-24: `SearchSetupMessage`
* :octicons-arrow-left-24: `SearchReadyMessage`
* :octicons-arrow-right-24: `SearchQueryMessage`
* :octicons-arrow-left-24: `SearchResultMessage`

[18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
[19]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
[20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
117 docs/troubleshooting.md
View file
@@ -0,0 +1,117 @@
---
template: overrides/main.html
---

# Troubleshooting

## Theme not recognized

Operating systems:
:fontawesome-brands-apple:
:fontawesome-brands-windows:
:fontawesome-brands-linux:

!!! error "Error: Unrecognized theme"

``` sh
mkdocs serve
# => INFO - Building documentation...
# => ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
# => ...
# => ConfigurationError: Aborted with 1 Configuration Errors!
```

If you run into this error, the most common reason is that you installed MkDocs
through some package manager (e.g. `brew` or `apt-get`) and Material for MkDocs
through `pip`, so both packages end up in different locations. MkDocs only
checks its install location for themes.

## Inadequate permissions

Operating systems: :fontawesome-brands-apple:

!!! error "Error: Permission denied"

``` sh
pip install mkdocs-material
# => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'
# => Consider using the --user option or check the permissions.
```

When you're running the pre-installed version of Python on macOS, `pip` tries
to install packages in a folder for which your user might not have the adequate
permissions. There are three possible solutions for this, the recommended one
of which is to use virtual environments:

=== "Virtual environments"

If you're installing Material for MkDocs with `pip`, the easiest way to make
sure that you end up with the correct versions and without any
incompatibility problems between packages it to use a [virtual
environment][1]. First, ensure that you have a Python version of 3 or
higher installed:

```
python --version
```

If you're good to go, create and activate a virtual environment with:

```
python -m venv venv
source ./venv/bin/activate
```

Note that the second `venv` is the name of the folder where to create the
virtual environment – you may choose it as you like. Your terminal should
now print `(venv)` before the prompt and the `python` executable should be
located inside the folder you just created.

Next, [install Material for MkDocs][2] with `pip`, which will download and
install all packages in the `venv` folder you just created, including MkDocs
and its dependencies:

```
pip install mkdocs-material
```

Verify that MkDocs and Material for MkDocs were both installed correctly:

```
mkdocs --version
mkdocs serve --help
```

MkDocs should list `material` as an option under the `--theme` flag. When
you're finished working with MkDocs, you can exit the virtual environment
with:

```
deactivate
```

=== "User space"

Provide the `--user` flag to the install command and `pip` will install the
package in a user-site location. While this is not a global installation,
it's still not isolated and may lead to problems when you use different
versions of Material for MkDocs in other projects:

```
pip install --user mkdocs-material
```

=== "Upgrade Python"

Upgrade your Python installation by installing Python with [Homebrew][3].
This should eliminate a lot of problems you will run into with `pip`. Yet,
it's still not an isolated installation which may also lead to the same
problems as installing in user space:

```
brew upgrade python
```

[1]: https://docs.python.org/3/tutorial/venv.html
[2]: getting-started.md#with-pip
[3]: https://brew.sh/
74 docs/releases/5.md → docs/upgrading.md
View file
@@ -2,29 +2,43 @@
template: overrides/main.html
---

# Upgrading to 5.x
# Upgrading

## Highlights
Upgrade to the latest version with:

```
pip install --upgrade mkdocs-material
```

Inspect the currently installed version with:

```
pip show mkdocs-material
```

## Upgrading from 4.x to 5.x

### What's new?

* Reactive architecture – try `app.dialog$.next("Hi!")` in the console
* [Instant loading][5] – make Material behave like a Single Page Application
* Improved CSS customization with [CSS variables][1] – set your brand's colors
* [Instant loading][1] – make Material behave like a Single Page Application
* Improved CSS customization with [CSS variables][2] – set your brand's colors
* Improved CSS resilience, e.g. proper sidebar locking for customized headers
* Improved [icon integration][6] and configuration – now including over 5k icons
* Improved [icon integration][3] and configuration – now including over 5k icons
* Added possibility to use any icon for logo, repository and social links
* Search UI does not freeze anymore (moved to web worker)
* Search index built only once when using instant loading
* Improved extensible keyboard handling
* Support for [prebuilt search indexes][2]
* Support for [prebuilt search indexes][4]
* Support for displaying stars and forks for GitLab repositories
* Support for scroll snapping of sidebars and search results
* Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
* Slight facelifting of some UI elements (Admonitions, tables, ...)

[1]: https://github.com/squidfunk/mkdocs-material/blob/081d540127c41703da3d73aa69eb521615c1cb89/src/assets/stylesheets/base/_colors.scss#L27-L55
[2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index

## How to upgrade
[1]: setup/setting-up-navigation.md#instant-loading
[2]: setup/changing-the-colors.md#custom-colors
[3]: setup/changing-the-logo-and-icons.md#icons
[4]: setup/setting-up-site-search.md#built-in-search

### Changes to `mkdocs.yml`

@@ -34,7 +48,7 @@ does not contain the key, you can skip it.

#### `theme.feature`

Optional features like [tabs][4] and [instant loading][5] are now implemented as
Optional features like [tabs][5] and [instant loading][1] are now implemented as
flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:

=== "5.x"
@@ -54,13 +68,12 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
tabs: true
```

[4]: ../../getting-started/#tabs
[5]: ../../getting-started/#instant-loading
[5]: setup/setting-up-navigation.md#navigation-tabs

#### `theme.logo.icon`

The logo icon configuration was centralized under `theme.icon.logo` and can now
be set to any of the [icons bundled with the theme][6]:
be set to any of the [icons bundled with the theme][3]:

=== "5.x"

@@ -70,8 +83,6 @@ be set to any of the [icons bundled with the theme][6]:
logo: material/cloud
```

[6]: ../../getting-started/#icons

=== "4.x"

``` yaml
@@ -83,7 +94,7 @@ be set to any of the [icons bundled with the theme][6]:
#### `extra.repo_icon`

The repo icon configuration was centralized under `theme.icon.repo` and can now
be set to any of the [icons bundled with the theme][6]:
be set to any of the [icons bundled with the theme][3]:

=== "5.x"

@@ -102,7 +113,7 @@ be set to any of the [icons bundled with the theme][6]:

#### `extra.search.*`

Search is now configured as part of the [plugin options][7]. Note that the
Search is now configured as part of the [plugin options][6]. Note that the
search languages must now be listed as an array of strings and the `tokenizer`
was renamed to `separator`:

@@ -124,10 +135,10 @@ was renamed to `separator`:
extra:
search:
language: en, de, ru
tokenizer: [\s\-\.]+
tokenizer: '[\s\-\.]+'
```

[7]: ../../plugins/search/#configuration
[6]: setup/setting-up-site-search.md#built-in-search

#### `extra.social.*`

@@ -869,3 +880,26 @@ matches the new structure:
{% endif %}
</nav>
```

## Upgrading from 3.x to 4.x

### What's new?

Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
includes a mandatory change of the base font-size from `10px` to `20px` which
means all `rem` values needed to be updated. Within the theme, `px` to `rem`
calculation is now encapsulated in a new function called `px2rem` which is part
of the SASS code base.

If you use Material for MkDocs with custom CSS that is based on `rem` values,
note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
`10px`, but `20px`. To learn more about the problem and implications, please
refer to #911 in which the problem was discovered and fixed.

### Changes to `mkdocs.yml`

None.

### Changes to `*.html` files

None.
2 material/.icons/fontawesome/brands/chromecast.svg
View file
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M447.83 64H64a42.72 42.72 0 00-42.72 42.72v63.92H64v-63.92h383.83v298.56H298.64V448H448a42.72 42.72 0 0042.72-42.72V106.72A42.72 42.72 0 00448 64zM21.28 383.58v63.92h63.91a63.91 63.91 0 00-63.91-63.92zm0-85.28V341a106.63 106.63 0 01106.64 106.66v.34h42.72a149.19 149.19 0 00-149-149.36h-.33zm0-85.27v42.72c106-.1 192 85.75 192.08 191.75v.5h42.72c-.46-129.46-105.34-234.27-234.8-234.64z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M447.8 64H64c-23.6 0-42.7 19.1-42.7 42.7v63.9H64v-63.9h383.8v298.6H298.6V448H448c23.6 0 42.7-19.1 42.7-42.7V106.7c0-23.6-19.3-42.7-42.9-42.7zM21.3 383.6v63.9h63.9c0-35.3-28.6-63.9-63.9-63.9zm0-85V341c58.9 0 106.6 48.1 106.6 107h42.7c.1-82.4-66.9-149.3-149.3-149.4zM213.4 448h42.7c-.5-129.5-105.3-234.3-234.8-234.6v42.4c106-.2 192 86.2 192.1 192.2z"/></svg>
2 material/.icons/fontawesome/brands/pied-piper.svg
View file
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 512"><path class="cls-1" d="M455.93 23.2c-26.7 6.8-68.14 28.49-114.58 67.46A206 206 0 00240 64C125.13 64 32 157.12 32 272s93.13 208 208 208 208-93.13 208-208a207.25 207.25 0 00-58.75-144.81 155.35 155.35 0 00-17 27.4A176.16 176.16 0 01417.1 272c0 97.66-79.44 177.11-177.09 177.11a175.81 175.81 0 01-87.63-23.4c82.94-107.33 150.79-37.77 184.31-226.65 5.79-32.62 28-94.26 126.23-160.18 8.08-5.43 2.43-18.08-6.99-15.68zM125 406.4A176.66 176.66 0 0162.9 272c0-97.66 79.45-177.1 177.1-177.1a174 174 0 0176.63 17.75C250.64 174.76 189.77 265.52 125 406.4z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 512"><path d="M455.93 23.2c-26.7 6.8-68.14 28.49-114.58 67.46A206 206 0 00240 64C125.13 64 32 157.12 32 272s93.13 208 208 208 208-93.13 208-208a207.25 207.25 0 00-58.75-144.81 155.35 155.35 0 00-17 27.4A176.16 176.16 0 01417.1 272c0 97.66-79.44 177.11-177.09 177.11a175.81 175.81 0 01-87.63-23.4c82.94-107.33 150.79-37.77 184.31-226.65 5.79-32.62 28-94.26 126.23-160.18 8.08-5.43 2.43-18.08-6.99-15.68zM125 406.4A176.66 176.66 0 0162.9 272c0-97.66 79.45-177.1 177.1-177.1a174 174 0 0176.63 17.75C250.64 174.76 189.77 265.52 125 406.4z" class="cls-1"/></svg>
2 material/.icons/fontawesome/brands/tripadvisor.svg
View file
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M195.11 285.18a51.06 51.06 0 11-51.05-51.06 51 51 0 0151.05 51.06m236.77-51.06a51.06 51.06 0 1051.06 51.06 51.06 51.06 0 00-51.06-51.06m144 51.06a143.94 143.94 0 01-241.77 105.58L288 440.93l-46.14-50.2A143.91 143.91 0 1147.09 178.82L0 127.58h104.66a326.11 326.11 0 01367 0H576l-47.09 51.24a143.56 143.56 0 0146.94 106.36m-334.4 0a97.39 97.39 0 10-97.39 97.39 97.39 97.39 0 0097.39-97.39m154.63-145.4a281 281 0 00-216.17 0C241.38 163.29 288 218.28 288 282.37c0-64.08 46.61-119.07 108.08-142.59m133.2 145.4a97.4 97.4 0 10-97.4 97.39 97.4 97.4 0 0097.4-97.39"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M528.91 178.82L576 127.58H471.66a326.11 326.11 0 00-367 0H0l47.09 51.24a143.911 143.911 0 00194.77 211.91l46.14 50.2 46.11-50.17a143.94 143.94 0 00241.77-105.58h-.03a143.56 143.56 0 00-46.94-106.36zM144.06 382.57a97.39 97.39 0 1197.39-97.39 97.39 97.39 0 01-97.39 97.39zM288 282.37c0-64.09-46.62-119.08-108.09-142.59a281 281 0 01216.17 0C334.61 163.3 288 218.29 288 282.37zm143.88 100.2h-.01a97.405 97.405 0 11.01 0zM144.06 234.12h-.01a51.06 51.06 0 1051.06 51.06v-.11a51 51 0 00-51.05-50.95zm287.82 0a51.06 51.06 0 1051.06 51.06 51.06 51.06 0 00-51.06-51.06z"/></svg>
2 material/.icons/fontawesome/brands/twitch.svg
View file
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M391.17 103.47h-38.63v109.7h38.63zM285 103h-38.63v109.75H285zM120.83 0L24.31 91.42v329.16h115.83V512l96.53-91.42h77.25L487.69 256V0zm328.24 237.75l-77.22 73.12h-77.24l-67.6 64v-64h-86.87V36.58h308.93z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M391.17,103.47H352.54v109.7h38.63ZM285,103H246.37V212.75H285ZM120.83,0,24.31,91.42V420.58H140.14V512l96.53-91.42h77.25L487.69,256V0ZM449.07,237.75l-77.22,73.12H294.61l-67.6,64v-64H140.14V36.58H449.07Z"/></svg>
2 material/.icons/fontawesome/solid/virus-slash.svg
View file
@@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><path d="M114 227.56H92.44a28.44 28.44 0 000 56.88H114c50.68 0 76.06 61.28 40.23 97.12L139 396.81A28.44 28.44 0 10179.19 437l15.25-15.25c35.84-35.84 97.11-10.45 97.11 40.23v21.54a28.45 28.45 0 0056.9 0V462c0-26.61 17-45.91 38.22-53.37l-244.5-189a55.58 55.58 0 01-28.17 7.93zm519.82 230.53L470.62 332c4.17-25.39 24.91-47.52 55.39-47.52h21.55a28.44 28.44 0 100-56.88H526c-50.68 0-76.06-61.28-40.23-97.12L501 115.19A28.44 28.44 0 00460.81 75l-15.25 15.22c-35.84 35.84-97.11 10.46-97.11-40.23V28.45a28.45 28.45 0 00-56.9 0V50c0 50.69-61.27 76.07-97.11 40.23L179.19 75A28.43 28.43 0 00139 75c-.13.14-.15.32-.28.46L45.46 3.38A16 16 0 0023 6.19L3.37 31.45a16 16 0 002.81 22.46l588.36 454.72a16 16 0 0022.46-2.82l19.64-25.26a16 16 0 00-2.82-22.46zM335.43 227.48l-62.87-48.59A46.55 46.55 0 01288 176a48 48 0 0148 48c0 1.22-.48 2.29-.57 3.48z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><path d="M114 227.6H92.4C76.7 227.6 64 240.3 64 256s12.7 28.4 28.4 28.4H114c50.7 0 76.1 61.3 40.2 97.1L139 396.8c-11.5 10.7-12.2 28.7-1.6 40.2s28.7 12.2 40.2 1.6c.5-.5 1.1-1 1.6-1.6l15.2-15.2c35.8-35.8 97.1-10.5 97.1 40.2v21.5c0 15.7 12.8 28.4 28.5 28.4s28.4-12.7 28.4-28.4V462c0-26.6 17-45.9 38.2-53.4l-244.5-189c-8.4 5.1-18.2 7.9-28.1 8zm503 278.2l19.6-25.3c5.4-7 4.2-17-2.8-22.5L470.6 332c4.2-25.4 24.9-47.5 55.4-47.5h21.5c15.7 0 28.4-12.7 28.4-28.4s-12.7-28.4-28.4-28.4H526c-50.7 0-76.1-61.3-40.2-97.1l15.2-15.3c10.7-11.5 10-29.5-1.6-40.2-10.9-10.1-27.7-10.1-38.6 0l-15.2 15.2c-35.8 35.8-97.1 10.5-97.1-40.2V28.5C348.4 12.7 335.7 0 320 0s-28.4 12.7-28.4 28.4V50c0 50.7-61.3 76.1-97.1 40.2L179.2 75c-11.1-11.1-29.4-10.6-40.5.5L45.5 3.4C38.5-2 28.5-.8 23 6.2L3.4 31.5c-5.4 7-4.2 17 2.8 22.5l588.4 454.7c6.9 5.4 17 4.1 22.4-2.9zM335.4 227.5l-62.9-48.6c4.9-1.8 10.2-2.8 15.4-2.9 26.5 0 48 21.5 48 48 .1 1.2-.4 2.3-.5 3.5z"/></svg>
25 material/.icons/material/LICENSE
View file
@@ -0,0 +1,25 @@
MIT License

Copyright (c) 2017 Austin Andrews

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For more information:

https://github.com/Templarian/MaterialDesign/blob/master/LICENSE
1 material/.icons/material/access-point-check.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.59 14.84l1.16 1.41L17 21l-2.75-3 1.16-1.16L17 18.43l3.59-3.59m-1.52-9.91l-1.41 1.41A7.955 7.955 0 0120 12v.34c.68.25 1.33.62 1.88 1.09.07-.47.12-.93.12-1.43 0-2.76-1.12-5.26-2.93-7.07m-3.11 7.43c.64-.23 1.32-.36 2.04-.36 0-1.65-.67-3.15-1.76-4.24l-1.41 1.41A3.99 3.99 0 0116 12c0 .12-.03.24-.04.36M12 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2M6.34 6.34L4.93 4.93C3.12 6.74 2 9.24 2 12s1.12 5.26 2.93 7.07l1.41-1.41A7.938 7.938 0 014 12c0-2.21.89-4.22 2.34-5.66m1.42 1.42C6.67 8.85 6 10.35 6 12s.67 3.15 1.76 4.24l1.41-1.41C8.45 14.11 8 13.11 8 12s.45-2.11 1.17-2.83L7.76 7.76z"/></svg>
1 material/.icons/material/access-point-minus.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16 12c0-1.11-.45-2.11-1.17-2.83l1.41-1.41A5.98 5.98 0 0118 12c-.72 0-1.4.13-2.04.36.01-.12.04-.24.04-.36m4 .34c.68.25 1.33.62 1.88 1.09.07-.47.12-.93.12-1.43 0-2.76-1.12-5.26-2.93-7.07l-1.41 1.41A7.955 7.955 0 0120 12v.34M12 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2M7.76 7.76C6.67 8.85 6 10.35 6 12s.67 3.15 1.76 4.24l1.41-1.41C8.45 14.11 8 13.11 8 12s.45-2.11 1.17-2.83L7.76 7.76M6.34 6.34L4.93 4.93C3.12 6.74 2 9.24 2 12s1.12 5.26 2.93 7.07l1.41-1.41A7.938 7.938 0 014 12c0-2.21.89-4.22 2.34-5.66M14 19h8v-2h-8v2z"/></svg>
1 material/.icons/material/access-point-off.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.84 22.73L12.1 14H12a2 2 0 01-2-2v-.1l-1.6-1.61c-.25.52-.4 1.09-.4 1.71 0 1.11.45 2.11 1.17 2.83l-1.41 1.41A5.98 5.98 0 016 12c0-1.17.34-2.26.93-3.18L5.5 7.37C4.55 8.67 4 10.27 4 12c0 2.22.89 4.22 2.34 5.66l-1.41 1.41A9.969 9.969 0 012 12c0-2.28.77-4.37 2.06-6.05L1.11 3l1.28-1.27 19.72 19.73-1.27 1.27m-4.91-10l1.6 1.6c.3-.72.47-1.5.47-2.33 0-1.65-.67-3.15-1.76-4.24l-1.41 1.41a3.99 3.99 0 011.1 3.56m3.1 3.1l1.47 1.45c.94-1.53 1.5-3.34 1.5-5.28 0-2.76-1.12-5.26-2.93-7.07l-1.41 1.41A7.955 7.955 0 0120 12c0 1.39-.35 2.7-.97 3.83z"/></svg>
1 material/.icons/material/access-point-plus.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16 12c0-1.11-.45-2.11-1.17-2.83l1.41-1.41A5.98 5.98 0 0118 12c-.72 0-1.4.13-2.04.36.01-.12.04-.24.04-.36m4 .34c.68.25 1.33.62 1.88 1.09.07-.47.12-.93.12-1.43 0-2.76-1.12-5.26-2.93-7.07l-1.41 1.41A7.955 7.955 0 0120 12v.34M12 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2M6.34 6.34L4.93 4.93C3.12 6.74 2 9.24 2 12s1.12 5.26 2.93 7.07l1.41-1.41A7.938 7.938 0 014 12c0-2.21.89-4.22 2.34-5.66m1.42 1.42C6.67 8.85 6 10.35 6 12s.67 3.15 1.76 4.24l1.41-1.41C8.45 14.11 8 13.11 8 12s.45-2.11 1.17-2.83L7.76 7.76M19 14h-2v3h-3v2h3v3h2v-3h3v-2h-3v-3z"/></svg>
1 material/.icons/material/access-point-remove.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16 12c0-1.11-.45-2.11-1.17-2.83l1.41-1.41A5.98 5.98 0 0118 12c-.72 0-1.4.13-2.04.36.01-.12.04-.24.04-.36M6.34 6.34L4.93 4.93C3.12 6.74 2 9.24 2 12s1.12 5.26 2.93 7.07l1.41-1.41A7.938 7.938 0 014 12c0-2.21.89-4.22 2.34-5.66m12.73-1.41l-1.41 1.41A7.955 7.955 0 0120 12v.34c.68.25 1.33.62 1.88 1.09.07-.47.12-.93.12-1.43 0-2.76-1.12-5.26-2.93-7.07M12 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2M7.76 7.76C6.67 8.85 6 10.35 6 12s.67 3.15 1.76 4.24l1.41-1.41C8.45 14.11 8 13.11 8 12s.45-2.11 1.17-2.83L7.76 7.76m12.36 6.7L18 16.59l-2.12-2.12-1.41 1.41L16.59 18l-2.12 2.12 1.41 1.41L18 19.41l2.12 2.12 1.41-1.41L19.41 18l2.12-2.12-1.41-1.42z"/></svg>
1 material/.icons/material/account-reactivate-outline.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21.5 9h-5l1.86-1.86A7.991 7.991 0 0012 4c-4.42 0-8 3.58-8 8 0 1.83.61 3.5 1.64 4.85 1.22-1.4 3.51-2.35 6.36-2.35 2.85 0 5.15.95 6.36 2.35A7.945 7.945 0 0020 12h2c0 5.5-4.5 10-10 10S2 17.5 2 12 6.5 2 12 2c3.14 0 5.95 1.45 7.78 3.72L21.5 4v5M12 20c1.9 0 3.64-.66 5-1.76-.64-1.01-2.55-1.74-5-1.74s-4.36.73-5 1.74c1.36 1.1 3.1 1.76 5 1.76m0-14c1.93 0 3.5 1.57 3.5 3.5S13.93 13 12 13s-3.5-1.57-3.5-3.5S10.07 6 12 6m0 2c-.83 0-1.5.67-1.5 1.5S11.17 11 12 11s1.5-.67 1.5-1.5S12.83 8 12 8z"/></svg>
1 material/.icons/material/account-reactivate.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21.5 9h-5l1.86-1.86A7.991 7.991 0 0012 4c-4.42 0-8 3.58-8 8 0 1.83.61 3.5 1.64 4.85 1.22-1.4 3.51-2.35 6.36-2.35 2.85 0 5.15.95 6.36 2.35A7.945 7.945 0 0020 12h2c0 5.5-4.5 10-10 10S2 17.5 2 12 6.5 2 12 2c3.14 0 5.95 1.45 7.78 3.72L21.5 4v5M12 7c1.66 0 3 1.34 3 3s-1.34 3-3 3-3-1.34-3-3 1.34-3 3-3z"/></svg>
1 material/.icons/material/account-supervisor-circle-outline.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12.5 10c0-1.66-1.34-3-3-3-1.64 0-3 1.34-3 3 0 1.64 1.36 3 3 3 1.66 0 3-1.36 3-3m-3 1c-.54 0-1-.46-1-1 0-.56.46-1 1-1 .56 0 1 .44 1 1 0 .54-.44 1-1 1m6.5 2c1.12 0 2-.9 2-2 0-1.12-.88-2-2-2-1.1 0-2 .88-2 2 0 1.1.9 2 2 2M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2M5.85 17.11C6.53 16.57 8.12 16 9.5 16h.24c.26-.63.67-1.28 1.3-1.85-.54-.1-1.09-.15-1.54-.15-1.29 0-3.38.44-4.72 1.42C4.28 14.38 4 13.22 4 12c0-4.42 3.59-8 8-8s8 3.58 8 8c0 1.19-.27 2.33-.75 3.36-1-.59-2.36-.86-3.25-.86-1.5 0-4.5.8-4.5 2.69v2.78a7.932 7.932 0 01-5.65-2.86z"/></svg>
1 material/.icons/material/archive-alert-outline.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 4h16v3H2V4m5.5 7h5c.28 0 .5.22.5.5V13H7v-1.5c0-.28.22-.5.5-.5M20 13V7h2v6h-2m0 4v-2h2v2h-2M3 8h2v10h10V8h2v12H3V8z"/></svg>
1 material/.icons/material/archive-alert.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 4h16v3H2V4m1 4h14v12H3V8m4.5 3c-.28 0-.5.22-.5.5V13h6v-1.5c0-.28-.22-.5-.5-.5h-5M20 13V7h2v6h-2m0 4v-2h2v2h-2z"/></svg>
1 material/.icons/material/basket-minus-outline.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M23 18v2h-8v-2h8m-11-5c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2m1.35 8H5.5c-.92 0-1.69-.62-1.92-1.46l-2.54-9.27C1 10.18 1 10.09 1 10c0-.55.45-1 1-1h4.79l4.38-6.55a.997.997 0 011.66-.01L17.21 9H22c.55 0 1 .45 1 1l-.03.27-.97 3.54c-.57-.31-1.21-.57-1.88-.7L20.7 11H3.31l2.19 8H13c0 .7.13 1.37.35 2M9.2 9h5.6L12 4.8 9.2 9z"/></svg>
1 material/.icons/material/basket-minus.svg
View file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M23 18v2h-8v-2h8m0-8l-.04.29L22 13.8a6.005 6.005 0 00-9 5.2c0 .7.13 1.37.35 2H5.5c-.78 0-1.46-.45-1.79-1.1L1.1 10.44 1 10c0-.55.45-1 1-1h4.58l4.6-6.57a.997.997 0 011.65.01L17.42 9H22c.55 0 1 .45 1 1m-9 5c0-1.1-.89-2-2-2s-2 .9-2 2 .9 2 2 2 2-.89 2-2m1-6l-3-4.26L9 9h6z"/></svg>