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

Updated documentation

Browse Source
This commit is contained in:
squidfunk
2021-11-28 16:35:55 +01:00
parent fc5f65a312
commit 2673cafe47
1 changed files with 585 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
docs/upgrade.md
View File

@@ -66,6 +66,277 @@ viewports]:
[Tabbed]: setup/extensions/python-markdown-extensions.md#tabbed [Tabbed]: setup/extensions/python-markdown-extensions.md#tabbed
[better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214 [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
### Changes to `*.html` files { data-search-exclude }
The templates have undergone a set of changes to make them future-proof. If
you've used theme extension to override a block or template, make sure that it
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
=== ":octicons-file-code-16: base.html"
``` diff
@@ -38,13 +38,6 @@
<meta name="description" content="{{ config.site_description }}" />
{% endif %}
- <!-- Page keywords -->
- {% if page and page.meta and page.meta.keywords %}
- <meta name="keywords" content="{{ page.meta.keywords }}" />
- {% elif config.site_keywords %}
- <meta name="keywords" content="{{ config.site_keywords }}" />
- {% endif %}
-
<!-- Page author -->
{% if page and page.meta and page.meta.author %}
<meta name="author" content="{{ page.meta.author }}" />
@@ -120,27 +113,21 @@
/>
<style>
:root {
- --md-text-font-family: "{{ font.text }}";
- --md-code-font-family: "{{ font.code }}";
+ --md-text-font: "{{ font.text }}";
+ --md-code-font: "{{ font.code }}";
}
</style>
{% endif %}
{% endblock %}
- <!-- Progressive Web App Manifest -->
- {% if config.extra.manifest %}
- <link
- rel="manifest"
- href="{{ config.extra.manifest | url }}"
- crossorigin="use-credentials"
- />
- {% endif %}
-
<!-- Custom style sheets -->
{% for path in config["extra_css"] %}
<link rel="stylesheet" href="{{ path | url }}" />
{% endfor %}
+ <!-- Helper functions for inline scripts -->
+ {% include "partials/javascripts/base.html" %}
+
<!-- Analytics -->
{% block analytics %}
{% include "partials/integrations/analytics.html" %}
@@ -172,7 +159,6 @@
<!-- Retrieve features from configuration -->
{% set features = config.theme.features or [] %}
- {% include "partials/javascripts/base.html" %}
<!-- User preference: color palette -->
{% if not config.theme.palette is mapping %}
@@ -214,14 +200,28 @@
<!-- Announcement bar -->
<div data-md-component="announce">
{% if self.announce() %}
- <aside class="md-banner md-announce">
- <div class="md-banner__inner md-announce__inner md-grid md-typeset">
+ <aside class="md-banner">
+ <div class="md-banner__inner md-grid md-typeset">
{% block announce %}{% endblock %}
</div>
</aside>
{% endif %}
</div>
+ <!-- Version warning -->
+ {% if config.extra.version %}
+ <div data-md-component="outdated" hidden>
+ <aside class="md-banner md-banner--warning">
+ {% if self.outdated() %}
+ <div class="md-banner__inner md-grid md-typeset">
+ {% block outdated %}{% endblock %}
+ </div>
+ {% include "partials/javascripts/outdated.html" %}
+ {% endif %}
+ </aside>
+ </div>
+ {% endif %}
+
<!-- Header -->
{% block header %}
{% include "partials/header.html" %}
@@ -295,49 +295,11 @@
{% block content %}
-
- <!-- Edit button -->
- {% if page.edit_url %}
- <a
- href="{{ page.edit_url }}"
- title="{{ lang.t('edit.link.title') }}"
- class="md-content__button md-icon"
- >
- {% include ".icons/material/pencil.svg" %}
- </a>
- {% endif %}
-
- <!--
- Hack: check whether the content contains a h1 headline. If it
- doesn't, the page title (or respectively site name) is used
- as the main headline.
- -->
- {% if not "\x3ch1" in page.content %}
- <h1>{{ page.title | d(config.site_name, true)}}</h1>
- {% endif %}
-
- <!-- Markdown content -->
- {{ page.content }}
-
- <!-- Last update of source file -->
- {% if page and page.meta %}
- {% if page.meta.git_revision_date_localized or
- page.meta.revision_date
- %}
- {% include "partials/source-file.html" %}
- {% endif %}
- {% endif %}
- {% endblock %}
-
- <!-- Disqus integration -->
- {% block disqus %}
- {% include "partials/integrations/disqus.html" %}
+ {% include "partials/content.html" %}
{% endblock %}
</article>
</div>
```
=== ":octicons-file-code-16: partials/copyright.html"
``` diff
@@ -0,0 +1,39 @@
+<!--
+ Copyright (c) 2016-2021 Martin Donath <martin.donath@squidfunk.com>
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to
+ deal in the Software without restriction, including without limitation the
+ rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ sell copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ IN THE SOFTWARE.
+-->
+
+<!-- Copyright and theme information -->
+<div class="md-copyright">
+ {% if config.copyright %}
+ <div class="md-copyright__highlight">
+ {{ config.copyright }}
+ </div>
+ {% endif %}
+ {% if not config.extra.generator == false %}
+ Made with
+ <a
+ href="https://squidfunk.github.io/mkdocs-material/"
+ target="_blank" rel="noopener"
+ >
+ Material for MkDocs
+ </a>
+ {% endif %}
+</div>
```
=== ":octicons-file-code-16: partials/footer.html"
``` diff
@@ -83,28 +81,12 @@
<!-- Further information -->
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
-
- <!-- Copyright and theme information -->
- <div class="md-footer-copyright">
- {% if config.copyright %}
- <div class="md-footer-copyright__highlight">
- {{ config.copyright }}
- </div>
- {% endif %}
- {% if not config.extra.generator == false %}
- Made with
- <a
- href="https://squidfunk.github.io/mkdocs-material/"
- target="_blank" rel="noopener"
- >
- Material for MkDocs
- </a>
- {% endif %}
- {{ extracopyright }}
- </div>
+ {% include "partials/copyright.html" %}
<!-- Social links -->
- {% include "partials/social.html" %}
+ {% if config.extra.social %}
+ {% include "partials/social.html" %}
+ {% endif %}
</div>
</div>
</footer>
```
=== ":octicons-file-code-16: partials/social.html"
``` diff
@@ -22,23 +22,21 @@
-<!-- Social links in footer -->
-{% if config.extra.social %}
- <div class="md-footer-social">
- {% for social in config.extra.social %}
- {% set title = social.name %}
- {% if not title and "//" in social.link %}
- {% set _,url = social.link.split("//") %}
- {% set title = url.split("/")[0] %}
- {% endif %}
- <a
- href="{{ social.link }}"
- target="_blank" rel="noopener"
- title="{{ title | e }}"
- class="md-footer-social__link"
- >
- {% include ".icons/" ~ social.icon ~ ".svg" %}
- </a>
- {% endfor %}
- </div>
-{% endif %}
+<!-- Social links -->
+<div class="md-social">
+ {% for social in config.extra.social %}
+ {% set title = social.name %}
+ {% if not title and "//" in social.link %}
+ {% set _, url = social.link.split("//") %}
+ {% set title = url.split("/")[0] %}
+ {% endif %}
+ <a
+ href="{{ social.link }}"
+ target="_blank" rel="noopener"
+ title="{{ title | e }}"
+ class="md-social__link"
+ >
+ {% include ".icons/" ~ social.icon ~ ".svg" %}
+ </a>
+ {% endfor %}
+</div>
```
## Upgrading from 6.x to 7.x ## Upgrading from 6.x to 7.x
### What's new? ### What's new?
@@ -341,7 +612,6 @@ matches the new structure:
{% include "partials/source.html" %} {% include "partials/source.html" %}
</div> </div>
{% endif %} {% endif %}
``` ```
=== ":octicons-file-code-16: partials/source.html" === ":octicons-file-code-16: partials/source.html"
@@ -368,7 +638,6 @@ matches the new structure:
{% for toc_item in toc %} {% for toc_item in toc %}
{% include "partials/toc-item.html" %} {% include "partials/toc-item.html" %}
{% endfor %} {% endfor %}
``` ```
## Upgrading from 5.x to 6.x ## Upgrading from 5.x to 6.x
@@ -619,6 +888,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/source-link" === ":octicons-file-code-16: partials/source-link"
``` diff ``` diff
@@ -1,14 +0,0 @@
-{#- -{#-
- This file was automatically generated - do not edit - This file was automatically generated - do not edit
--#} --#}
@@ -792,9 +1062,7 @@ matches the new structure:
=== ":octicons-file-code-16: base.html" === ":octicons-file-code-16: base.html"
``` diff ``` diff
@@ -2,7 +2,6 @@ @@ -4,7 +4,6 @@
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %} {% import "partials/language.html" as lang with context %}
-{% set feature = config.theme.feature %} -{% set feature = config.theme.feature %}
{% set palette = config.theme.palette %} {% set palette = config.theme.palette %}
@@ -1094,9 +1362,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/header.html" === ":octicons-file-code-16: partials/header.html"
``` diff ``` diff
@@ -2,51 +2,43 @@ @@ -4,51 +4,43 @@
This file was automatically generated - do not edit
-#}
<header class="md-header" data-md-component="header"> <header class="md-header" data-md-component="header">
- <nav class="md-header-nav md-grid"> - <nav class="md-header-nav md-grid">
- <div class="md-flex"> - <div class="md-flex">
@@ -1185,10 +1451,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/hero.html" === ":octicons-file-code-16: partials/hero.html"
``` diff ``` diff
@@ -1,9 +1,8 @@ @@ -4,9 +4,8 @@
{#-
This file was automatically generated - do not edit
-#}
-{% set feature = config.theme.feature %} -{% set feature = config.theme.feature %}
{% set class = "md-hero" %} {% set class = "md-hero" %}
-{% if not feature.tabs %} -{% if not feature.tabs %}
@@ -1201,8 +1464,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/language.html" === ":octicons-file-code-16: partials/language.html"
``` diff ``` diff
@@ -3,12 +3,4 @@ @@ -4,12 +4,4 @@
-#}
{% import "partials/language/" + config.theme.language + ".html" as lang %} {% import "partials/language/" + config.theme.language + ".html" as lang %}
{% import "partials/language/en.html" as fallback %} {% import "partials/language/en.html" as fallback %}
-{% macro t(key) %}{{ { -{% macro t(key) %}{{ {
@@ -1267,10 +1529,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/nav.html" === ":octicons-file-code-16: partials/nav.html"
``` diff ``` diff
@@ -1,14 +1,10 @@ @@ -4,14 +4,10 @@
{#-
This file was automatically generated - do not edit
-#}
-<nav class="md-nav md-nav--primary" data-md-level="0"> -<nav class="md-nav md-nav--primary" data-md-level="0">
- <label class="md-nav__title md-nav__title--site" for="__drawer"> - <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"> - <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo">
@@ -1319,8 +1578,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/social.html" === ":octicons-file-code-16: partials/social.html"
``` diff ``` diff
@@ -3,9 +3,12 @@ @@ -4,9 +4,12 @@
-#}
{% if config.extra.social %} {% if config.extra.social %}
<div class="md-footer-social"> <div class="md-footer-social">
- <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}"> - <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}">
@@ -1379,9 +1637,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/source.html" === ":octicons-file-code-16: partials/source.html"
``` diff ``` diff
@@ -2,24 +2,11 @@ @@ -4,24 +4,11 @@
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %} {% import "partials/language.html" as lang with context %}
-{% set platform = config.extra.repo_icon or config.repo_url %} -{% set platform = config.extra.repo_icon or config.repo_url %}
-{% if "github" in platform %} -{% if "github" in platform %}
@@ -1414,10 +1670,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/tabs-item.html" === ":octicons-file-code-16: partials/tabs-item.html"
``` diff ``` diff
@@ -1,7 +1,7 @@ @@ -4,7 +4,7 @@
{#-
This file was automatically generated - do not edit
-#}
-{% if nav_item.is_homepage %} -{% if nav_item.is_homepage %}
+{% if nav_item.is_homepage or nav_item.url == "index.html" %} +{% if nav_item.is_homepage or nav_item.url == "index.html" %}
<li class="md-tabs__item"> <li class="md-tabs__item">
@@ -1456,9 +1709,7 @@ matches the new structure:
=== ":octicons-file-code-16: partials/toc.html" === ":octicons-file-code-16: partials/toc.html"
``` diff ``` diff
@@ -2,35 +2,22 @@ @@ -4,35 +4,22 @@
This file was automatically generated - do not edit
-#}
{% import "partials/language.html" as lang with context %} {% import "partials/language.html" as lang with context %}
-<nav class="md-nav md-nav--secondary"> -<nav class="md-nav md-nav--secondary">
+<nav class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}"> +<nav class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}">