diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 5562d70cc..4054c0598 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -2,7 +2,12 @@
## Our Pledge
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
## Our Standards
@@ -16,31 +21,54 @@ Examples of behavior that contributes to creating a positive environment include
Examples of unacceptable behavior by participants include:
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
## Our Responsibilities
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
## Scope
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
## Enforcement
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at https://gitter.im/squidfunk/mkdocs-material. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at
+https://gitter.im/squidfunk/mkdocs-material. The project team will review and
+investigate all complaints, and will respond in a way that it deems appropriate
+to the circumstances. The project team is obligated to maintain confidentiality
+with regard to the reporter of an incident. Further details of specific
+enforcement policies may be posted separately.
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
## Attribution
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b0173dc43..ca43ddeb1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,7 +1,7 @@
# Contributing
-Interested in contributing to the Material theme? Want to report a bug? Before
-you do, please read the following guidelines.
+Interested in contributing to the Material for MkDocs? Want to report a bug?
+Before you do, please read the following guidelines.
## Submission context
@@ -27,8 +27,8 @@ a Pull Request with a fix. However, before doing so, please read the
You can request a new feature by submitting an issue to our GitHub Repository.
If you would like to implement a new feature, please submit an issue with a
proposal for your work first, to be sure that it is of use for everyone, as
-the Material theme is highly opinionated. Please consider what kind of change
-it is:
+the Material for MkDocs is highly opinionated. Please consider what kind of
+change it is:
* For a **major feature**, first open an issue and outline your proposal so
that it can be discussed. This will also allow us to better coordinate our
@@ -37,8 +37,8 @@ it is:
* **Small features and bugs** can be crafted and directly submitted as a Pull
Request. However, there is no guarantee that your feature will make it into
- the master, as it's always a matter of opinion whether if benefits the
- overall functionality of the theme.
+ the `master`, as it's always a matter of opinion whether if benefits the
+ overall functionality of the project.
## Submission guidelines
diff --git a/README.md b/README.md
index 831e642e7..54a758421 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ Append the following line to your project's `mkdocs.yml`:
``` yaml
theme:
- name: 'material'
+ name: material
```
## What to expect
diff --git a/docs/customization.md b/docs/customization.md
index 8ed7f716d..a810cedaa 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -30,7 +30,7 @@ Then, add the following line to your `mkdocs.yml`:
``` yaml
extra_css:
- - 'stylesheets/extra.css'
+ - stylesheets/extra.css
```
Spin up the development server with `mkdocs serve` and start typing your
@@ -52,7 +52,7 @@ Then, add the following line to your `mkdocs.yml`:
``` yaml
extra_javascript:
- - 'javascripts/extra.js'
+ - javascripts/extra.js
```
Further assistance can be found in the [MkDocs documentation][2].
@@ -75,8 +75,8 @@ new folder for overrides, e.g. `theme`, which you reference using `custom_dir`:
``` yaml
theme:
- name: 'material'
- custom_dir: 'theme'
+ name: material
+ custom_dir: theme
```
!!! warning "Theme extension prerequisites"
diff --git a/docs/data-privacy.md b/docs/data-privacy.md
index 2bec2591d..0540d3018 100644
--- a/docs/data-privacy.md
+++ b/docs/data-privacy.md
@@ -1,12 +1,8 @@
-# Compliance with GDPR
+# Data privacy
-## Material does not process any personal data
-
-Material is a theme for MkDocs, a static site generator. In itself, Material
-does not perform any tracking or processing of personal data. However, some of
-the third-party services that Material integrates with may actually be in breach
-with the [General Data Protection Regulation][1] (GDPR) and need to be evaluated
-carefully.
+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
@@ -14,34 +10,30 @@ carefully.
### Google Fonts
-Material makes fonts [easily configurable][2] by relying on Google Fonts CDN.
-However, embedding fonts from Google is currently within a gray area as there's
+Material for MkDocs makes fonts [easily configurable][2] by relying on Google
+Fonts CDN. Embedding fonts from Google is currently within a gray area as there's
no official statement or ruling regarding GDPR compliance and the topic is still
-[actively discussed][3]. For this reason, if you need to ensure GDPR compliance,
-you should disable the usage of the Google Font CDN with:
+[actively discussed][3]. If you need to ensure GDPR compliance, you may disable
+the usage of the Google Font CDN with:
``` yaml
theme:
font: false
```
-When Google Fonts are disabled, Material will default to **Helvetica Neue** and
-**Monaco** with their corresponding fall backs, relying on system fonts. You
-could however include your own, self-hosted webfont by [overriding][4] the
-`fonts` block.
+When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
+Neue** and **Monaco** with their corresponding fall backs, relying on system
+fonts. You can easily include your own, self-hosted webfont by [overriding][4]
+the `fonts` block.
-The icon fonts (Material and FontAwesome) are bundled with the theme, and thus
-self-hosted so there's no third-party involved.
-
- [2]: getting-started.md#font-family
+ [2]: getting-started.md#fonts
[3]: https://github.com/google/fonts/issues/1495
[4]: customization.md#overriding-template-blocks
### Google Analytics and Disqus
-Material comes with [Google Analytics][5] and [Disqus][6] integrations that need
-to be *enabled explicitly*. Disable both integrations in order to be in
-compliance with the GDPR.
+Material for MkDocs comes with optional [Google Analytics][5] and [Disqus][6]
+integrations, both of which must be enabled explicitly.
[5]: getting-started.md#google-analytics
[6]: getting-started.md#disqus
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 15da6cbde..3a5864fd4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -128,7 +128,7 @@ a package manager add:
``` yaml
theme:
- name: 'material'
+ name: material
```
If you cloned Material for MkDocs from GitHub add:
@@ -136,7 +136,7 @@ If you cloned Material for MkDocs from GitHub add:
``` yaml
theme:
name: null
- custom_dir: 'mkdocs-material/material'
+ custom_dir: mkdocs-material/material
```
MkDocs includes a development server, so you can preview your changes as you
diff --git a/docs/plugins/search.md b/docs/plugins/search.md
index e74a3ae22..69b0cc10d 100644
--- a/docs/plugins/search.md
+++ b/docs/plugins/search.md
@@ -84,6 +84,8 @@ plugins:
### Prebuilding :hatching_chick:
+> Default: `false`
+
MkDocs can generate a [prebuilt index][4] 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
diff --git a/docs/releases/4.md b/docs/releases/4.md
new file mode 100644
index 000000000..16b156671
--- /dev/null
+++ b/docs/releases/4.md
@@ -0,0 +1,26 @@
+# Material for MkDocs 4
+
+## 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.
diff --git a/docs/releases/5.md b/docs/releases/5.md
new file mode 100644
index 000000000..6f8c1af65
--- /dev/null
+++ b/docs/releases/5.md
@@ -0,0 +1,820 @@
+# Material for MkDocs 5
+
+## Highlights
+
+* Reactive architecture – try `__material.dialog$.next("Hi!")` in the console
+* [Instant loading][5] – make Material behave like a Single Page Application
+* Improved CSS customization with [CSS variables][1] – set your brand's colors
+* Improved CSS resilience, e.g. proper sidebar locking for customized headers
+* Improved [icon integration][6] 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 displaying stars and forks for GitLab repositories
+* Support for scroll snapping of sidebars and search results
+* Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
+* Slight facelifting of some UI elements (Admonitions, tables, ...)
+
+ [1]: https://github.com/squidfunk/mkdocs-material/blob/081d540127c41703da3d73aa69eb521615c1cb89/src/assets/stylesheets/base/_colors.scss#L27-L55
+ [2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+
+## How to upgrade
+
+### Changes to `mkdocs.yml`
+
+Following is a list of changes that need to be made to `mkdocs.yml`. Note that
+you only have to adjust the value if you defined it, so if your configuration
+does not contain the key, you can skip it.
+
+#### `theme.feature`
+
+Optional features like [tabs][4] and [instant loading][5] are now implemented as
+flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ features:
+ - tabs
+ - instant
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ theme:
+ feature:
+ tabs: true
+ ```
+
+ [4]: ../../../getting-started/#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]:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ icon:
+ logo: material/cloud
+ ```
+
+ [6]: ../../../getting-started/#icons
+
+=== "4.x"
+
+ ``` yaml
+ theme:
+ logo:
+ icon: cloud
+ ```
+
+#### `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]:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ icon:
+ repo: fontawesome/brands/gitlab
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ repo_icon: gitlab
+ ```
+
+#### `extra.search.*`
+
+Search is now configured as part of the [plugin options][7]. Note that the
+search languages must now be listed as an array of strings and the `tokenizer`
+was renamed to `separator`:
+
+=== "5.x"
+
+ ``` yaml
+ plugins:
+ - search:
+ separator: [\s\-\.]+
+ lang:
+ - en
+ - de
+ - ru
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ search:
+ language: en, de, ru
+ tokenizer: [\s\-\.]+
+ ```
+
+ [7]: ../../../plugins/search/#configuration
+
+#### `extra.social.*`
+
+Social links stayed in the same place, but the `type` key was renamed to `icon`
+in order to match the new way of specifying which icon to be used:
+
+=== "5.x"
+
+ ``` yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/github-alt
+ link: https://github.com/squidfunk
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ social:
+ - type: github
+ link: https://github.com/squidfunk
+ ```
+
+### Changes to `*.html` files
+
+The templates have undergone a set of changes to make them future-proof. If
+you've used theme extension to override a block or template, make sure that it
+matches the new structure:
+
+- If you've overridden a **block**, check `base.html` for potential changes
+- If you've overridden a **template**, check the respective `*.html` file for
+ potential changes
+
+#### `base.html`
+
+``` diff
+@@ -2,7 +2,6 @@
+ This file was automatically generated - do not edit
+ -#}
+ {% import "partials/language.html" as lang with context %}
+-{% set feature = config.theme.feature %}
+ {% set palette = config.theme.palette %}
+ {% set font = config.theme.font %}
+
+@@ -30,19 +29,6 @@
+ {% elif config.site_author %}
+
+ {% endif %}
+- {% for key in [
+- "clipboard.copy",
+- "clipboard.copied",
+- "search.language",
+- "search.pipeline.stopwords",
+- "search.pipeline.trimmer",
+- "search.result.none",
+- "search.result.one",
+- "search.result.other",
+- "search.tokenizer"
+- ] %}
+-
+- {% endfor %}
+
+
+ {% endblock %}
+@@ -56,9 +42,9 @@
+ {% endif %}
+ {% endblock %}
+ {% block styles %}
+-
++
+ {% if palette.primary or palette.accent %}
+-
++
+ {% endif %}
+ {% if palette.primary %}
+ {% import "partials/palette.html" as map %}
+@@ -69,20 +55,17 @@
+ {% endif %}
+ {% endblock %}
+ {% block libs %}
+-
+ {% endblock %}
+ {% block fonts %}
+ {% if font != false %}
+
+
+
+ {% endif %}
+ {% endblock %}
+-
+ {% if config.extra.manifest %}
+
+ {% endif %}
+@@ -95,47 +78,46 @@
+ {% endblock %}
+ {% block extrahead %}{% endblock %}
+
++ {% set direction = config.theme.direction | default(lang.t('direction')) %}
+ {% if palette.primary or palette.accent %}
+ {% set primary = palette.primary | replace(" ", "-") | lower %}
+ {% set accent = palette.accent | replace(" ", "-") | lower %}
+-