@@ -2,21 +2,152 @@
template: overrides/main.html
---

# Upgrading
# Changelog

To upgrade to the latest version:
## Material for MkDocs Insiders

``` sh
pip install --upgrade mkdocs-material
```
### 1.5.1 <small>_ September 21, 2020</small>

To inspect the currently installed version:
* Fixed content area stretching to whole width for long code blocks

``` sh
pip show mkdocs-material
```
### 1.5.0 <small>_ September 19, 2020</small>

## Changelog
* Added support for autohiding table of contents when empty

### 1.4.1 <small>_ September 6, 2020</small>

* Improved typeahead and search result relevance and scoring

### 1.4.0 <small>_ August 30, 2020</small>

* Added support for auto-hiding header on scroll

### 1.3.0 <small>_ August 26, 2020</small>

* Added support for user-selectable color palettes

### 1.2.0 <small>_ August 11, 2020</small>

* Added feature to expand navigation by default

### 1.1.0 <small>_ August 3, 2020</small>

* Added highlighting of search results

### 1.0.0 <small>_ July 14, 2020</small>

* Added grouping of search results
* Added missing query terms to search result
* Improved search result relevance and scoring

## Material for MkDocs

### 6.0.1 <small>_ September 26, 2020</small>

* Fixed stemmer support for `file://` protocol through `iframe-worker`
* Fixed details marker showing for search result in Firefox
* Fixed tabbing behavior when search query is not empty
* Switched TypeScript compilation target to ES2015
* Reduced size of JavaScript by 36% (`176kb``113kb`)
* Removed `mkdocs` and `readthedocs` themes from Docker image

### 6.0.0 <small>_ September 25, 2020</small>

* Improved search result look and feel
* Improved search result stability while typing
* Improved search result grouping (pages + headings)
* Improved search result relevance and scoring
* Added display of missing query terms to search results
* Reduced size of vendor bundle by 25% (`84kb``67kb`)
* Reduced size of the Docker image to improve CI build performance
* Removed hero partial in favor of custom implementation
* Removed deprecated front matter features

### 5.5.14 <small>_ September 23, 2020</small>

* Improved spacing around image captions
* Fixed #1939: Long tables cause header overlap in print view

### 5.5.13 <small>_ September 19, 2020</small>

* Improved abbreviations on touch devices

### 5.5.12 <small>_ August 31, 2020</small>

* Fixed #1638: occasional `404` for images when using instant loading

### 5.5.11 <small>_ August 28, 2020</small>

* Fixed Disqus integration, as the minifier killed the config

### 5.5.10 <small>_ August 28, 2020</small>

* Improved rendering by moving Disqus integration after page load
* Fixed #1887: Moved navigation icons to CSS to reduce size of HTML

### 5.5.9 <small>_ August 26, 2020</small>

* Added Esperanto translations
* Fixed #1884: External links not included in navigation tabs

### 5.5.8 <small>_ August 23, 2020</small>

* Removed focus outline on `details` and content tabs for pointer devices
* Improved accessibility of content tabs (now navigable via arrow keys)
* Fixed #1877: `404` on search index when search is disabled
* Fixed some memleaks in observable subscriptions
* Fixed color definitions for `theme-color` meta tag

### 5.5.7 <small>_ August 16, 2020</small>

* Improved contrast ratio to 4.5:1 for syntax highlighting
* Improved contrast ratio to 4.5:1 for table of contents

### 5.5.6 <small>_ August 12, 2020</small>

* Switched base template for `404.html` to `main.html`
* Fixed #1864: GitHub organisation stats not loading

### 5.5.5 <small>_ August 11, 2020</small>

* Fixed missing vendor and worker distribution files

### 5.5.4 <small>_ August 11, 2020</small>

* Added support for sortable data tables

### 5.5.3 <small>_ August 4, 2020</small>

* Fixed search for languages other than English (5.5.1 regression)

### 5.5.2 <small>_ August 3, 2020</small>

* Improved highlight colors and spacing for `ins`, `del` and `mark`
* Changed some keyboard symbols for better equivalents
* Removed focus `outline` for details and code blocks on touch devices
* Fixed margins for Admonitions (5.5.1 regression)
* Fixed too small content tab labels (5.5.1 regression)
* Fixed icon repeating for custom admonition icons

### 5.5.1 <small>_ August 1, 2020</small>

* Improved typesetting by basing `font-size` and spacings on `em`
* Improved print view by slightly scaling down `font-size`
* Changed custom site title (metadata) to be suffixed with site name
* Fixed top- and bottom spacing of paragraphs inside table cells

### 5.5.0 <small>_ July 24, 2020</small>

* Rewrite of entire documentation
* Rewrite of syntax highlighting to be customizable with CSS variables
* Improved syntax highlighting to work with light and dark theme
* Improved `slate` color scheme to be more customizable and easier on the eyes
* Added licenses of icon sets to distribution files
* Fixed stale document titles in Google Analytics when using instant loading
* Fixed width of previous and next footer links for tablet and above
* Fixed issues with top scroll margin for footnotes
* Fixed top margin for tabbed content when using a JavaScript highlighter
* Deprecated metadata-based redirects, source links and heroes

