Updated upgrading guide and changelog

This commit is contained in:
squidfunk
2020-09-27 12:05:16 +02:00
parent ca0b6a93b1
commit 01fdf26486
3 changed files with 970 additions and 697 deletions

View File

@@ -42,6 +42,17 @@ template: overrides/main.html
## Material for MkDocs ## Material for MkDocs
### 6.0.0 <small>_ September 25, 2020</small>
* Improved search result look and feel
* Improved search result stability while typing
* Improved search result grouping (pages + headings)
* Improved search result relevance and scoring
* Added display of missing query terms to search results
* Reduced size of the Docker image to improve CI build performance
* Removed hero partial in favor of custom implementation
* Removed deprecated front matter features
### 5.5.14 <small>_ September 23, 2020</small> ### 5.5.14 <small>_ September 23, 2020</small>
* Improved spacing around image captions * Improved spacing around image captions

View File

@@ -115,7 +115,6 @@ The directory layout of the theme is as follows:
│ ├─ language/ # Localized languages │ ├─ language/ # Localized languages
│ ├─ footer.html # Footer bar │ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar │ ├─ header.html # Header bar
│ ├─ hero.html # Hero teaser
│ ├─ language.html # Localized labels │ ├─ language.html # Localized labels
│ ├─ logo.html # Logo in header and sidebar │ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation │ ├─ nav.html # Main navigation

View File

