91 docs/reference/footnotes.md
View file
@@ -0,0 +1,91 @@
---
template: overrides/main.html
---

# Footnotes

Footnotes are a great way to add references to supplemental or additional
information for a specific section of a document without interrupting the
document flow. Material for MkDocs provides the ability to insert inline
footnotes and render them at the bottom of the page.

## Configuration

### Footnotes

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

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

``` yaml
markdown_extensions:
- footnotes
```

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

## Usage

### Adding footnote references

A footnote reference must be enclosed in square brackets and must start with a
caret `^`, directly followed by an arbitrary identifier, which is similar to
the standard Markdown link syntax.

_Example_:

``` markdown
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
```

_Result_:

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

### Adding footnote content

The footnote content must be declared with the same identifier as the reference.
It can be inserted at an arbitrary position in the document and is always
rendered at the bottom of the page. Furthermore, a backlink to the footnote
reference is automatically added.

#### on a single line

Short statements can be written on the same line.

_Example_:

``` markdown
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

_Result_:

[Jump to footnote at the bottom of the page](#fn:1)

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

#### on multiple lines

Paragraphs can be written on the next line and must be indented by four spaces.

_Example_:

``` markdown
[^2]:
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.
```

_Result_:

[^2]:
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.

[Jump to footnote at the bottom of the page](#fn:2)
189 docs/reference/formatting.md
View file
@@ -0,0 +1,189 @@
---
template: overrides/main.html
---

# Formatting

Material for MkDocs provides support for several HTML elements that can be used
to highlight sections of a document or apply specific formatting. Additionally,
[Critic Markup][1] is supported, adding the ability to display suggested changes
for a document.

[1]: http://criticmarkup.com/

## Configuration

### Critic

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

The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
allows for the __usage of [Critic Markup][1] to highlight changes__ in a
document, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.critic
```

The following options are supported:

