Material 5 Beta 3 is here! See deploy preview.
This will be the last beta before the first RC. The API can be considered stable, so from this beta on no big changes should be expected to the HTML or CSS.
Please post any problems you encounter during migration in this issue.
Installation
pip install "mkdocs-material>=5.0.0b3"
Features
- [x] Reactive architecture – try
__material.dialog$.next("Hi!") in the console!
- [x] Instant loading – make Material behave like a Single Page Application!
- [x] Improved CSS customization with CSS variables – define your CI colors!
- [x] Improved CSS resilience, e.g. proper sidebar locking for customized headers
- [x] Improved icon integration and configuration – now including over 5k icons!
- [x] Added possibility to use any icon for logo, repository and social links
- [x] Search UI does not freeze anymore (moved to web worker)
- [x] Search index built only once when using instant loading
- [x] Improved extensible keyboard handling
- [x] Support for prebuilt search indexes
- [x] Support for displaying stars and forks for GitLab repositories
- [x] Support for scroll snapping of sidebars and search results
- [x] Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
- [x] Slight facelifting of some UI elements (Admonitions, tables, ...)
Migration
Material 5 includes some long awaited but breaking changes. The migration guide will help you switch to the latest version.
Changes to mkdocs.yml
Following is a list of changes that need to be made to your mkdocs.yml. Note that you only need to adjust the values if you defined them. Click on the options to see examples.
theme.feature → theme.features
Material 4.x
theme:
feature:
tabs: true
Material 5.x
theme:
features:
- tabs
- instant
theme.logo.icon → theme.icon.logo
Material 4.x
theme:
logo:
icon: cloud
Material 5.x
theme:
icon:
logo: material/cloud
extra.repo_icon → theme.icon.repo
Material 4.x
extra:
repo_icon: gitlab
Material 5.x
theme:
icon:
repo: fontawesome/brands/gitlab
extra.search → plugins.search
Material 4.x
extra:
search:
language: en, de, ru
tokenizer: [\s\-\.]+
Material 5.x
plugins:
- search:
separator: '[\s\-\.]+'
lang:
- en
- de
- ru
extra.social.*.type → extra.social.*.icon
Material 4.x
extra:
social:
- type: github
link: https://github.com/squidfunk
- type: twitter
link: https://twitter.com/squidfunk
- type: linkedin
link: https://www.linkedin.com/in/squidfunk
Material 5.x
extra:
social:
- icon: fontawesome/brands/github-alt
link: https://github.com/squidfunk
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
- icon: fontawesome/brands/linkedin
link: https://www.linkedin.com/in/squidfunk/
Changes to *.html files
The templates have undergone a set of necessary changes to make them future-proof. If you've used theme extension to override a template block or HTML file, make sure that the structure of the HTML matches the new structure.
- If you've overridden a block, check
base.html for potential changes
- If you've overridden a template, check the respective
*.html file for potential changes
base.html
diff --git a/material/base.html b/material/base.html
index f26b7283..34340f8c 100644
--- a/material/base.html
+++ b/material/base.html
@@ -2,7 +2,6 @@
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %}
-{% set feature = config.theme.feature %}
{% set palette = config.theme.palette %}
{% set font = config.theme.font %}
<!doctype html>
@@ -30,21 +29,8 @@
{% elif config.site_author %}
<meta name="author" content="{{ config.site_author }}">
{% endif %}
- {% 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 %}
<link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0b2-1">
{% endblock %}
{% block htmltitle %}
{% if page and page.meta and page.meta.title %}
@@ -56,9 +42,9 @@
{% endif %}
{% endblock %}
{% block styles %}
- <link rel="stylesheet" href="{{ 'assets/stylesheets/application.adb8469c.css' | url }}">
+ <link rel="stylesheet" href="{{ 'assets/stylesheets/main.14bb5ffa.min.css' | url }}">
{% if palette.primary or palette.accent %}
- <link rel="stylesheet" href="{{ 'assets/stylesheets/application-palette.a8b3c06d.css' | url }}">
+ <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.f5f04e6f.min.css' | url }}">
{% endif %}
{% if palette.primary %}
{% import "partials/palette.html" as map %}
@@ -68,25 +54,22 @@
<meta name="theme-color" content="{{ primary }}">
{% endif %}
{% endblock %}
{% block libs %}
- <script src="{{ 'assets/javascripts/modernizr.86422ebf.js' | url }}"></script>
{% endblock %}
{% block fonts %}
{% if font != false %}
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family={{
font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
font.code | replace(' ', '+')
}}&display=fallback">
<style>body,input{font-family:"{{ font.text }}","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}","Courier New",Courier,monospace}</style>
{% endif %}
{% endblock %}
- <link rel="stylesheet" href="{{ 'assets/fonts/material-icons.css' | url }}">
{% if config.extra.manifest %}
<link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
{% endif %}
{% for path in config["extra_css"] %}
<link rel="stylesheet" href="{{ path | url }}">
{% endfor %}
{% block analytics %}
{% if config.google_analytics %}
@@ -95,47 +78,46 @@
{% endblock %}
{% block extrahead %}{% endblock %}
</head>
+ {% set direction = config.theme.direction | default(lang.t('direction')) %}
{% if palette.primary or palette.accent %}
{% set primary = palette.primary | replace(" ", "-") | lower %}
{% set accent = palette.accent | replace(" ", "-") | lower %}
- <body dir="{{ lang.t('direction') }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
+ <body dir="{{ direction }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
{% else %}
- <body dir="{{ lang.t('direction') }}">
+ <body dir="{{ direction }}">
{% endif %}
- <svg class="md-svg">
- <defs>
- {% set platform = config.extra.repo_icon or config.repo_url %}
- {% if "github" in platform %}
- {% include "assets/images/icons/github.f0b8504a.svg" %}
- {% elif "gitlab" in platform %}
- {% include "assets/images/icons/gitlab.6dd19c00.svg" %}
- {% elif "bitbucket" in platform %}
- {% include "assets/images/icons/bitbucket.1b09e088.svg" %}
- {% endif %}
- </defs>
- </svg>
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
- <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
+ <label class="md-overlay" for="__drawer"></label>
{% if page.toc | first is defined %}
- <a href="{{ (page.toc | first).url }}" tabindex="0" class="md-skip">
+ {% set skip = page.toc | first %}
+ <a href="{{ skip.url | url }}" class="md-skip" data-md-component="skip">
{{ lang.t('skip.link.title') }}
</a>
{% endif %}
+ {% if self.announce() %}
+ <aside class="md-announce" data-md-component="announce">
+ <div class="md-announce__inner md-grid md-typeset">
+ {% block announce %}{% endblock %}
+ </div>
+ </aside>
+ {% endif %}
{% block header %}
{% include "partials/header.html" %}
{% endblock %}
- <div class="md-container">
+ <div class="md-container" data-md-component="container">
{% block hero %}
{% if page and page.meta and page.meta.hero %}
{% include "partials/hero.html" with context %}
{% endif %}
{% endblock %}
- {% if feature.tabs %}
- {% include "partials/tabs.html" %}
- {% endif %}
+ {% block tabs %}
+ {% if "tabs" in config.theme.features %}
+ {% include "partials/tabs.html" %}
+ {% endif %}
+ {% endblock %}
- <main class="md-main" role="main">
- <div class="md-main__inner md-grid" data-md-component="container">
+ <main class="md-main" data-md-component="main">
+ <div class="md-main__inner md-grid">
{% block site_nav %}
{% if nav %}
<div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
@@ -160,41 +142,25 @@
<article class="md-content__inner md-typeset">
{% block content %}
{% if page.edit_url %}
- <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-icon md-content__icon"></a>
+ <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
+ {% include ".icons/material/pencil.svg" %}
+ </a>
{% endif %}
+ {% block source %}
+ {% if page and page.meta and page.meta.source %}
+ {% include "partials/source-link.html" %}
+ {% endif %}
+ {% endblock %}
{% if not "\x3ch1" in page.content %}
<h1>{{ page.title | default(config.site_name, true)}}</h1>
{% endif %}
{{ page.content }}
- {% block source %}
- {% if page and page.meta and page.meta.source %}
- <h2 id="__source">{{ lang.t("meta.source") }}</h2>
- {% set repo = config.repo_url %}
- {% if repo | last == "/" %}
- {% set repo = repo[:-1] %}
- {% endif %}
- {% set path = page.meta.path | default([""]) %}
- {% set file = page.meta.source %}
- <a href="{{ [repo, path, file] | join('/') }}" title="{{ file }}" class="md-source-file">
- {{ file }}
- </a>
- {% endif %}
- {% endblock %}
+ {% if page and page.meta %}
+ {% if page.meta.git_revision_date_localized or
+ page.meta.revision_date
+ %}
+ {% include "partials/source-date.html" %}
+ {% endif %}
+ {% endblock %}
- {% if page and page.meta and (
- page.meta.git_revision_date_localized or
- page.meta.revision_date
- ) %}
- {% set label = lang.t("source.revision.date") %}
- <hr>
- <div class="md-source-date">
- <small>
- {% if page.meta.git_revision_date_localized %}
- {{ label }}: {{ page.meta.git_revision_date_localized }}
- {% elif page.meta.revision_date %}
- {{ label }}: {{ page.meta.revision_date }}
- {% endif %}
- </small>
- </div>
- {% endif %}
- {% endblock %}
{% block disqus %}
@@ -208,29 +174,40 @@
{% include "partials/footer.html" %}
{% endblock %}
</div>
+ {% block config %}
+ <script>var __config={}</script>
+ {% endblock %}
{% block scripts %}
- <script src="{{ 'assets/javascripts/application.df00da5d.js' | url }}"></script>
- {% 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 ("ar", "da", "de", "es", "fi", "fr", "hu", "it", "ja", "nl", "no", "pt", "ro", "ru", "sv", "th", "tr", "vi") %}
- <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 %}
- <script>app.initialize({version:"{{ mkdocs_version }}",url:{base:"{{ base_url }}"}})</script>
+ <script src="{{ 'assets/javascripts/vendor.31a2e7b9.min.js' | url }}"></script>
+ <script src="{{ 'assets/javascripts/bundle.5b33ad8d.min.js' | url }}"></script>
+ {%- set translations = {} -%}
+ {%- for key in [
+ "clipboard.copy",
+ "clipboard.copied",
+ "search.config.lang",
+ "search.config.pipeline",
+ "search.config.separator",
+ "search.result.placeholder",
+ "search.result.none",
+ "search.result.one",
+ "search.result.other"
+ ] -%}
+ {%- set _ = translations.update({ key: lang.t(key) }) -%}
+ {%- endfor -%}
+ <script id="__lang" type="application/json">
+ {{ translations | tojson }}
+ </script>
+ <script>
+ __material = initialize(Object.assign({
+ url: {
+ base: "{{ base_url }}",
+ worker: {
+ search: "{{ 'assets/javascripts/worker/search.edc88caf.min.js' | url }}"
+ }
+ },
+ features: {{ config.theme.features | tojson }}
+ }, __config))
+ </script>
{% for path in config["extra_javascript"] %}
<script src="{{ path | url }}"></script>
{% endfor %}
partials/footer.html
diff --git a/material/partials/footer.html b/material/partials/footer.html
index c2f5a1c0..ca248f62 100644
--- a/material/partials/footer.html
+++ b/material/partials/footer.html
@@ -7,32 +7,32 @@
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid">
{% if page.previous_page %}
- <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
- <div class="md-flex__cell md-flex__cell--shrink">
- <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
+ <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+ <div class="md-footer-nav__button md-icon">
+ {% include ".icons/material/arrow-left.svg" %}
</div>
- <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
- <span class="md-flex__ellipsis">
+ <div class="md-footer-nav__title">
+ <div class="md-ellipsis">
<span class="md-footer-nav__direction">
{{ lang.t("footer.previous") }}
</span>
{{ page.previous_page.title }}
- </span>
+ </div>
</div>
</a>
{% endif %}
{% if page.next_page %}
- <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
- <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
- <span class="md-flex__ellipsis">
+ <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
+ <div class="md-footer-nav__title">
+ <div class="md-ellipsis">
<span class="md-footer-nav__direction">
{{ lang.t("footer.next") }}
</span>
{{ page.next_page.title }}
- </span>
+ </div>
</div>
- <div class="md-flex__cell md-flex__cell--shrink">
- <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
+ <div class="md-footer-nav__button md-icon">
+ {% include ".icons/material/arrow-right.svg" %}
</div>
</a>
{% endif %}
partials/header.html
diff --git a/material/partials/header.html b/material/partials/header.html
index cfaf1a3b..90438e8c 100644
--- a/material/partials/header.html
+++ b/material/partials/header.html
@@ -3,50 +3,44 @@
-#}
<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid">
- <div class="md-flex">
- <div class="md-flex__cell md-flex__cell--shrink">
- <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
- {% if config.theme.logo.icon %}
- <i class="md-icon">{{ config.theme.logo.icon }}</i>
- {% else %}
- <img alt="logo" src="{{ config.theme.logo | url }}" width="24" height="24">
- {% endif %}
- </a>
- </div>
- <div class="md-flex__cell md-flex__cell--shrink">
- <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
- </div>
- <div class="md-flex__cell md-flex__cell--stretch">
- <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
- {% if config.site_name == page.title %}
+ <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
+ {% if config.theme.logo %}
+ <img src="{{ config.theme.logo | url }}" alt="logo">
+ {% else %}
+ {% include ".icons/" ~ config.theme.icon.logo ~ ".svg" %}
+ {% endif %}
+ </a>
+ <label class="md-header-nav__button md-icon" for="__drawer">
+ {% include ".icons/material/menu" ~ ".svg" %}
+ </label>
+ <div class="md-header-nav__title" data-md-component="header-title">
+ <div class="md-header-nav__ellipsis md-ellipsis">
+ {% if config.site_name == page.title %}
+ {{ config.site_name }}
+ {% else %}
+ <span class="md-header-nav__topic">
{{ config.site_name }}
- {% else %}
- <span class="md-header-nav__topic">
- {{ config.site_name }}
- </span>
- <span class="md-header-nav__topic">
- {% if page and page.meta and page.meta.title %}
- {{ page.meta.title }}
- {% else %}
- {{ page.title }}
- {% endif %}
- </span>
- {% endif %}
- </div>
- </div>
- <div class="md-flex__cell md-flex__cell--shrink">
- {% if "search" in config["plugins"] %}
- <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
- {% include "partials/search.html" %}
+ </span>
+ <span class="md-header-nav__topic">
+ {% if page and page.meta and page.meta.title %}
+ {{ page.meta.title }}
+ {% else %}
+ {{ page.title }}
+ {% endif %}
+ </span>
{% endif %}
</div>
- {% if config.repo_url %}
- <div class="md-flex__cell md-flex__cell--shrink">
- <div class="md-header-nav__source">
- {% include "partials/source.html" %}
- </div>
- </div>
- {% endif %}
</div>
+ {% if "search" in config["plugins"] %}
+ <label class="md-header-nav__button md-icon" for="__search">
+ {% include ".icons/material/magnify.svg" %}
+ </label>
+ {% include "partials/search.html" %}
+ {% endif %}
+ {% if config.repo_url %}
+ <div class="md-header-nav__source">
+ {% include "partials/source.html" %}
+ </div>
+ {% endif %}
</nav>
</header>
partials/hero.html
diff --git a/material/partials/hero.html b/material/partials/hero.html
index 3d6a2cc8..2c244e18 100644
--- a/material/partials/hero.html
+++ b/material/partials/hero.html
@@ -1,9 +1,8 @@
{#-
This file was automatically generated - do not edit
-#}
-{% set feature = config.theme.feature %}
{% set class = "md-hero" %}
-{% if not feature.tabs %}
+{% if "tabs" not in config.theme.features %}
{% set class = "md-hero md-hero--expand" %}
{% endif %}
<div class="{{ class }}" data-md-component="hero">
partials/language.html
diff --git a/material/partials/language.html b/material/partials/language.html
index d0314ffc..46188a6b 100644
--- a/material/partials/language.html
+++ b/material/partials/language.html
@@ -3,12 +3,4 @@
-#}
{% import "partials/language/" + config.theme.language + ".html" as lang %}
{% import "partials/language/en.html" as fallback %}
-{% macro t(key) %}{{ {
- "direction": config.theme.direction,
- "search.language": (
- config.extra.search | default({})
- ).language,
- "search.tokenizer": (
- config.extra.search | default({})
- ).tokenizer | default("", true),
-}[key] or lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}
partials/nav-item.html
diff --git a/material/partials/nav-item.html b/material/partials/nav-item.html
index 54c06034..15e626ab 100644
--- a/material/partials/nav-item.html
+++ b/material/partials/nav-item.html
@@ -8,15 +8,21 @@
{% if nav_item.children %}
<li class="{{ class }} md-nav__item--nested">
{% if nav_item.active %}
<input class="md-nav__toggle md-toggle" data-md-toggle="{{ path }}" type="checkbox" id="{{ path }}" checked>
{% else %}
<input class="md-nav__toggle md-toggle" data-md-toggle="{{ path }}" type="checkbox" id="{{ path }}">
{% endif %}
<label class="md-nav__link" for="{{ path }}">
{{ nav_item.title }}
+ <span class="md-nav__icon md-icon">
+ {% include ".icons/material/chevron-right.svg" %}
+ </span>
</label>
- <nav class="md-nav" data-md-component="collapsible" data-md-level="{{ level }}">
+ <nav class="md-nav" data-md-level="{{ level }}">
<label class="md-nav__title" for="{{ path }}">
+ <span class="md-nav__icon md-icon">
+ {% include ".icons/material/arrow-left.svg" %}
+ </span>
{{ nav_item.title }}
</label>
<ul class="md-nav__list" data-md-scrollfix>
@@ -32,13 +38,16 @@
{% elif nav_item == page %}
<li class="{{ class }}">
{% set toc_ = page.toc %}
<input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
{% if toc_ | first is defined and "\x3ch1 id=" in page.content %}
{% set toc_ = (toc_ | first).children %}
{% endif %}
{% if toc_ | first is defined %}
<label class="md-nav__link md-nav__link--active" for="__toc">
{{ nav_item.title }}
+ <span class="md-nav__icon md-icon">
+ {% include ".icons/material/table-of-contents.svg" %}
+ </span>
</label>
{% endif %}
<a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">
partials/nav.html
diff --git a/material/partials/nav.html b/material/partials/nav.html
index b72383d4..0735f58e 100644
--- a/material/partials/nav.html
+++ b/material/partials/nav.html
@@ -2,12 +2,12 @@
This file was automatically generated - do not edit
-#}
<nav class="md-nav md-nav--primary" data-md-level="0">
- <label class="md-nav__title md-nav__title--site" for="__drawer">
- <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo">
- {% if config.theme.logo.icon %}
- <i class="md-icon">{{ config.theme.logo.icon }}</i>
+ <label class="md-nav__title" for="__drawer">
+ <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-nav__button md-logo">
+ {% if config.theme.logo %}
+ <img src="{{ config.theme.logo | url }}" alt="logo">
{% else %}
- <img alt="logo" src="{{ config.theme.logo | url }}" width="48" height="48">
+ {% include ".icons/" ~ config.theme.icon.logo ~ ".svg" %}
{% endif %}
</a>
{{ config.site_name }}
partials/search.html
diff --git a/material/partials/search.html b/material/partials/search.html
index 4863b708..4510355b 100644
--- a/material/partials/search.html
+++ b/material/partials/search.html
@@ -6,15 +6,18 @@
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
- <input type="text" class="md-search__input" aria-label="search" name="query" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
+ <input type="text" class="md-search__input" name="query" aria-label="search" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
<label class="md-search__icon md-icon" for="__search">
+ {% include ".icons/material/magnify.svg" %}
+ {% include ".icons/material/arrow-left.svg" %}
</label>
- <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
- 
+ <button type="reset" class="md-search__icon md-icon" data-md-component="search-reset" tabindex="-1">
+ {% include ".icons/material/close.svg" %}
</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>
partials/social.html
diff --git a/material/partials/social.html b/material/partials/social.html
index 391385e5..8b4ebdfe 100644
--- a/material/partials/social.html
+++ b/material/partials/social.html
@@ -3,9 +3,10 @@
-#}
{% if config.extra.social %}
<div class="md-footer-social">
- <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}">
{% for social in config.extra.social %}
- <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ social.type }}" class="md-footer-social__link fa fa-{{ social.type }}"></a>
+ <a href="{{ social.link }}" target="_blank" rel="noopener" class="md-footer-social__link">
+ {% include ".icons/" ~ social.icon ~ ".svg" %}
+ </a>
{% endfor %}
</div>
{% endif %}
partials/source-date.html
diff --git a/material/partials/source-date.html b/material/partials/source-date.html
new file mode 100644
index 00000000..9c72b8bc
--- /dev/null
+++ b/material/partials/source-date.html
@@ -0,0 +1,15 @@
+{#-
+ This file was automatically generated - do not edit
+-#}
+{% import "partials/language.html" as lang with context %}
+{% set label = lang.t("source.revision.date") %}
+<hr>
+<div class="md-source-date">
+ <small>
+ {% if page.meta.git_revision_date_localized %}
+ {{ label }}: {{ page.meta.git_revision_date_localized }}
+ {% elif page.meta.revision_date %}
+ {{ label }}: {{ page.meta.revision_date }}
+ {% endif %}
+ </small>
+</div>
partials/source-link.html
diff --git a/material/partials/source-link.html b/material/partials/source-link.html
new file mode 100644
index 00000000..86418fa1
--- /dev/null
+++ b/material/partials/source-link.html
@@ -0,0 +1,17 @@
+{#-
+ This file was automatically generated - do not edit
+-#}
+{% import "partials/language.html" as lang with context %}
+{% set repo = config.repo_url %}
+{% if repo | last == "/" %}
+ {% set repo = repo[:-1] %}
+{% endif %}
+{% set path = page.meta.path | default([""]) %}
+{% set file = page.meta.source %}
+{% set repo_icon = config.extra.repo_icon | default(
+ "fontawesome/brands/git-alt"
+) %}
+<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ file }}" class="md-content__button md-icon">
+ {{ lang.t("meta.source") }}
+ {% include ".icons/" ~ repo_icon ~ ".svg" %}
+</a>
partials/source.html
diff --git a/material/partials/source.html b/material/partials/source.html
index 742d42de..a65295a4 100644
--- a/material/partials/source.html
+++ b/material/partials/source.html
@@ -2,24 +2,10 @@
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %}
-{% 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 %}
-<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 %}
+<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
+ <div class="md-source__icon md-icon">
+ {% include ".icons/" ~ config.theme.icon.repo ~ ".svg" %}
+ </div>
<div class="md-source__repository">
{{ config.repo_name }}
</div>
partials/tabs-item.html
diff --git a/material/partials/tabs-item.html b/material/partials/tabs-item.html
index 1f3179d3..64ced43b 100644
--- a/material/partials/tabs-item.html
+++ b/material/partials/tabs-item.html
@@ -1,7 +1,7 @@
{#-
This file was automatically generated - do not edit
-#}
-{% if nav_item.is_homepage %}
+{% if nav_item.is_homepage or nav_item.url == "index.html" %}
<li class="md-tabs__item">
{% if not page.ancestors | length and nav | selectattr("url", page.url) %}
<a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active">
partials/toc.html
diff --git a/material/partials/toc.html b/material/partials/toc.html
index 14a5e070..db4cfbea 100644
--- a/material/partials/toc.html
+++ b/material/partials/toc.html
@@ -3,34 +3,21 @@
-#}
{% import "partials/language.html" as lang with context %}
<nav class="md-nav md-nav--secondary">
{% set toc = page.toc %}
{% if toc | first is defined and "\x3ch1 id=" in page.content %}
{% set toc = (toc | first).children %}
{% endif %}
{% if toc | first is defined %}
<label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon">
+ {% include ".icons/material/arrow-left.svg" %}
+ </span>
{{ lang.t("toc.title") }}
</label>
<ul class="md-nav__list" data-md-scrollfix>
{% for toc_item in toc %}
{% include "partials/toc-item.html" %}
{% endfor %}
- {% if page.meta.source and page.meta.source | length > 0 %}
- <li class="md-nav__item">
- <a href="#__source" class="md-nav__link md-nav__link--active">
- {{ lang.t("meta.source") }}
- </a>
- </li>
- {% endif %}
- {% set disqus = config.extra.disqus %}
- {% if page and page.meta and page.meta.disqus is string %}
- {% set disqus = page.meta.disqus %}
- {% endif %}
- {% if not page.is_homepage and disqus %}
- <li class="md-nav__item">
- <a href="#__comments" class="md-nav__link md-nav__link--active">
- {{ lang.t("meta.comments") }}
- </a>
- </li>
- {% endif %}
</ul>
{% endif %}
</nav>
Notes
Instant loading
The basic idea is: why should we reconstruct the whole page again and again when only the content and navigation changes? When instant loading is enabled, all internal links are intercepted and dispatched via XHR. The resulting document is parsed, injected and all event handlers are automatically rebound. The search index will remain intact in-between loads.
With instant loading enabled, Material effectively behaves like a Single Page Application.
This feature shows the true beauty of the new architecture - everything is observable and automatically updates when new values become available. The following gifs were recorded on Fast 3G to show the speed advantage of instant loading:
Without instant loading
With instant loading
Social links
FontAwesome was updated to the latest version and is now provided via inline SVGs which reduces the overall footprint. To reference an icon, reference its path from the top-level .icons directory which is distributed with the theme without the .svg at the end. Besides FontAwesome, the Material icons and GitHub's octicons are also bundled with the theme.
Note that mkdocs build will now terminate with an error if an invalid icon is referenced.
Known bugs
- [x] Instant loading sometimes doubles the URL (race condition) 80f1d3e3
- [x]
direction="None" when no direction is set 584eac86
Feedback is appreciated!
help wanted
266 Dec 13, 2022
282 Dec 28, 2022
198 Jan 3, 2023
38 Feb 26, 2022
67 Jan 4, 2023
1.1k Jan 4, 2023
10 May 20, 2022
14 Sep 10, 2022
49 Jan 9, 2023
35 Dec 23, 2022
4.3k Dec 31, 2022
670 Dec 19, 2022
584 Nov 16, 2022
166 Jan 4, 2023
1 Jan 22, 2022
2.6k Jan 8, 2023
124 Jan 6, 2023
61 Oct 26, 2022
8 Jun 25, 2022