@@ -16,29 +16,21 @@ Inspect the currently installed version with:
pip show mkdocs-material pip show mkdocs-material
``` ```
## Upgrading from 4.x to 5.x ## Upgrading from 5.x to 6.x
### What's new? ### What's new?
* Reactive architecture try `app.dialog$.next("Hi!")` in the console * Improved search result look and feel
* [Instant loading][1] make Material behave like a Single Page Application * Improved search result stability while typing
* Improved CSS customization with [CSS variables][2] set your brand's colors * Improved search result grouping (pages + headings)
* Improved CSS resilience, e.g. proper sidebar locking for customized headers * Improved search result relevance and scoring
* Improved [icon integration][3] and configuration now including over 5k icons * Added display of missing query terms to search results
* Added possibility to use any icon for logo, repository and social links * Reduced size of the Docker image to improve CI build performance
* Search UI does not freeze anymore (moved to web worker) * Removed hero partial in favor of [custom implementation][1]
* Search index built only once when using instant loading * Removed [deprecated front matter features][2]
* Improved extensible keyboard handling
* 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]: setup/setting-up-navigation.md#instant-loading [1]: http://localhost:8000/deprecations/#hero
[2]: setup/changing-the-colors.md#custom-colors [2]: http://localhost:8000/deprecations/#front-matter
[3]: setup/changing-the-logo-and-icons.md#icons
[4]: setup/setting-up-site-search.md#built-in-search
### Changes to `mkdocs.yml` ### Changes to `mkdocs.yml`
@@ -48,7 +40,280 @@ does not contain the key, you can skip it.
#### `theme.feature` #### `theme.feature`
Optional features like [tabs][5] and [instant loading][1] are now implemented as All feature flags that can be set from `mkdocs.yml`, like [tabs][3] and
[instant loading][4], are now prefixed with the name of the component or
function they apply to, e.g. `navigation.*`:
=== "6.x"
``` yaml
theme:
features:
- navigation.tabs
- navigation.instant
```
=== "5.x"
``` yaml
theme:
features:
- tabs
- instant
```
[3]: setup/setting-up-navigation.md#navigation-tabs
[4]: setup/setting-up-navigation.md#instant-loading
### 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
??? quote "`base.html`"
``` diff
@@ -22,13 +22,6 @@
{% import "partials/language.html" as lang with context %}
-<!-- Theme options -->
-{% set palette = config.theme.palette %}
-{% if not palette is mapping %}
- {% set palette = palette | first %}
-{% endif %}
-{% set font = config.theme.font %}
-
<!doctype html>
<html lang="{{ lang.t('language') }}" class="no-js">
<head>
@@ -45,21 +38,8 @@
<meta name="description" content="{{ config.site_description }}" />
{% endif %}
- <!-- Redirect -->
- {% if page and page.meta and page.meta.redirect %}
- <script>
- var anchor = window.location.hash.substr(1)
- location.href = '{{ page.meta.redirect }}' +
- (anchor ? '#' + anchor : '')
- </script>
-
- <!-- Fallback in case JavaScript is not available -->
- <meta http-equiv="refresh" content="0; url={{ page.meta.redirect }}" />
- <meta name="robots" content="noindex" />
- <link rel="canonical" href="{{ page.meta.redirect }}" />
-
<!-- Canonical -->
- {% elif page.canonical_url %}
+ {% if page.canonical_url %}
<link rel="canonical" href="{{ page.canonical_url }}" />
{% endif %}
@@ -96,20 +76,21 @@
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
<!-- Extra color palette -->
- {% if palette.scheme or palette.primary or palette.accent %}
+ {% if config.theme.palette %}
+ {% set palette = config.theme.palette %}
<link
rel="stylesheet"
href="{{ 'assets/stylesheets/palette.css' | url }}"
/>
- {% endif %}
- <!-- Theme-color meta tag for Android -->
- {% if palette.primary %}
- {% import "partials/palette.html" as map %}
- {% set primary = map.primary(
- palette.primary | replace(" ", "-") | lower
- ) %}
- <meta name="theme-color" content="{{ primary }}" />
+ <!-- Theme-color meta tag for Android -->
+ {% if palette.primary %}
+ {% import "partials/palette.html" as map %}
+ {% set primary = map.primary(
+ palette.primary | replace(" ", "-") | lower
+ ) %}
+ <meta name="theme-color" content="{{ primary }}" />
+ {% endif %}
{% endif %}
{% endblock %}
@@ -120,7 +101,8 @@
{% block fonts %}
<!-- Load fonts from Google -->
- {% if font != false %}
+ {% if config.theme.font != false %}
+ {% set font = config.theme.font %}
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin />
<link
rel="stylesheet"
@@ -169,8 +151,12 @@
<!-- Text direction and color palette, if defined -->
{% set direction = config.theme.direction or lang.t('direction') %}
- {% if palette.scheme or palette.primary or palette.accent %}
- {% set scheme = palette.scheme | lower %}
+ {% if config.theme.palette %}
+ {% set palette = config.theme.palette %}
+ {% if not palette is mapping %}
+ {% set palette = palette | first %}
+ {% endif %}
+ {% set scheme = palette.scheme | replace(" ", "-") | lower %}
{% set primary = palette.primary | replace(" ", "-") | lower %}
{% set accent = palette.accent | replace(" ", "-") | lower %}
<body
@@ -179,18 +165,19 @@
data-md-color-primary="{{ primary }}"
data-md-color-accent="{{ accent }}"
>
+
+ <!-- Experimental: set color scheme based on preference -->
+ {% if "preference" == scheme %}
+ <script>
+ if (matchMedia("(prefers-color-scheme: dark)").matches)
+ document.body.setAttribute("data-md-color-scheme", "slate")
+ </script>
+ {% endif %}
+
{% else %}
<body dir="{{ direction }}">
{% endif %}
- <!-- Experimental: set color scheme based on preference -->
- {% if "preference" == palette.scheme %}
- <script>
- if (matchMedia("(prefers-color-scheme: dark)").matches)
- document.body.setAttribute("data-md-color-scheme", "slate")
- </script>
- {% endif %}
-
<!--
State toggles - we need to set autocomplete="off" in order to reset the
drawer on back button invocation in some browsers
@@ -243,15 +230,11 @@
<div class="md-container" data-md-component="container">
<!-- Hero teaser -->
- {% block hero %}
- {% if page and page.meta and page.meta.hero %}
- {% include "partials/hero.html" with context %}
- {% endif %}
- {% endblock %}
+ {% block hero %}{% endblock %}
<!-- Tabs navigation -->
{% block tabs %}
- {% if "tabs" in config.theme.features %}
+ {% if "navigation.tabs" in config.theme.features %}
{% include "partials/tabs.html" %}
{% endif %}
{% endblock %}
@@ -310,13 +293,6 @@
</a>
{% endif %}
- <!-- Link to source file -->
- {% block source %}
- {% if page and page.meta and page.meta.source %}
- {% include "partials/source-link.html" %}
- {% endif %}
- {% endblock %}
-
<!--
Hack: check whether the content contains a h1 headline. If it
doesn't, the page title (or respectively site name) is used
@@ -370,7 +346,10 @@
"search.result.placeholder",
"search.result.none",
"search.result.one",
- "search.result.other"
+ "search.result.other",
+ "search.result.more.one",
+ "search.result.more.other",
+ "search.result.term.missing"
] -%}
{%- set _ = translations.update({ key: lang.t(key) }) -%}
{%- endfor -%}
```
??? quote "`partials/hero.html`"
``` diff
@@ -1,12 +0,0 @@
-{#-
- This file was automatically generated - do not edit
--#}
-{% set class = "md-hero" %}
-{% if "tabs" not in config.theme.features %}
- {% set class = "md-hero md-hero--expand" %}
-{% endif %}
-<div class="{{ class }}" data-md-component="hero">
- <div class="md-hero__inner md-grid">
- {{ page.meta.hero }}
- </div>
-</div>
```
??? quote "`partials/source-link`"
``` diff
-{#-
- This file was automatically generated - do not edit
--#}
-{% import "partials/language.html" as lang with context %}
-{% set repo = config.repo_url %}
-{% if repo | last == "/" %}
- {% set repo = repo[:-1] %}
-{% endif %}
-{% 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" %}
- {% include ".icons/" ~ icon ~ ".svg" %}
-</a>
```
## Upgrading from 4.x to 5.x
### What's new?
* Reactive architecture try `#!js app.dialog$.next("Hi!")` in the console
* [Instant loading][4] make Material behave like a Single Page Application
* Improved CSS customization with [CSS variables][5] 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][7]
* 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, ...)
[5]: setup/changing-the-colors.md#custom-colors
[6]: setup/changing-the-logo-and-icons.md#icons
[7]: setup/setting-up-site-search.md#built-in-search
### 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][3] and [instant loading][4] are now implemented as
flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`: flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
=== "5.x" === "5.x"
@@ -68,8 +333,6 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
tabs: true tabs: true
``` ```
[5]: setup/setting-up-navigation.md#navigation-tabs
#### `theme.logo.icon` #### `theme.logo.icon`
The logo icon configuration was centralized under `theme.icon.logo` and can now The logo icon configuration was centralized under `theme.icon.logo` and can now
@@ -173,7 +436,7 @@ matches the new structure:
- If you've overridden a **template**, check the respective `*.html` file for - If you've overridden a **template**, check the respective `*.html` file for
potential changes potential changes
#### `base.html` ??? quote "`base.html`"
``` diff ``` diff
@@ -2,7 +2,6 @@ @@ -2,7 +2,6 @@
@@ -424,7 +687,7 @@ matches the new structure:
{% endfor %} {% endfor %}
``` ```
#### `partials/footer.html` ??? quote "`partials/footer.html`"
``` diff ``` diff
@@ -5,34 +5,34 @@ @@ -5,34 +5,34 @@
@@ -475,7 +738,7 @@ matches the new structure:
{% endif %} {% endif %}
``` ```
#### `partials/header.html` ??? quote "`partials/header.html`"
``` diff ``` diff
@@ -2,51 +2,43 @@ @@ -2,51 +2,43 @@
@@ -566,7 +829,7 @@ matches the new structure:
</header> </header>
``` ```
#### `partials/hero.html` ??? quote "`partials/hero.html`"
``` diff ``` diff
@@ -1,9 +1,8 @@ @@ -1,9 +1,8 @@
@@ -582,7 +845,7 @@ matches the new structure:
<div class="{{ class }}" data-md-component="hero"> <div class="{{ class }}" data-md-component="hero">
``` ```
#### `partials/language.html` ??? quote "`partials/language.html`"
``` diff ``` diff
@@ -3,12 +3,4 @@ @@ -3,12 +3,4 @@
@@ -601,7 +864,7 @@ matches the new structure:
+{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %} +{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}
``` ```
#### `partials/logo.html` ??? quote "`partials/logo.html`"
``` diff ``` diff
@@ -0,0 +1,9 @@ @@ -0,0 +1,9 @@
@@ -616,7 +879,7 @@ matches the new structure:
+{% endif %} +{% endif %}
``` ```
#### `partials/nav-item.html` ??? quote "`partials/nav-item.html`"
``` diff ``` diff
@@ -14,9 +14,15 @@ @@ -14,9 +14,15 @@
@@ -648,7 +911,7 @@ matches the new structure:
<a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active"> <a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">
``` ```
#### `partials/nav.html` ??? quote "`partials/nav.html`"
``` diff ``` diff
@@ -1,14 +1,10 @@ @@ -1,14 +1,10 @@
@@ -672,7 +935,7 @@ matches the new structure:
</label> </label>
``` ```
#### `partials/search.html` ??? quote "`partials/search.html`"
``` diff ``` diff
@@ -6,15 +6,18 @@ @@ -6,15 +6,18 @@
@@ -700,7 +963,7 @@ matches the new structure:
</div> </div>
``` ```
#### `partials/social.html` ??? quote "`partials/social.html`"
``` diff ``` diff
@@ -3,9 +3,12 @@ @@ -3,9 +3,12 @@
@@ -720,7 +983,7 @@ matches the new structure:
{% endif %} {% endif %}
``` ```
#### `partials/source-date.html` ??? quote "`partials/source-date.html`"
``` diff ``` diff
@@ -0,0 +1,15 @@ @@ -0,0 +1,15 @@
@@ -741,7 +1004,7 @@ matches the new structure:
+</div> +</div>
``` ```
#### `partials/source-link.html` ??? quote "`partials/source-link.html`"
``` diff ``` diff
@@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
@@ -760,7 +1023,7 @@ matches the new structure:
+</a> +</a>
``` ```
#### `partials/source.html` ??? quote "`partials/source.html`"
``` diff ``` diff
@@ -2,24 +2,11 @@ @@ -2,24 +2,11 @@
@@ -795,7 +1058,7 @@ matches the new structure:
</div> </div>
``` ```
#### `partials/tabs-item.html` ??? quote "`partials/tabs-item.html`"
``` diff ``` diff
@@ -1,7 +1,7 @@ @@ -1,7 +1,7 @@
@@ -809,7 +1072,7 @@ matches the new structure:
<a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active"> <a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active">
``` ```
#### `partials/tabs.html` ??? quote "`partials/tabs.html`"
``` diff ``` diff
@@ -5,7 +5,7 @@ @@ -5,7 +5,7 @@
@@ -823,7 +1086,7 @@ matches the new structure:
{% for nav_item in nav %} {% for nav_item in nav %}
``` ```
#### `partials/toc-item.html` ??? quote "`partials/toc-item.html`"
``` diff ``` diff
@@ -6,7 +6,7 @@ @@ -6,7 +6,7 @@
@@ -837,7 +1100,7 @@ matches the new structure:
{% include "partials/toc-item.html" %} {% include "partials/toc-item.html" %}
``` ```
#### `partials/toc.html` ??? quote "`partials/toc.html`"
``` diff ``` diff
@@ -2,35 +2,22 @@ @@ -2,35 +2,22 @@