mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Added primer on necessary template changes for v5
This commit is contained in:
squidfunk
parent
24c58d8fd4
commit
2025881c32
352
docs/changelog/5.x.md
Normal file
352
docs/changelog/5.x.md
Normal file
@ -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"
|
||||||
|
>
|
||||||
|
<!-- 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>
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user