template

docs/creating-your-site.md

+---
+template: overrides/main.html
+---
+
+# Creating your site
+
+After you've [installed][1] Material for MkDocs, you can bootstrap your project 
+documentation using the `mkdocs` executable. Go to the directory where you want
+your project to be located and enter:
+
+```
+mkdocs new .
+```
+
+Alternatively, if you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+    ```
+    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
+
+Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
+since there are several [installation methods][2], configuration might be
+slightly different:
+
+=== "pip, docker"
+
+    ``` yaml
+    theme:
+      name: material
+    ```
+
+=== "git"
+
+    ``` yaml
+    theme:
+      name: null
+      custom_dir: mkdocs-material/material
+
+      # 404 page
+      static_templates:
+        - 404.html
+
+      # Necessary for search to work properly
+      include_search_page: false
+      search_index_only: true
+
+      # Default values, taken from mkdocs_theme.yml
+      language: en
+      font:
+        text: Roboto
+        code: Roboto Mono
+      favicon: assets/favicon.png
+      icon:
+        logo: logo
+    ```
+
+_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
+defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
+[described in the official documentation][4]._
+
+  [2]: getting-started.md#installation
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
+  [4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
+
+### Advanced configuration
+
+Material for MkDocs comes with many configuration options. The _setup_ section
+explains in great detail how to configure and customize colors, fonts, icons
+and much more:
+
+<div class="mdx-columns" markdown="1">
+
+- [Changing the colors][5]
+- [Changing the fonts][6]
+- [Changing the language][7]
+- [Changing the logo and icons][8]
+- [Setting up navigation][9]
+- [Setting up site search][10]
+- [Setting up site analytics][11]
+- [Setting up versioning][12]
+- [Setting up the header][13]
+- [Setting up the footer][14]
+- [Adding a git repository][15]
+- [Adding a comment system][16]
+
+</div>
+
+  [5]: setup/changing-the-colors.md
+  [6]: setup/changing-the-fonts.md
+  [7]: setup/changing-the-language.md
+  [8]: setup/changing-the-logo-and-icons.md
+  [9]: setup/setting-up-navigation.md
+  [10]: setup/setting-up-site-search.md
+  [11]: setup/setting-up-site-analytics.md
+  [12]: setup/setting-up-versioning.md
+  [13]: setup/setting-up-the-header.md
+  [14]: setup/setting-up-the-footer.md
+  [15]: setup/adding-a-git-repository.md
+  [16]: setup/adding-a-comment-system.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, Powershell"
+
+    ```
+    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][17] and you should see:
+
+[![Creating your site][18]][18]
+
+  [17]: http://localhost:8000
+  [18]: assets/screenshots/creating-your-site.png
+
+## Building your site
+
+When you're finished editing, you can build a static site from your Markdown
+files with:
+
+```
+mkdocs build
+```
+
+The contents of this directory make up your project documentation. There's no
+need for operating a database or server, as it is completely self-contained.
+The site can be hosted on [GitHub Pages][19], [GitLab Pages][20], a CDN of your
+choice or your private web space.
+
+  [19]: publishing-your-site.md#github-pages
+  [20]: publishing-your-site.md#gitlab-pages

docs/customization.md