### 5.4.0 <small>_ June 29, 2020</small>

@@ -30,7 +161,7 @@ pip show mkdocs-material

### 5.3.2 <small>_ June 21, 2020</small>

* Improved search type-ahead experience with non-Latin characters
* Improved search typeahead experience with non-Latin characters
* Fixed #1753: Japanese search doesn't work anymore

### 5.3.1 <small>_ June 20, 2020</small>

This file was deleted.

@@ -0,0 +1,140 @@
---
template: overrides/main.html
---

# Creating your site

After you've [installed][1] Material for MkDocs, you can bootstrap your project
documentation using the `mkdocs` executable. Go to the directory where you want
your project to be located and enter:

```
mkdocs new .
```

Alternatively, if you're running Material for MkDocs from within Docker, use:

=== "Unix"

```
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```

=== "Windows"

```
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
```

This will create the following structure:

```
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```

[1]: getting-started.md

## Configuration

### Minimal configuration

Depending on your [installation method][2], you can now add the following lines
to `mkdocs.yml` in your project root. If you installed Material for MkDocs using
`pip` or `docker`, add:

``` yaml
theme:
name: material
```

If you cloned Material for MkDocs from GitHub, add:

``` yaml
theme:
name: null
custom_dir: mkdocs-material/material
```

### Advanced configuration

Material for MkDocs comes with a lot of configuration options. The _setup_
section explains in great detail how to configure and customize colors, fonts,
icons and much more:

* [Changing the colors][3]
* [Changing the fonts][4]
* [Changing the language][5]
* [Changing the logo and icons][6]
* [Setting up navigation][7]
* [Setting up site search][8]
* [Setting up site analytics][9]
* [Setting up the header][10]
* [Adding social links][11]
* [Adding a git repository][12]
* [Adding a comment system][13]
<!-- * [Adding a landing page][14] -->

[2]: getting-started.md#installation
[3]: setup/changing-the-colors.md
[4]: setup/changing-the-fonts.md
[5]: setup/changing-the-language.md
[6]: setup/changing-the-logo-and-icons.md
[7]: setup/setting-up-navigation.md
[8]: setup/setting-up-site-search.md
[9]: setup/setting-up-site-analytics.md
[10]: setup/setting-up-the-header.md
[11]: setup/adding-social-links.md
[12]: setup/adding-a-git-repository.md
[13]: setup/adding-a-comment-system.md
<!--[14]: setup/adding-a-landing-page.md-->

## Previewing as you write

MkDocs includes a live preview server, so you can preview your changes as you
write your documentation. The server will automatically rebuild the site upon
saving. Start it with:

```
mkdocs serve
```

If you're running Material for MkDocs from within Docker, use:

=== "Unix"

```
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```

=== "Windows"

```
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```

Point your browser to [localhost:8000][15] and you should see:

[![Creating your site][16]][15]

[15]: http://localhost:8000
[16]: assets/screenshots/creating-your-site.png

## Building your site

When you're finished editing, you can build a static site from your Markdown
files with:

```
mkdocs build
```

The contents of this directory make up your project documentation. There's no
need for operating a database or server, as it is completely self-contained.
The site can be hosted on [GitHub Pages][17], [GitLab Pages][18], a CDN of your
choice or your private web space.

[17]: publishing-your-site.md#github-pages
[18]: publishing-your-site.md#gitlab-pages
@@ -4,77 +4,83 @@ template: overrides/main.html

# Customization

## A great starting point

Project documentation is as diverse as the projects themselves and Material for
MkDocs is a good starting point for making it look great. However, as you write
your documentation, you may reach a point where some small adjustments are
MkDocs is a great starting point for making it look beautiful. However, as you
write your documentation, you may reach a point where small adjustments are
necessary to preserve your brand's style.

## Adding assets

[MkDocs][1] provides several ways to interfere with themes. In order to make a
few tweaks to an existing theme, you can just add your stylesheets and
JavaScript files to the `docs` directory.
[MkDocs][1] provides several ways to customize a theme. In order to make a few
tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
files to the `docs` directory.

[1]: https://www.mkdocs.org

### Additional stylesheets
### Additional CSS

If you want to tweak some colors or change the spacing of certain elements,
you can do this in a separate stylesheet. The easiest way is by creating a
new stylesheet file in your `docs` directory:
new stylesheet file in the `docs` directory:

``` sh
mkdir docs/stylesheets
touch docs/stylesheets/extra.css
.
├─ docs/
│ └─ stylesheets/
│ └─ extra.css
└─ mkdocs.yml
```

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

``` yaml
extra_css:
- stylesheets/extra.css
```

