--- template: overrides/main.html --- # Upgrading Upgrade to the latest version with: ``` pip install --upgrade mkdocs-material ``` Inspect the currently installed version with: ``` pip show mkdocs-material ``` ## Upgrading from 5.x to 6.x ### What's new? * 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 vendor bundle by 25% (84kb → 67kb) * Reduced size of the Docker image to improve CI build performance * Removed hero partial in favor of [custom implementation][1] * Removed [deprecated front matter features][2] [1]: deprecations.md#hero [2]: deprecations.md#front-matter ### 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.features` 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 %} - -{% set palette = config.theme.palette %} -{% if not palette is mapping %} - {% set palette = palette | first %} -{% endif %} -{% set font = config.theme.font %} - @@ -45,21 +38,8 @@ {% endif %} - - {% if page and page.meta and page.meta.redirect %} - - - - - - - - {% elif page.canonical_url %} + {% if page.canonical_url %} {% endif %} @@ -96,20 +76,21 @@ - {% if palette.scheme or palette.primary or palette.accent %} + {% if config.theme.palette %} + {% set palette = config.theme.palette %} - {% endif %} - - {% if palette.primary %} - {% import "partials/palette.html" as map %} - {% set primary = map.primary( - palette.primary | replace(" ", "-") | lower - ) %} - + + {% if palette.primary %} + {% import "partials/palette.html" as map %} + {% set primary = map.primary( + palette.primary | replace(" ", "-") | lower + ) %} + + {% endif %} {% endif %} {% endblock %} @@ -120,7 +101,8 @@ {% block fonts %} - {% if font != false %} + {% if config.theme.font != false %} + {% set font = config.theme.font %} {% 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 %} + + + {% if "preference" == scheme %} + + {% endif %} + {% else %} {% endif %} - - {% if "preference" == palette.scheme %} - - {% endif %} - - {% block hero %} - {% if page and page.meta and page.meta.hero %} - {% include "partials/hero.html" with context %} - {% endif %} - {% endblock %} + {% block hero %}{% endblock %} {% 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 @@ {% endif %} - - {% block source %} - {% if page and page.meta and page.meta.source %} - {% include "partials/source-link.html" %} - {% endif %} - {% endblock %} -