diff --git a/docs/customization.md b/docs/customization.md index b4450e390..b4b22db61 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -142,7 +142,7 @@ called _blocks_, which are defined inside the templates and wrap specific features. To override a block, create a `main.html` inside the `overrides` directory and define the block, e.g.: -``` jinja +``` html {% extends "base.html" %} {% block htmltitle %} diff --git a/docs/deprecations.md b/docs/deprecations.md index beb689435..d17111834 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -99,9 +99,9 @@ templates can be shared among multiple pages: === "Template" - ``` jinja + ``` html {% block hero %} - {# Add custom hero here #} + {% endblock %} ``` diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 934bd55c6..457900edd 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -353,7 +353,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are several [types of string tokens][24], Material for MkDocs assigns a single color to most of them. -Add an [additional stylesheet][6], and add: +Create an [additional stylesheet][6], and add: ``` css :root { diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index 2c790e7a6..302bfcc7f 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -4,12 +4,20 @@ template: overrides/main.html # Meta tags +In HTML, `meta` tags allow to provide additional metadata for a document, e.g. +page titles and descriptions, additional assets to be loaded, and [Open Graph] +[1] data. While metadata can always be added via [customization][2], some tags +can be configured. + + [1]: https://ogp.me/ + [2]: #customization + ## Configuration ### Metadata -The [Metadata][1] extension, which is part of the standard Markdown library, -adds the ability to add [front matter][2] to a document and can be enabled via +The [Metadata][3] extension, which is part of the standard Markdown library, +adds the ability to add [front matter][4] to a document and can be enabled via `mkdocs.yml`: ``` yaml @@ -20,14 +28,14 @@ markdown_extensions: Front matter is written as a series of key-value pairs at the beginning of the Markdown document, delimited by a blank line which ends the YAML context. - [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html - [2]: https://jekyllrb.com/docs/front-matter/ + [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [4]: https://jekyllrb.com/docs/front-matter/ ## Usage ### Setting the page title -If the [Metadata][3] extension is enabled, the page title can be overridden on +If the [Metadata][5] extension is enabled, the page title can be overridden on a per-document basis with custom front matter: ``` markdown @@ -41,11 +49,11 @@ to the provided value. It will also override the default behavior of Material for MkDocs which appends the site title using a dash as a separator to the page title. - [3]: #metadata + [5]: #metadata ### Setting the page description -If the [Metadata][3] extension is enabled, the page description can also be +If the [Metadata][5] extension is enabled, the page description can also be overridden on a per-document basis with custom front matter: ``` markdown @@ -59,11 +67,58 @@ document `head` for the current page to the provided value. ### Adding a web app manifest -A [web app manifest][4] is a simple JSON file that specifies how your web application should behave when installed on the user's mobile device or desktop, which can be set via `mkdocs.yml`: +A [web app manifest][6] is a simple JSON file that specifies how your web application should behave when installed on the user's mobile device or desktop, which can be set via `mkdocs.yml`: ``` yaml extra: manifest: manifest.webmanifest ``` - [4]: https://developers.google.com/web/fundamentals/web-app-manifest/ + [6]: https://developers.google.com/web/fundamentals/web-app-manifest/ + +## Customization + +### Open Graph + +In order to add [Open Graph][1] data to your document, you can [extend the +theme][7] and [override the `extrahead` block][8] to add the respective `meta` +tags to the template: + +``` html +{% block extrahead %} + + + + + + + + +{% endblock %} +``` + + [7]: ../customization.md#extending-the-theme + [8]: ../customization.md#overriding-blocks + +### Twitter Cards + +When you post links to your project documentation on [Twitter][9], it's +highly recommended to add [Twitter's `meta` tags][10] to optimize the preview +of your site: + +``` html +{% block extrahead %} + + + + + + +{% endblock %} +``` + +You should also [check the preview][11] of your Tweets. + + [9]: https://twitter.com + [10]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards + [11]: https://cards-dev.twitter.com/validator diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 22766ada5..b67f9db56 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -34,6 +34,23 @@ This will insert a comment system on _every page, except the index page_. [3]: https://www.mkdocs.org/user-guide/configuration/#site_url [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname +### Metadata + +The [Metadata][5] extension, which is part of the standard Markdown library, +adds the ability to add [front matter][6] to a document and can be enabled via +`mkdocs.yml`: + +``` yaml +markdown_extensions: + - meta +``` + +Front matter is written as a series of key-value pairs at the beginning of the +Markdown document, delimited by a blank line which ends the YAML context. + + [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [6]: https://jekyllrb.com/docs/front-matter/ + ## Customization ### Selective integration @@ -41,7 +58,7 @@ This will insert a comment system on _every page, except the index page_. [:octicons-file-code-24: Source][2] ยท :octicons-mortar-board-24: Difficulty: _easy_ -If the [Metadata][5] extension is enabled, you can disable or enable Disqus for +If the [Metadata][7] extension is enabled, you can disable or enable Disqus for specific pages by adding the following to the front matter of a page: === "Enable Disqus" @@ -60,4 +77,4 @@ specific pages by adding the following to the front matter of a page: --- ``` - [5]: ../reference/meta-tags.md#metadata + [7]: #metadata diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 376eac19e..c9308d0d4 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -230,6 +230,16 @@ in the [color schemes][10] section: --md-primary-fg-color--light: #ECB7B7; --md-primary-fg-color--dark: #90030C; } +``` + +Additionally, the `slate` color scheme defines all of it's colors via `hsla` +color functions and deduces its colors from the `--md-hue` CSS variable. You +can tune the `slate` theme with: + +``` css +[data-md-color-scheme="slate"] { + --md-hue: 210; /* [0, 360] */ +} ``` [9]: https://www.w3.org/TR/selectors-4/#attribute-selectors diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md index c8a55c133..c89c857b7 100644 --- a/docs/setup/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -142,7 +142,7 @@ want to change in the [base translation][1] and add it to the partial. Let's say you want to change "__Table of contents__" to "__On this page__": -``` jinja +``` html {% macro t(key) %}{{ { "toc.title": "On this page" }[key] }}{% endmacro %} diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 305fe4a70..b4392a572 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -54,9 +54,9 @@ In order to integrate another analytics service provider offering an asynchronous JavaScript-based tracking solution, you can [extend the theme][5] and [override the `analytics` block][6]: -``` jinja +``` html {% block analytics %} - {# Add custom analytics integration here #} + {% endblock %} ``` diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 486885585..68b3a8aa9 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -212,7 +212,7 @@ template, both of which don't transform the query prior to submission, or customize the `transform` function, you can do this by [overriding the `config` block][14]: -``` jinja +``` html {% block config %}