diff --git a/docs/changelog/5.x.md b/docs/changelog/5.x.md
new file mode 100644
index 000000000..2e0c20fc5
--- /dev/null
+++ b/docs/changelog/5.x.md
@@ -0,0 +1,352 @@
+# 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>
+```