Merge pull request #1735 from squidfunk/docs/restructure

WIP – Restructure documentation

.github/workflows/ci.yml

@@ -81,7 +81,9 @@ jobs:
       - run: |
           pip install -r requirements.txt
           pip install .
-          pip install mkdocs-minify-plugin>=0.2
+          pip install \
+            mkdocs-minify-plugin>=0.3 \
+            mkdocs-redirects>=1.0
 
       # Build documentation
       - env:

CHANGELOG

@@ -10,7 +10,7 @@ mkdocs-material-5.3.3 (2020-06-24)
 
 mkdocs-material-5.3.2 (2020-06-21)
 
-  * 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
 
 mkdocs-material-5.3.1 (2020-06-20)

MANIFEST.in

@@ -1,5 +1,6 @@
 recursive-include material *.js *.css *.map *.html *.svg *.png *.yml
 recursive-include material *.ttf *.woff *.woff2 LICENSE*
+recursive-exclude material/assets overrides*
 recursive-exclude material/overrides *
 recursive-exclude site *
 recursive-exclude src *

docs/changelog.md

@@ -2,21 +2,9 @@
 template: overrides/main.html
 ---
 
-# Upgrading
+# Changelog
 
-To upgrade to the latest version:
+## Release notes
-
-``` sh
-pip install --upgrade mkdocs-material
-```
-
-To inspect the currently installed version:
-
-``` sh
-pip show mkdocs-material
-```
-
-## Changelog
 
 ### 5.4.0 <small>_ June 29, 2020</small>
 
@@ -30,7 +18,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>

docs/contributing.md

@@ -1,5 +0,0 @@
----
-template: overrides/main.html
----
-
---8<-- "CONTRIBUTING.md"

docs/creating-your-site.md

@@ -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:
+
+``` sh
+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 _guides_
+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]
+* [Adding social links][10]
+* [Adding a git repository][11]
+* [Adding a comment system][12]
+<!-- * [Adding an announcement bar][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/adding-social-links.md
+  [11]: setup/adding-a-git-repository.md
+  [12]: setup/adding-a-comment-system.md
+  <!-- [13]: setup/adding-an-announcement-bar.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/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

docs/customization.md

@@ -4,8 +4,6 @@ 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
@@ -13,9 +11,9 @@ necessary to preserve your brand's style.
 
 ## Adding assets
 
-[MkDocs][1] provides several ways to interfere with themes. In order to make a
+[MkDocs][1] provides several ways to customize a theme. In order to make a few
-few tweaks to an existing theme, you can just add your stylesheets and
+tweaks to an existing theme, you can just add your stylesheets and JavaScript
-JavaScript files to the `docs` directory.
+files to the `docs` directory.
 
   [1]: https://www.mkdocs.org
 
@@ -23,58 +21,59 @@ JavaScript files to the `docs` directory.
 
 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
 ```
 