Spin up the development server with `mkdocs serve` and start typing your
changes in your additional stylesheet file – you can see them instantly after
saving, as the MkDocs development server supports live reloading.
Spin up the [live preview server][2] and start typing your changes in your
additional stylesheet file – you should see them almost instantly after saving.

[2]: creating-your-site.md#previewing-as-you-write

### Additional JavaScript

The same is true for additional JavaScript. If you want to integrate another
syntax highlighter or add some custom logic to your theme, create a new
JavaScript file in your `docs` directory:
JavaScript file in the `docs` directory:

``` sh
mkdir docs/javascripts
touch docs/javascripts/extra.js
.
├─ docs/
│ └─ javascripts/
│ └─ extra.js
└─ mkdocs.yml
```

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

``` yaml
extra_javascript:
- javascripts/extra.js
```

Further assistance can be found in the [MkDocs documentation][2].
Further assistance can be found in the [MkDocs documentation][3].

[2]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
[3]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme

## Extending the theme

If you want to alter the HTML source (e.g. add or remove some part), you can
extend the theme. MkDocs supports [theme extension][3], an easy way to override
parts of a theme without forking and changing the main theme.
If you want to alter the HTML source (e.g. add or remove some parts), you can
extend the theme. MkDocs supports [theme extension][4], an easy way to override
parts of Material for MkDocs without forking from git. This ensures that you
can update to the latest version more easily.

[3]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir

### Setup and theme structure

Reference the Material theme as usual in your `mkdocs.yml`, and create a
new folder for `overrides` which you reference using `custom_dir`:
Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
for `overrides` which you then reference using the `custom_dir` key:

``` yaml
theme:
@@ -84,9 +90,9 @@ theme:

!!! warning "Theme extension prerequisites"

As the `custom_dir` variable is used for the theme extension process, the
As the `custom_dir` variable is used for the theme extension process,
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in your `mkdocs.yml`.
`name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.

The structure in the `overrides` directory must mirror the directory structure
of the original theme, as any file in the `overrides` directory will replace the
@@ -97,48 +103,72 @@ The directory layout of the theme is as follows:

``` sh
.
├─ .icons/ # Bundled icon sets
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript
│ └─ stylesheets/ # Stylesheets
├─ partials/
│ ├─ integrations/ # 3rd-party integrations
│ ├─ integrations/ # Third-party integrations
│ │ ├─ analytics.html # - Google Analytics
│ │ └─ disqus.html # - Disqus
│ ├─ language/ # Localized languages
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ hero.html # Hero teaser
│ ├─ language.html # Localized labels
│ ├─ nav-item.html # Main navigation item
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ palette.html # Color palette
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-date.html # Last updated date
│ ├─ source-link.html # Link to source file
│ ├─ source.html # Repository information
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ tabs.html # Tabs navigation
│ ├─ toc-item.html # Table of contents item
│ └─ toc.html # Table of contents
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
```

### Overriding partials

In order to override the footer, we can replace the `footer.html` partial with
our own partial. To do this, create the file `partials/footer.html` in the
`overrides` directory. MkDocs will now use the new partial when rendering the
theme. This can be done with any file.
In order to override a partial, we can replace it with a file of the same name
and location in the `overrides` directory. For example. to replace the original
`footer.html`, create a `footer.html` file in the `overrides/partials`
directory:

``` sh
.
├─ overrides/
│ └─ partials/
│ └─ footer.html
└─ mkdocs.yml
```

MkDocs will now use the new partial when rendering the theme. This can be done
with any file.

### Overriding template blocks
### Overriding blocks

Besides overriding partials, one can also override so called *template blocks*,
which are defined inside the templates and wrap specific features. To override a
template block, create a `main.html` inside the `overrides` directory and define
the block, e.g.:
Besides overriding partials, it's also possible to override (and extend)
_template blocks_, which are defined inside the templates and wrap specific
features. To override a block, create a `main.html` file inside the `overrides`
directory:

``` jinja
``` sh
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
```

Then, e.g. to override the site title, add the following line to `main.html`:

``` html
{% extends "base.html" %}

{% block htmltitle %}
@@ -151,12 +181,12 @@ Material for MkDocs provides the following template blocks:
| Block name | Wrapped contents |
| ------------ | ----------------------------------------------- |
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the Announcement bar |
| `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content |
| `disqus` | Wraps the disqus integration |
| `extrahead` | Empty block to define additional meta tags |
| `fonts` | Wraps the webfont definitions |
| `disqus` | Wraps the Disqus integration |
| `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions |
| `footer` | Wraps the footer with navigation and copyright |
| `header` | Wraps the fixed header bar |
| `hero` | Wraps the hero teaser (if available) |
@@ -169,76 +199,78 @@ Material for MkDocs provides the following template blocks:
| `styles` | Wraps the stylesheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |

For more on this topic refer to the [MkDocs documentation][4]
For more on this topic refer to the [MkDocs documentation][5].

