Improved getting started guide and added further guides

docs/creating-your-site.md

@@ -1,73 +0,0 @@
----
-template: overrides/main.html
----
-
-# Creating your site
-
-After you've installed Material for MkDocs, bootstrap your site using the
-`mkdocs` executable. Change to the directory where you want your documentation
-to be located and enter:
-
-``` sh
-mkdocs new .
-```
-
-This will create the following structure along your existing files:
-
-```
-├─ docs/
-│  └─ index.md
-└─ mkdocs.yml
-```
-
-## Configuration
-
-Depending on your [installation method][1], you can now add the following lines
-to `mkdocs.yml` in your project root. If you installed Material for MkDocs with
-`pip` or pulled the Docker image, add:
-
-``` yaml
-theme:
-  name: material
-```
-
-If you cloned Material for MkDocs from GitHub, add:
-
-``` yaml
-theme:
-  name: null
-  custom_dir: mkdocs-material/material
-```
-
-!!! todo "Add note about many customization options with links to guides"
-
-## Previewing
-
-MkDocs includes a live preview server, so you can preview your changes as you
-write your documentation. 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][2] and you should see:
-
-[![Creating your site][3]][3]
-
-  [1]: getting-started.md#installation
-  [2]: http://localhost:8000
-  [3]: assets/screenshots/creating-your-site.png

docs/getting-started.md

@@ -5,13 +5,16 @@ template: overrides/main.html
 # Getting started
 
 Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
-towards technical 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].
+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]: getting-started/troubleshooting.md
 
 ## Installation
 
@@ -24,16 +27,13 @@ pip install mkdocs-material
 ```
 
 This will automatically install compatible versions of all dependencies:
-[MkDocs][1], [Markdown][4], [Pygments][5] and [PyMdown Extensions][6]. Material
+[MkDocs][1], [Markdown][5], [Pygments][6] and [PyMdown Extensions][7]. Material
 for MkDocs always strives to support the latest versions, so there's no need to
 install those packages separately.
 
-If you're running into problems, read the section on [virtual environments][7].
-
-  [4]: https://python-markdown.github.io/
-  [5]: https://pygments.org/
-  [6]: https://facelessuser.github.io/pymdown-extensions/
-  [7]: #virtual-environments
+  [5]: https://python-markdown.github.io/
+  [6]: https://pygments.org/
+  [7]: https://facelessuser.github.io/pymdown-extensions/
 
 ### with docker
 
@@ -69,54 +69,3 @@ pip install -r mkdocs-material/requirements.txt
 ```
 
   [9]: https://github.com/squidfunk/mkdocs-material
-
-## 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:
-
-``` sh
-which python
-```
-
-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

docs/getting-started/creating-your-site.md

@@ -0,0 +1,137 @@
+---
+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 .
+```
+
+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 colors][3]
+* [Changing the fonts][4]
+* [Changing the language][5]
+* [Navigation structure][6]
+* [Syntax highlighting][7]
+* [Adding a landing page][8]
+* [Adding an announcement bar][9]
+* [Adding icons and emojis][10]
+* [Adding footer links][11]
+* [Adding site analytics][12]
+* [Adding a comment system][13]
+
+  [2]: ../getting-started.md#installation
+  [3]: ../guides/changing-colors.md
+  [4]: ../guides/changing-the-fonts.md
+  [5]: ../guides/changing-the-language.md
+  [6]: ../guides/navigation-structure.md
+  [7]: ../guides/syntax-highlighting.md
+  [8]: ../guides/adding-a-landing-page.md
+  [9]: ../guides/adding-an-announcement-bar.md
+  [10]: ../guides/adding-icons-and-emojis.md
+  [11]: ../guides/adding-footer-links.md
+  [12]: ../guides/adding-site-analytics.md
+  [13]: ../guides/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"
+
+    ```
+    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][14] and you should see:
+
+[![Creating your site][15]][14]
+
+  [14]: http://localhost:8000
+  [15]: ../assets/guides/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][16], [GitLab Pages][17], a CDN of your
+choice or your private web space.
+
+  [16]: publishing-your-site.md#github-pages
+  [17]: publishing-your-site.md#gitlab-pages

