OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added primer on necessary template changes for v5

Browse Source
This commit is contained in:
squidfunk 2020-02-01 16:59:23 +01:00
parent 24c58d8fd4
commit 2025881c32
1 changed files with 352 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

352
docs/changelog/5.x.md Normal file
View 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"
>
&#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>
```