100 docs/setup/adding-a-git-repository.md
View file
@@ -0,0 +1,100 @@
---
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, certain
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
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 good 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 available [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
236 docs/setup/changing-the-colors.md
View file
@@ -0,0 +1,236 @@
---
template: overrides/main.html
---

# Changing the colors

As any good 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
chosing 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_), so 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 `[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;
}
```

[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 destination, 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
157 docs/setup/changing-the-language.md
View file
@@ -0,0 +1,157 @@
---
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,
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__":

``` jinja
{% 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 very little 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 automatically rebound. This means that __Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation
sites that come with a huge 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 the active when _search is not active_, i.e. when there's no
other focussed element that is suceptible 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 key press 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
86 docs/setup/setting-up-site-analytics.md
View file
@@ -0,0 +1,86 @@
---
template: overrides/main.html
---

# Setting up site analytics

As with any other service that is offered on the web, understanding how your
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 new 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

#### Enabling site search tracking

Besides basic page views, _site search_ can also be tracked to better understand
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

### Using other analytics services

[: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]:

``` jinja
{% block analytics %}
{# Add custom analytics integration here #}
{% endblock %}
```

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

### Using instant loading

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

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, which is included in the `head` of
the document.

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

# Setting up site search

Material for MkDocs provides a great, client-side search implementation,
omitting the need for the integration of third-party services, which might
violate data privacy regulations. Furthermore, 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]

The [built-in search plugin][3] integrates seamlessly with Material for MkDocs,
adding multilingual client-side search with [lunr][4] and [lunr-languages][5].
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][5].
Note that Material for MkDocs will set this automatically based on the
[site language][6], but it may be overriden, 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 which are not part of
this list, by automatically chosing the best-matching stemmer_.

!!! 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, which makes it possible
to index parts of words that are 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][7] 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]: https://lunrjs.com
[5]: https://github.com/MihaiValentin/lunr-languages
[6]: changing-the-language.md#site-language
[7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index

### Offline search

[:octicons-file-code-24: Source][8] ·
[:octicons-cpu-24: Plugin][9] · :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 plugin][9] in
combination with @squidfunk's [iframe-worker][10] polyfill.

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

[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
[9]: https://github.com/wilhelmer/mkdocs-localsearch/
[10]: https://github.com/squidfunk/iframe-worker
[11]: 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 it deviates from other themes.

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

### Query transformation

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

``` 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 value - Query value
*
* @return Transformed query value
*/
function defaultTransform(value: string): string {
return value
.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][14]:

``` jinja
{% 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.

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

### Custom search

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

Material for MkDocs implements search as part of a [web worker][16]. 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][14]:

``` jinja
{% 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`][17]
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]

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`

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

# <span hidden>Sponsorship</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart }

Material for MkDocs uses the [sponsorware][1] release strategy, which means that
__new features are first exclusively released to sponsors__. Read on to learn
[how sponsorship works][2] and how you can [become a sponsor][3] to enjoy the
latest features before everybody else.

[1]: https://github.com/sponsorware/docs
[2]: #how-sponsorship-works
[3]: #how-to-become-a-sponsor

## How sponsorship works

__Material for MkDocs is available as a community edition and sponsor edition__.

New features will first land in the _sponsor edition_, which means that sponsors
will have access immediately. Every feature is tied to a funding goal in monthly
subscriptions. If this funding goal is hit, the feature is merged into the
_community edition_ and released to the public to be generally available. Bugs
will be fixed in the community edition and merged back into the sponsor edition:

- :material-bug-check: Bugfixes: _community edition_ :material-arrow-right:
_sponsor edition_
- :material-new-box: Features: _community edition_ :material-arrow-left:
_sponsor edition_

See the [roadmap][4] for a list of available and upcoming features of the
_sponsor edition_, and for demonstration purposes, [__the official docs built
with the sponsor edition__][5].

[4]: #roadmap
[5]: https://squidfunk.github.io/mkdocs-material-next/

## How to become a sponsor

You've decided to become a sponsor? Great! You're just __three easy steps__ away
from enjoying the latest features of Material for MkDocs. Complete the following
steps and you're in:

- Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive
access to squidfunk's sponsorware, which is any tier above $10/month. Select
the tier and complete the checkout.
- Within 24 hours, you will be added as a collaborator to a private GitHub
repository, which contains a fork of Material for MkDocs with [brand new and
exclusive features][7].
- Create a [personal access token][8], which allows installing the _sponsor
edition_ of Material for MkDocs from any destination, including other CI
providers like [GitLab][9] or [Bitbucket][10].

__Congratulations! :partying_face: You're now officially a sponsor and can use
the sponsor edition until you decide to cancel your monthly subscription, which
you're free to do at any time.__

[6]: https://github.com/sponsors/squidfunk
[7]: #roadmap
[8]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[9]: https://gitlab.com
[10]: https://bitbucket.org

## Roadmap

The following list of funding goals – named after varieties of chili peppers
[I'm growing on my balcony][11] – shows, which features are already part of the
sponsor edition or yet to come.

[11]: https://www.instagram.com/squidfunk/

### Madame Jeanette

[:octicons-fire-24: Funding goal: __$500__][6] ·
:octicons-lock-24: Status: _exclusively available_

Improve search UI and UX to show relevant results more prominently, show missing
terms that were not found on a specific page and highlight terms found when
following a search result.

- [x] #1790 – Added grouping of search results
- [x] #1799 – Added missing query terms to search result
- [x] #1799 – Improved search result relevance and scoring
- [ ] TBD – Improved search result summaries
- [ ] TBD – Added highlighting of query terms on target pages

### Bhut Jolokia

[:octicons-fire-24: Funding goal: __$1,500__][6] ·
:octicons-lock-24: Status: _pending_

Add native support to Material for MkDocs to build and deploy multiple versions
of a single documentation project, with the help of a plugin.

### Caribbean Red

[:octicons-fire-24: Funding goal: __$3,000__][6] ·
:octicons-lock-24: Status: _pending_

Add an alternative, completely different _vertical layout_, optimized to read
documentation and code side-by-side, e.g. for the documentation of APIs.

## Terms

Regardless of whether you're an individual or a company, you may use the
_sponsor edition_ exactly under the same terms as the _community edition_,
which are given by the [MIT license][12]. However, we kindly ask you to respect
the following guidelines:

- Please __don't distribute the source code__ from the _sponsor edition_.
You may freely use it for public, private or commercial projects, fork it,
mirror it, do whatever you want with it, as long as you're not releasing the
source code, as this would cannibalize the sponsorware model.

- If you cancel your subscription, you're removed as a collaborator and will not
receive future updates of the sponsor edition. However, you may continue to
use the latest version that's available to you for __as long as you like__.
Just remember that __[GitHub deletes private forks][13]__.

[12]: license.md
[13]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
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/
72 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`:

@@ -127,7 +138,7 @@ was renamed to `separator`:
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>
2 material/assets/javascripts/bundle.1688372e.min.js
View file

Large diffs are not rendered by default.

2 ...ts/javascripts/bundle.fc9c3121.min.js.map → ...ts/javascripts/bundle.1688372e.min.js.map
View file

Large diffs are not rendered by default.

2 material/assets/javascripts/bundle.fc9c3121.min.js
View file

This file was deleted.

31 material/assets/javascripts/vendor.877163d5.min.js
View file

Large diffs are not rendered by default.

1 material/assets/javascripts/vendor.877163d5.min.js.map
View file

Large diffs are not rendered by default.

31 material/assets/javascripts/vendor.de50e36d.min.js
View file

This file was deleted.

1 material/assets/javascripts/vendor.de50e36d.min.js.map
View file

This file was deleted.

2 material/assets/javascripts/worker/search.a68abb33.min.js.map
View file

Large diffs are not rendered by default.

18 material/assets/manifest.json
View file
@@ -1,12 +1,14 @@
{
"assets/javascripts/bundle.js": "assets/javascripts/bundle.fc9c3121.min.js",
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.fc9c3121.min.js.map",
"assets/javascripts/vendor.js": "assets/javascripts/vendor.de50e36d.min.js",
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.de50e36d.min.js.map",
"assets/javascripts/bundle.js": "assets/javascripts/bundle.1688372e.min.js",
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.1688372e.min.js.map",
"assets/javascripts/vendor.js": "assets/javascripts/vendor.877163d5.min.js",
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.545621a7.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.545621a7.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.36d1b78f.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.36d1b78f.min.css.map"
"assets/stylesheets/main.css": "assets/stylesheets/main.d2af3d17.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.d2af3d17.min.css.map",
"assets/stylesheets/overrides.css": "assets/stylesheets/overrides.5036298b.min.css",
"assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.5036298b.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.89d31e3b.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.89d31e3b.min.css.map"
}
3 material/assets/stylesheets/main.545621a7.min.css
View file

This file was deleted.

1 material/assets/stylesheets/main.545621a7.min.css.map
View file

This file was deleted.

3 material/assets/stylesheets/main.d2af3d17.min.css
View file

Large diffs are not rendered by default.

1 material/assets/stylesheets/main.d2af3d17.min.css.map
View file

Large diffs are not rendered by default.

3 material/assets/stylesheets/overrides.5036298b.min.css
View file
1 material/assets/stylesheets/overrides.5036298b.min.css.map
View file

Large diffs are not rendered by default.

1 material/assets/stylesheets/palette.36d1b78f.min.css.map
View file

This file was deleted.

4 ...sets/stylesheets/palette.36d1b78f.min.css → ...sets/stylesheets/palette.89d31e3b.min.css
View file

Large diffs are not rendered by default.

1 material/assets/stylesheets/palette.89d31e3b.min.css.map
View file

Large diffs are not rendered by default.

10 material/base.html
View file
@@ -29,7 +29,7 @@
<meta name="author" content="{{ config.site_author }}">
{% endif %}
<link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.4.0">
<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.5.0">
{% endblock %}
{% block htmltitle %}
{% if page and page.meta and page.meta.title %}
@@ -41,9 +41,9 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.545621a7.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.d2af3d17.min.css' | url }}">
{% if palette.scheme or palette.primary or palette.accent %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.36d1b78f.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.89d31e3b.min.css' | url }}">
{% endif %}
{% if palette.primary %}
{% import "partials/palette.html" as map %}
@@ -182,8 +182,8 @@ <h1>{{ page.title | default(config.site_name, true)}}</h1>
{% endblock %}
</div>
{% block scripts %}
<script src="{{ 'assets/javascripts/vendor.de50e36d.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/bundle.fc9c3121.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/vendor.877163d5.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/bundle.1688372e.min.js' | url }}"></script>
{%- set translations = {} -%}
{%- for key in [
"clipboard.copy",
2 material/overrides/home.html
View file
@@ -4,7 +4,7 @@
{% extends "overrides/main.html" %}
{% block tabs %}
{{ super() }}
<style>.md-header{position:initial}.md-main__inner{margin:0}.md-content{display:none}.tx-container{padding-top:1rem;background:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: white' /></svg>") no-repeat bottom,linear-gradient(to bottom,var(--md-primary-fg-color),#a53fd9 99%,#fff 99%)}.tx-hero{margin:0 .8rem;color:var(--md-primary-bg-color)}.tx-hero h1{margin-bottom:1rem;color:currentColor;font-weight:700}.tx-hero__content{padding-bottom:6rem}.tx-hero .md-button{margin-top:.5rem;margin-right:.5rem;color:var(--md-primary-bg-color)}.tx-hero .md-button--primary{background-color:var(--md-primary-bg-color);color:hsla(280deg,37%,48%,1);border-color:var(--md-primary-bg-color)}.tx-hero .md-button:focus,.tx-hero .md-button:hover{background-color:var(--md-accent-fg-color);color:var(--md-default-bg-color);border-color:var(--md-accent-fg-color)}@media screen and (max-width:30em){.tx-hero h1{font-size:1.4rem}}@media screen and (min-width:60em){.md-sidebar--secondary{display:none}.tx-hero{display:flex;align-items:stretch}.tx-hero__content{max-width:19rem;margin-top:3.5rem;padding-bottom:14vw}.tx-hero__image{width:38rem;order:1;transform:translateX(4rem)}}@media screen and (min-width:76.25em){.md-sidebar--primary{display:none}.tx-hero__image{transform:translateX(8rem)}}</style>
<style>.md-header{position:initial}.md-main__inner{margin:0}.md-content{display:none}@media screen and (min-width:60em){.md-sidebar--secondary{display:none}}@media screen and (min-width:76.25em){.md-sidebar--primary{display:none}}</style>
<section class="tx-container">
<div class="md-grid md-typeset">
<div class="tx-hero">
38 material/overrides/main.html
View file
@@ -22,16 +22,46 @@
<meta name="twitter:title" content="{{ title }}">
<meta name="twitter:description" content="{{ config.site_description }}">
<meta name="twitter:image" content="{{ image }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/overrides.5036298b.min.css' | url }}">
{% endblock %}
{% block announce %}
<style>.md-announce a,.md-announce a:focus,.md-announce a:hover{color:currentColor}.md-announce strong{white-space:nowrap}.md-announce .twitter{margin-left:.2em;color:#00acee}</style>
<a href="https://twitter.com/squidfunk">
For updates follow <strong>@squidfunk</strong> on
<span class="twemoji twitter">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path>
</svg>
{% include ".icons/fontawesome/brands/twitter.svg" %}
</span>
<strong>Twitter</strong>
</a>
{% endblock %}
{% block content %}
{{ super() }}
<aside class="tx-sponsor md-typeset">
<a href="{{ 'sponsorship/' | url }}" title="Become a sponsor">
<hr>
<span class="twemoji">
{% include ".icons/logo.svg" %}
</span>
<span class="twemoji">
{% include ".icons/material/plus.svg" %}
</span>
<span class="twemoji tx-heart">
{% include ".icons/octicons/heart-fill-24.svg" %}
</span>
<hr>
</a>
</aside>
{% endblock %}
{% block analytics %}
{{ super() }}
<script>
document.addEventListener("DOMContentLoaded", function() {
document.body.addEventListener("click", ev => {
if (ev.target instanceof HTMLElement) {
var el = ev.target.closest("a[href^=http]")
if (el)
ga("send", "event", "outbound", "click", el.href)
}
})
})
</script>
{% endblock %}
2 material/partials/integrations/analytics.html
View file
@@ -2,5 +2,5 @@
This file was automatically generated - do not edit
-#}
{% set analytics = config.google_analytics %}
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","{{ analytics[0] }}","{{ analytics[1] }}"),ga("set","anonymizeIp",!0),ga("send","pageview"),document.addEventListener("DOMContentLoaded",function(){document.forms.search&&document.forms.search.query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})}),document.addEventListener("DOMContentSwitch",function(){ga("send","pageview")})</script>
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","{{ analytics[0] }}","{{ analytics[1] }}"),ga("set","anonymizeIp",!0),ga("send","pageview"),document.addEventListener("DOMContentLoaded",function(){document.forms.search&&document.forms.search.query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})}),document.addEventListener("DOMContentSwitch",function(){ga("send","pageview",document.location.pathname)})</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
11 material/partials/more.html
View file

This file was deleted.

2 material/partials/source-link.html
View file
@@ -6,7 +6,7 @@
{% if repo | last == "/" %}
{% set repo = repo[:-1] %}
{% endif %}
{% set path = page.meta.path | default([""]) %}
{% set path = page.meta.path | default("") %}
<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ page.meta.source }}" class="md-content__button md-icon">
{{ lang.t("meta.source") }}
{% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
76 mkdocs.yml
View file
@@ -60,13 +60,27 @@ theme:
font:
text: Roboto
code: Roboto Mono
favicon: assets/favicon.png
icon:
logo: logo
favicon: assets/favicon.png

# Plugins
plugins:
- search
- redirects:
redirect_maps:
extensions/admonition.md: reference/admonitions.md
extensions/codehilite.md: reference/code-blocks.md
extensions/footnotes.md: reference/footnotes.md
extensions/metadata.md: reference/meta-tags.md
extensions/permalinks.md: setup/setting-up-navigation.md #permalink
plugins/search.md: setup/setting-up-site-search.md
# plugins/minification.md:
# plugins/revision-date.md:
# plugins/awesome-pages.md:
releases/4.md: upgrading.md #upgrading-from-4x-to-5x
releases/5.md: upgrading.md #upgrading-from-3x-to-4x
releases/changelog.md: changelog.md
- minify:
minify_html: true

@@ -90,8 +104,6 @@ extra:
markdown_extensions:
- markdown.extensions.admonition
- markdown.extensions.attr_list
- markdown.extensions.codehilite:
guess_lang: false
- markdown.extensions.def_list
- markdown.extensions.footnotes
- markdown.extensions.meta
@@ -106,8 +118,7 @@ markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
# - pymdownx.highlight:
# linenums_style: pymdownx-inline
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.magiclink:
@@ -127,27 +138,40 @@ markdown_extensions:
# Page tree
nav:
- Home: index.md
- Getting started: getting-started.md
- Extensions:
- Admonition: extensions/admonition.md
- CodeHilite: extensions/codehilite.md
- Footnotes: extensions/footnotes.md
- Metadata: extensions/metadata.md
- Permalinks: extensions/permalinks.md
- PyMdown: extensions/pymdown.md
- Plugins:
- Search: plugins/search.md
- Minification: plugins/minification.md
- Revision date: plugins/revision-date.md
- Awesome pages: plugins/awesome-pages.md
- Releases:
- Upgrading to 5.x: releases/5.md
- Upgrading to 4.x: releases/4.md
- Changelog: releases/changelog.md
- Customization: customization.md
- Data privacy: data-privacy.md
- Contributing: contributing.md
- License: license.md
- Getting started:
- Installation: getting-started.md
- Creating your site: creating-your-site.md
- Publishing your site: publishing-your-site.md
- Customization: customization.md
- Troubleshooting: troubleshooting.md
- Data privacy: data-privacy.md
- Sponsorship: sponsorship.md
- License: license.md
- Setup:
- Changing the colors: setup/changing-the-colors.md
- Changing the fonts: setup/changing-the-fonts.md
- Changing the language: setup/changing-the-language.md
- Changing the logo and icons: setup/changing-the-logo-and-icons.md
- Setting up navigation: setup/setting-up-navigation.md
- Setting up site search: setup/setting-up-site-search.md
- Setting up site analytics: setup/setting-up-site-analytics.md
- Adding social links: setup/adding-social-links.md
- Adding a git repository: setup/adding-a-git-repository.md
- Adding a comment system: setup/adding-a-comment-system.md
#- Adding an announcement bar: setup/adding-an-announcement-bar.md
#- Adding a landing page: setup/adding-a-landing-page.md
- Reference:
- Admonitions: reference/admonitions.md
- Code blocks: reference/code-blocks.md
- Content tabs: reference/content-tabs.md
- Footnotes: reference/footnotes.md
- Icons + Emojis: reference/icons-emojis.md
- Lists: reference/lists.md
- Meta tags: reference/meta-tags.md
- Changelog:
- Release notes: changelog.md
- Upgrading: upgrading.md
- Deprecations: deprecations.md

# Google Analytics
google_analytics:
4 netlify.toml
View file
@@ -21,6 +21,8 @@
[build]
publish = "site"
command = """
pip install mkdocs-minify-plugin
pip install \
mkdocs-minify-plugin>=0.3 \
mkdocs-redirects>=1.0
python -m mkdocs build
"""
258 package-lock.json
View file

Large diffs are not rendered by default.

28 package.json
View file
@@ -1,6 +1,6 @@
{
"name": "mkdocs-material",
"version": "5.4.0",
"version": "5.5.0",
"description": "A Material Design theme for MkDocs",
"keywords": [
"mkdocs",
@@ -37,10 +37,10 @@
"lunr": "^2.3.8",
"lunr-languages": "^1.4.0",
"ramda": "^0.27.0",
"rxjs": "^7.0.0-beta.0"
"rxjs": "^7.0.0-beta.2"
},
"devDependencies": {
"@fortawesome/fontawesome-free": "^5.13.1",
"@fortawesome/fontawesome-free": "^5.14.0",
"@mdi/svg": "^5.3.45",
"@primer/octicons": "^10.0.0",
"@types/clipboard": "^2.0.1",
@@ -50,15 +50,15 @@
"@types/html-minifier": "^4.0.0",
"@types/lunr": "^2.3.3",
"@types/mini-css-extract-plugin": "^0.9.1",
"@types/node": "^14.0.14",
"@types/ramda": "^0.27.6",
"@types/node": "^14.0.23",
"@types/ramda": "^0.27.11",
"@types/resize-observer-browser": "^0.1.3",
"@types/webpack": "^4.41.18",
"@types/webpack": "^4.41.21",
"@types/webpack-assets-manifest": "^3.0.1",
"autoprefixer": "9.8.4",
"copy-webpack-plugin": "^6.0.2",
"autoprefixer": "9.8.5",
"copy-webpack-plugin": "^6.0.3",
"css-loader": "^3.6.0",
"event-hooks-webpack-plugin": "^2.1.6",
"event-hooks-webpack-plugin": "^2.1.7",
"expose-loader": "^0.7.5",
"github-types": "^1.0.0",
"gitlab": "^14.2.2",
@@ -72,23 +72,23 @@
"postcss-inline-svg": "^4.1.0",
"postcss-loader": "^3.0.0",
"postcss-svgo": "^4.0.2",
"preact": "^10.4.4",
"preact": "^10.4.6",
"resize-observer-polyfill": "^1.5.1",
"rimraf": "^3.0.2",
"sass": "^1.26.9",
"sass-loader": "^8.0.2",
"sass": "^1.26.10",
"sass-loader": "^9.0.2",
"stylelint": "^13.6.1",
"stylelint-config-rational-order": "^0.1.2",
"stylelint-config-standard": "^20.0.0",
"stylelint-order": "^4.1.0",
"stylelint-scss": "^3.18.0",
"ts-loader": "^7.0.5",
"ts-loader": "^8.0.1",
"ts-node": "^8.10.2",
"tsconfig-paths-webpack-plugin": "^3.2.0",
"tslib": "^2.0.0",
"tslint": "^6.1.2",
"tslint-sonarts": "^1.9.0",
"typescript": "^3.9.5",
"typescript": "^3.9.7",
"webpack": "^4.43.0",
"webpack-assets-manifest": "^3.1.1",
"webpack-cli": "^3.3.12"
4 src/assets/javascripts/integrations/instant/index.ts
View file
@@ -229,7 +229,6 @@ export function setupInstantLoading(
withLatestFrom(document$)
)
.subscribe(([, { title, head }]) => {
document.dispatchEvent(new CustomEvent("DOMContentSwitch"))
document.title = title

/* Replace meta tags */
@@ -247,6 +246,9 @@ export function setupInstantLoading(
replaceElement(prev, next)
}
}

/* Finished, dispatch document switch event */
document.dispatchEvent(new CustomEvent("DOMContentSwitch"))
})

/* Debounce update of viewport offset */
2 src/assets/javascripts/integrations/search/transform/index.ts
View file
@@ -55,7 +55,7 @@ export type SearchTransformFn = (value: string) => string
* 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 type-ahead experience, by adding an
* 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.
*
2 src/assets/javascripts/integrations/search/worker/message/index.ts
View file
@@ -50,7 +50,7 @@ export interface SearchSetupMessage {
* A message indicating the search index is ready
*/
export interface SearchReadyMessage {
type: SearchMessageType.READY /* Message type */
type: SearchMessageType.READY /* Message type */
}

/**
308 src/assets/stylesheets/extensions/_codehilite.scss
View file

This file was deleted.

61 src/assets/stylesheets/main.scss
View file
@@ -37,37 +37,38 @@

@import "config";

@import "base/reset";
@import "base/colors";
@import "base/icons";
@import "base/typeset";
@import "main/reset";
@import "main/colors";
@import "main/icons";
@import "main/typeset";

@import "layout/base";
@import "layout/announce";
@import "layout/button";
@import "layout/clipboard";
@import "layout/content";
@import "layout/dialog";
@import "layout/header";
@import "layout/hero";
@import "layout/footer";
@import "layout/nav";
@import "layout/search";
@import "layout/sidebar";
@import "layout/source";
@import "layout/tabs";
@import "main/layout/base";
@import "main/layout/announce";
@import "main/layout/button";
@import "main/layout/clipboard";
@import "main/layout/content";
@import "main/layout/dialog";
@import "main/layout/header";
@import "main/layout/hero";
@import "main/layout/footer";
@import "main/layout/nav";
@import "main/layout/search";
@import "main/layout/sidebar";
@import "main/layout/source";
@import "main/layout/tabs";

@import "extensions/admonition";
@import "extensions/codehilite";
@import "extensions/footnotes";
@import "extensions/permalinks";
@import "main/extensions/markdown/admonition";
@import "main/extensions/markdown/codehilite";
@import "main/extensions/markdown/footnotes";
@import "main/extensions/markdown/toc";

@import "extensions/pymdown/arithmatex";
@import "extensions/pymdown/critic";
@import "extensions/pymdown/details";
@import "extensions/pymdown/emoji";
@import "extensions/pymdown/highlight";
@import "extensions/pymdown/tabbed";
@import "extensions/pymdown/tasklist";
@import "main/extensions/pymdownx/arithmatex";
@import "main/extensions/pymdownx/critic";
@import "main/extensions/pymdownx/details";
@import "main/extensions/pymdownx/emoji";
@import "main/extensions/pymdownx/highlight";
@import "main/extensions/pymdownx/keys";
@import "main/extensions/pymdownx/tabbed";
@import "main/extensions/pymdownx/tasklist";

@import "shame";
@import "main/shame";