-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
+Spin up the [live preview server][2] and start typing your changes in your
-changes in your additional stylesheet file – you can see them instantly after
+additional stylesheet file – you should see them almost instantly after saving.
-saving, as the MkDocs development server supports live reloading.
+
+  [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
 ```
 
-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
+extend the theme. MkDocs supports [theme extension][4], an easy way to override
 parts of a theme without forking and changing the main theme.
 
-  [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
+Reference the original theme as usual in `mkdocs.yml`, and create a new folder
-new folder for `overrides` which you reference using `custom_dir`:
+for `overrides` which you reference using `custom_dir`:
 
 ``` yaml
 theme:
@@ -84,9 +83,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,28 +96,33 @@ 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
+│  ├─ tabs-item.html                   # Tabs navigation item
-│  └─ toc.html                         # Table of contents
+│  ├─ 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
@@ -131,12 +135,12 @@ 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.
 
-### Overriding template blocks
+### Overriding blocks
 
-Besides overriding partials, one can also override so called *template blocks*,
+Besides overriding partials, it's also possible to override (and extend) so
-which are defined inside the templates and wrap specific features. To override a
+called _blocks_, which are defined inside the templates and wrap specific
-template block, create a `main.html` inside the `overrides` directory and define
+features. To override a block, create a `main.html` inside the `overrides`
-the block, e.g.:
+directory and define the block, e.g.:
 
 ``` jinja
 {% extends "base.html" %}
@@ -151,12 +155,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                    |
+| `disqus`     | Wraps the Disqus integration                    |
-| `extrahead`  | Empty block to define additional meta tags      |
+| `extrahead`  | Empty block to add custom meta tags             |
-| `fonts`      | Wraps the webfont definitions                   |
+| `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,24 +173,24 @@ 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
+Material for MkDocs uses [Webpack][6] as a build tool to leverage modern web
-technologies like [TypeScript][6] and [SASS][7]. If you want to make more
+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://webpack.js.org/
-  [6]: https://www.typescriptlang.org/
+  [7]: https://www.typescriptlang.org/
-  [7]: https://sass-lang.com
+  [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
@@ -198,10 +202,11 @@ 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
 
@@ -217,7 +222,8 @@ Then, in a second session, start the MkDocs server with:
 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"
 
@@ -225,11 +231,11 @@ Point your browser to [localhost:8000][9] and you should see this documentation
     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
@@ -238,7 +244,7 @@ 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.

docs/data-privacy.md

@@ -25,14 +25,14 @@ theme:
   font: false
 ```
 
-When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
+When Google Fonts are disabled, Material for MkDocs will default to __Helvetica
-Neue** and **Monaco** with their corresponding fall backs, relying on system
+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
+  [2]: setup/changing-the-fonts.md
   [3]: https://github.com/google/fonts/issues/1495
-  [4]: customization.md#overriding-template-blocks
+  [4]: customization.md#overriding-blocks
 
 ### Google Analytics and Disqus
 

docs/extensions/admonition.md

@@ -1,459 +0,0 @@
----
-template: overrides/main.html
----
-
-# Admonition
-
-[Admonition][1] is an extension included in the standard Markdown library that
-makes it possible to add block-styled side content to your documentation, e.g.
-summaries, notes, hints or warnings.
-
-  [1]: https://python-markdown.github.io/extensions/admonition/
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - admonition
-```
-
-## Usage
-
-Admonitions follow a simple syntax: every block is started with `!!!`, followed
-by a single keyword which is used as the [type qualifier][2] of the block. The
-content of the block then follows on the next line, indented by four spaces.
-
-Example:
-
-``` markdown
-!!! note
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! note
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-  [2]: #types
-
-### Changing the title
-
-By default, the Admonition title will equal the type qualifier in titlecase.
-However, it can be changed by adding a quoted string after the type qualifier.
-
-Example:
-
-``` markdown
-!!! note "Phasellus posuere in sem ut cursus"
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! note "Phasellus posuere in sem ut cursus"
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-### Removing the title
-
-Similar to [changing the title][3], the icon and title can be omitted by
-providing an empty string after the type qualifier:
-
-Example:
-
-``` markdown
-!!! note ""
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! note ""
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-  [3]: #changing-the-title
-
-### Embedded content
-
-Admonitions can contain all kinds of text content, including headlines, lists,
-paragraphs and other blocks – except code blocks, because the parser from the
-standard Markdown library does not account for those.
-
-The [PyMdown Extensions][4] package adds an extension called [SuperFences][5],
-which makes it possible to nest code blocks within other blocks, respectively
-Admonition blocks.
-
-  [4]: https://facelessuser.github.io/pymdown-extensions
-  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-
-Example:
-
-!!! note
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-    ``` mysql
-    SELECT
-      Employees.EmployeeID,
-      Employees.Name,
-      Employees.Salary,
-      Manager.Name AS Manager
-    FROM
-      Employees
-    LEFT JOIN
-      Employees AS Manager
-    ON
-      Employees.ManagerID = Manager.EmployeeID
-    WHERE
-      Employees.EmployeeID = '087652';
-    ```
-
-    Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
-    sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
-    Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
-
-### Collapsible blocks
-
-The [Details][6] extension which is also part of the [PyMdown Extensions][4]
-package adds support for rendering collapsible Admonition blocks. This is
-useful for FAQs or content that is of secondary nature.
-
-Example:
-
-``` markdown
-??? note "Phasellus posuere in sem ut cursus"
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-??? note "Phasellus posuere in sem ut cursus"
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-By adding a `+` sign directly after the start marker, blocks can be rendered
-open by default.
-
-  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
-
-## Types
-
-Admonition supports user-defined type qualifiers which may influence the style
-of the inserted block. Following is a list of type qualifiers provided by
-Material for MkDocs, whereas the default type, and thus fallback for unknown
-type qualifiers, is `note`.
-
-### Note
-
-Example:
-
-``` markdown
-!!! note
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! note
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `note`
-* `seealso`
-
-### Abstract
-
-Example:
-
-``` markdown
-!!! abstract
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! abstract
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `abstract`
-* `summary`
-* `tldr`
-
-### Info
-
-Example:
-
-``` markdown
-!!! info
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! info
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `info`
-* `todo`
-
-### Tip
-
-Example:
-
-``` markdown
-!!! tip
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! tip
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `tip`
-* `hint`
-* `important`
-
-### Success
-
-Example:
-
-``` markdown
-!!! success
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! success
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `success`
-* `check`
-* `done`
-
-### Question
-
-Example:
-
-``` markdown
-!!! question
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! question
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `question`
-* `help`
-* `faq`
-
-### Warning
-
-Example:
-
-``` markdown
-!!! warning
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! warning
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `warning`
-* `caution`
-* `attention`
-
-### Failure
-
-Example:
-
-``` markdown
-!!! failure
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! failure
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `failure`
-* `fail`
-* `missing`
-
-### Danger
-
-Example:
-
-``` markdown
-!!! danger
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! danger
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `danger`
-* `error`
-
-### Bug
-
-Example:
-
-``` markdown
-!!! bug
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! bug
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `bug`
-
-### Example
-
-Example:
-
-``` markdown
-!!! example
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! example
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `example`
-
-### Quote
-
-Example:
-
-``` markdown
-!!! quote
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-!!! quote
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-
-Qualifiers:
-
-* `quote`
-* `cite`

docs/extensions/codehilite.md

@@ -1,966 +0,0 @@
----
-template: overrides/main.html
----
-
-# CodeHilite
-
-[CodeHilite][1] is an extension that adds syntax highlighting to code blocks
-and is included in the standard Markdown library. It uses [Pygments][2] during
-the compilation of the Markdown file to provide syntax highlighting for over 
-[300 languages][3] and has no JavaScript runtime dependency.
-
-  [1]: https://python-markdown.github.io/extensions/code_hilite/
-  [2]: https://pygments.org
-  [3]: http://pygments.org/languages
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - codehilite
-```
-
-## Usage
-
-### Specifying the language
-
-The CodeHilite extension uses the same syntax as regular Markdown code blocks,
-but needs to know the language of the code block. This can be done in three
-different ways.
-
-#### via Markdown syntax <small>recommended</small>
-
-In Markdown, code blocks can be opened and closed by writing three backticks on
-separate lines. To add code highlighting to those blocks, the easiest way is
-to specify the language identifier directly after the opening block.
-
-Example:
-
-```` markdown
-``` python
-import tensorflow as tf
-```
-````
-
-Result:
-
-``` python
-import tensorflow as tf
-```
-
-#### via Shebang
-
-Alternatively, if the first line of a code block contains a shebang, the
-language is derived from the path referenced in the shebang. This will only
-work for code blocks that are indented using four spaces, not for those
-encapsulated in three backticks.
-
-Example:
-
-```` markdown
-    #!/usr/bin/python
-    import tensorflow as tf
-````
-
-Result:
-
-``` python
-#!/usr/bin/python
-import tensorflow as tf
-```
-
-#### via three colons
-
-If the first line starts with three colons followed by a language identifier,
-the first line is stripped. This will only work for code blocks that are
-indented using four spaces, not for those encapsulated in three backticks.
-
-Example:
-
-``` markdown
-    :::python
-    import tensorflow as tf
-```
-
-Result:
-
-    :::python
-    import tensorflow as tf
-
-### Adding line numbers
-
-Line numbers can be added to a code block by enabling the `linenums` flag in
-`mkdocs.yml` or adding `linenums=1` right after the language identifier:
-
-``` yaml
-markdown_extensions:
-  - codehilite:
-      linenums: true
-```
-
-Example:
-
-```` markdown
-``` python linenums="1"
-""" Bubble sort """
-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"
-""" Bubble sort """
-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]
-```
-
-### Grouping code blocks
-
-The [Tabbed][4] extension which is part of the [PyMdown Extensions][5]
-package adds support for grouping Markdown blocks with tabs. This is especially
-useful for documenting projects with multiple language bindings.
-
-Add the Tabbed and SuperFences extensions to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-    - codehilite
-    - pymdownx.tabbed
-    - pymdownx.superfences
-```
-
-Add your tabbed code to your markdown file. Example:
-
-````
-=== "Bash"
-    ``` bash
-    #!/bin/bash
-
-    echo "Hello world!"
-    ```
-
-=== "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;
-    }
-    ```
-
-=== "C#"
-    ``` c#
-    using System;
-
-    class Program {
-      static void Main(string[] args) {
-        Console.WriteLine("Hello world!");
-      }
-    }
-    ```
-````
-
-Result:
-
-=== "Bash"
-    ``` bash
-    #!/bin/bash
-
-    echo "Hello world!"
-    ```
-
-=== "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;
-    }
-    ```
-
-=== "C#"
-    ``` c#
-    using System;
-
-    class Program {
-      static void Main(string[] args) {
-        Console.WriteLine("Hello world!");
-      }
-    }
-    ```
-
-  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
-  [5]: https://facelessuser.github.io/pymdown-extensions
-
-### Highlighting specific lines
-
-Specific lines can be highlighted by passing the line numbers to the `hl_lines`
-argument placed right after the language identifier. Line counts start at 1.
-
-Example:
-
-```` markdown
-``` python hl_lines="3 4"
-""" Bubble sort """
-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" hl_lines="3 4"
-""" Bubble sort """
-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]
-```
-
-## Supported languages <small>excerpt</small>
-
-CodeHilite uses [Pygments][2], a generic syntax highlighter with support for
-over [300 languages][3], so the following list of examples is just an excerpt.
-
-### Bash
-
-``` bash
-#!/bin/bash
-
-for OPT in "$@"
-do
-  case "$OPT" in
-    '-f' )  canonicalize=1 ;;
-    '-n' )  switchlf="-n" ;;
-  esac
-done
-
-# readlink -f
-function __readlink_f {
-  target="$1"
-  while test -n "$target"; do
-    filepath="$target"
-    cd `dirname "$filepath"`
-    target=`readlink "$filepath"`
-  done
-  /bin/echo $switchlf `pwd -P`/`basename "$filepath"`
-}
-
-if [ ! "$canonicalize" ]; then
-  readlink $switchlf "$@"
-else
-  for file in "$@"
-  do
-    case "$file" in
-      -* )  ;;
-      *  )  __readlink_f "$file" ;;
-    esac
-    done
-fi
-
-exit $?
-```
-
-### C
-
-``` c
-extern size_t
-pb_varint_scan(const uint8_t data[], size_t left) {
-  assert(data && left);
-  left = left > 10 ? 10 : left;
-
-#ifdef __SSE2__
-
-  /* Mapping: remaining bytes ==> bitmask */
-  static const int mask_map[] = {
-    0x0000, 0x0001, 0x0003, 0x0007,
-    0x000F, 0x001F, 0x003F, 0x007F,
-    0x00FF, 0x01FF, 0x03FF
-  };
-
-  /* Load buffer into 128-bit integer and create high-bit mask */
-  __m128i temp = _mm_loadu_si128((const __m128i *)data);
-  __m128i high = _mm_set1_epi8(0x80);
-
-  /* Intersect and extract mask with high-bits set */
-  int mask = _mm_movemask_epi8(_mm_and_si128(temp, high));
-  mask = (mask & mask_map[left]) ^ mask_map[left];
-
-  /* Count trailing zeroes */
-  return mask ? __builtin_ctz(mask) + 1 : 0;
-
-#else
-
-  /* Linear scan */
-  size_t size = 0;
-  while (data[size++] & 0x80)
-    if (!--left)
-      return 0;
-  return size;
-
-#endif /* __SSE2__ */
-
-}
-```
-
-### C++
-
-``` cpp
-Extension::
-Extension(const Descriptor *descriptor, const Descriptor *scope) :
-    descriptor_(descriptor),
-    scope_(scope) {
-
-  /* Extract full name for signature */
-  variables_["signature"] = descriptor_->full_name();
-
-  /* Prepare message symbol */
-  variables_["message"] = StringReplace(
-    variables_["signature"], ".", "_", true);
-  LowerString(&(variables_["message"]));
-
-  /* Suffix scope to identifiers, if given */
-  string suffix ("");
-  if (scope_) {
-    suffix = scope_->full_name();
-
-    /* Check if the base and extension types are in the same package */
-    if (!scope_->file()->package().compare(descriptor_->file()->package()))
-      suffix = StripPrefixString(suffix,
-        scope_->file()->package() + ".");
-
-    /* Append to signature */
-    variables_["signature"] += ".[" + suffix +"]";
-    suffix = "_" + suffix;
-  }
-
-  /* Prepare extension symbol */
-  variables_["extension"] = StringReplace(
-    suffix, ".", "_", true);
-  LowerString(&(variables_["extension"]));
-}
-```
-
-### C&#35;
-
-``` csharp
-public static void Send(
-    Socket socket, byte[] buffer, int offset, int size, int timeout) {
-  int startTickCount = Environment.TickCount;
-  int sent = 0;
-  do {
-    if (Environment.TickCount > startTickCount + timeout)
-      throw new Exception("Timeout.");
-    try {
-      sent += socket.Send(buffer, offset + sent,
-        size - sent, SocketFlags.None);
-    } catch (SocketException ex) {
-      if (ex.SocketErrorCode == SocketError.WouldBlock ||
-          ex.SocketErrorCode == SocketError.IOPending ||
-          ex.SocketErrorCode == SocketError.NoBufferSpaceAvailable) {
-        /* Socket buffer is probably full, wait and try again */
-        Thread.Sleep(30);
-      } else {
-        throw ex;
-      }
-    }
-  } while (sent < size);
-}
-```
-
-### Clojure
-
-``` clojure
-(clojure-version)
-
-(defn partition-when
-  [f]
-  (fn [rf]
-    (let [a (java.util.ArrayList.)
-          fval (volatile! false)]
-      (fn
-        ([] (rf))
-        ([result]
-           (let [result (if (.isEmpty a)
-                          result
-                          (let [v (vec (.toArray a))]
-                            ;; Clear first
-                            (.clear a)
-                            (unreduced (rf result v))))]
-             (rf result)))
-        ([result input]
-            (if-not (and (f input)  @fval)
-               (do
-                 (vreset! fval true)
-                 (.add a input)
-                 result)
-               (let [v (vec (.toArray a))]
-                 (.clear a)
-                 (let [ret (rf result v)]
-                   (when-not (reduced? ret)
-                     (.add a input))
-                   ret))))))))
-
-
-(into [] (partition-when
-          #(.startsWith % ">>"))
-          ["1d" "33" ">> 1" ">> 2" "22" ">> 3"])
-```
-
-### Diff
-
-``` diff
-Index: grunt.js
-===================================================================
---- grunt.js	(revision 31200)
-+++ grunt.js	(working copy)
-@@ -12,6 +12,7 @@
-
- module.exports = function (grunt) {
-
-+  console.log('hello world');
-   // Project configuration.
-   grunt.initConfig({
-     lint: {
-@@ -19,10 +20,6 @@
-         'packages/services.web/{!(test)/**/,}*.js',
-         'packages/error/**/*.js'
-       ],
--      scripts: [
--        'grunt.js',
--        'db/**/*.js'
--      ],
-       browser: [
-         'packages/web/server.js',
-         'packages/web/server/**/*.js',
-```
-
-### Docker
-
-``` docker
-FROM ubuntu
-
-# Install vnc, xvfb in order to create a 'fake' display and firefox
-RUN apt-get update && apt-get install -y x11vnc xvfb firefox
-RUN mkdir ~/.vnc
-
-# Setup a password
-RUN x11vnc -storepasswd 1234 ~/.vnc/passwd
-
-# Autostart firefox (might not be the best way, but it does the trick)
-RUN bash -c 'echo "firefox" >> /.bashrc'
-
-EXPOSE 5900
-CMD ["x11vnc", "-forever", "-usepw", "-create"]
-```
-
-### Elixir
-
-``` elixir
-require Logger
-
-def accept(port) do
-  {:ok, socket} = :gen_tcp.listen(port,
-                    [:binary, packet: :line, active: false, reuseaddr: true])
-  Logger.info "Accepting connections on port #{port}"
-  loop_acceptor(socket)
-end
-
-defp loop_acceptor(socket) do
-  {:ok, client} = :gen_tcp.accept(socket)
-  serve(client)
-  loop_acceptor(socket)
-end
-
-defp serve(socket) do
-  socket
-  |> read_line()
-  |> write_line(socket)
-
-  serve(socket)
-end
-
-defp read_line(socket) do
-  {:ok, data} = :gen_tcp.recv(socket, 0)
-  data
-end
-
-defp write_line(line, socket) do
-  :gen_tcp.send(socket, line)
-end
-```
-
-### Erlang
-
-``` erlang
-circular(Defs) ->
-  [ { { Type, Base }, Fields } ||
-    { { Type, Base }, Fields } <- Defs, Type == msg, circular(Base, Defs) ].
-
-circular(Base, Defs) ->
-  Fields = proplists:get_value({ msg, Base }, Defs),
-  circular(Defs, Fields, [Base]).
-
-circular(_Defs, [], _Path) ->
-  false;
-circular(Defs, [Field | Fields], Path) ->
-  case Field#field.type of
-    { msg, Type } ->
-      case lists:member(Type, Path) of
-        false ->
-          Children = proplists:get_value({ msg, Type }, Defs),
-          case circular(Defs, Children, [Type | Path]) of
-            false -> circular(Defs, Fields, Path);
-            true  -> true
-          end;
-        true ->
-          Type == lists:last(Path) andalso
-            (length(Path) == 1 orelse not is_tree(Path))
-      end;
-    _ ->
-      circular(Defs, Fields, Path)
-  end.
-```
-
-### F&#35;
-
-``` fsharp
-/// Asynchronously download retangles from the server
-/// and decode the JSON format to F# Rectangle record
-let [<Js>] getRectangles () : Async<Rectangle[]> = async {
-  let req = XMLHttpRequest()
-  req.Open("POST", "/get", true)
-  let! resp = req.AsyncSend()
-  return JSON.parse(resp) }
-
-/// Repeatedly update rectangles after 0.5 sec
-let [<Js>] updateLoop () = async {
-  while true do
-    do! Async.Sleep(500)
-    let! rects = getRectangles()
-    cleanRectangles()
-    rects |> Array.iter createRectangle }
-```
-
-### Go
-
-``` go
-package main
-
-import "fmt"
-
-func counter(id int, channel chan int, closer bool) {
-  for i := 0; i < 10000000; i++ {
-    fmt.Println("process", id," send", i)
-    channel <- 1
-  }
-  if closer { close(channel ) }
-}
-
-func main() {
-  channel := make(chan int)
-  go counter(1, channel, false)
-  go counter(2, channel, true)
-
-  x := 0
-
-  // receiving data from channel
-  for i := range channel {
-    fmt.Println("receiving")
-    x += i
-  }
-
-  fmt.Println(x)
-}
-```
-
-### HTML
-
-``` html
-<!doctype html>
-<html class="no-js" lang="">
-  <head>
-    <meta charset="utf-8">
-    <meta http-equiv="x-ua-compatible" content="ie=edge">
-    <title>HTML5 Boilerplate</title>
-    <meta name="description" content="">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-
-    <link rel="apple-touch-icon" href="apple-touch-icon.png">
-    <link rel="stylesheet" href="css/normalize.css">
-    <link rel="stylesheet" href="css/main.css">
-    <script src="js/vendor/modernizr-2.8.3.min.js"></script>
-  </head>
-  <body>
-    <p>Hello world! This is HTML5 Boilerplate.</p>
-  </body>
-</html>
-```
-
-### Java
-
-``` java
-import java.util.LinkedList;
-import java.lang.reflect.Array;
-
-public class UnsortedHashSet<E> {
-
-  private static final double LOAD_FACTOR_LIMIT = 0.7;
-
-  private int size;
-  private LinkedList<E>[] con;
-
-  public UnsortedHashSet() {
-    con  = (LinkedList<E>[])(new LinkedList[10]);
-  }
-
-  public boolean add(E obj) {
-    int oldSize = size;
-    int index = Math.abs(obj.hashCode()) % con.length;
-    if (con[index] == null)
-      con[index] = new LinkedList<E>();
-    if (!con[index].contains(obj)) {
-      con[index].add(obj);
-      size++;
-    }
-    if (1.0 * size / con.length > LOAD_FACTOR_LIMIT)
-      resize();
-    return oldSize != size;
-  }
-
-  private void resize() {
-    UnsortedHashSet<E> temp = new UnsortedHashSet<E>();
-    temp.con = (LinkedList<E>[])(new LinkedList[con.length * 2 + 1]);
-    for (int i = 0; i < con.length; i++) {
-      if (con[i] != null)
-        for (E e : con[i])
-          temp.add(e);
-    }
-    con = temp.con;
-  }
-
-  public int size() {
-    return size;
-  }
-}
-```
-
-### JavaScript
-
-``` javascript
-var Math = require('lib/math');
-
-var _extends = function (target) {
-  for (var i = 1; i < arguments.length; i++) {
-    var source = arguments[i];
-    for (var key in source) {
-      target[key] = source[key];
-    }
-  }
-
-  return target;
-};
-
-var e = exports.e = 2.71828182846;
-exports['default'] = function (x) {
-  return Math.exp(x);
-};
-
-module.exports = _extends(exports['default'], exports);
-```
-
-### JSON
-
-``` json
-{
-  "name": "mkdocs-material",
-  "version": "0.2.4",
-  "description": "A Material Design theme for MkDocs",
-  "homepage": "http://squidfunk.github.io/mkdocs-material/",
-  "authors": [
-    "squidfunk <martin.donath@squidfunk.com>"
-  ],
-  "license": "MIT",
-  "main": "Gulpfile.js",
-  "scripts": {
-    "start": "./node_modules/.bin/gulp watch --mkdocs",
-    "build": "./node_modules/.bin/gulp build --production"
-  }
-  ...
-}
-```
-
-### Julia
-
-``` julia
-using MXNet
-
-mlp = @mx.chain mx.Variable(:data)             =>
-  mx.FullyConnected(name=:fc1, num_hidden=128) =>
-  mx.Activation(name=:relu1, act_type=:relu)   =>
-  mx.FullyConnected(name=:fc2, num_hidden=64)  =>
-  mx.Activation(name=:relu2, act_type=:relu)   =>
-  mx.FullyConnected(name=:fc3, num_hidden=10)  =>
-  mx.SoftmaxOutput(name=:softmax)
-
-# data provider
-batch_size = 100
-include(Pkg.dir("MXNet", "examples", "mnist", "mnist-data.jl"))
-train_provider, eval_provider = get_mnist_providers(batch_size)
-
-# setup model
-model = mx.FeedForward(mlp, context=mx.cpu())
-
-# optimization algorithm
-optimizer = mx.SGD(lr=0.1, momentum=0.9)
-
-# fit parameters
-mx.fit(model, optimizer, train_provider, n_epoch=20, eval_data=eval_provider)
-```
-
-### Lua
-
-``` lua
-local ffi = require("ffi")
-
-ffi.cdef[[
-  void Sleep(int ms);
-  int poll(struct pollfd *fds, unsigned long nfds, int timeout);
-]]
-
-local sleep
-if ffi.os == "Windows" then
-  function sleep(s)
-    ffi.C.Sleep(s*1000)
-  end
-else
-  function sleep(s)
-    ffi.C.poll(nil, 0, s * 1000)
-  end
-end
-
-for i = 1,160 do
-  io.write("."); io.flush()
-  sleep(0.01)
-end
-io.write("\n")
-```
-
-### MySQL
-
-``` mysql
-SELECT
-  Employees.EmployeeID,
-  Employees.Name,
-  Employees.Salary,
-  Manager.Name AS Manager
-FROM
-  Employees
-LEFT JOIN
-  Employees AS Manager
-ON
-  Employees.ManagerID = Manager.EmployeeID
-WHERE
-  Employees.EmployeeID = '087652';
-```
-
-### PHP
-
-``` php
-<?php
-
-// src/AppBundle/Controller/LuckyController.php
-namespace AppBundle\Controller;
-
-use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
-use Symfony\Component\HttpFoundation\Response;
-
-class LuckyController {
-
-  /**
-   * @Route("/lucky/number")
-   */
-  public function numberAction() {
-    $number = mt_rand(0, 100);
-
-    return new Response(
-      '<html><body>Lucky number: '.$number.'</body></html>'
-    );
-  }
-}
-```
-
-### Protocol Buffers
-
-``` proto
-syntax = "proto2";
-
-package caffe;
-
-// Specifies the shape (dimensions) of a Blob.
-message BlobShape {
-  repeated int64 dim = 1 [packed = true];
-}
-
-message BlobProto {
-  optional BlobShape shape = 7;
-  repeated float data = 5 [packed = true];
-  repeated float diff = 6 [packed = true];
-
-  // 4D dimensions -- deprecated.  Use "shape" instead.
-  optional int32 num = 1 [default = 0];
-  optional int32 channels = 2 [default = 0];
-  optional int32 height = 3 [default = 0];
-  optional int32 width = 4 [default = 0];
-}
-```
-
-### Python
-
-``` python
-
-"""
-  A very simple MNIST classifier.
-  See extensive documentation at
-  http://tensorflow.org/tutorials/mnist/beginners/index.md
-"""
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-
-# Import data
-from tensorflow.examples.tutorials.mnist import input_data
-
-import tensorflow as tf
-
-flags = tf.app.flags
-FLAGS = flags.FLAGS
-flags.DEFINE_string('data_dir', '/tmp/data/', 'Directory for storing data')
-
-mnist = input_data.read_data_sets(FLAGS.data_dir, one_hot=True)
-
-sess = tf.InteractiveSession()
-
-# Create the model
-x = tf.placeholder(tf.float32, [None, 784])
-W = tf.Variable(tf.zeros([784, 10]))
-b = tf.Variable(tf.zeros([10]))
-y = tf.nn.softmax(tf.matmul(x, W) + b)
-```
-
-### Ruby
-
-``` ruby
-require 'finity/event'
-require 'finity/machine'
-require 'finity/state'
-require 'finity/transition'
-require 'finity/version'
-
-module Finity
-  class InvalidCallback < StandardError; end
-  class MissingCallback < StandardError; end
-  class InvalidState    < StandardError; end
-
-  # Class methods to be injected into the including class upon inclusion.
-  module ClassMethods
-
-    # Instantiate a new state machine for the including class by accepting a
-    # block with state and event (and subsequent transition) definitions.
-    def finity options = {}, &block
-      @finity ||= Machine.new self, options, &block
-    end
-
-    # Return the names of all registered states.
-    def states
-      @finity.states.map { |name, _| name }
-    end
-
-    # Return the names of all registered events.
-    def events
-      @finity.events.map { |name, _| name }
-    end
-  end
-
-  # Inject methods into the including class upon inclusion.
-  def self.included base
-    base.extend ClassMethods
-  end
-end
-```
-
-### Scala
-
-```scala
-// Every record of this DataFrame contains the label and
-// features represented by a vector.
-val df = sqlContext.createDataFrame(data).toDF("label", "features")
-
-// Set parameters for the algorithm.
-// Here, we limit the number of iterations to 10.
-val lr = new LogisticRegression().setMaxIter(10)
-
-// Fit the model to the data.
-val model = lr.fit(df)
-
-// Inspect the model: get the feature weights.
-val weights = model.weights
-
-// Given a dataset, predict each point's label, and show the results.
-model.transform(df).show()g
-```
-
-### XML
-
-``` xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE mainTag SYSTEM "some.dtd" [ENTITY % entity]>
-<?oxygen RNGSchema="some.rng" type="xml"?>
-<xs:main-Tag xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <!-- This is a sample comment -->
-  <childTag attribute="Quoted Value" another-attribute='Single quoted value'
-      a-third-attribute='123'>
-    <withTextContent>Some text content</withTextContent>
-    <withEntityContent>Some text content with &lt;entities&gt; and
-      mentioning uint8_t and int32_t</withEntityContent>
-    <otherTag attribute='Single quoted Value'/>
-  </childTag>
-  <![CDATA[ some CData ]]>
-</main-Tag>
-```