+---
+template: overrides/main.html
+---
+
+# Customization
+
+Project documentation is as diverse as the projects themselves and Material for
+MkDocs is a great starting point for making it look beautiful. However, as you
+write your documentation, you may reach a point where small adjustments are
+necessary to preserve your brand's style.
+
+## Adding assets
+
+[MkDocs][1] provides several ways to customize a theme. In order to make a few
+tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
+files to the `docs` directory.
+
+  [1]: https://www.mkdocs.org
+
+### Additional CSS
+
+If you want to tweak some colors or change the spacing of certain elements,
+you can do this in a separate stylesheet. The easiest way is by creating a
+new stylesheet file in the `docs` directory:
+
+``` sh
+.
+├─ docs/
+│  └─ stylesheets/
+│     └─ extra.css
+└─ mkdocs.yml
+```
+
+Then, add the following line to `mkdocs.yml`:
+
+``` yaml
+extra_css:
+  - stylesheets/extra.css
+```
+
+Spin up the [live preview server][2] and start typing your changes in your
+additional stylesheet file – you should see them almost instantly after saving.
+
+  [2]: creating-your-site.md#previewing-as-you-write
+
+### Additional JavaScript
+
+The same is true for additional JavaScript. If you want to integrate another
+syntax highlighter or add some custom logic to your theme, create a new
+JavaScript file in the `docs` directory:
+
+``` sh
+.
+├─ docs/
+│  └─ javascripts/
+│     └─ extra.js
+└─ 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][3].
+
+  [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 parts), you can
+extend the theme. MkDocs supports [theme extension][4], an easy way to override
+parts of Material for MkDocs without forking from git. This ensures that you
+can update to the latest version more easily.
+
+  [4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
+
+### Setup and theme structure
+
+Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
+for `overrides` which you then reference using the `custom_dir` key:
+
+``` yaml
+theme:
+  name: material
+  custom_dir: overrides
+```
+
+!!! warning "Theme extension prerequisites"
+
+    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 `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
+file with the same name which is part of the original theme. Besides, further
+assets may also be put in the `overrides` directory.
+
+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/                    # Third-party integrations
+│  │  ├─ analytics.html                # - Google Analytics
+│  │  └─ disqus.html                   # - Disqus
+│  ├─ languages/                       # Localized languages
+│  ├─ footer.html                      # Footer bar
+│  ├─ header.html                      # Header bar
+│  ├─ language.html                    # Localized labels
+│  ├─ 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
+│  ├─ tabs.html                        # Tabs navigation
+│  ├─ tabs-item.html                   # Tabs navigation item
+│  ├─ toc.html                         # Table of contents
+│  └─ toc-item.html                    # Table of contents item
+├─ 404.html                            # 404 error page
+├─ base.html                           # Base template
+└─ main.html                           # Default page
+```
+
+### Overriding partials
+
+In order to override a partial, we can replace it with a file of the same name
+and location in the `overrides` directory. For example, to replace the original
+`footer.html`, create a `footer.html` file in the `overrides/partials`
+directory:
+
+``` sh
+.
+├─ overrides/
+│  └─ partials/
+│     └─ footer.html
+└─ mkdocs.yml
+```
+
+MkDocs will now use the new partial when rendering the theme. This can be done
+with any file.
+
+### Overriding blocks
+
+Besides overriding partials, it's also possible to override (and extend)
+_template blocks_, which are defined inside the templates and wrap specific
+features. To override a block, create a `main.html` file inside the `overrides`
+directory:
+
+``` sh
+.
+├─ overrides/
+│  └─ main.html
+└─ mkdocs.yml
+```
+
+Then, e.g. to override the site title, add the following line to `main.html`:
+
+``` html
+{% extends "base.html" %}
+
+{% block htmltitle %}
+  <title>Lorem ipsum dolor sit amet</title>
+{% endblock %}
+```
+
+Material for MkDocs provides the following template blocks:
+
+| Block name        | Purpose                                         |
+|:------------------|:------------------------------------------------|
+| `analytics`       | Wraps the Google Analytics integration          |
+| `announce`        | Wraps the announcement bar                      |
+| `config`          | Wraps the JavaScript application config         |
+| `content`         | Wraps the main content                          |
+| `disqus`          | Wraps the Disqus integration                    |
+| `extrahead`       | Empty block to add custom meta tags             |
+| `fonts`           | Wraps the font definitions                      |
+| `footer`          | Wraps the footer with navigation and copyright  |
+| `header`          | Wraps the fixed header bar                      |
+| `hero`            | Wraps the hero teaser (if available)            |
+| `htmltitle`       | Wraps the `<title>` tag                         |
+| `libs`            | Wraps the JavaScript libraries (header)         |
+| `outdated`        | Wraps the version warning                       |
+| `scripts`         | Wraps the JavaScript application (footer)       |
+| `source`          | Wraps the linked source files                   |
+| `site_meta`       | Wraps the meta tags in the document head        |
+| `site_nav`        | Wraps the site navigation and table of contents |
+| `styles`          | Wraps the stylesheets (also extra sources)      |
+| `tabs`            | Wraps the tabs navigation (if available)        |
+
+For more on this topic refer to the [MkDocs documentation][5].
+
+[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
+
+#### Additional variables
+
+Besides template blocks, Material for MkDocs provides extra variables for parts
+that cannot be overridden with template blocks (due to technical limitations of
+the template engine). If you want to add further information after the _Made
+with Material for MkDocs_ hint in the footer, add the following line to
+`main.html`:
+
+``` html
+{% extends "base.html" %}
+
+{% set extracopyright %}
+  <!-- Add your additional information here -->
+{% endset %}
+```
+
+Material for MkDocs provides the following additional variables:
+
+| Block name        | Purpose                                         |
+|:------------------|:------------------------------------------------|
+| `extracopyright`  | Adds custom copyright information               |
+
+## Theme development
+
+Material for MkDocs is built on top of [TypeScript][6], [RxJS][7] and [SASS][8],
+and uses a lean, custom build process to put everything together.[^1] 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.
+
+  [^1]:
+    Prior to version 7.0, the build was based on Webpack. This led to broken
+    builds due to frequent incompatibilities with loaders and plugins, so we
+    decided to swap Webpack for a leaner custom solution which is now based on
+    [RxJS][7] as the application itself. This enabled us to remove more than
+    500 dependencies (~30% less).
+
+  [6]: https://www.typescriptlang.org/
+  [7]: https://github.com/ReactiveX/rxjs
+  [8]: https://sass-lang.com
+
+### Environment setup
+
+In order to start development on Material for MkDocs, a [Node.js][9] version of
+at least 14 is required. First, clone the repository:
+
+```
+git clone https://github.com/squidfunk/mkdocs-material
+```
+
+Next, all dependencies need to be installed, which is done with:
+
+```
+cd mkdocs-material
+pip install -r requirements.txt
+pip install mkdocs-minify-plugin
+pip install mkdocs-redirects
+npm install
+```
+
+  [9]: https://nodejs.org
+
+### Development mode
+
+Start the watcher with:
+
+```
+npm start
+```
+
+Then, in a second session, start the MkDocs server with:
+
+```
+mkdocs serve
+```
+
+Point your browser to [localhost:8000][10] and you should see this documentation
+in front of you.
+
+!!! warning "Automatically generated files"
+
+    Never make any changes in the `material` directory, as the contents of this
+    directory are automatically generated from the `src` directory and will be
+    overridden when the theme is built.
+
+  [10]: http://localhost:8000
+
+### Building the theme
+
+When you're finished making your changes, you can build the theme by invoking:
+
+```
+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 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

