mkdocs-material/docs/changelog/5.x.md

# Material 5.x

## Migration

### Templates and partials

If you customized the theme by [overriding partials][1] or [template blocks][2], 
make sure that you review and adapt the respective HTML structure, as there are 
some critical changes that need to made to ensure the theme works as expected.

  [1]: http://localhost:8000/customization/#overriding-partials
  [2]: http://localhost:8000/customization/#overriding-template-blocks

#### `src/base.html`

The `meta` tag localization approach is superseded by a JSON-based localization
technique which can now be found at the bottom of the template.

``` diff
-      <!-- Localization -->
-      {% 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"
-      ] %}
-        <meta name="lang:{{ key }}" content="{{ lang.t(key) }}" />
-      {% endfor %}
```

The `application.css` stylesheet is now called `app.min.css` to signal that the
source is optimized and minified, which may be important for legal purposes.

``` diff
       <!-- Theme-related stylesheets -->
       <link 
         rel="stylesheet" type="text/css"
-        href="{{ 'assets/stylesheets/application.css' | url }}"
+        href="{{ 'assets/stylesheets/app.min.css' | url }}"
       />
```

The `application-palette.css` stylesheet has been removed in favor of the new 
color customization approach which is based on CSS variables. 

``` diff
-      <!-- Extra color palette -->
-      {% if palette.primary or palette.accent %}
-        <link rel="stylesheet" type="text/css"
-            href="{{ 'assets/stylesheets/application-palette.css' | url }}" />
-        <link
-          rel="stylesheet"
-          type="text/css"
-          href="{{ 'assets/stylesheets/app-palette.min.css' | url }}"
-        />
-      {% endif %}
```

The `modernizr.js` custom build was completely removed.

``` diff
     <!-- JavaScript libraries -->
-    {% block libs %}
-      <script src="{{ 'assets/javascripts/modernizr.js' | url }}"></script>
-    {% endblock %}
+    {% block libs %}{% endblock %}
```

The hidden inline SVG container has been removed, as the repository icons are 
now provided through the FontAwesome iconset.

``` diff 
-    <!-- Hidden container for inline SVGs -->
-    <svg class="md-svg">
-      <defs>
-
-        <!--
-          Check whether the repository is hosted on one of the supported code
-          hosting platforms (GitHub, GitLab or Bitbucket) to show icon.
-        -->
-        {% set platform = config.extra.repo_icon or config.repo_url %}
-        {% if "github" in platform %}
-          {% include "assets/images/icons/github.svg" %}
-        {% elif "gitlab" in platform %}
-          {% include "assets/images/icons/gitlab.svg" %}
-        {% elif "bitbucket" in platform %}
-          {% include "assets/images/icons/bitbucket.svg" %}
-        {% endif %}
-      </defs>
-    </svg>
-
```

An announcement bar was added just above the header which is shown if the
`announcement` block is defined through template extension.

``` diff
+    <!-- Announcement bar -->
+    {% if self.announcement() %}
+      <aside class="md-announcement" data-md-component="announcement">
+        <div class="md-announcement__inner md-grid md-typeset">
+          {% block announcement %}{% endblock %}
+        </div>
+      </aside>
+    {% endif %}
+
     <!-- Application header -->
     {% block header %}
       {% include "partials/header.html" %}
     {% endblock %}
```

The container and main area now state their corresponding component names.

``` diff
     <!-- Container, necessary for web-application context -->
-    <div class="md-container">
+    <div class="md-container" data-md-component="container">
 
       ...
 
-      <!-- Main container -->
-      <main class="md-main" role="main">
-        <div class="md-main__inner md-grid" data-md-component="container">
+      <!-- Main area -->
+      <main class="md-main" data-md-component="main">
+        <div class="md-main__inner md-grid">
 
           <!-- Navigation -->
           {% block site_nav %}
```

The `lunr-language`-related JavaScript like stemmers and segmenters are now
loaded explicitly by the search worker. The main application is now called
`bundle.min.js`.

``` diff
     <!-- Theme-related JavaScript -->
     {% block scripts %}
+      <script src="{{ 'assets/javascripts/bundle.min.js' | url }}"></script>
-      <script src="{{ 'assets/javascripts/application.js' | url }}"></script>
-
-      <!-- Load additional languages for search -->
-      {% if lang.t("search.language") != "en" %}
-        {% set languages = lang.t("search.language").split(",") %}
-        {% if languages | length and languages[0] != "" %}
-          {% set path = "assets/javascripts/lunr/" %}
-          <script src="{{ (path ~ 'lunr.stemmer.support.js') | url }}"></script>
-          {% for language in languages | map("trim") %}
-            {% if language != "en" %}
-              {% if language == "ja" %}
-                <script src="{{ (path ~ 'tinyseg.js') | url }}"></script>
-              {% endif %}
-              {% if language in ($md-lunr-languages$) %}
-                <script src="{{ (path ~ 'lunr.' ~ language ~ '.js') | url }}">
-                </script>
-              {% endif %}
-            {% endif %}
-          {% endfor %}
-          {% if languages | length > 1 %}
-            <script src="{{ (path ~ 'lunr.multi.js') | url }}"></script>
-          {% endif %}
-        {% endif %}
-      {% endif %}
 
+      <!-- Translations -->
+      <script id="__lang" type="application/json">
+        {%- set translations = {} -%}
+        {%- for key in [
+          "clipboard.copy",
+          "clipboard.copied",
+          "search.language",
+          "search.pipeline.stopwords",
+          "search.pipeline.trimmer",
+          "search.result.placeholder",
+          "search.result.none",
+          "search.result.one",
+          "search.result.other",
+          "search.tokenizer"
+        ] -%}
+          {%- set _ = translations.update({ key: lang.t(key) }) -%}
+        {%- endfor -%}
+        {{ translations | tojson }}
+      </script>
 
       <!-- Initialize application -->
       <script>
-        app.initialize({
-          version: "{{ mkdocs_version }}",
-          url: {
-            base: "{{ base_url }}"
+        app = initialize({
+          base: "{{ base_url }}",
+          worker: {
+            search: "{{ 'assets/javascripts/worker/search.js' | url }}",
+            packer: "{{ 'assets/javascripts/worker/packer.js' | url }}"
           }
         });
       </script>
```