docs/getting-started/customization.md

@@ -0,0 +1,247 @@
+---
+template: overrides/main.html
+---
+
+# Customization
+
+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
+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 an existing theme, you can just add your stylesheets and JavaScript
+files to the `docs` directory.
+
+  [1]: https://www.mkdocs.org
+
+### Additional stylesheets
+
+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
+mkdir docs/stylesheets
+touch docs/stylesheets/extra.css
+```
+
+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
+mkdir docs/javascripts
+touch docs/javascripts/extra.js
+```
+
+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 part), you can
+extend the theme. MkDocs supports [theme extension][4], an easy way to override
+parts of a theme without forking and changing the main theme.
+
+  [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 `mkdocs.yml`, and create a new folder
+for `overrides` which you reference using `custom_dir`:
+
+``` 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
+.
+├─ assets/
+│  ├─ images/                          # Images and icons
+│  ├─ javascripts/                     # JavaScript
+│  └─ stylesheets/                     # Stylesheets
+├─ partials/
+│  ├─ integrations/                    # 3rd-party integrations
+│  ├─ language/                        # Localized languages
+│  ├─ footer.html                      # Footer bar
+│  ├─ header.html                      # Header bar
+│  ├─ hero.html                        # Hero teaser
+│  ├─ 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 the footer, we can replace the `footer.html` partial with
+our own partial. To do this, create the file `partials/footer.html` in the
+`overrides` directory. MkDocs will now use the new partial when rendering the
+theme. This can be done with any file.
+
+### Overriding blocks
+
+Besides overriding partials, it's also possible to override (and extend) so
+called *blocks*, which are defined inside the templates and wrap specific
+features. To override a block, create a `main.html` inside the `overrides`
+directory and define the block, e.g.:
+
+``` jinja
+{% extends "base.html" %}
+
+{% block htmltitle %}
+  <title>Lorem ipsum dolor sit amet</title>
+{% endblock %}
+```
+
+Material for MkDocs provides the following template blocks:
+
+| Block name   | Wrapped contents                                |
+| ------------ | ----------------------------------------------- |
+| `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 define additional meta tags      |
+| `fonts`      | Wraps the webfont 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)         |
+| `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
+
+## Theme development
+
+Material for MkDocs uses [Webpack][6] as a build tool to leverage modern web
+technologies like [TypeScript][7] and [SASS][8]. If you want to make more
+fundamental changes, it may be necessary to make the adjustments directly in
+the source of the theme and recompile it.
+
+  [6]: https://webpack.js.org/
+  [7]: https://www.typescriptlang.org/
+  [8]: https://sass-lang.com
+
+### Environment setup
+
+In order to start development on Material for MkDocs, a [Node.js][9] version of
+at least 12 is required. First, clone the repository:
+
+``` sh
+git clone https://github.com/squidfunk/mkdocs-material
+```
+
+Next, all dependencies need to be installed, which is done with:
+
+``` sh
+cd mkdocs-material
+pip install -r requirements.txt
+pip install mkdocs-minify-plugin
+npm install
+```
+
+  [9]: https://nodejs.org
+
+### Development mode
+
+Start the Webpack watchdog with:
+
+``` sh
+npm start
+```
+
+Then, in a second session, start the MkDocs server with:
+
+```sh
+mkdocs serve
+```
+
+Point your browser to [localhost:8000][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
+
+### Build process
+
+When you're finished making your changes, you can build the theme by invoking:
+
+``` sh
+npm run build
+```
+
+This triggers the production-level compilation and minification of all
+stylesheets and JavaScript sources. When the command exits, the final files are
+located in the `material` directory. Add the `theme_dir` variable pointing to
+the aforementioned directory in the original `mkdocs.yml`.
+
+Now you can run `mkdocs build` and you should see your documentation with your
+changes to the original theme.

docs/getting-started/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 automatically deploy it 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
+      - pull_request
+    jobs:
+      deploy:
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+        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/getting-started/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. 
+
+1. **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
+
+2. **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/guides/changing-colors.md

@@ -0,0 +1,274 @@
+---
+template: overrides/main.html
+---
+
+# Changing 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 adjusted with a few lines of CSS to
+fit your brand identity by using [CSS variables][2].
+
+  [1]: http://www.materialui.co/colors
+  [2]: #customization
+
+## Configuration
+
+### 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: default
+```
+
+:material-cursor-default-click-outline: click on a tile to change the color
+scheme:
+
+<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() {
+      var name = document.querySelector("#__code_0 code span:nth-child(7)")
+      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = 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
+```
+
+### Primary color
+
+> 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:
+
+<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() {
+      var name = document.querySelector("#__code_2 code span:nth-child(7)")
+      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = this.getAttribute(attr)
+    })
+  })
+</script>
+
+### Accent color
+
+> 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] {
+    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() {
+      var name = document.querySelector("#__code_3 code span:nth-child(7)")
+      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = this.getAttribute(attr)
+    })
+  })
+</script>
+
+## Customization
+
+Material for MkDocs implements colors using [CSS variables][3] (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][4] 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][5], [admonitions][6], 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);
+}
+```
+
+  [3]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+  [4]: ../getting-started/customization.md#additional-stylesheets
+
+## Caveats
+
+!!! 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.

docs/guides/changing-the-fonts.md

@@ -0,0 +1,38 @@
+---
+template: overrides/main.html
+---
+
+# Changing the fonts
+
+## Configuration
+
+> Default: `Roboto` and `Roboto Mono`
+
+The [Roboto font family][1] 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][2] and can be changed to any
+supported typeface, like for example the [Ubuntu font family][3]:
+
+``` 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
+```
+
+  [1]: https://fonts.google.com/specimen/Roboto
+  [2]: https://fonts.google.com
+  [3]: https://fonts.google.com/specimen/Ubuntu
+
+## Customization
+
+TBD

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.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.map": "assets/stylesheets/main.61729dd2.min.css.map",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.ee9eac3c.min.css",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.ee9eac3c.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
   "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
 }