`mode`{: #mode }

: :octicons-milestone-24: Default: `view` – This option defines how the markup
should be parsed, i.e. whether to just `view` all suggest changes, or
alternatively `accept` or `reject` them:

=== "View changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: view
```

=== "Accept changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: accept
```

=== "Reject changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: reject
```

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

### BetterEm

The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.betterem:
smart_enable: all
```

[5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/

### Caret, Mark & Tilde

The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
Markdown Extensions][4], allow for the __highlighting of text__, as well as
__handling sub- and superscripts__:

``` yaml
markdown_extensions:
- pymdownx.caret
- pymdownx.mark
- pymdownx.tilde
```

[6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/

### SmartSymbols

The [SmartSymbols][9] extension, which is also part of [Python Markdown
Extensions][4], __converts special characters into their corresponding
symbols__, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.smartsymbols
```

See the [official documentation][9] for a list of supported symbols.

[9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/

## Usage

### Highlighting changes

When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
ability to _highlight suggested changes_, as well as add _inline comments_ to a
document:

[10]: #critic

_Example_:

``` markdown
Text can be {​--deleted--} and replacement text {​++added++}. This can also be
combined into {​~~one~>a single~~} operation. {​==Highlighting==} is also
possible {​>>and comments can be added inline<<}.

{​==

Formatting can also be applied to blocks, by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

==}
```

_Result_:

Text can be {--deleted--} and replacement text {++added++}. This can also be
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
possible {>>and comments can be added inline<<}.

{==

Formatting can also be applied to blocks, by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

==}

### Highlighting text

When the [Caret, Mark & Tilde][11] extensions are enabled, text can be
highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
`del` HTML tags:

_Example_:

``` markdown
* ==This was marked==
* ^^This was inserted^^
* ~~This was deleted~~
```

_Result_:

* ==This was marked==
* ^^This was inserted^^
* ~~This was deleted~~

[11]: #caret-mark-tilde

### Sub- and superscripts

When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
superscripted with a nicer syntax than using the corresponding `sub` and `sup`
HTML tags:

_Example_:

``` markdown
* H~2~0
* A^T^A
```

_Result_:

* H~2~0
* A^T^A

[11]: #caret-mark-tilde
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
112 docs/reference/images.md
View file
@@ -0,0 +1,112 @@
---
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][3] 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._

[3]: #attribute-list

### 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>


### Image lazy-loading

Modern browsers provide [native support for lazy-loading images][4] through the
`loading` attribute, which degrades to eager-loading in browsers without
support. As with [image alignment][5], if the [Attribute List][3] extension is
enabled, images can be lazy-loaded by adding `loading=lazy`.

_Example_:

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

_Result_:

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

[4]: https://caniuse.com/#feat=loading-lazy-attr
[5]: #image-alignment
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
306 docs/setup/changing-the-colors.md
View file
@@ -0,0 +1,306 @@
---
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 palette

#### 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.

### Color palette toggle

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

[Material for MkDocs Insiders][6] makes it possible to define multiple color
palettes, including a [scheme][7], [primary][8] and [accent][9] color each, and
let the user choose. Define them via `mkdocs.yml`:

``` yaml
theme:
palette:
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch
name: Switch to light mode
- scheme: slate
primary: blue
accent: blue
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
```

The `toggle` field allows to specify an `icon` and `name` for each palette. The
toggle is rendered next to the search bar and will cycle through all defined
color palettes:

`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][10], or the build will not succeed. Some popular
combinations:

* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
* :material-weather-sunny: + :material-weather-night: – `material/weather-sunny` + `material/weather-night`
* :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye`
* :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb`

`name`{: #name }

: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field is used as the toggle's `title` attribute and should be set to a
discernable name to improve accessibility.

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

[6]: ../insiders.md
[7]: #color-scheme
[8]: #primary-color
[9]: #accent-color
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[11]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors

## Customization

### Custom colors

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

Material for MkDocs implements colors using [CSS variables][13] (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][14] 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][12] for a list of all CSS
variables.

[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[13]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[14]: ../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][15], which you can then set via `mkdocs.yml` as described
in the [color schemes][7] 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] */
}
```

[15]: https://www.w3.org/TR/selectors-4/#attribute-selectors
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
159 docs/setup/changing-the-language.md
View file
@@ -0,0 +1,159 @@
---
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>eo</code> – Esperanto</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/
250 docs/setup/setting-up-navigation.md
View file
@@ -0,0 +1,250 @@
---
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 expansion

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

When `navigation.expand` is activated, the left sidebar will expand all
collapsible subsections by default, so the user doesn't have to do it manually.
It can be enabled via `mkdocs.yml` with:

``` yaml
theme:
features:
- navigation.expand
```

[3]: ../insiders.md

### Navigation tabs

[:octicons-file-code-24: Source][4] · :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`][5] 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`][6]
used to render these pages.

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

### Table of contents

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

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

=== "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._

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

## Customization

### Keyboard shortcuts

[:octicons-file-code-24: Source][11] ·
: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][12], 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.

[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[12]: ../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
57 docs/setup/setting-up-the-header.md
View file
@@ -0,0 +1,57 @@
---
template: overrides/main.html
---

# Setting up the header

Material for MkDocs' header can be customized to show an announcement bar that
disappears upon scrolling, and provides some options for further configuration.
It also includes the [search bar][1] and a place to display your project's
[git repository][2], as explained in those dedicated guides.

[1]: setting-up-site-search.md
[2]: adding-a-git-repository.md

## Configuration

### Automatic hiding

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

When _auto-hiding_ is activated, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. It can
be enabled via `mkdocs.yml` with:

``` yaml
theme:
features:
- header.hide
```

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

[3]: ../insiders.md
[4]: https://squidfunk.github.io/mkdocs-material-insiders/

## Customization

### Announcement bar

Material for MkDocs includes an announcement bar, which is the perfect place to
display project news or other important information to the user. When the user
scrolls past the header, the bar will automatically disappear. In order to add
an announcement bar, [extend the theme][5] and [override the `announce`
block][6], which is empty by default:

``` html
{% block announce %}
<!-- Add your announcement here, including arbitrary HTML -->
{% endblock %}
```

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