Added Open Graph and Twitter cards documentation

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 %}

docs/deprecations.md

@@ -99,9 +99,9 @@ templates can be shared among multiple pages:
 
 === "Template"
 
-    ``` jinja
+    ``` html
     {% block hero %}
-      {# Add custom hero here #}
+      <!-- Add custom hero here -->
     {% endblock %}
     ```
 

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 {

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,
+The [Metadata][3] 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
+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
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
-  [2]: https://jekyllrb.com/docs/front-matter/
+  [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 %}
+  <meta property="og:type" content="website" />
+  <meta property="og:title" content="{{ title }}" />
+  <meta property="og:description" content="{{ config.site_description }}" />
+  <meta property="og:url" content="{{ page.canonical_url }}" />
+  <meta property="og:image" content="<url>" />
+  <meta property="og:image:type" content="image/png" />
+  <meta property="og:image:width" content="1200" />
+  <meta property="og:image:height" content="630" />
+{% 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 %}
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:site" content="<username>" />
+  <meta name="twitter:creator" content="<username>" />
+  <meta name="twitter:title" content="{{ title }}" />
+  <meta name="twitter:description" content="{{ config.site_description }}" />
+  <meta name="twitter:image" content="<url>" />
+{% 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

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

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

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 %}

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 #}
+  <!-- Add custom analytics integration here -->
 {% endblock %}
 ```
 

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 %}
   <script>
     var search = {
@@ -241,7 +241,7 @@ want to switch the web worker with your own implementation, e.g. to submit
 search to an external service, you can add a custom JavaScript file to the `docs`
 directory and [override the `config` block][14]:
 
-``` jinja
+``` html
 {% block config %}
   <script>
     var search = {

src/assets/stylesheets/palette/_scheme.scss

@@ -27,7 +27,7 @@
 // Slate theme, i.e. dark mode
 [data-md-color-scheme="slate"] {
 
-  // Slate's hue in the range [0,255] - change this variable to alter the tone
+  // Slate's hue in the range [0,360] - change this variable to alter the tone
   // of the theme, e.g. to make it more redish or greenish. This is a slate-
   // specific variable, but the same approach may be adapted to custom themes.
   --md-hue: 232;