material/base.html

@@ -41,7 +41,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.61729dd2.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.ee9eac3c.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e185632b.min.css' | url }}">
       {% endif %}

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>

mkdocs.yml

@@ -129,19 +129,22 @@ nav:
   - Home: index.md
   - Getting started:
     - Installation: getting-started.md
-    - Creating your site: creating-your-site.md
-    - Publishing your site: publishing-your-site.md
+    - Creating your site: getting-started/creating-your-site.md
+    - Publishing your site: getting-started/publishing-your-site.md
+    - Customization: getting-started/customization.md
+    - Troubleshooting: getting-started/troubleshooting.md
   - Guides:
     - Changing colors: guides/changing-colors.md
     - Changing the fonts: guides/changing-the-fonts.md
     - Changing the language: guides/changing-the-language.md
     - Navigation structure: guides/navigation-structure.md
     - Syntax highlighting: guides/syntax-highlighting.md
-    - Third-party integrations: guides/third-party-integrations.md
     - Adding a landing page: guides/adding-a-landing-page.md
     - Adding an announcement bar: guides/adding-an-announcement-bar.md
     - Adding icons and emojis: guides/adding-icons-and-emojis.md
     - Adding footer links: guides/adding-footer-links.md
+    - Adding site analytics: guides/adding-site-analytics.md
+    - Adding a comment systems: guides/adding-a-comment-system.md
   - Extensions:
     - Admonition: extensions/admonition.md
     - CodeHilite: extensions/codehilite.md

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