[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks

## Theme development

Material for MkDocs uses [Webpack][5] as a build tool to leverage modern web
technologies like [TypeScript][6] and [SASS][7]. If you want to make more
Material for MkDocs uses [Webpack][6] as a build tool to leverage modern web
technologies like [TypeScript][7] and [SASS][8]. If you want to make more
fundamental changes, it may be necessary to make the adjustments directly in
the source of the theme and recompile it. This is fairly easy.
the source of the theme and recompile it.

[5]: https://webpack.js.org/
[6]: https://www.typescriptlang.org/
[7]: https://sass-lang.com
[6]: https://webpack.js.org/
[7]: https://www.typescriptlang.org/
[8]: https://sass-lang.com

### Environment setup

In order to start development on Material for MkDocs, a [Node.js][8] version of
In order to start development on Material for MkDocs, a [Node.js][9] version of
at least 12 is required. First, clone the repository:

``` sh
```
git clone https://github.com/squidfunk/mkdocs-material
```

Next, all dependencies need to be installed, which is done with:

``` sh
```
cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
npm install
```

[8]: https://nodejs.org
[9]: https://nodejs.org

### Development mode

Start the Webpack watchdog with:

``` sh
```
npm start
```

Then, in a second session, start the MkDocs server with:

```sh
```
mkdocs serve
```

Point your browser to [localhost:8000][9] and you should see this documentation in front of you.
Point your browser to [localhost:8000][10] and you should see this documentation
in front of you.

!!! warning "Automatically generated files"

Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.

[9]: http://localhost:8000
[10]: http://localhost:8000

### Build process
### Building the theme

When you've finished making your changes, you can build the theme by invoking:
When you're finished making your changes, you can build the theme by invoking:

``` sh
```
npm run build
```

This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command exits, the final files are
located in the `material` directory. Add the `theme_dir` variable pointing to
the aforementioned directory in your original `mkdocs.yml`.
the aforementioned directory in the original `mkdocs.yml`.

Now you can run `mkdocs build` and you should see your documentation with your
changes to the original theme.
@@ -14,30 +14,18 @@ some third-party services that may not.

### Google Fonts

Material for MkDocs makes fonts [easily configurable][2] by relying on Google
Fonts CDN. Embedding fonts from Google is currently within a gray area as there's
no official statement or ruling regarding GDPR compliance and the topic is still
[actively discussed][3]. If you need to ensure GDPR compliance, you may disable
the usage of the Google Font CDN with:

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

When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
Neue** and **Monaco** with their corresponding fall backs, relying on system
fonts. You can easily include your own, self-hosted webfont by [overriding][4]
the `fonts` block.

[2]: getting-started.md#fonts
[3]: https://github.com/google/fonts/issues/1495
[4]: customization.md#overriding-template-blocks
Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
disabled][3] via `mkdocs.yml`.

[2]: setup/changing-the-fonts.md
[3]: setup/changing-the-fonts.md#disabling-font-loading

### Google Analytics and Disqus

Material for MkDocs comes with optional [Google Analytics][5] and [Disqus][6]
integrations, both of which must be enabled explicitly.
Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
integrations, both of which must be enabled explicitly, so there's no immediate
action if you don't use those.

[5]: getting-started.md#google-analytics
[6]: getting-started.md#disqus
[4]: setup/setting-up-site-analytics.md#google-analytics
[5]: setup/adding-a-comment-system.md#disqus
@@ -0,0 +1,136 @@
---
template: overrides/main.html
---

# Deprecations

This page includes a list of deprecations, indicating which features of Material
for MkDocs were replaced with newer, more flexible alternatives, and thus should
not be used anymore.

## Front matter

### Redirect

:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0

The `redirect` key, which could be added via [Metadata][1], allowed to
specify a redirect from within a document to a new address, which is a good
idea when moving content around:

``` markdown
---
redirect: /path/to/new/file
---
```

The [redirects][2] plugin provides the ability to define redirect mappings via
`mkdocs.yml`, which is considered to be a much better solution to achieve the
same result. It can be installed with `pip`:

```
pip install mkdocs-redirects
```

Redirect mappings can then be added to `mkdocs.yml`:

``` yaml
plugins:
- redirects:
redirect_maps:
path/to/old/file.md: path/to/new/file.md
```

[1]: reference/meta-tags.md#metadata
[2]: https://github.com/datarobot/mkdocs-redirects

### Source link

:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0

The `source` and `path` keys, which could be added via [Metadata][1], showed
a source icon at the top right corner of a document, linking a document to a
single source file:

``` markdown
---
path: tree/master/docs
source: deprecations.md
---
```

Only a single source file could be linked, which is useless if a document refers
to multiple files (or multiple sections within a single file). A more flexible
approach is to use the new [icon integration][3]:

``` markdown
[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
```

This will render as [:octicons-file-code-24: Source][4], which can be included
at arbitrary positions in any document.

[3]: setup/changing-the-logo-and-icons.md#icons
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md

### Hero

:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0

The `hero` key, which could be added via [Metadata][1], allowed to render a
simple, text-only and page-local teaser text as part of a document. It could
be set from front matter with:

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

The recommended way is to [override the `hero` block][5] via [theme
extension][6] for a specific page, which has the nice side effect that hero
templates can be shared among multiple pages:

=== "Markdown"

``` markdown
---
template: overrides/hero.html
---
```

=== "Template"

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

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

## Docker image

### Bundled plugins

:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0

Over the last years, the Docker image has continually increased in size. For CI
it's important that download times are as short as possible, which is why the
following plugins will be removed:

- [mkdocs-awesome-pages-plugin][7]
- [mkdocs-git-revision-date-localized-plugin][8]

Note that it's trivial to install plugins inside the Docker image before
building your documentation. See the [installation guide][9] for a step-by-step
guide.

[7]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
[8]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
[9]: getting-started.md#with-docker

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Large diffs are not rendered by default.

@@ -0,0 +1,176 @@
---
template: overrides/main.html
---

# <span hidden>Insiders</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_ as part of
__Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2],
and how you can [become a sponsor][3].

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

<div style="width:100%;height:0px;position:relative;padding-bottom:56.138%;">
<iframe src="https://streamable.com/e/lz4me5" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe>
</div>
<p style="text-align: center; font-style: oblique">
A demo is worth a thousand words — check it out at <br />
<a href="https://squidfunk.github.io/mkdocs-material-insiders/">
squidfunk.github.io/mkdocs-material-insiders
</a>
</p>

## How sponsorship works

New features will first land in Material for MkDocs Insiders, which means that
_sponsors will have access immediately_. Every feature is tied to a funding
goal in monthly subscriptions. If a funding goal is hit, the features that are
tied to it are merged back into Material for MkDocs and released for general
availability. Bugfixes will always be released simultaneously in both editions.

See the [roadmap][4] for a list of already available and upcoming features, and
for demonstration purposes, [the official documentation][5] built with Material
for MkDocs Insiders.

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

## How to become a sponsor

So you've decided to become a sponsor? Great! You're just __three easy steps__
away from enjoying the latest features of Material for MkDocs Insiders.
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 from $10/month_. Select
the tier and complete the checkout.
- Within 24 hours, you will become a collaborator of the private Material for
MkDocs Insiders GitHub repository, a fork of Material for MkDocs with
[brand new and exclusive features][7].
- Create a [personal access token][8], which allows installing Material for
MkDocs Insiders from any destination, including other CI providers like
[GitLab][9] or [Bitbucket][10].

__Congratulations! :partying_face: You're now officially a sponsor and will
get updates for Material for MkDocs Insiders, until you decide to cancel your
monthly subscription, which you can 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 available
in Material for MkDocs Insiders.

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

### Madame Jeanette

[:octicons-flame-24: Funding goal: __$500__][6] ·
:octicons-unlock-24: Status: _released_

New features and improvements for _search_, including:

- [x] Improved search result grouping (pages + headings)
- [x] Improved search result relevance and scoring
- [x] Display of missing query terms in search results

### Prairie Fire

[:octicons-flame-24: Funding goal: __$1,000__][6] ·
:octicons-lock-24: Status: _exclusive_

New features and improvements for _content and toc_, including:

- [x] Highlighting of matched search terms in content area
- [x] Navigation can always be expanded via configuration
- [x] Header can be automatically hidden on scrolling
- [x] Table of contents can be automatically hidden when empty
- [ ] Table of contents can be moved into navigation for more space
- [ ] Table of contents shows which sections have search results
- [ ] Table of contents auto-collapses and expands only the active section
- [ ] Better support for wide screens, i.e. more horizontal space
- [ ] ... more to come

### Bhut Jolokia

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

New features and improvements for _hosting multiple versions_, including:

- [ ] Support for multiple languages of documents
- [ ] Support for multiple versions of documents
- [ ] Support for one or more management plugins
- [ ] ... more to come

### Black Pearl

[:octicons-flame-24: Funding goal: __$2,000__][6] ·
:octicons-lock-24: Status: _exclusive_

New features and improvements for _user preferences_, including:

- [x] Support for user-toggleable themes
- [ ] Support for user-toggleable code-block styles (light/dark)
- [ ] Display last searches when search is empty
- [ ] Improved search result summaries
- [ ] ... more to come

### Caribbean Red

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

Alternative, completely different _vertical layout_, optimized to read
documentation and code side-by-side, e.g. for the documentation of APIs with
the same functionality as Material for MkDocs.

## Frequently asked questions

### Compatibility

_We're running an open source project and want to make sure that users can build
the documentation without having access to Insiders. Is that still possible?_

Yes. Material for MkDocs Insiders strives to be compatible with Material for
MkDocs, so all new features are implemented as feature flags and all
improvements (e.g. search) do not require any changes to existing configuration.
This means that your users will be able to build the docs locally with the
regular version and when they push their changes to CI/CD, they will be built
with Material for MkDocs Insiders. For this reason, it's recommended to
[install Insiders][12] only in CI, as you don't want to expose your `GH_TOKEN`
to users.

### Terms

_We're using Material for MkDocs to build the developer documentation of a
commercial project. Can we use Material for MkDocs Insiders under the same
terms?_

Yes. Whether you're an individual or a company, you may use _Material for MkDocs
Insiders_ precisely under the same terms as Material for MkDocs, which are given
by the [MIT license][13]. However, we kindly ask you to respect the following
guidelines:

- Please __don't distribute the source code__ from Material for MkDocs Insiders.
You may freely use it for public, private or commercial projects, fork it,
mirror it, do whatever you want with it, but please don't release the source
code, as it would cannibalize the sponsorware strategy.

- If you cancel your subscription, you're removed as a collaborator and will
miss out on future updates of Material for MkDocs Insiders. However, you may
__use the latest version__ that's available to you __as long as you like__.
Just remember that __[GitHub deletes private forks][14]__.

[12]: publishing-your-site.md#github-pages
[13]: license.md
[14]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
@@ -6,22 +6,4 @@ template: overrides/main.html

**MIT License**

Copyright &copy; 2016 - 2020 Martin Donath

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

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

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

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

@@ -0,0 +1,143 @@
---
template: overrides/main.html
---

# Publishing your site

The great thing about hosting project documentation in a `git` repository is
the ability to deploy it automatically when new changes are pushed. MkDocs
makes this ridiculously simple.

## GitHub Pages

If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly
the most convenient way to publish your project documentation. It's free of
charge and pretty easy to set up.

[1]: https://pages.github.com/

### with GitHub Actions

Using [GitHub Actions][2] you can automate the deployment of your project
documentation. At the root of your repository, create a new GitHub Actions
workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
contents:

=== "Material for MkDocs"

``` yaml
name: ci
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
```

=== "Insiders"

``` yaml
name: ci
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- run: mkdocs gh-deploy --force
env:
GH_TOKEN: ${{ secrets.GH_TOKEN }}
```

Now, when a new commit is pushed to `master`, the static site is automatically
built and deployed. Commit and push the file to your repository to see the
workflow in action.

Your documentation should shortly appear at `<username>.github.io/<repository>`.

_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
[personal access token][3] when using [Material for MkDocs Insiders][4], which
can be done using [secrets][5]._

[2]: https://github.com/features/actions
[3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[4]: insiders.md
[5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets

### with MkDocs

If you prefer to deploy your project documentation manually, you can just invoke
the following command from the directory containing the `mkdocs.yml` file:

```
mkdocs gh-deploy --force
```

## GitLab Pages

If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be
done by using the [GitLab CI][7] task runner. At the root of your repository,
create a task definition named `.gitlab-ci.yml` and copy and paste the
following contents:

=== "Material for MkDocs"

``` yaml
image: python:latest
deploy:
stage: deploy
only:
- master
script:
- pip install mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
```

=== "Insiders"

``` yaml
image: python:latest
deploy:
stage: deploy
only:
- master
script:
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- mkdocs build --site-dir public
artifacts:
paths:
- public
```

Now, when a new commit is pushed to `master`, the static site is automatically
built and deployed. Commit and push the file to your repository to see the
workflow in action.

Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.

_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
[personal access token][3] when using [Material for MkDocs Insiders][4], which
can be done using [masked custom variables][8]._

[6]: https://gitlab.com/pages
[7]: https://docs.gitlab.com/ee/ci/
[8]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
@@ -0,0 +1,99 @@
---
template: overrides/main.html
---

# Abbreviations

Technical documentation often incurs the usage of a lot of acronyms, which may
need additional explanation, especially for new user of your project. For these
matters, Material for MkDocs uses a combination of Markdown extensions to
enable site-wide glossaries.

## Configuration

### Abbreviations

The [Abbreviations][1] extension, which is part of the standard Markdown
library, allows to __add additional content to parts of the text which are then
shown on hover__, e.g. for glossaries:

``` yaml
markdown_extensions:
- abbr
```

[1]: https://python-markdown.github.io/extensions/abbreviations/

### Snippets

The [Snippets][2] extension, which is part of [Python Markdown Extensions][3],
allows to __insert content from other files__ or other, regular content, and can
be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.snippets
```

[2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[3]: https://facelessuser.github.io/pymdown-extensions/

## Usage

### Adding abbreviations

When the [Abbreviations][4] extension is enabled, abbreviations can be defined
with a special syntax similar to URLs and [footnotes][5] at any point in the
Markdown document.

_Example_:

``` markdown
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
```

_Result_:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

[4]: #abbreviations_1
[5]: footnotes.md

### Adding a glossary

When [Snippets][6] is enabled, content from other files can be embedded, which
is especially useful to include abbreviations from a central file – a glossary –
and embed them into any other file.

_Example_:

=== "docs/page.md"

```` markdown
The HTML specification is maintained by the W3C.

--8<--​ "includes/abbreviations.md"
````

=== "includes/abbreviations.md"

```` markdown
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
````

_Result_:

The HTML specification is maintained by the W3C.

_Remember to locate the Markdown file containing the definitions outside of the_
`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
unreferenced file._

[6]: #snippets

Large diffs are not rendered by default.

@@ -0,0 +1,83 @@
---
template: overrides/main.html
---

# Buttons

Material for MkDocs provides dedicated styles for primary and secondary buttons
that can be added to any link, `label` or `button` element. This is especially
useful for documents or landing pages with dedicated _call-to-actions_.

## Configuration

### Attribute List

The [Attribute List][1] 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
```

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

## Usage

### Adding buttons

When the [Attribute List][2] extension is enabled, any clickable element can be
converted into a button by adding the `.md-button` CSS class, which will receive
the selected [primary color][3].

_Example_:

``` markdown
[Subscribe to our mailing list](#){: .md-button }
```

_Result_:

[Subscribe to our mailing list][4]{: .md-button }

[2]: #attribute-list
[3]: ../setup/changing-the-colors.md#primary-color
[4]: javascript:app.dialog$.next("Done!")

### Adding primary buttons

If you want to display a filled, primary button (like on the [landing page][5]
of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
CSS classes.

_Example_:

``` markdown
[Subscribe to our mailing list](#){: .md-button .md-button--primary }
```

_Result_:

[Subscribe to our mailing list][4]{: .md-button .md-button--primary }

[5]: ../index.md

### Adding icon buttons

Of course, icons can be added to both types of buttons by using the [regular
icon syntax][6] and referencing a valid path to [any icon bundled with the
theme][7].

_Example_:

``` markdown
[Submit :fontawesome-solid-paper-plane:](#){: .md-button .md-button--primary }
```

_Result_:

[Submit :fontawesome-solid-paper-plane:][4]{: .md-button .md-button--primary }

[6]: icons-emojis.md#using-icons
[7]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
@@ -0,0 +1,387 @@
---
template: overrides/main.html
---

# Code blocks

Code blocks and examples are an essential part of technical project
documentation. Material for MkDocs provides different ways to set up syntax
highlighting for code blocks, either during build time using [Pygments][1] or
during runtime using a JavaScript syntax highlighter.

[1]: https://pygments.org

## Configuration

### Highlight

[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
:octicons-zap-24: Supersedes: [CodeHilite][4]

The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
integrates with Material for MkDocs and provides several options for
configuring syntax highlighting of code blocks:

`use_pygments`{: #use-pygments }

: :octicons-milestone-24: Default: `true` – This option allows to control
whether highlighting should be carried out during build time by
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
necessary [additional stylesheets][6] and [JavaScript][7] if you want to
use the latter:

=== "Pygments"

``` yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.superfences
```

=== "JavaScript"

``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: false
```

??? example "Syntax highlighting with Highlight.js"

[Highlight.js][8] can be integrated by creating an [additional
JavaScript][7] file initializing the highlighter and including the
respective stylesheet and JavaScript from a [CDN][9] serving
Highlight.js in `mkdocs.yml`:

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

``` js
hljs.initHighlighting()
```

=== "mkdocs.yml"

``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
- javascripts/config.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css
```

Note that Highlight.js has no affiliation with the Highlight extension.

`linenums`{: #linenums }

: :octicons-milestone-24: Default: `false` – This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
code blocks, consult the section on [adding line numbers][10] later in this
document, which also contains some tips on working with line numbers:

``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums: true
```

`linenums_style`{: #linenums-style }

: :octicons-milestone-24: Default: `table` – The Highlight extension provides
three ways to add line numbers, all of which are supported by Material for
MkDocs. While `table` wraps a code block in a table, `inline` and
`pymdownx.inline` render line numbers as part of the line itself:

``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums_style: pymdownx.inline
```

Note that `inline` will put line numbers next to the actual code, which
means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of `table` or
`pymdownx.inline` is recommended.

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

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[4]: https://python-markdown.github.io/extensions/code_hilite/
[5]: https://facelessuser.github.io/pymdown-extensions/
[6]: ../customization.md#additional-css
[7]: ../customization.md#additional-javascript
[8]: https://highlightjs.org/
[9]: https://cdnjs.com/libraries/highlight.js/
[10]: #adding-line-numbers

### InlineHilite

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

The [InlineHilite][11] extension, which is part of [Python Markdown
Extensions][5] also integrates with Material for MkDocs and adds support for
__syntax highlighting of inline code blocks__. It's built on top of the
[Highlight][3] extension and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.inlinehilite
```

See the section on [inline code blocks][12] for usage information.

[11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[12]: #highlighting-inline-code-blocks

### Keys

[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]

The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.keys
```

[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/

### SuperFences

The [SuperFences][15] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code blocks inside other blocks__,
and is therefore strongly recommended:

``` yaml
markdown_extensions:
- pymdownx.superfences
```

[15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

### Snippets

The [Snippets][16] extension, which is also part of [Python Markdown
Extensions][5], allows to __insert content from other files__ or other, regular
content, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.snippets
```

[16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

## Usage

This section discusses how to use different syntax highlighting features with
[Pygments][1] – the default highlighter – so they don't apply when using
a JavaScript syntax highlighter.

### Specifying the language

Code blocks must be enclosed with two separate lines containing three backticks.
To add code highlighting to those blocks, add the language short name directly
after the opening block. See the [list of available lexers][17] to find the
short name for a given language.

_Example_:

```` markdown
``` python
import tensorflow as tf
```
````

_Result_:

``` python
import tensorflow as tf
```

[17]: https://pygments.org/docs/lexers/

### Adding line numbers

Line numbers can be added to a code block by using the `linenums="<start>"`
option directly after the short name, whereas `<start>` represents the starting
line number. A code block can start from a line number other than `1`, which
allows splitting large code blocks for readability.

_Example_:

```` markdown
``` python linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````

_Result_:

``` python linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```

### Highlighting specific lines

Specific lines can be highlighted by passing the line numbers to the `hl_lines`
argument placed right after the language short name. Note that line counts start
at `1`, regardless of the starting line number specified as part of `linenums`.

_Example_:

```` markdown
``` python hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````

_Result_:

``` python hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```

### Highlighting inline code blocks

When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
the [language short name][17].

_Example_:

``` markdown
The `#!python range()` function is used to generate a sequence of numbers.
```

_Result_:

The `#!python range()` function is used to generate a sequence of numbers.

[18]: #inlinehilite

### Adding keyboard keys

When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
Consult the [Python Markdown Extensions][16] documentation to learn about all
available key codes.

_Example_:

``` markdown
++ctrl+alt+del++
```

_Result_:

++ctrl+alt+del++

[19]: #keys

### Embedding external files

_Also known as transcludes or file transclusion in [MultiMarkdown][20]_.

When [Snippets][21] is enabled, content from other files can be embedded, which
is especially useful to reference and embed the contents of source files
directly into your project documentation.

_Example_:

```` markdown
```
--8<--​ ".browserslistrc"
```
````

_Result_:

```
--8<-- ".browserslistrc"
```

Note that [Snippets][21] is not limited to code blocks, but can be used anywhere
from a document to move repeating content to separate files, which is also
explained in the [official documentation][16].

[20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
[21]: #snippets

## Customization

### Custom syntax theme

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

If [Pygments][23] is used, Material for MkDocs provides the [styles for code
blocks][22], which are built with a custom and well-balanced palette that works
equally well for both [color schemes][24]:

* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`

Code block foreground, background and line highlight colors are defined via:

* :material-checkbox-blank-circle:{: style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color`

Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens][25], Material for MkDocs assigns a single color
to most of them.

Create an [additional stylesheet][6], and add:

``` css
:root > * {
--md-code-hl-string-color: #0FF1CE;
}
```

If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
can lookup the specific class name in the [syntax theme definition][26], and
override it as part of your additional stylesheet:

``` css
.highlight .sb {
color: #0FF1CE;
}
```

[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#L60-L73
[23]: #use-pygments
[24]: ../setup/changing-the-colors.md#color-scheme
[25]: https://pygments.org/docs/tokens/#literals
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss#L42
@@ -0,0 +1,218 @@
---
template: overrides/main.html
---

# Content tabs

Sometimes, it's desirable to group alternative content under different tabs,
e.g. when describing how to access an API from different languages or
environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.

## Configuration

### Tabbed

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

The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.tabbed
```

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

### SuperFences

The [SuperFences][4] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code and content blocks inside
tabs__, and is therefore strongly recommended:

``` yaml
markdown_extensions:
- pymdownx.superfences
```

[4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

## Usage

### Grouping code blocks

Code blocks are one of the primary targets to be grouped, and can be considered
a special case of content tabs, as tabs with a single code block are always
rendered without horizontal spacing.

_Example_:

```
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```

=== "C++"

``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
```
_Result_:
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```

=== "C++"

``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```

### Grouping other content

When a content tab contains more than one code block, it is rendered with
horizontal spacing. Vertical spacing is never added, but can be achieved
by nesting tabs in other blocks.

_Example_:

```
=== "Unordered list"
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
=== "Ordered list"
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```

_Result_:

=== "Unordered list"

* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci

=== "Ordered list"

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

### Embedded content

When [SuperFences][5] is enabled, content tabs can contain arbitrary nested
content, including further content tabs, and can be nested in other blocks like
[admonitions][6], [details][7] or blockquotes:

_Example_:

``` markdown
!!! example

=== "Unordered List"

_Example_:

``` markdown
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
```

_Result_:

* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci

=== "Ordered List"

_Example_:

``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```

_Result_:

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```

_Result_:

!!! example

=== "Unordered List"

_Example_:

``` markdown
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
```

_Result_:

* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci

=== "Ordered List"

_Example_:

``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```

_Result_:

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

[5]: #superfences
[6]: admonitions.md
[7]: admonitions.md#details