11 KiB
Material 5.x
Migration
Templates and partials
If you customized the theme by overriding partials or template blocks, 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.
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.
- <!-- 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.
<!-- 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.
- <!-- 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.
<!-- 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.
- <!-- 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.
+ <!-- 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.
<!-- 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.
<!-- 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.
<!-- 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.
<!-- 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.
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"
>
<!-- 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.
<!-- 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.
-<!--
- 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>