+---
+template: overrides/main.html
+---
+
+# Data privacy
+
+In itself, Material for MkDocs does not perform any tracking and should adhere
+to the [General Data Protection Regulation][1] (GDPR), but it integrates with
+some third-party services that may not.
+
+  [1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
+
+## Third-party services
+
+### Google Fonts
+
+Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
+CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily 
+disabled][3] via `mkdocs.yml`.
+
+  [2]: setup/changing-the-fonts.md
+  [3]: setup/changing-the-fonts.md#disabling-font-loading
+
+### Google Analytics and Disqus
+
+Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] 
+integrations, both of which must be enabled explicitly, so there's no immediate
+action if you don't use those.
+
+  [4]: setup/setting-up-site-analytics.md#google-analytics
+  [5]: setup/adding-a-comment-system.md#disqus

docs/deprecations.md

+---
+template: overrides/main.html
+---
+
+# Deprecations
+
+This page includes a list of deprecations, indicating which features of Material
+for MkDocs were replaced with newer, more flexible alternatives, and thus should
+not be used anymore.
+
+## Front matter
+
+### Redirect
+
+:octicons-archive-24: Deprecated: 5.5 ·
+:octicons-trash-24: Removed: 6.0
+
+The `redirect` key, which could be added via [Metadata][1], allowed to
+specify a redirect from within a document to a new address, which is a good
+idea when moving content around:
+
+``` markdown
+---
+redirect: /path/to/new/file
+---
+```
+
+The [redirects][2] plugin provides the ability to define redirect mappings via
+`mkdocs.yml`, which is considered to be a much better solution to achieve the
+same result. It can be installed with `pip`:
+
+```
+pip install mkdocs-redirects
+```
+
+Redirect mappings can then be added to `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - redirects:
+      redirect_maps:
+        path/to/old/file.md: path/to/new/file.md
+```
+
+  [1]: reference/meta-tags.md#metadata
+  [2]: https://github.com/datarobot/mkdocs-redirects
+
+### Source link
+
+:octicons-archive-24: Deprecated: 5.5 ·
+:octicons-trash-24: Removed: 6.0
+
+The `source` and `path` keys, which could be added via [Metadata][1], showed
+a source icon at the top right corner of a document, linking a document to a
+single source file:
+
+``` markdown
+---
+path: tree/master/docs
+source: deprecations.md
+---
+```
+
+Only a single source file could be linked, which is useless if a document refers
+to multiple files (or multiple sections within a single file). A more flexible
+approach is to use the new [icon integration][3]:
+
+``` markdown
+[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
+```
+
+This will render as [:octicons-file-code-24: Source][4], which can be included
+at arbitrary positions in any document.
+
+  [3]: setup/changing-the-logo-and-icons.md#icons
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md
+
+### Hero
+
+:octicons-archive-24: Deprecated: 5.5 ·
+:octicons-trash-24: Removed: 6.0
+
+The `hero` key, which could be added via [Metadata][1], allowed to render a
+simple, text-only and page-local teaser text as part of a document. It could
+be set from front matter with:
+
+``` markdown
+---