#### `src/partials/header.html`

The header `data-md-component` attribute values have been renamed and prefixed 
with `header-` in order to better reflect that they belong to the header.

``` diff 
       <!-- Header title -->
       <div class="md-flex__cell md-flex__cell--stretch">
         <div
           class="md-flex__ellipsis md-header-nav__title"
-          data-md-component="title"
+          data-md-component="header-title"
         >
           {% if config.site_name == page.title %}
             {{ config.site_name }}
           {% else %}
```

#### `src/partials/language.html`

The options exposed through `config.extra.search` are now available through the
default search plugin integration and have been removed from the template.

``` diff
 <!-- Re-export translations -->
 {% macro t(key) %}{{ {
-  "direction": config.theme.direction,
-  "search.language": (
-    config.extra.search | default({})
-  ).language,
-  "search.tokenizer": (
-    config.extra.search | default({})
-  ).tokenizer | default("", true),
+  "direction": config.theme.direction
 }[key] or lang.t(key) or fallback.t(key) }}{% endmacro %}
```

#### `src/partials/search.html`

The search `data-md-component` attribute values have been renamed and prefixed 
with `search-` in order to better reflect that they belong to the search.

``` diff
         autocorrect="off"
         autocomplete="off"
         spellcheck="false"
-        data-md-component="query"
+        data-md-component="search-query"
         data-md-state="active"
       />
       <label class="md-icon md-search__icon" for="__search"></label>
       <button
         type="reset"
         class="md-icon md-search__icon"
-        data-md-component="reset"
+        data-md-component="search-reset"
         tabindex="-1"
       >
         &#xE5CD;<!-- close -->
       </button>
     </form>
     <div class="md-search__output">
       <div class="md-search__scrollwrap" data-md-scrollfix>
-        <div class="md-search-result" data-md-component="result">
+        <div class="md-search-result" data-md-component="search-result">
           <div class="md-search-result__meta">
             {{ lang.t("search.result.placeholder") }}
           </div>

```

#### `src/partials/social.html`

Social icons are implemented by inlining FontAwesome's original SVGs. Thus, the 
icon font was removed and the `type` member was renamed to `icon` as part of the 
`config.extra.social` configuration option in `mkdocs.yml`.

``` diff
 <!-- Social links in footer -->
 {% if config.extra.social %}
   <div class="md-footer-social">
-    <link 
-      rel="stylesheet" type="text/css"
-      href="{{ 'assets/fonts/font-awesome.css' | url }}"
-    />
     {% for social in config.extra.social %}
-      <a 
-        href="{{ social.link }}" 
-        class="md-footer-social__link fa fa-{{ social.type }}"
-      ></a>
       <a
+        href="{{ social.link }}"
+        target="_blank" rel="noopener"
+        class="md-footer-social__link"
+      >
+        {% include "assets/images/icons/fontawesome/" ~ social.icon ~ ".svg" %}
+      </a>
     {% endfor %}
   </div>
 {% endif %}
```

#### `src/partials/source.html`

The buildtime platform detection was removed and is now carried out during 
runtime initialization. The repository icon now supports the entire FontAwesome 
iconset by setting `config.extra.repo_icon` to a valid FontAwesome icon.

``` diff
-<!--
-  Check whether the repository is hosted on one of the supported code hosting
-  platforms (GitHub, GitLab or Bitbucket) to show icon.
--->
-{% set platform = config.extra.repo_icon or config.repo_url %}
-{% if "github" in platform %}
-  {% set repo_type = "github" %}
-{% elif "gitlab" in platform %}
-  {% set repo_type = "gitlab" %}
-{% elif "bitbucket" in platform %}
-  {% set repo_type = "bitbucket" %}
-{% else %}
-  {% set repo_type = "" %}
-{% endif %}
-
 <!-- Repository containing source -->
 <a
   href="{{ config.repo_url }}"
   title="{{ lang.t('source.link.title') }}"
   class="md-source"
-  data-md-source="{{ repo_type }}"
 >
-  {% if repo_type %}
-    <div class="md-source__icon">
-      <svg viewBox="0 0 24 24" width="24" height="24">
-        <use xlink:href="#__{{ repo_type }}" width="24" height="24"></use>
-      </svg>
-    </div>
-  {% endif %}
+  <div class="md-source__icon">
+    {% set repo_icon = config.extra.repo_icon | default("brands/git-alt") %}
+    {% include "assets/images/icons/fontawesome/" ~ repo_icon ~ ".svg" %}
+  </div>
   <div class="md-source__repository">
     {{ config.repo_name }}
   </div>
```