docs/extensions/footnotes.md

@@ -1,89 +0,0 @@
----
-template: overrides/main.html
----
-
-# Footnotes
-
-[Footnotes][1] is another extension included in the standard Markdown library.
-As the name says, it adds the ability to add inline footnotes to your
-documentation.
-
-  [1]: https://python-markdown.github.io/extensions/footnotes/
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - footnotes
-```
-
-## Usage
-
-The markup for footnotes is similar to the standard Markdown markup for links.
-A reference is inserted in the text, which can then be defined at any point in
-the document.
-
-### Inserting the reference
-
-The footnote reference is enclosed in square brackets and starts with a caret,
-followed by an arbitrary label which may contain numeric identifiers [1, 2, 3,
-...] or names [Granovetter et al. 1998]. The rendered references are always
-consecutive superscripted numbers.
-
-Example:
-
-``` markdown
-Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
-```
-
-Result:
-
-Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
-
-### Inserting the content
-
-The footnote content is also declared with a label, which must match the label
-used for the footnote reference. It can be inserted at an arbitrary position in
-the document and is always rendered at the bottom of the page. Furthermore, a
-backlink is automatically added to the footnote reference.
-
-#### on a single line
-
-Short statements can be written on the same line.
-
-Example:
-
-``` markdown
-[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-```
-
-Result:
-
-<a href="#fn:1">Jump to footnote at the bottom of the page</a>
-
-  [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-
-#### on multiple lines
-
-Paragraphs should be written on the next line. As with all Markdown blocks, the
-content must be indented by four spaces.
-
-Example:
-
-``` markdown
-[^2]:
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
-    massa, nec semper lorem quam in massa.
-```
-
-Result:
-
-  [^2]:
-      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-      nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
-      auctor massa, nec semper lorem quam in massa.
-
-<a href="#fn:2">Jump to footnote at the bottom of the page</a>

docs/extensions/permalinks.md

@@ -1,37 +0,0 @@
----
-template: overrides/main.html
----
-
-# Permalinks
-
-Permalinks are a feature of the [Table of Contents][1] extension, which is part
-of the standard Markdown library. The extension inserts an anchor at the end of
-each headline, which makes it possible to directly link to a specific section
-of the document.
-
-  [1]: https://python-markdown.github.io/extensions/toc/
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - toc:
-      permalink: true
-```
-
-This will add a link containing the paragraph 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. In order to change the text of the
-permalink, a string can be passed, e.g.:
-
-``` yaml
-markdown_extensions:
-  - toc:
-      permalink: Link
-```
-
-## Usage
-
-When enabled, permalinks are inserted automatically.

docs/extensions/pymdown.md

@@ -1,375 +0,0 @@
----
-template: overrides/main.html
----
-
-# PyMdown Extensions
-
-[PyMdown Extensions][1] is a collection of Markdown extensions that add some
-great missing features to the standard Markdown library. A compatible version
-is always included with the theme.
-
-  [1]: https://facelessuser.github.io/pymdown-extensions/
-
-## Configuration
-
-The following list of extensions that are part of the PyMdown Extensions
-package are recommended to be used together with Material for MkDocs:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.arithmatex
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.critic
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
-  - pymdownx.inlinehilite
-  - pymdownx.magiclink
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.superfences
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tabbed
-  - pymdownx.tilde
-```
-
-## Usage
-
-### Arithmatex <small>MathJax</small>
-
-<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML"></script>
-
-[Arithmatex][2] integrates Material for MkDocs with [MathJax][3] which parses
-block-style and inline equations written in TeX markup and outputs them in
-mathematical notation. See [this thread][4] for a short introduction and quick
-reference on how to write equations in TeX syntax.
-
-Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript
-runtime needs to be included. This can be done with [additional JavaScript][5]:
-
-``` yaml
-extra_javascript:
-  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
-```
-
-If you want to override the default MathJax configuration, you can do this by
-adding another JavaScript file **before** the MathJax runtime which contains
-the MathJax configuration, e.g.:
-
-``` js
-window.MathJax = {
-  tex2jax: {
-    inlineMath: [ ["\\(","\\)"] ],
-    displayMath: [ ["\\[","\\]"] ]
-  },
-  TeX: {
-    TagSide: "right",
-    TagIndent: ".8em",
-    MultLineWidth: "85%",
-    equationNumbers: {
-      autoNumber: "AMS",
-    },
-    unicode: {
-      fonts: "STIXGeneral,'Arial Unicode MS'"
-    }
-  },
-  displayAlign: "left",
-  showProcessingMessages: false,
-  messageStyle: "none"
-};
-```
-
-Then, add the following lines to `mkdocs.yml`:
-
-``` yaml
-extra_javascript:
-  - javascripts/extra.js
-  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
-```
-
-  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
-  [3]: https://www.mathjax.org/
-  [4]: https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference
-  [5]: ../customization.md#additional-javascript
-
-#### Blocks
-
-Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines.
-
-Example:
-
-``` tex
-$$
-\frac{n!}{k!(n-k)!} = \binom{n}{k}
-$$
-```
-
-Result:
-
-$$
-\frac{n!}{k!(n-k)!} = \binom{n}{k}
-$$
-
-#### Inline
-
-Inline equations must be enclosed in `:::tex $...$`:
-
-Example:
-
-``` tex
-Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
-```
-
-Result:
-
-Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
-
-### BetterEm
-
-[BetterEm][6] improves the handling of emphasis markup (**bold** and *italic*)
-within Markdown by providing a more sophisticated parser for better detecting
-start and end tokens. Read the documentation for [usage notes][7].
-
-  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
-  [7]: https://facelessuser.github.io/pymdown-extensions/usage_notes/
-
-### Caret
-
-[Caret][8] makes it possible to highlight ^^inserted text^^. The portion of
-text that should be marked as added must be enclosed in two carets `^^...^^`.
-
-  [8]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
-
-### Critic
-
-[Critic][9] implements [Critic Markup][10], a Markdown extension that enables
-the tracking of changes (additions, deletions and comments) on documents.
-During compilation of the Markdown document, changes can be rendered (default),
-accepted or rejected.
-
-Text can be {--deleted--} and replacement text {++added++}. This can also be
-combined into {~~one~>a single~~} operation. {==Highlighting==} is also
-possible {>>and comments can be added inline<<}.
-
-{==
-
-Formatting can also be applied to blocks, by putting the opening and closing
-tags on separate lines and adding new lines between the tags and the content.
-
-==}
-
-  [9]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
-  [10]: http://criticmarkup.com/
-
-### Details
-
-[Details][11] adds [collapsible Admonition blocks][12] which can contain
-arbitrary content using the HTML5 `details` and `summary` tags. Additionally,
-all Admonition qualifiers can be used, e.g. `note`, `question`, `warning` etc.:
-
-??? question "How many Prolog programmers does it take to change a lightbulb?"
-
-    Yes.
-
-  [11]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
-  [12]: ../admonition/#collapsible-blocks
-
-### Emoji :tada:
-
-[Emoji][13] adds the ability to insert, well, emojis! :smile:
-
-By default, [Emoji][13] uses JoyPixles' emoji under the former name EmojiOne.
-Recent versions of the extension lock support to an older version (2.2.7) due
-to JoyPixels' newer, less permissible licenses included in later releases. This
-restricts support to Unicode 9. To get the latest support for the current
-Unicode version, you can use Twemoji instead which has a much more permissible
-license. Simply override the default emoji index being used:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.emoji:
-      emoji_index: !!python/name:pymdownx.emoji.twemoji
-      emoji_generator: !!python/name:pymdownx.emoji.to_svg
-```
-
-To view all the available short names and emoji available, see
-[Emoji's documentation][18] on your chosen index which includes links to the
-files containing the short names and emoji associated with each supported
-index.
-
-!!! warning "Legal disclaimer"
-
-    Material has no affiliation with [JoyPixles][15] or [Twemoji][14], both
-    of which are licensed under [CC BY 4.0][16]. When including images or CSS
-    from either provider, please read their licenses to ensure proper
-    attribution: [EmojiOne][17] or [Twemoji][14].
-
-### Icons :hatching_chick:
-
-In addition, you can embed the Material Design icons, Fontawesome icons and
-GitHub's Octicons directly from Markdown by using [Material for MkDocs's custom
-emoji index][19]. It extends the Twemoji index with new short names that access
-any of the included icons. To use the custom index, you need to use
-`materialx.emoji` instead of `pymdownx.emoji`:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
-```
-
-Example:
-
-``` markdown
-* :material-account-circle: – we can use Material Design icons
-* :fontawesome-regular-laugh-wink: – we can also use FontAwesome icons
-* :octicons-octoface-16: – that's not all, we can also use GitHub's Octicons
-```
-
-Result:
-
-* :material-account-circle: – we can use [Material Design icons][20]
-* :fontawesome-regular-laugh-wink: – we can also use [FontAwesome icons][21]
-* :octicons-octoface-16: – that's not all, we can also use [GitHub's Octicons][22]
-
-  [13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
-  [14]: https://twemoji.twitter.com/
-  [15]: https://www.joypixels.com/
-  [16]: https://creativecommons.org/licenses/by/4.0/legalcode
-  [17]: https://github.com/joypixels/emojione#emojione-version-2
-  [18]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
-  [19]: https://github.com/facelessuser/mkdocs-material-extensions
-  [20]: https://material.io/resources/icons/
-  [21]: https://fontawesome.com/icons?d=gallery&m=free
-  [22]: https://octicons.github.com/
-
-### InlineHilite
-
-[InlineHilite][23] adds support for inline code highlighting. It's useful for
-short snippets included within body copy, e.g. `#!js var test = 0;` and can be
-activated by prefixing inline code with a shebang and language identifier,
-e.g. `#!js`.
-
-  [23]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
-
-### MagicLink
-
-[MagicLink][24] detects links in Markdown and auto-generates the necessary
-markup, so no special syntax is required. It auto-links `http[s]://` and
-`ftp://` links, as well as references to email addresses.
-
-  [24]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
-
-### Mark
-
-[Mark][25] adds the ability to ==highlight text== like it was marked with a
-==text marker==. The portion of text that should be highlighted must be
-enclosed in two equal signs `==...==`.
-
-  [25]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
-
-### SmartSymbols
-
-[SmartSymbols][26] converts markup for special characters into their
-corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
-symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
-
-  [26]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
-
-### SuperFences
-
-[SuperFences][27] provides the ability to nest code blocks under blockquotes,
-lists and other block elements, which the [Fenced Code Blocks][28] extension
-from the standard Markdown library doesn't parse correctly.
-
-SuperFences does also allow [grouping code blocks with tabs][29].
-
-  [27]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-  [28]: https://python-markdown.github.io/extensions/fenced_code_blocks/
-  [29]: codehilite.md#grouping-code-blocks
-
-### Tabbed
-
-[Tabbed][30] adds support for creating tabbed groups of Markdown content.
-
-Example:
-
-``` markdown
-=== "Fruit List"
-    - :apple: Apple
-    - :banana: Banana
-    - :kiwi: Kiwi
-
-=== "Fruit Table"
-    Fruit           | Color
-    --------------- | -----
-    :apple:  Apple  | Red
-    :banana: Banana | Yellow
-    :kiwi:   Kiwi   | Green
-```
-
-Result:
-
-=== "Fruit List"
-    - :apple: Apple
-    - :banana: Banana
-    - :kiwi: Kiwi
-
-=== "Fruit Table"
-    Fruit           | Color
-    --------------- | -----
-    :apple:  Apple  | Red
-    :banana: Banana | Yellow
-    :kiwi:   Kiwi   | Green
-
-[30]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
-
-### Tasklist
-
-[Tasklist][31] adds support for styled checkbox lists. This is useful for
-keeping track of tasks and showing what has been done and has yet to be done.
-Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or
-`[x]` for filled checkboxes.
-
-Example:
-
-``` markdown
-* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
-* [x] Nulla lobortis egestas semper
-* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
-* [ ] Vestibulum convallis sit amet nisi a tincidunt
-    * [x] In hac habitasse platea dictumst
-    * [x] In scelerisque nibh non dolor mollis congue sed et metus
-    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
-    * [ ] Praesent sed risus massa
-* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
-* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
-```
-
-Result:
-
-* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
-* [x] Nulla lobortis egestas semper
-* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
-* [ ] Vestibulum convallis sit amet nisi a tincidunt
-    * [x] In hac habitasse platea dictumst
-    * [x] In scelerisque nibh non dolor mollis congue sed et metus
-    * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
-    * [ ] Praesent sed risus massa
-* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
-* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
-
-[31]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
-
-### Tilde
-
-[Tilde][32] provides an easy way to ~~strike through~~ cross out text.
-The portion of text that should be erased must be enclosed in two tildes
-`~~...~~` and the extension will take care of the rest.
-
-[32]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/

docs/getting-started.md

@@ -4,64 +4,55 @@ template: overrides/main.html
 
 # Getting started
 
+Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
+towards (technical) project documentation. If you're familar with Python, you
+can install Material for MkDocs with [`pip`][2], the Python package manager.
+If not, we recommended using [`docker`][3].
+
+In case you're running into problems, consult the [troubleshooting][4] section.
+
+  [1]: https://www.mkdocs.org
+  [2]: #with-pip
+  [3]: #with-docker
+  [4]: troubleshooting.md
+
 ## Installation
 
-While there are several ways of installing Material for MkDocs, the recommended
+### with pip
-methods are either by using `pip` – the Python package manager – or by pulling
-the [official Docker image][1].
-
-  [1]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-
-### with pip <small>recommended</small>
 
 Material for MkDocs can be installed with `pip`:
 
+=== "Community edition"
+
     ``` sh
     pip install mkdocs-material
     ```
 
-Note that this will automatically install compatible versions of [MkDocs][2],
+=== "Sponsor edition"
-[Markdown][3], [Pygments][4] and [PyMdown Extensions][5]. Material for MkDocs
-always strives to support the latest versions, so there's no need to install
-those packages separately.
 
-!!! tip "Installation in a virtual environment"
+    ``` sh
+    pip install git+https://$GH_TOKEN@github.com/squidfunk/mkdocs-material-next.git
+    ```
 
-    The best way to make sure that you end up with the correct versions and
+This will automatically install compatible versions of all dependencies:
-    without any incompatibility problems between packages it to use a **virtual
+[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
-    environment**. Don't know what this is or how to set it up? We recommend
+Material for MkDocs always strives to support the latest versions, so there's
-    to start by reading a [tutorial on virtual environments][6] for Python.
+no need to install those packages separately.
 
-!!! warning "Installation on macOS"
+Note that in order to install the [sponsor edition][8], you'll need to [become
+a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN`
+environment variable to the token's value.
 
-    When you're running the pre-installed version of Python on macOS, `pip`
+  [5]: https://python-markdown.github.io/
-    tries to install packages in a folder for which your user might not have
+  [6]: https://pygments.org/
-    the adequate permissions. There are two possible solutions for this:
+  [7]: https://facelessuser.github.io/pymdown-extensions/
+  [8]: sponsorship.md
+  [9]: sponsorship.md#how-to-become-a-sponsor
+  [10]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
 
-    1. **Installing in user space** (recommended): Provide the `--user` flag
+### with docker
-      to the install command and `pip` will install the package in a user-site
-      location. This is the recommended way.
 
-    2. **Switching to a homebrewed Python**: Upgrade your Python installation
+The official [Docker image][11] is a great way to get up and running in a few
-      to a self-contained solution by installing Python with Homebrew. This
-      should eliminate a lot of problems you could be having with `pip`.
-
-!!! failure "Error: unrecognized theme 'material'"
-
-    If you run into this error, the most common reason is that you installed
-    MkDocs through some package manager (e.g. Homebrew 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.
-
-  [2]: https://www.mkdocs.org
-  [3]: https://python-markdown.github.io/
-  [4]: https://pygments.org/
-  [5]: https://facelessuser.github.io/pymdown-extensions/
-  [6]: https://docs.python-guide.org/dev/virtualenvs/
-
-### with docker <small>recommended</small>
-
-The official [Docker image][7] is a great way to get up and running in a few
 minutes, as it comes with all dependencies pre-installed. Pull the image for the 
 `latest` version with:
 
@@ -69,726 +60,35 @@ minutes, as it comes with all dependencies pre-installed. Pull the image for the
 docker pull squidfunk/mkdocs-material
 ```
 
-The `mkdocs` executable is provided as an entry point and `serve` is the default
+The `mkdocs` executable is provided as an entry point and `serve` is the 
-command. Start the development server in your project root – the folder where
+default command. If you're not familar with Docker don't worry, we have you
-`mkdocs.yml` resides — with:
+covered in the following sections.
 
-=== "Unix"
+  [11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-
-    ```
-    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
-    ```
-
-  [7]: https://hub.docker.com/r/squidfunk/mkdocs-material/
 
 ### with git
 
-Material for MkDocs can be directly used from [GitHub][8] by cloning the
+Material for MkDocs can be directly used from [GitHub][12] by cloning the
 repository into a subfolder of your project root which might be useful if you
 want to use the very latest version:
 
+=== "Community edition"
+
     ``` sh
     git clone https://github.com/squidfunk/mkdocs-material.git
     ```
 
-The theme will reside in the folder `mkdocs-material/material`.
+=== "Sponsor edition"
-
-  [8]: https://github.com/squidfunk/mkdocs-material
-
-## Configuration
-
-Depending on your installation method, you can now add the following lines to
-`mkdocs.yml` in your project root. If you installed Material for MkDocs using
-a package manager, add:
-
-``` yaml
-theme:
-  name: material
-```
-
-If you cloned Material for MkDocs from GitHub add:
-
-``` yaml
-theme:
-  name: null
-  custom_dir: mkdocs-material/material
-```
-
-MkDocs includes a development server, so you can preview your changes as you
-write your documentation. The development server can be started with the
-following command:
 
     ``` sh
-mkdocs serve
+    git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material
     ```
 
-Point your browser to http://localhost:8000 and your documentation should greet
+The theme will reside in the folder `mkdocs-material/material`. Note that when
-you in a new look. If you're starting from scratch, the following configuration
+cloning from `git`, you must install all required dependencies yourself:
-can be used as a starting point:
 
-??? summary "Example configuration"
+``` sh
-
+pip install -r mkdocs-material/requirements.txt
-    This is an excerpt from the [`mkdocs.yml`][9] used to render these pages:
-
-    ``` yaml
-    # Project information
-    site_name: Material for MkDocs
-    site_description: A Material Design theme for MkDocs
-    site_author: Martin Donath
-    site_url: https://squidfunk.github.io/mkdocs-material/
-
-    # Repository
-    repo_name: squidfunk/mkdocs-material
-    repo_url: https://github.com/squidfunk/mkdocs-material
-
-    # Copyright
-    copyright: Copyright &copy; 2016 - 2020 Martin Donath
-
-    # Configuration
-    theme:
-      name: material
-      language: en
-      palette:
-        primary: indigo
-        accent: indigo
-      font:
-        text: Roboto
-        code: Roboto Mono
-
-    # Extras
-    extra:
-      social:
-        - icon: fontawesome/brands/github-alt
-          link: https://github.com/squidfunk
-        - icon: fontawesome/brands/twitter
-          link: https://twitter.com/squidfunk
-        - icon: fontawesome/brands/linkedin
-          link: https://linkedin.com/in/squidfunk
-
-    # Google Analytics
-    google_analytics:
-      - UA-XXXXXXXX-X
-      - auto
-
-    # Extensions
-    markdown_extensions:
-      - admonition
-      - codehilite:
-          guess_lang: false
-      - toc:
-          permalink: true
 ```
 
-[9]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
+  [12]: https://github.com/squidfunk/mkdocs-material
-
-### Feature flags
-
-These optional features are hidden behind flags and can be explicitly enabled
-in `mkdocs.yml`.
-
-#### Instant loading :hatching_chick:
-
-The (still experimental) *instant loading* feature will intercept clicks on all 
-internal links and dispatch them directly via XHR without a full page reload.
-It can be enabled from `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.
-
-#### Tabs
-
-The *tabs* feature will render *top-level subsections* in another navigational
-layer below the header on big screens (but leave them untouched on mobile). It
-can be enabled from `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` 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, as each subsection is rendered as another tab. If you want more
-fine-grained control, i.e.,  collapsible subsections for the first tab, you can
-move all *top-level pages into a subsection*, so that the top-level is entirely
-made up of subsections. Note that tabs are only shown for larger screens, so
-make sure that navigation is plausible on mobile devices.
-
-As an example, see the [`mkdocs.yml`][9] used to render these pages.
-
-### Language
-
-> Default: `en`
-
-Material for MkDocs supports internationalization (i18n) and provides
-translations for all template variables and labels. You can set the language
-from `mkdocs.yml` with:
-
-``` yaml
-theme:
-  language: en
-```
-
-The following language codes are supported:
-
-<style>
-  .md-language-list {
-    -webkit-columns: 2;
-       -moz-columns: 2;
-            columns: 2;
-  }
-  .md-language-list li {
-    -webkit-column-break-inside: avoid;
-              page-break-inside: avoid;
-                   break-inside: avoid;
-  }
-</style>
-<ul class="md-language-list">
-  <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>
-
-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: rtl
-```
-
-### Color scheme
-
-> 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 from `mkdocs.yml`:
-
-``` yaml
-theme:
-  palette:
-    scheme: slate
-```
-
-Click on a color name to change the color scheme of the theme:
-
-<style>
-  .md-typeset button[data-md-color-scheme] {
-    cursor: pointer;
-    transition: opacity 250ms;
-  }
-  .md-typeset button[data-md-color-scheme]:hover {
-    opacity: 0.75;
-  }
-  .md-typeset button[data-md-color-scheme] > code {
-    display: block;
-    color: var(--md-primary-bg-color);
-    background-color: var(--md-primary-fg-color);
-  }
-</style>
-
-<button data-md-color-scheme="default"><code>default</code></button>
-<button data-md-color-scheme="slate"><code>slate</code></button>
-
-<script>
-  var buttons = document.querySelectorAll("button[data-md-color-scheme]")
-  buttons.forEach(function(button) {
-    var attr = "data-md-color-scheme"
-    button.addEventListener("click", function() {
-      document.body.setAttribute(attr, this.getAttribute(attr))
-    })
-  })
-</script>
-
-The color scheme can also be set based on _user preference_, which makes use of
-the `prefers-color-scheme` media query. This can be done by adding the following
-to `mkdocs.yml`:
-
-``` yaml
-theme:
-  palette:
-    scheme: preference
-```
-
-### Color palette
-
-The Material Design [color palette][10] comes with 20 hues, all of which are
-included with Material for MkDocs. Primary and accent colors can be set from
-the project root's `mkdocs.yml`:
-
-``` yaml
-theme:
-  palette:
-    primary: indigo
-    accent: indigo
-```
-
-If the colors are set with these configuration options, an additional CSS file
-that includes the hues of the color palette is automatically included and linked
-from the template.
-
-??? tip "Custom colors with CSS variables"
-
-    Material for MkDocs defines all colors as CSS variables. If you want to
-    customize the colors beyond the palette (e.g. to use your brand's colors),
-    you can add an [additional stylesheet][11] and override the defaults:
-
-    ``` css
-    :root {
-
-      /* Default color shades */
-      --md-default-fg-color:               ...;
-      --md-default-fg-color--light:        ...;
-      --md-default-fg-color--lighter:      ...;
-      --md-default-fg-color--lightest:     ...;
-      --md-default-bg-color:               ...;
-      --md-default-bg-color--light:        ...;
-      --md-default-bg-color--lighter:      ...;
-      --md-default-bg-color--lightest:     ...;
-
-      /* Primary color shades */
-      --md-primary-fg-color:               ...;
-      --md-primary-fg-color--light:        ...;
-      --md-primary-fg-color--dark:         ...;
-      --md-primary-bg-color:               ...;
-      --md-primary-bg-color--light:        ...;
-
-      /* Accent color shades */
-      --md-accent-fg-color:                ...;
-      --md-accent-fg-color--transparent:   ...;
-      --md-accent-bg-color:                ...;
-      --md-accent-bg-color--light:         ...;
-    }
-
-    :root > * {
-
-      /* Code block color shades */
-      --md-code-bg-color:                  ...;
-      --md-code-fg-color:                  ...;
-    }
-    ```
-
-  [10]: http://www.materialui.co/colors
-  [11]: customization.md#additional-stylesheets
-
-#### Primary color
-
-> Default: `indigo`
-
-Click on a color name to change the primary color of the theme:
-
-<style>
-  .md-typeset button[data-md-color-primary] {
-    cursor: pointer;
-    transition: opacity 250ms;
-  }
-  .md-typeset button[data-md-color-primary]:hover {
-    opacity: 0.75;
-  }
-  .md-typeset button[data-md-color-primary] > code {
-    display: block;
-    color: var(--md-primary-bg-color);
-    background-color: var(--md-primary-fg-color);
-  }
-</style>
-
-<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>
-
-<script>
-  var buttons = document.querySelectorAll("button[data-md-color-primary]")
-  buttons.forEach(function(button) {
-    var attr = "data-md-color-primary"
-    button.addEventListener("click", function() {
-      document.body.setAttribute(attr, this.getAttribute(attr))
-    })
-  })
-</script>
-
-#### Accent color
-
-> Default: `indigo`
-
-Click on a color name to change the accent color of the theme:
-
-<style>
-  .md-typeset button[data-md-color-accent] {
-    cursor: pointer;
-    transition: opacity 250ms;
-  }
-  .md-typeset button[data-md-color-accent]:hover {
-    opacity: 0.75;
-  }
-  .md-typeset button[data-md-color-accent] > code {
-    display: block;
-    color: var(--md-accent-fg-color);
-  }
-</style>
-
-<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>
-
-<script>
-  var buttons = document.querySelectorAll("button[data-md-color-accent]")
-  buttons.forEach(function(button) {
-    var attr = "data-md-color-accent"
-    button.addEventListener("click", function() {
-      document.body.setAttribute(attr, this.getAttribute(attr))
-    })
-  })
-</script>
-
-### Fonts
-
-> Default: `Roboto` and `Roboto Mono`
-
-The [Roboto font family][12] is the default font included with the theme,
-specifically the regular sans-serif type for text and the `monospaced` type for
-code. Both fonts are loaded from [Google Fonts][13] and can be changed to any
-valid webfont, like for example the [Ubuntu font family][14]:
-
-``` yaml
-theme:
-  font:
-    text: Ubuntu
-    code: Ubuntu Mono
-```
-
-The text font will be loaded in weights 400 and **700**, the `monospaced` font
-in regular weight. If you want to load fonts from other destinations or don't
-want to use Google Fonts for data privacy reasons, just set `font` to `false`:
-
-``` yaml
-theme:
-  font: false
-```
-
-  [12]: https://fonts.google.com/specimen/Roboto
-  [13]: https://fonts.google.com
-  [14]: https://fonts.google.com/specimen/Ubuntu
-
-### Icons
-
-> Default: `material/library` and `fontawesome/brands/git-alt`
-
-Material for MkDocs uses icons in several places. Currently, the following icons
-can be changed from `mkdocs.yml`: the logo icon, the repository icon and the
-[social link icons][15]. While the social link icons are tied to the respective
-entries, the other icons can be changed by referencing a valid path (without the 
-trailing `.svg`) relative to the `.icons` folder which comes with the theme:
-
-``` yaml
-theme:
-  icon:
-    logo: material/library
-    repo: fontawesome/brands/git-alt
-```
-
-All icons are directly inlined as `*.svg` files, so no further requests will be
-made. Icon sets which are bundled with Material for MkDocs:
-
-* [Material Design icons][16] (`material`): 5.1k icons
-* [FontAwesome icons][17] (`fontawesome`): 1.6k icons
-* [GitHub's Octicons][18] (`octicons`): 200 icons
-
-__You can use all those icons [directly from :fontawesome-brands-markdown:
-Markdown][19]!__
-
-  [15]: #adding-social-links
-  [16]: https://materialdesignicons.com/
-  [17]: https://fontawesome.com/icons?d=gallery&m=free
-  [18]: https://octicons.github.com/
-  [19]: extensions/pymdown.md#icons
-
-### Logo
-
-> Default: icon set through `theme.icon.logo`
-
-If you want to replace the icon in the header (screen) and drawer (mobile)
-with your brand's logo, you can place an image file in your `docs` folder
-and use the following option in `mkdocs.yml`:
-
-``` yaml
-theme:
-  logo: images/logo.svg
-```
-
-Ideally, the image should be a square with a minimum resolution of 96x96, leave
-some room towards the edges and be composed of high contrast areas on a
-transparent ground, as it will be placed on the colored header and drawer.
-
-### Favicon
-
-> Default: `assets/images/favicon.png`
-
-The default favicon can be changed with:
-
-``` yaml
-theme:
-  favicon: images/favicon.png
-```
-
-## Extras
-
-### Adding a source repository
-
-To include a link to the repository of your project within your documentation,
-set the following variables via your project's `mkdocs.yml`:
-
-``` yaml
-repo_name: squidfunk/mkdocs-material
-repo_url: https://github.com/squidfunk/mkdocs-material
-```
-
-The name of 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 shown.
-Note that the repository icon can be explicitly set through `theme.icon.repo`.
-
-!!! question "Why is there an edit button at the top of every article?"
-
-    If the `repo_url` is set to a GitHub or BitBucket repository, and the
-    `repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
-    edit button will appear at the top of every article. This is the automatic
-    behavior that MkDocs implements. See the [MkDocs documentation][20] on more
-    guidance regarding the `edit_uri` attribute, which defines whether the edit
-    button is shown or not.
-
-  [20]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
-
-### Adding social links
-
-Social accounts can be linked in the footer of the documentation using the
-[icons][21] which are bundled with the theme. Note that each `icon` must point
-to a valid path (without the trailing `.svg`) relative to the `.icons` folder
-which comes with the theme:
-
-``` yaml
-extra:
-  social:
-    - icon: fontawesome/brands/github-alt
-      link: https://github.com/squidfunk
-    - icon: fontawesome/brands/twitter
-      link: https://twitter.com/squidfunk
-    - icon: fontawesome/brands/linkedin
-      link: https://linkedin.com/in/squidfunk
-```
-
-By default, the link `title` will be set to the domain name, e.g. _github.com_.
-If you want to set a discernable name, e.g., to improve your Lighthouse score,
-you can set the `name` attribute on each social link.
-
-  [21]: #icons
-
-### Adding a Web App Manifest
-
-A [Web App Manifest][22] is a simple JSON file that tells the browser about your
-web application and how it should behave when installed on the user's mobile
-device or desktop. You can specify such a manifest in `mkdocs.yml`:
-
-``` yaml
-extra:
-  manifest: manifest.webmanifest
-```
-
-  [22]: https://developers.google.com/web/fundamentals/web-app-manifest/
-
-## Integrations
-
-### Google Analytics
-
-MkDocs makes it easy to integrate site tracking with Google Analytics. To enable
-tracking, which is disabled by default, you must add your tracking identifier
-to `mkdocs.yml`:
-
-``` yaml
-google_analytics:
-  - UA-XXXXXXXX-X
-  - auto
-```
-
-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`.
-
-### Disqus
-
-Material for MkDocs is integrated with [Disqus][23], so if you want to add a
-comments section to your documentation set the *shortname* of your Disqus
-project in `mkdocs.yml`:
-
-``` yaml
-extra:
-  disqus: your-shortname
-```
-
-The comments section is inserted on *every page, except the index page*. The 
-necessary JavaScript is automatically included.
-
-!!! warning "Requirements"
-
-    Note that `site_url` must be set in `mkdocs.yml` for the Disqus integration
-    to load properly.
-
-Disqus can also be enabled or disabled for specific pages using [Metadata][24].
-
-  [23]: https://disqus.com
-  [24]: extensions/metadata.md#disqus
-
-## Extensions
-
-[Markdown][3] comes with several very useful extensions, the following of which
-are not enabled by default but highly recommended, so enabling them should
-definitely be a good idea:
-
-``` yaml
-markdown_extensions:
-  - admonition
-  - codehilite:
-      guess_lang: false
-  - toc:
-      permalink: true
-```
-
-See the following list of extensions supported by Material for MkDocs including
-some more information on configuration and usage:
-
-* [Admonition][25]
-* [Codehilite][26]
-* [Footnotes][27]
-* [Metadata][28]
-* [Permalinks][29]
-* [PyMdown Extensions][30]
-
-  [25]: extensions/admonition.md
-  [26]: extensions/codehilite.md
-  [27]: extensions/footnotes.md
-  [28]: extensions/metadata.md
-  [29]: extensions/permalinks.md
-  [30]: extensions/pymdown.md
-
-## Plugins
-
-MkDocs' plugin architecture makes it possible to add pre- or post-processing
-steps that sit between the theme and your documentation. For more information,
-see the following list of plugins tested and supported by Material for MkDocs 
-including more information regarding installation and usage:
-
-* [Search][31] (enabled by default)
-* [Minification][32]
-* [Revision date][33]
-* [Awesome pages][34]
-
-For further reference, the MkDocs wiki contains a list of all
-[available plugins][35].
-
-  [31]: plugins/search.md
-  [32]: plugins/minification.md
-  [33]: plugins/revision-date.md
-  [34]: plugins/awesome-pages.md
-  [35]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

docs/license.md

@@ -6,22 +6,4 @@ template: overrides/main.html
 
 **MIT License**
 
-Copyright © 2016 - 2020 Martin Donath
+--8<-- "LICENSE"
-
-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.

docs/plugins/awesome-pages.md

@@ -1,80 +0,0 @@
----
-template: overrides/main.html
----
-
-# Awesome pages
-
-The [mkdocs-awesome-pages-plugin][1] omits the need to specify all pages in the
-`nav` entry of `mkdocs.yml` and gives you control over page visibility, titles
-and order on a directory level.
-
-!!! success "Bundled with the official Docker image"
-
-    This plugin is already installed for your convenience when you use the
-    official [Docker image][2], so the installation step can be skipped. Read
-    the [getting started guide][3] to get up and running with Docker.
-
-  [1]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
-  [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [3]: ../getting-started.md#with-docker-recommended
-
-## Installation
-
-Install the plugin using `pip`:
-
-``` sh
-pip install mkdocs-awesome-pages-plugin
-```
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search # necessary for search to work
-  - awesome-pages
-```
-
-## Usage
-
-If the `nav` entry in `mkdocs.yml` is omitted, MkDocs will automatically include
-all pages in a specific order. This plugin allows for more fine-grained control
-on a per-directory basis. In order to configure behavior for a specific
-directory, create a YAML file named `.pages` in it and set one of the following
-options.
-
-### Setting a directory title
-
-The directory title, which is shown as part of the navigation, can be set with:
-
-``` yaml
-title: Lorem ipsum dolor sit amet
-```
-
-### Changing the order of pages
-
-The order of pages and subsections can be configured with:
-
-``` yaml
-arrange:
-  - page-1.md
-  - page-2.md
-  - subdirectory
-```
-
-### Excluding a directory
-
-A directory can be hidden (i.e. excluded) with:
-
-``` yaml
-hide: true
-```
-
-### Collapsing single-page directories
-
-Directories which contain a single page can be collapsed with:
-
-``` yaml
-collapse: true
-```

docs/plugins/minification.md

@@ -1,42 +0,0 @@
----
-template: overrides/main.html
----
-
-# Minification 
-
-The [mkdocs-minify-plugin][1] will minify all `*.html` files generated by
-`mkdocs build` in a post-processing step, stripping all unnecessary characters
-to reduce the payload served to the client.
-
-!!! success "Bundled with the official Docker image"
-
-    This plugin is already installed for your convenience when you use the
-    official [Docker image][2], so the installation step can be skipped. Read
-    the [getting started guide][3] to get up and running with Docker.
-
-  [1]: https://github.com/byrnereese/mkdocs-minify-plugin
-  [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [3]: ../getting-started.md#with-docker-recommended
-
-## Installation
-
-Install the plugin using `pip`:
-
-``` sh
-pip install mkdocs-minify-plugin
-```
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search # necessary for search to work
-  - minify:
-      minify_html: true
-```
-
-## Usage
-
-When enabled, all `*.html` will be minified automatically.

docs/plugins/revision-date.md

@@ -1,85 +0,0 @@
----
-template: overrides/main.html
----
-
-# Revision date
-
-The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a
-Markdown file was last updated at the bottom of each page.
-
-!!! success "Bundled with the official Docker image"
-
-    This plugin is already installed for your convenience when you use the
-    official [Docker image][2], so the installation step can be skipped. Read
-    the [getting started guide][3] to get up and running with Docker.
-
-  [1]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
-  [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [3]: ../getting-started.md#with-docker-recommended
-
-!!! warning "Requirements"
-
-    The date is extracted at the time of the build, so `mkdocs build` must be
-    triggered from within a git repository.
-
-## Installation
-
-Install the plugin using `pip`:
-
-``` sh
-pip install mkdocs-git-revision-date-localized-plugin
-```
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search # necessary for search to work
-  - git-revision-date-localized
-```
-
-Note that the date is printed according to the locale which is determined
-through the [theme language][2] that was set in `mkdocs.yml`.
-
-  [2]: ../getting-started.md/#language
-
-### Language
-
-The language (i.e. locale) is deduced from the `theme.language` option.
-
-### Format
-
-> Default: `date`
-
-To change the date format, set the `type` parameter to one of `date`,
-`datetime`, `iso_date`, `iso_datetime` or `timeago`, e.g.:
-
-``` yaml
-plugins:
-  - search # necessary for search to work
-  - git-revision-date-localized:
-      type: date
-```
-
-The following formats are supported:
-
-``` gnuplot
-28 November, 2019                      # type: date
-28 November, 2019 13:57:28             # type: datetime
-2019-11-28                             # type: iso_date
-2019-11-28 13:57:26                    # type: iso_datetime
-20 hours ago                           # type: timeago
-```
-
-## Usage
-
-When enabled, the respective date is automatically added at the bottom of each
-page, e.g.:
-
----
-
-<small>
-  Last updated: 28 November, 2019
-</small>

docs/plugins/search.md

@@ -1,133 +0,0 @@
----
-template: overrides/main.html
----
-
-# Search
-
-The [built-in search plugin][1] provides client-side search inside the browser
-and is implemented using [lunr.js][2] which includes stemmers for the English
-language by default, while stemmers for other languages are included with 
-[lunr-languages][3], both of which are integrated with this theme.
-
-!!! tip "Make search work offline"
-
-    While search will not work for the `file://` protocol, as web workers and
-    the use of `XMLHTTPRequest` are both blocked by modern browsers for security
-    reasons, the [localsearch][4] plugin and @squidfunk's [iframe-worker][5]
-    polyfill add support for cases where this is a mandatory requirement, e.g.,
-    for offline use.
-
-  [1]: https://www.mkdocs.org/user-guide/configuration/#search
-  [2]: https://lunrjs.com
-  [3]: https://github.com/MihaiValentin/lunr-languages
-  [4]: https://github.com/wilhelmer/mkdocs-localsearch
-  [5]: https://github.com/squidfunk/iframe-worker
-
-## Installation
-
-The search plugin is a built-in plugin, and thus doesn't need to be installed.
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search
-```
-
-### Language
-
-> Default: best match for `theme.language`, automatically set
-
-Material for MkDocs selects the (best-)matching stemmer for the given theme
-language. Multilingual search can be enabled in `mkdocs.yml` by explicitly
-defining the search language(s):
-
-``` yaml
-plugins:
-  - search:
-      lang:
-        - en
-        - de
-        - ru
-```
-
-The following language codes are supported:
-
-<style>
-  .md-language-list {
-    -webkit-columns: 2;
-       -moz-columns: 2;
-            columns: 2;
-  }
-  .md-language-list li {
-    -webkit-column-break-inside: avoid;
-              page-break-inside: avoid;
-                   break-inside: avoid;
-  }
-</style>
-<ul class="md-language-list">
-  <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>
-
-!!! 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.
-
-### Tokenization
-
-> Default: `[\s\-]+`
-
-The separator for tokenization can be customized which makes it possible to
-index parts of words that are separated by `-` or `.`:
-
-``` yaml
-plugins:
-  - search:
-      separator: '[\s\-\.]+'
-```
-
-### Prebuilding :hatching_chick:
-
-> Default: `false`
-
-MkDocs can generate a [prebuilt index][6] of all pages during build time, which
-provides performance improvements at the cost of more bandwidth. This may be
-beneficial for large documentation projects that are served with appropriate
-HTTP headers (e.g. `Content-Encoding: gzip`).
-
-Material for MkDocs 5 finally brings experimental support for prebuilt indexes
-which can be enabled by adding the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - search:
-      prebuild_index: true
-```
-
-  [6]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
-
-## Usage
-
-When enabled, a search bar is shown in the header.

docs/publishing-your-site.md

@@ -0,0 +1,94 @@
+---
+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:
+
+=== ".github/workflows/ci.yml"
+
+    ``` 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
+    ```
+
+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>`.
+
+  [2]: https://github.com/features/actions
+
+### 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][3] can be
+done by using the [GitLab CI][4] task runner. At the root of your repository,
+create a task definition named `.gitlab-ci.yml` and copy and paste the
+following contents:
+
+=== ".gitlab-ci.yml"
+
+    ``` yaml
+    image: python:latest
+    deploy:
+      stage: deploy
+      only:
+        - master
+      script:
+        - pip install mkdocs-material
+        - 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>`.
+
+  [3]: https://gitlab.com/pages
+  [4]: https://docs.gitlab.com/ee/ci/
+

docs/reference/admonitions.md

@@ -0,0 +1,331 @@
+---
+template: overrides/main.html
+---
+
+# Admonitions
+
+Admonitions, also known as _call-outs_, are an excellent choice for including
+side content without significantly interrupting the document flow. Material for
+MkDocs provides several different types of admonitions and allows for the
+inclusion and nesting of arbitrary content.
+
+## Configuration
+
+### Admonition
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Admonition][2] extension, which is part of the standard Markdown
+library, is integrated with Material for MkDocs and can be enabled from
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - admonition
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_admonition.scss
+  [2]: https://python-markdown.github.io/extensions/admonition/
+
+### Details
+
+[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
+
+The [Details][4] extension, which is part of [Python Markdown Extensions][5],
+adds the ability to __make admonitions collapsible__. It can be enabled from
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.details
+```
+
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_details.scss
+  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+  [5]: https://facelessuser.github.io/pymdown-extensions/
+
+### SuperFences
+
+[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
+
+The [SuperFences][7] extension, which is also part of [Python Markdown
+Extensions][5], allows for the __nesting of content blocks inside admonitions__, 
+and is therefore strongly recommended:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+```
+
+  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
+  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
+## Usage
+
+Admonitions follow a simple syntax: a block must start with `!!!`, followed
+by a single keyword which is used as the [type qualifier][8] of the block. The
+content of the block then follows on the next line, indented by four spaces.
+
+_Example_:
+
+``` markdown
+!!! note
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+  [8]: #supported-types
+
+### Changing the title
+
+By default, the title will equal the type qualifier in titlecase. However, it
+can be changed by adding a quoted string containing valid Markdown (including
+links, formatting, ...) after the type qualifier.
+
+_Example_:
+
+``` markdown
+!!! note "Phasellus posuere in sem ut cursus"
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+!!! note "Phasellus posuere in sem ut cursus"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+### Removing the title
+
+Similar to [changing the title][9], the icon and title can be omitted entirely
+by adding an empty string directly after the type qualifier. Note that this 
+will not work for [collapsible blocks][10].
+
+_Example_:
+
+``` markdown
+!!! note ""
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+!!! note ""
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+  [9]: #changing-the-title
+  [10]: #collapsible-blocks
+
+### Embedded content
+
+Admonitions can contain all kinds of text content, including headlines, lists,
+paragraphs and other blocks. While the parser from the standard Markdown library
+doesn't account for nested blocks, the [SuperFences][11] extension adds the 
+ability to nest arbitrary content inside admonitions.
+
+_Example_:
+
+``` markdown
+!!! note
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+    ``` python
+    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]
+    ```
+
+    Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
+    sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
+    Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
+```
+
+_Result_:
+
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+    ``` python
+    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]
+    ```
+
+    Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
+    sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
+    Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
+
+  [11]: #superfences
+
+### Collapsible blocks
+
+The [Details][12] extension adds support for rendering collapsible admonition
+blocks. This is useful for FAQs or content that is of secondary nature. A
+details block follows the syntax and semantics of admonition blocks, but must
+start with `???`.
+
+_Example_:
+
+``` markdown
+??? note
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+??? note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+Adding a `+` after `???` will render the block as open on page load:
+
+_Example_:
+
+``` markdown
+???+ note
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+???+ note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+
+  [12]: #details
+
+### Supported types
+
+Following is a list of type qualifiers provided by Material for MkDocs, whereas
+the default type, and thus fallback for unknown type qualifiers, is `note`:
+
+`note`, `seealso`
+
+:   !!! note
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`abstract`, `summary`, `tldr`
+
+:   !!! abstract
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`info`, `todo`
+
+:   !!! info
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`tip`, `hint`, `important`
+
+:   !!! tip
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`success`, `check`, `done`
+
+:   !!! success
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`question`, `help`, `faq`
+
+:   !!! question
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`warning`, `caution`, `attention`
+
+:   !!! warning
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`failure`, `fail`, `missing`
+
+:   !!! failure
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`danger`, `error`
+
+:   !!! danger
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`bug`
+
+:   !!! bug
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`example`
+
+:   !!! example
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.
+
+`quote`, `cite`
+
+:   !!! quote
+
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+        euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+        purus auctor massa, nec semper lorem quam in massa.

docs/reference/code-blocks.md

@@ -0,0 +1,290 @@
+---
+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:
+              use_pygments: true
+        ```
+
+    === "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/extra.js"
+
+            ``` js
+            hljs.initHighlighting()
+            ```
+
+        === "mkdocs.yml"
+
+            ``` yaml
+            extra_javascript:
+              - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
+              - javascripts/extra.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/extensions/pymdown/_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-stylesheets
+  [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 from `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
+
+### SuperFences
+
+[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
+
+The [SuperFences][14] 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
+```
+
+  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
+  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
+### Keys
+
+[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
+
+The [Keys][16] extension, which is part of [Python Markdown Extensions][5],
+allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
+can be enabled from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.keys
+```
+
+  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_keys.scss
+  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+
+## 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_:
+
+```
+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
+
+### Displaying keyboard keys
+
+When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
+See the [Python Markdown Extensions][16] documentation for a list of all
+available keys.
+
+_Example_:
+
+```
+++ctrl+alt+del++
+```
+
+_Result_:
+
+++ctrl+alt+del++
+
+  [19]: #keys

docs/reference/content-tabs.md

@@ -0,0 +1,220 @@
+---
+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 from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.tabbed
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_tabbed.scss
+  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+  [3]: https://facelessuser.github.io/pymdown-extensions/
+
+### SuperFences
+
+[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5]
+
+The [SuperFences][5] extension, which is also part of [Python Markdown
+Extensions][3], allows for the __nesting of code blocks inside tabs__, and is
+therefore strongly recommended:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+```
+
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
+  [5]: 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
+
+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
+
+  [6]: admonitions.md
+  [7]: admonitions.md#details

docs/reference/footnotes.md

@@ -0,0 +1,91 @@
+---
+template: overrides/main.html
+---
+
+# Footnotes
+
+Footnotes are a great way to add references to supplemental or additional
+information for a specific section of a document without interrupting the
+document flow. Material for MkDocs provides the ability to insert inline
+footnotes and render them at the bottom of the page.
+
+## Configuration
+
+### Footnotes
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Footnotes][2] extension, which is part of the standard Markdown library,
+adds the ability to add inline footnotes to a document and can be enabled from
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - footnotes
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_footnotes.scss
+  [2]: https://python-markdown.github.io/extensions/footnotes/
+
+## Usage
+
+### Adding footnote references
+
+A footnote reference must be enclosed in square brackets and must start with a
+caret `^`, directly followed by an arbitrary identifier, which is similar to
+the standard Markdown link syntax.
+
+_Example_:
+
+``` markdown
+Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
+```
+
+_Result_:
+
+Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
+
+### Adding footnote content
+
+The footnote content must be declared with the same identifier as the reference.
+It can be inserted at an arbitrary position in the document and is always
+rendered at the bottom of the page. Furthermore, a backlink to the footnote
+reference is automatically added.
+
+#### on a single line
+
+Short statements can be written on the same line.
+
+_Example_:
+
+``` markdown
+[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+```
+
+_Result_:
+
+[Jump to footnote at the bottom of the page](#fn:1)
+
+  [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+#### on multiple lines
+
+Paragraphs can be written on the next line and must be indented by four spaces.
+
+_Example_:
+
+``` markdown
+[^2]:
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+    massa, nec semper lorem quam in massa.
+```
+
+_Result_:
+
+  [^2]:
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+      nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+      auctor massa, nec semper lorem quam in massa.
+
+[Jump to footnote at the bottom of the page](#fn:2)

docs/reference/lists.md

@@ -0,0 +1,202 @@
+---
+template: overrides/main.html
+---
+
+# Lists
+
+Material for MkDocs supports several flavors of lists that cater to different
+use cases, including _unordered lists_ and _ordered lists_, which are supported
+through standard Markdown, as well as _definition lists_ and _task lists_, which
+are supported through extensions.
+
+## Configuration
+
+### Definition Lists
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Definition List][1] extension, which is part of the standard Markdown
+library, adds the ability to add definitions lists to a document and can be 
+enabled from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - def_list
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
+  [2]: https://python-markdown.github.io/extensions/definition_lists/
+
+### Tasklist
+
+[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
+
+The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5], 
+adds support for lists with styled checkboxes, and provides several options for 
+configuring the style:
+
+`custom_checkbox`{: #custom_checkbox }
+
+:   :octicons-milestone-24: Default: `false` · This option toggles the rendering
+    style of checkboxes, replacing native checkbox styles with beautiful icons, 
+    and is therefore _strongly recommended_:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tasklist:
+          custom_checkbox: true
+    ```
+
+`clickable_checkbox`{: #clickable_checkbox }
+
+:   :octicons-milestone-24: Default: `false` · This option toggles whether
+    checkboxes are clickable. As the state is not persisted, the use of this 
+    option is _rather discouraged_ from a user experience perspective:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tasklist:
+          clickable_checkbox: true
+    ```
+
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_tasklist.scss
+  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
+  [5]: https://facelessuser.github.io/pymdown-extensions/
+
+## Usage
+
+### Using unordered lists
+
+An unordered list can be written by prefixing a line with a `-`, `*` or `+`
+list marker, all of which can be used interchangeably. Furthermore, all flavors
+of lists can be nested inside each other.
+
+_Example_:
+
+``` markdown
+* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+  accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+  lacinia sed. Aenean in finibus diam.
+
+    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+    * Nam vulputate tincidunt fringilla.
+    * Nullam dignissim ultrices urna non auctor.
+```
+
+_Result_:
+
+* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+  accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+  lacinia sed. Aenean in finibus diam.
+
+    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+    * Nam vulputate tincidunt fringilla.
+    * Nullam dignissim ultrices urna non auctor.
+
+### Using ordered lists
+
+An ordered list must start with a number immediately followed by a dot. The 
+numbers do not need to be consecutive and can be all set to `1.`, as they will
+be re-numbered when renderer.
+
+_Example_:
+
+``` markdown
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+  sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+  nulla. Vivamus a pharetra leo.
+
+    1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+      quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+      ultricies libero efficitur sed.
+
+    2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+      rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+        1. Mauris dictum mi lacus
+        2. Ut sit amet placerat ante
+        3. Suspendisse ac eros arcu
+```
+
+_Result_:
+
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+  sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+  nulla. Vivamus a pharetra leo.
+
+    1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+      quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+      ultricies libero efficitur sed.
+
+    2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+      rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+        1. Mauris dictum mi lacus
+        2. Ut sit amet placerat ante
+        3. Suspendisse ac eros arcu
+
+### Using definition lists
+
+[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g. 
+the parameters of functions or modules, as used within this documentation to 
+describe extension or plugin parameters.
+
+_Example_:
+
+``` markdown
+`Lorem ipsum dolor sit amet`
+:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+    tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+    Nam vulputate tincidunt fringilla.
+    Nullam dignissim ultrices urna non auctor.
+```
+
+_Result_:
+
+`Lorem ipsum dolor sit amet`
+:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+    tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+    Nam vulputate tincidunt fringilla.
+    Nullam dignissim ultrices urna non auctor.
+
+  [6]: #definition-lists
+
+### Using tasklists
+
+When the [Tasklist][7] extension is enabled, unordered list items can be
+prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
+checkbox.
+
+_Example_:
+
+``` markdown
+* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+* [ ] Vestibulum convallis sit amet nisi a tincidunt
+    * [x] In hac habitasse platea dictumst
+    * [x] In scelerisque nibh non dolor mollis congue sed et metus
+    * [ ] Praesent sed risus massa
+* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+```
+
+_Result_:
+
+* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+* [ ] Vestibulum convallis sit amet nisi a tincidunt
+    * [x] In hac habitasse platea dictumst
+    * [x] In scelerisque nibh non dolor mollis congue sed et metus
+    * [ ] Praesent sed risus massa
+* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+
+  [7]: #tasklist

docs/reference/meta-tags.md

@@ -1,27 +1,29 @@
 ---
 template: overrides/main.html
-hero: Set heroes with metadata
-path: tree/master/docs/extensions
-source: metadata.md
 ---
 
-# Metadata
+# Meta tags
 
-[Metadata][1] is an extension included in the standard Markdown library that
+<!-- TBD -->
-makes it possible to control certain properties in a page-specific context,
-e.g. the page title or description.
-
-  [1]: https://python-markdown.github.io/extensions/meta_data/
 
 ## Configuration
 
-Add the following lines to `mkdocs.yml`:
+### Metadata
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Metadata][1] extension, which is part of the standard Markdown
+library, adds the ability to add custom metadata to a document and can be 
+enabled from `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - meta
 ```
 
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [2]: https://python-markdown.github.io/extensions/meta_data/
+
 ## Usage
 
 Metadata is written as a series of key-value pairs at the beginning of the
@@ -116,20 +118,3 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 
 This will set the `meta` tag containing the site description inside the
 document `head` for the current page to the provided value.
-
-#### Disqus
-
-As described in the [getting started guide][3], Disqus can be enabled on a
-per-document basis:
-
-``` markdown
-disqus: your-shortname
-```
-
-Disqus can also be disabled for a specific page by setting it to an empty value:
-
-``` markdown
-disqus: ''
-```
-
-  [3]: ../getting-started.md#disqus

docs/releases/4.md

@@ -1,30 +0,0 @@
----
-template: overrides/main.html
----
-
-# Upgrading to 4.x
-
-## Highlights
-
-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 [the issue][1] in which the problem was discovered and fixed.
-
-  [1]: https://github.com/squidfunk/mkdocs-material/issues/911
-
-## How to upgrade
-
-### Changes to `mkdocs.yml`
-
-None.
-
-### Changes to `*.html` files
-
-None.

docs/setup/adding-a-comment-system.md

@@ -0,0 +1,55 @@
+---
+template: overrides/main.html
+---
+
+# Adding a comment system
+
+Material for MkDocs is natively integrated with [Disqus][1], a comment system
+that provides a wide range of features like social integrations, user profiles,
+as well as spam and moderation tools. Of course, other comment systems can be 
+integrated, too.
+
+  [1]: https://disqus.com/
+
+## Configuration
+
+### Disqus
+
+First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate
+Material for MkDocs with [Disqus][1], create an account and a site giving you a
+[shortname][3], and add it to `mkdocs.yml`:
+
+``` yaml
+extra:
+  disqus: <shortname>
+```
+
+This will insert a comment system on _every page, except the index page_.
+
+  [2]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
+
+## Customization
+
+### Selective integration
+
+If the [Metadata][4] extension is enabled, you can disable or enable Disqus for
+specific pages by adding the following to the front matter of a page:
+
+=== "Enable Disqus"
+
+    ``` markdown
+    ---
+    disqus: <shortname>
+    ---
+    ```
+
+=== "Disable Disqus"
+
+    ``` markdown
+    ---
+    disqus: ""
+    ---
+    ```
+
+  [4]: ../reference/meta-tags.md#metadata

docs/setup/adding-a-git-repository.md

@@ -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_url
+
+### Repository icon
+
+[:octicons-file-code-24: Source][1] · :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

docs/setup/adding-social-links.md

@@ -0,0 +1,90 @@
+---
+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: #3B5998" }, which can be
+configured through `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
+    ```

docs/setup/changing-the-colors.md

@@ -0,0 +1,257 @@
+---
+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 from `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 following CSS variables:
+
+``` css
+:root {
+
+  /* Default color shades */
+  --md-default-fg-color:               hsla(0, 0%, 0%, 0.87);
+  --md-default-fg-color--light:        hsla(0, 0%, 0%, 0.54);
+  --md-default-fg-color--lighter:      hsla(0, 0%, 0%, 0.32);
+  --md-default-fg-color--lightest:     hsla(0, 0%, 0%, 0.07);
+  --md-default-bg-color:               hsla(0, 0%, 100%, 1);
+  --md-default-bg-color--light:        hsla(0, 0%, 100%, 0.7);
+  --md-default-bg-color--lighter:      hsla(0, 0%, 100%, 0.3);
+  --md-default-bg-color--lightest:     hsla(0, 0%, 100%, 0.12);
+
+  /* Primary color shades */
+  --md-primary-fg-color:               hsla(231, 48%, 48%, 1);
+  --md-primary-fg-color--light:        hsla(231, 44%, 56%, 1);
+  --md-primary-fg-color--dark:         hsla(232, 54%, 41%, 1);
+  --md-primary-bg-color:               hsla(0, 0%, 100%, 1);
+  --md-primary-bg-color--light:        hsla(0, 0%, 100%, 0.7);
+
+  /* Accent color shades */
+  --md-accent-fg-color:                hsla(231, 99%, 66%, 1);
+  --md-accent-fg-color--transparent:   hsla(231, 99%, 66%, 0.1);
+  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
+  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);
+}
+```
+
+The colors of [code blocks][9], [admonitions][10], text links and the footer can
+be adjusted through dedicated CSS variables, which partly default to the base
+colors or neutral colors:
+
+``` css
+:root > * {
+
+  /* Code color shades */
+  --md-code-bg-color:                  hsla(0, 0%, 96%, 1);
+  --md-code-fg-color:                  hsla(200, 18%, 26%, 1);
+
+  /* Text color shades */
+  --md-text-color:                     var(--md-default-fg-color);
+  --md-text-link-color:                var(--md-primary-fg-color);
+
+  /* Admonition color shades */
+  --md-admonition-bg-color:            var(--md-default-bg-color);
+  --md-admonition-fg-color:            var(--md-default-fg-color);
+
+  /* Footer color shades */
+  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
+  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
+  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
+  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
+  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.3);
+}
+```
+
+  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss
+  [7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+  [8]: ../customization.md#additional-stylesheets
+  [9]: ../reference/code-blocks.md
+  [10]: ../reference/admonitions.md

docs/setup/changing-the-fonts.md

@@ -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#L120-L139
+  [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] from
+`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

docs/setup/changing-the-language.md

@@ -0,0 +1,156 @@
+---
+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_ from `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
+
+### 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 you just
+created. 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

docs/setup/changing-the-logo-and-icons.md

@@ -0,0 +1,130 @@
+---
+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 from `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 from `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][5] · [:octicons-workflow-24: Extension][6]
+
+The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
+adds the ability to __integrate custom icons__ in the `*.svg` file format,
+which are inlined into the HTML when [building your site][8]:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+```
+
+The following icon sets are bundled with Material for MkDocs:
+
+* :material-material-design: – [Material Design][9]
+* :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
+* :fontawesome-brands-github: – [Octicons][11]
+
+If you want to add [additional icons][1], read on.
+
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_emoji.scss
+  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
+  [7]: https://facelessuser.github.io/pymdown-extensions/
+  [8]: ../creating-your-site.md#building-your-site
+  [9]: https://materialdesignicons.com/
+  [10]: https://fontawesome.com/icons?d=gallery&m=free
+  [11]: https://octicons.github.com/
+
+## Customization
+
+### Additional icons
+
+[:octicons-file-code-24: Source][3] · 
+:octicons-mortar-board-24: Difficulty: _moderate_
+
+In order to add additional icons, [extend the theme][13] and create a folder
+named `.icons` in the [`custom_dir`][14] 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][15] 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.
+
+  [13]: ../customization.md#extending-the-theme
+  [14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+  [15]: https://icons.getbootstrap.com/

docs/setup/setting-up-navigation.md

@@ -0,0 +1,182 @@
+---
+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 from `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 from `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/

docs/setup/setting-up-site-analytics.md

@@ -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][2] · 
+: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][2] · 
+: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

docs/setup/setting-up-site-search.md

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

docs/sponsorship.md

@@ -0,0 +1,116 @@
+---
+template: overrides/main.html
+---
+
+# <span hidden>Sponsorship</span> :logo: :material-plus: :octicons-heart-fill-24:
+
+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 split into a community edition and a 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.
+
+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

docs/troubleshooting.md

@@ -0,0 +1,102 @@
+---
+template: overrides/main.html
+---
+
+# Troubleshooting
+
+## 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:
+
+1. __Installing in a virtual environment__: Virtual environments provide an easy
+   way of encapsulation. 
+
+2. __Installing in user space__: Provide the `--user` flag to the install
+   command and `pip` will install the package in a user-site location. Note
+   that while this is not a global installation, it's still not
+
+3. __Switching to a homebrewed Python__: Upgrade your Python installation to a
+   self-contained solution by installing Python with Homebrew. This should
+   eliminate a lot of problems you could be having with `pip`.
+
+### 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][9]. First, ensure
+that you have a Python version of 3 or higher installed:
+
+``` sh
+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 with `pip`, which will download and install
+all packages in the `venv` folder you just created, including MkDocs and its 
+dependencies:
+
+``` sh
+pip install mkdocs-material
+```
+
+Verify that MkDocs and Material for MkDocs were both installed correctly:
+
+``` sh
+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
+```
+
+  [9]: https://docs.python.org/3/tutorial/venv.html
+ 
+## 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.

docs/upgrading.md

@@ -2,29 +2,43 @@
 template: overrides/main.html
 ---
 
-# Upgrading to 5.x
+# Upgrading
 
-## Highlights
+Upgrade to the latest version with:
+
+``` sh
+pip install --upgrade mkdocs-material
+```
+
+Inspect the currently installed version with:
+
+``` sh
+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
+* [Instant loading][1] – make Material behave like a Single Page Application
-* Improved CSS customization with [CSS variables][1] – set your brand's colors
+* 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
+  [1]: setup/setting-up-navigation.md#instant-loading
-  [2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [2]: setup/changing-the-colors.md#custom-colors
-
+  [3]: setup/changing-the-logo-and-icons.md#icons
-## How to upgrade
+  [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]: setup/setting-up-navigation.md#navigation-tabs
-  [5]: ../../getting-started/#instant-loading
 
 #### `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.

material/assets/manifest.json

@@ -1,12 +1,14 @@
 {
-  "assets/javascripts/bundle.js": "assets/javascripts/bundle.2a81e305.min.js",
+  "assets/javascripts/bundle.js": "assets/javascripts/bundle.1b3af799.min.js",
-  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.2a81e305.min.js.map",
+  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.1b3af799.min.js.map",
-  "assets/javascripts/vendor.js": "assets/javascripts/vendor.568ba93b.min.js",
+  "assets/javascripts/vendor.js": "assets/javascripts/vendor.877163d5.min.js",
-  "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map",
+  "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.61729dd2.min.css",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.364d010a.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.61729dd2.min.css.map",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.364d010a.min.css.map",
-  "assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
+  "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.823d2928.min.css",
-  "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
+  "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.823d2928.min.css.map",
+  "assets/stylesheets/palette.css": "assets/stylesheets/palette.a53427c9.min.css",
+  "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.a53427c9.min.css.map"
 }

material/assets/stylesheets/overrides.823d2928.min.css

@@ -0,0 +1,3 @@
+:root{--md-admonition-icon--sponsor: url( 'data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"/></svg>' )}.md-typeset .admonition.sponsor{border-color:#ea4aaa}.md-typeset .sponsor>.admonition-title{background-color:rgba(234,74,170,.1)}.md-typeset .sponsor>.admonition-title::before{background-color:#ea4aaa;-webkit-mask-image:var(--md-admonition-icon--sponsor);mask-image:var(--md-admonition-icon--sponsor)}.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}@-webkit-keyframes tx-sponsor{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.1)}}@keyframes tx-sponsor{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.1)}}.tx-sponsor{margin-top:1rem;text-align:center}.tx-sponsor a{color:#e91e63;font-variant:all-petite-caps}.tx-sponsor hr{display:inline-block;width:2rem;margin:1em;vertical-align:middle;background-color:currentColor;border:none}.tx-sponsor__heart{-webkit-animation:tx-sponsor 1000ms infinite;animation:tx-sponsor 1000ms infinite}.md-typeset .tx-switch button{cursor:pointer;transition:opacity 250ms}.md-typeset .tx-switch button:hover{opacity:.75}.md-typeset .tx-switch button>code{display:block;color:var(--md-primary-bg-color);background-color:var(--md-primary-fg-color)}.md-typeset .tx-columns{-moz-columns:2;columns:2}.md-typeset .tx-columns>*{-moz-column-break-inside:avoid;break-inside:avoid}
+
+/*# sourceMappingURL=overrides.823d2928.min.css.map*/

material/base.html

@@ -41,9 +41,9 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.61729dd2.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.364d010a.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
-        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e185632b.min.css' | url }}">
+        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.a53427c9.min.css' | url }}">
       {% endif %}
       {% if palette.primary %}
         {% import "partials/palette.html" as map %}
@@ -182,8 +182,8 @@
       {% endblock %}
     </div>
     {% block scripts %}
-      <script src="{{ 'assets/javascripts/vendor.568ba93b.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/vendor.877163d5.min.js' | url }}"></script>
-      <script src="{{ 'assets/javascripts/bundle.2a81e305.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.1b3af799.min.js' | url }}"></script>
       {%- set translations = {} -%}
       {%- for key in [
         "clipboard.copy",

material/overrides/main.html

@@ -22,9 +22,9 @@
   <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.823d2928.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">
@@ -35,3 +35,30 @@
     <strong>Twitter</strong>
   </a>
 {% endblock %}
+{% block content %}
+  {{ super() }}
+  <aside class="tx-sponsor md-typeset">
+    <a href="{{ 'sponsorship' | url }}" title="Becoming a sponsor">
+      <hr>
+      <span class="twemoji">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 89 89">
+          <path d="M3.136 17.387v42.932l42.932 21.467L3.136 17.387z"></path>
+          <path fill-opacity=".5" d="M21.91 8l42.933 64.398-18.775 9.388L3.136 17.387 21.91 8z"></path>
+          <path d="M67.535 17.387L40.273 35.543l21.878 32.818 5.384 2.691V17.387z"></path>
+          <path fill-opacity=".25" d="M67.535 17.387v53.666l18.774-9.388V8l-18.774 9.387z"></path>
+        </svg>
+      </span>
+      <span class="twemoji">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+          <path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"></path>
+        </svg>
+      </span>
+      <span class="twemoji tx-sponsor__heart">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+          <path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"></path>
+        </svg>
+      </span>
+      <hr>
+    </a>
+  </aside>
+{% endblock %}

material/partials/more.html

@@ -1,11 +0,0 @@
-{#-
-  This file was automatically generated - do not edit
--#}
-<div class="md-more">
-  <input class="md-toggle" data-md-toggle="more" type="checkbox" id="__more" autocomplete="off">
-  <ul class="md-more__list">
-    <li class="md-more__item">Item 1</li>
-    <li class="md-more__item">Item 2</li>
-    <li class="md-more__item">Item 3</li>
-  </ul>
-</div>

material/partials/source-link.html

@@ -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" %}

mkdocs.yml

@@ -67,6 +67,20 @@ theme:
 # 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:
+  - pymdownx.highlight
-  #     linenums_style: pymdownx-inline
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.magiclink:
@@ -127,27 +138,38 @@ markdown_extensions:
 # Page tree
 nav:
   - Home: index.md
-  - Getting started: getting-started.md
+  - Getting started:
-  - Extensions:
+    - Installation: getting-started.md
-    - Admonition: extensions/admonition.md
+    - Creating your site: creating-your-site.md
-    - CodeHilite: extensions/codehilite.md
+    - Publishing your site: publishing-your-site.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
+    - Troubleshooting: troubleshooting.md
     - Data privacy: data-privacy.md
-  - Contributing: contributing.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
+    - Lists: reference/lists.md
+    - Meta tags: reference/meta-tags.md
+  - Changelog:
+    - Release notes: changelog.md
+    - Upgrading: upgrading.md
 
 # Google Analytics
 google_analytics:

netlify.toml

@@ -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
 """

src/assets/javascripts/integrations/search/transform/index.ts

@@ -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.
  *

src/assets/stylesheets/base/_colors.scss

@@ -57,6 +57,11 @@
     --md-code-bg-color:                hsla(0, 0%, 96%, 1);
     --md-code-fg-color:                hsla(200, 18%, 26%, 1);
 
+    // Keyboard color shades
+    --md-kbd-color:                    hsla(0, 0%, 98%, 1);
+    --md-kbd-accent-color:             hsla(0, 100%, 100%, 1);
+    --md-kbd-border-color:             hsla(0, 0%, 72%, 1);
+
     // Text color shades
     --md-text-color:                   var(--md-default-fg-color);
     --md-text-link-color:              var(--md-primary-fg-color);

src/assets/stylesheets/base/_typeset.scss

@@ -52,7 +52,7 @@ kbd {
 // ----------------------------------------------------------------------------
 
 // Content that is typeset - if possible, all margins, paddings and font sizes
-// should be set in ems, so nested blocks (e.g. Admonition) render correctly,
+// should be set in ems, so nested blocks (e.g. admonitions) render correctly,
 // except headlines that should only appear on the top level and need to have
 // consistent spacing due to layout constraints.
 .md-typeset {
@@ -246,19 +246,21 @@ kbd {
     }
   }
 
-  // Keystrokes
+  // Keyboard key
   kbd {
     display: inline-block;
     padding: 0 px2em(8px, 12px);
+    color: var(--md-default-fg-color);
     font-size: px2em(12px);
     line-height: 1.5;
     vertical-align: text-top;
     word-break: break-word;
+    background-color: var(--md-kbd-color);
     border-radius: px2rem(2px);
     box-shadow:
-      0 px2rem(2px) 0 px2rem(1px) var(--md-default-fg-color--lighter),
+      0 px2rem(2px)  0 px2rem(1px) var(--md-kbd-border-color),
-      0 px2rem(2px) 0             var(--md-default-fg-color--lighter),
+      0 px2rem(2px)  0             var(--md-kbd-border-color),
-      inset 0 px2rem(-2px) px2rem(4px) var(--md-default-bg-color);
+      0 px2rem(-2px) px2rem(4px)   var(--md-kbd-accent-color) inset;
   }
 
   // Text highlighting marker
@@ -374,7 +376,7 @@ kbd {
 
   // Definition lists
   dd {
-    margin: 1em 0 1em px2em(30px, 16px);
+    margin: 1em 0 1.5em px2em(30px, 16px);
 
     // Adjust for right-to-left languages
     [dir="rtl"] & {

src/assets/stylesheets/extensions/_admonition.scss

@@ -52,7 +52,7 @@ $admonitions: (
     $name: nth($names, 1);
     $icon: nth($props, 1);
 
-    // Inline icon through postcss in webpack
+    // Inline icon through PostCSS in Webpack
     --md-admonition-icon--#{$name}: svg-load("@mdi/svg/svg/#{$icon}.svg");
   }
 }
@@ -107,6 +107,11 @@ $admonitions: (
     .md-typeset__table {
       padding: 0 px2rem(12px);
     }
+
+    // Tabbed block container is the only child
+    > .tabbed-set:only-child {
+      margin-top: 0;
+    }
   }
 
   // Admonition title
@@ -144,7 +149,7 @@ $admonitions: (
       }
     }
 
-    // Reset code inside Admonition titles
+    // Reset code inside admonition titles
     code {
       margin: initial;
       padding: initial;
@@ -153,6 +158,11 @@ $admonitions: (
       border-radius: initial;
       box-shadow: none;
     }
+
+    // Tabbed block container is the last child
+    + .tabbed-set:last-child {
+      margin-top: 0;
+    }
   }
 }
 

src/assets/stylesheets/extensions/_codehilite.scss

@@ -242,7 +242,7 @@ $codehilite-whitespace: transparent;
   // Add spacing to line number container
   .linenodiv {
     padding-right: px2em(8px, 13.6px);
-    box-shadow: inset px2rem(-1px) 0 var(--md-default-fg-color--lightest);
+    box-shadow: px2rem(-1px) 0 var(--md-default-fg-color--lightest) inset;
 
     // Reset spacings
     pre {

src/assets/stylesheets/extensions/_footnotes.scss

@@ -43,6 +43,7 @@
       margin-top: -1 * px2rem(48px + 12px + 16px);
       padding-top: px2rem(48px + 12px + 16px);
       pointer-events: none;
+      scroll-margin-top: initial;
     }
   }
 
@@ -56,6 +57,11 @@
       content: "";
     }
 
+    // Reset, as we use the anchor-correction hack here.
+    &:target {
+      scroll-margin-top: initial;
+    }
+
     // Targeted anchor
     &:target::before {
       display: block;

src/assets/stylesheets/extensions/pymdown/_emoji.scss

@@ -32,6 +32,7 @@
   img.twemoji,
   img.gemoji {
     width: px2em(18px);
+    max-height: 100%;
     vertical-align: -15%;
   }
 
@@ -44,6 +45,7 @@
     // Icon
     svg {
       width: px2em(18px);
+      max-height: 100%;
       fill: currentColor;
     }
   }

src/assets/stylesheets/extensions/pymdown/_highlight.scss

@@ -40,7 +40,7 @@
     padding-left: px2em(16px, 13.6px);
     color: var(--md-default-fg-color--lighter);
     background-color: var(--md-code-bg-color);
-    box-shadow: inset px2rem(-1px) 0 var(--md-default-fg-color--lightest);
+    box-shadow: px2rem(-1px) 0 var(--md-default-fg-color--lightest) inset;
     content: attr(data-linenos);
     user-select: none;
   }

src/assets/stylesheets/extensions/pymdown/_keys.scss

@@ -0,0 +1,116 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Scoped in typesetted content to match specificity of regular content
+.md-typeset .keys {
+
+  // Keyboard key icon
+  kbd::before,
+  kbd::after {
+    position: relative;
+    margin: 0;
+    color: inherit;
+    -moz-osx-font-smoothing: initial;
+    -webkit-font-smoothing: initial;
+  }
+
+  // Surrounding text
+  span {
+    padding: 0 px2em(3.2px);
+    color: var(--md-default-fg-color--light);
+  }
+
+  // Build special keys with left icon
+  @each $name, $code in (
+
+    // Modifiers
+    "alt":           "\2387",
+    "left-alt":      "\2387",
+    "right-alt":     "\2387",
+    "command":       "\2318",
+    "left-command":  "\2318",
+    "right-command": "\2318",
+    "control":       "\2303",
+    "left-control":  "\2303",
+    "right-control": "\2303",
+    "meta":          "\25C6",
+    "left-meta":     "\25C6",
+    "right-meta":    "\25C6",
+    "option":        "\2325",
+    "left-option":   "\2325",
+    "right-option":  "\2325",
+    "shift":         "\21E7",
+    "left-shift":    "\21E7",
+    "right-shift":   "\21E7",
+    "super":         "\2756",
+    "left-super":    "\2756",
+    "right-super":   "\2756",
+    "windows":       "\229E",
+    "left-windows":  "\229E",
+    "right-windows": "\229E",
+
+    // Other keys
+    "arrow-down":    "\25bd",
+    "arrow-left":    "\25c1",
+    "arrow-right":   "\25b7",
+    "arrow-up":      "\25b3",
+    "backspace":     "\232B",
+    "backtab":       "\21E4",
+    "caps-lock":     "\21EA",
+    "clear":         "\2327",
+    "context-menu":  "\2630",
+    "delete":        "\2326",
+    "eject":         "\23CF",
+    "end":           "\2913",
+    "escape":        "\238b",
+    "home":          "\2912",
+    "insert":        "\2380",
+    "page-down":     "\21df",
+    "page-up":       "\21de",
+    "print-screen":  "\2399"
+  ) {
+    .key-#{$name} {
+      &::before {
+        padding-right: px2em(6.4px);
+        content: $code;
+      }
+    }
+  }
+
+  // Build special keys with right icon
+  @each $name, $code in (
+    "tab":           "\21B9",
+    "num-enter":     "\2324",
+    "enter":         "\23CE"
+  ) {
+    .key-#{$name} {
+      &::after {
+        padding-left: px2em(6.4px);
+        content: $code;
+      }
+    }
+  }
+}

src/assets/stylesheets/extensions/pymdown/_tabbed.scss

@@ -35,6 +35,7 @@
     box-shadow: 0 px2rem(-1px) var(--md-default-fg-color--lightest);
 
     // Mirror old superfences behavior, if there's only a single code block.
+    > pre:only-child,
     > .codehilite:only-child pre,
     > .codehilitetable:only-child,
     > .highlight:only-child pre,

src/assets/stylesheets/extensions/pymdown/_tasklist.scss

@@ -26,8 +26,12 @@
 
 // Icon definitions
 :root {
-  --md-tasklist-icon: svg-load("@mdi/svg/svg/checkbox-blank-circle.svg");
+  --md-tasklist-icon: svg-load(
-  --md-tasklist-icon--checked: svg-load("@mdi/svg/svg/check-circle.svg");
+    "@primer/octicons/build/svg/check-circle-fill-24.svg"
+  );
+  --md-tasklist-icon--checked: svg-load(
+    "@primer/octicons/build/svg/check-circle-fill-24.svg"
+  );
 }
 
 // ----------------------------------------------------------------------------

src/assets/stylesheets/layout/_nav.scss

@@ -208,7 +208,7 @@
           overflow-y: auto;
           background-color: var(--md-default-bg-color);
           box-shadow:
-            inset 0 px2rem(1px) 0 var(--md-default-fg-color--lightest);
+            0 px2rem(1px) 0 var(--md-default-fg-color--lightest) inset;
           scroll-snap-type: y mandatory;
           touch-action: pan-y;
 

src/assets/stylesheets/main.scss

@@ -67,6 +67,7 @@
 @import "extensions/pymdown/details";
 @import "extensions/pymdown/emoji";
 @import "extensions/pymdown/highlight";
+@import "extensions/pymdown/keys";
 @import "extensions/pymdown/tabbed";
 @import "extensions/pymdown/tasklist";
 

src/assets/stylesheets/overrides.scss

@@ -0,0 +1,42 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Dependencies
+// ----------------------------------------------------------------------------
+
+@import "modularscale";
+@import "material-color";
+
+// ----------------------------------------------------------------------------
+// Local imports
+// ----------------------------------------------------------------------------
+
+@import "utilities/break";
+@import "utilities/convert";
+
+@import "config";
+
+@import "overrides/admonition";
+@import "overrides/announce";
+@import "overrides/sponsor";
+@import "overrides/typeset";

src/assets/stylesheets/overrides/_admonition.scss

@@ -0,0 +1,83 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Variables
+// ----------------------------------------------------------------------------
+
+///
+/// Admonition flavours
+///
+$admonitions: (
+  sponsor:                    heart-fill-24 #EA4AAA
+) !default;
+
+// ----------------------------------------------------------------------------
+// Rules: layout
+// ----------------------------------------------------------------------------
+
+// Icon definitions
+:root {
+  @each $names, $props in $admonitions {
+    $name: nth($names, 1);
+    $icon: nth($props, 1);
+
+    // Inline icon through PostCSS in Webpack
+    --md-admonition-icon--#{$name}: svg-load(
+      "@primer/octicons/build/svg/#{$icon}.svg"
+    );
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Rules: flavours
+// ----------------------------------------------------------------------------
+
+@each $names, $props in $admonitions {
+  $name: nth($names, 1);
+  $tint: nth($props, 2);
+
+  // Define base class
+  .md-typeset .admonition.#{$name} {
+    border-color: $tint;
+  }
+
+  // Define base class
+  .md-typeset .#{$name} > .admonition-title {
+    background-color: transparentize($tint, 0.9);
+
+    // Icon
+    &::before {
+      background-color: $tint;
+      mask-image: var(--md-admonition-icon--#{$name});
+    }
+  }
+
+  // Define synonyms for base class
+  @if length($names) > 1 {
+    @for $n from 2 through length($names) {
+      .#{nth($names, $n)} {
+        @extend .#{$name};
+      }
+    }
+  }
+}

src/assets/stylesheets/overrides/_announce.scss

@@ -0,0 +1,47 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Announcement bar
+.md-announce {
+
+  // Preserve link colors
+  a,
+  a:focus,
+  a:hover {
+    color: currentColor;
+  }
+
+  // Don't wrap name of blog article
+  strong {
+    white-space: nowrap;
+  }
+
+  // Twitter icon
+  .twitter {
+    margin-left: .2em;
+    color: #00ACEE;
+  }
+}

src/assets/stylesheets/overrides/_sponsor.scss

@@ -0,0 +1,66 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Keyframes
+// ----------------------------------------------------------------------------
+
+// Heart animation
+@keyframes tx-sponsor {
+  0%, 40%, 80%, 100% {
+    transform: scale(1);
+  }
+  20%, 60% {
+    transform: scale(1.1);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Sponsor banner
+.tx-sponsor {
+  margin-top: px2rem(20px);
+  text-align: center;
+
+  // Sponsor link
+  a {
+    color: $clr-pink-500;
+    font-variant: all-petite-caps;
+  }
+
+  // Horizontal separators
+  hr {
+    display: inline-block;
+    width: px2rem(40px);
+    margin: px2em(16px);
+    vertical-align: middle;
+    background-color: currentColor;
+    border: none;
+  }
+
+  // Pumping heart
+  &__heart {
+    animation: tx-sponsor 1000ms infinite;
+  }
+}

src/assets/stylesheets/overrides/_typeset.scss

@@ -0,0 +1,57 @@
+////
+/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
+///
+/// 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
+////
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Typesetted content
+.md-typeset {
+
+  // Extension: switch buttons
+  .tx-switch button {
+    cursor: pointer;
+    transition: opacity 250ms;
+
+    // Hovered button
+    &:hover {
+      opacity: 0.75;
+    }
+
+    // Code block
+    > code {
+      display: block;
+      color: var(--md-primary-bg-color);
+      background-color: var(--md-primary-fg-color);
+    }
+  }
+
+  // Two-column layout
+  .tx-columns {
+    columns: 2;
+
+    // Column
+    > * {
+      break-inside: avoid;
+    }
+  }
+}

src/assets/stylesheets/palette/_scheme.scss

@@ -39,7 +39,12 @@
 
   // Code color shades
   --md-code-bg-color:                  hsla(232, 15%, 18%, 1);
-  --md-code-fg-color:                  hsla(60, 30%, 96%, 1);
+  --md-code-fg-color:                  hsla(232, 18%, 86%, 1);
+
+  // Keyboard color shades
+  --md-kbd-color:                      hsla(232, 15%, 94%, 0.12);
+  --md-kbd-accent-color:               hsla(232, 15%, 94%, 0.2);
+  --md-kbd-border-color:               hsla(232, 15%, 14%, 1);
 
   // Text color shades
   --md-text-color:                     var(--md-default-fg-color--light);

src/overrides/main.html

@@ -51,30 +51,16 @@
   <meta name="twitter:title" content="{{ title }}" />
   <meta name="twitter:description" content="{{ config.site_description }}" />
   <meta name="twitter:image" content="{{ image }}" />
+
+  <!-- Extra stylesheets -->
+  <link
+    rel="stylesheet"
+    href="{{ 'assets/stylesheets/overrides.css' | url }}"
+  />
 {% endblock %}
 
 <!-- Announcement bar -->
 {% block announce %}
-  <style>
-
-    /* Preserve link color */
-    .md-announce a,
-    .md-announce a:focus,
-    .md-announce a:hover {
-      color: currentColor;
-    }
-
-    /* Don't wrap name of blog article */
-    .md-announce strong {
-      white-space: nowrap;
-    }
-
-    /* Twitter icon */
-    .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">
@@ -85,3 +71,34 @@
     <strong>Twitter</strong>
   </a>
 {% endblock %}
+
+<!-- Content -->
+{% block content %}
+  {{ super() }}
+
+  <!-- Sponsor banner -->
+  <aside class="tx-sponsor md-typeset">
+    <a href="{{ 'sponsorship' | url }}" title="Becoming a sponsor">
+      <hr />
+      <span class="twemoji">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 89 89">
+          <path d="M3.136 17.387v42.932l42.932 21.467L3.136 17.387z"></path>
+          <path fill-opacity=".5" d="M21.91 8l42.933 64.398-18.775 9.388L3.136 17.387 21.91 8z"></path>
+          <path d="M67.535 17.387L40.273 35.543l21.878 32.818 5.384 2.691V17.387z"></path>
+          <path fill-opacity=".25" d="M67.535 17.387v53.666l18.774-9.388V8l-18.774 9.387z"></path>
+        </svg>
+      </span>
+      <span class="twemoji">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+          <path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"></path>
+        </svg>
+      </span>
+      <span class="twemoji tx-sponsor__heart">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+          <path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"></path>
+        </svg>
+      </span>
+      <hr />
+    </a>
+  </aside>
+{% endblock %}

src/partials/more.html

@@ -1,39 +0,0 @@
-<!--
-  Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
-
-  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.
--->
-
-<!-- Options dialog -->
-<div class="md-more">
-  <input
-    class="md-toggle"
-    data-md-toggle="more"
-    type="checkbox"
-    id="__more"
-    autocomplete="off"
-  />
-
-  <!-- Options -->
-  <ul class="md-more__list">
-    <li class="md-more__item">Item 1</li>
-    <li class="md-more__item">Item 2</li>
-    <li class="md-more__item">Item 3</li>
-  </ul>
-</div>

src/partials/source-link.html

@@ -27,7 +27,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 }}"

webpack.config.ts

@@ -189,6 +189,7 @@ export default (_env: never, args: Configuration): Configuration[] => {
       entry: {
         "assets/javascripts/bundle":    "src/assets/javascripts",
         "assets/stylesheets/main":      "src/assets/stylesheets/main.scss",
+        "assets/stylesheets/overrides": "src/assets/stylesheets/overrides.scss",
         "assets/stylesheets/palette":   "src/assets/stylesheets/palette.scss"
       },
       output: {
@@ -312,16 +313,21 @@ export default (_env: never, args: Configuration): Configuration[] => {
         new EventHooksPlugin({
           afterEmit: () => {
 
-            /* Replace asset URLs in base template */
+            /* Replace asset URLs in templates */
             if (args.mode === "production") {
               const manifest = require("./material/assets/manifest.json")
+              for (const file of [
+                "material/base.html",
+                "material/overrides/main.html"
+              ]) {
                 const template = toPairs<string>(manifest)
                   .reduce((content, [from, to]) => {
                     return content.replace(new RegExp(from, "g"), to)
-                }, fs.readFileSync("material/base.html", "utf8"))
+                  }, fs.readFileSync(file, "utf8"))
 
                 /* Save template with replaced assets */
-              fs.writeFileSync("material/base.html", template, "utf8")
+                fs.writeFileSync(file, template, "utf8")
+              }
             }
           }
         }),