Added guide for social links

docs/creating-your-site.md

@@ -63,32 +63,32 @@ Material for MkDocs comes with a lot of configuration options. The _guides_
 section explains in great detail how to configure and customize colors, fonts,
 icons and much more:
 
-* [Changing colors][3]
+* [Changing the colors][3]
 * [Changing the fonts][4]
 * [Changing the language][5]
-* [Setting up navigation][6]
-* [Setting up site search][7]
-* [Adding a git repository][8]
-* [Adding icons and emojis][9]
-* [Adding footer links][10]
+* [Changing the logo and icons][6]
+* [Setting up navigation][7]
+* [Setting up site search][8]
+* [Adding a git repository][9]
+* [Adding social links][10]
 * [Adding site analytics][11]
 * [Adding a comment system][12]
 * [Adding an announcement bar][13]
-* [Adding a landing page][14]
+<!-- * [Adding a landing page][14] -->
 
   [2]: getting-started.md#installation
-  [3]: guides/changing-colors.md
-  [4]: guides/changing-the-fonts.md
-  [5]: guides/changing-the-language.md
-  [6]: guides/setting-up-navigation.md
-  [7]: guides/setting-up-site-search.md
-  [8]: guides/adding-a-git-repository.md
-  [9]: guides/adding-icons-and-emojis.md
-  [10]: guides/adding-footer-links.md
-  [11]: guides/adding-site-analytics.md
-  [12]: guides/adding-a-comment-system.md
-  [13]: guides/adding-an-announcement-bar.md
-  [14]: guides/adding-a-landing-page.md
+  [3]: setup/changing-the-colors.md
+  [4]: setup/changing-the-fonts.md
+  [5]: setup/changing-the-language.md
+  [6]: setup/changing-the-logo-and-icons.md
+  [7]: setup/setting-up-navigation.md
+  [8]: setup/setting-up-site-search.md
+  [9]: setup/adding-a-git-repository.md
+  [10]: setup/adding-social-links.md
+  [11]: setup/adding-site-analytics.md
+  [12]: setup/adding-a-comment-system.md
+  [13]: setup/adding-an-announcement-bar.md
+  <!--[14]: setup/adding-a-landing-page.md-->
 
 ## Previewing as you write
 
@@ -119,7 +119,7 @@ Point your browser to [localhost:8000][15] and you should see:
 [![Creating your site][16]][15]
 
   [15]: http://localhost:8000
-  [16]: assets/guides/creating-your-site.png
+  [16]: assets/creating-your-site.png
 
 ## Building your site
 

docs/data-privacy.md

@@ -30,7 +30,7 @@ Neue__ and __Monaco__ with their corresponding fall backs, relying on system
 fonts. You can easily include your own, self-hosted webfont by [overriding][4]
 the `fonts` block.
 
-  [2]: guides/changing-the-fonts.md
+  [2]: setup/changing-the-fonts.md
   [3]: https://github.com/google/fonts/issues/1495
   [4]: customization.md#overriding-blocks
 

docs/reference/code-blocks.md

@@ -24,7 +24,7 @@ configuring syntax highlighting of code blocks:
 
 `use_pygments`
 
-:   :octicons-milestone-24: Default: `true` · This option allows to control
+:   :octicons-milestone-24: Default: `true` – This option allows to control
     whether highlighting should be carried out during build time by
     [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
     necessary  [additional stylesheets][6] and [JavaScript][7] if you want to
@@ -73,7 +73,7 @@ configuring syntax highlighting of code blocks:
 
 `linenums`
 
-:   :octicons-milestone-24: Default: `false` · This option will add line numbers
+:   :octicons-milestone-24: Default: `false` – This option will add line numbers
     to _all_ code blocks. If you wish to add line numbers to _some_, but not all
     code blocks, consult the section on [adding line numbers][10] later in this
     document, which also contains some tips on working with line numbers:
@@ -86,7 +86,7 @@ configuring syntax highlighting of code blocks:
 
 `linenums_style`
 
-:   :octicons-milestone-24: Default: `table` · The Highlight extension provides
+:   :octicons-milestone-24: Default: `table` – The Highlight extension provides
     three ways to add line numbers, all of which are supported by Material for
     MkDocs. While `table` wraps a code block in a table, `inline` and
     `pymdownx.inline` render line numbers as part of the line itself:

docs/reference/content-tabs.md

@@ -26,6 +26,22 @@ markdown_extensions:
   [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
   [3]: https://facelessuser.github.io/pymdown-extensions/
 
+### SuperFences
+
+[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5]
+
+The [SuperFences][5] extension, which is also part of [Python Markdown
+Extensions][3], allows for the __nesting of code blocks inside tabs__, and is
+therefore strongly recommended:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+```
+
+  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
+  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
 ## Usage
 
 ### Grouping code blocks
@@ -123,7 +139,7 @@ _Result_:
 ### Embedded content
 
 Content tabs can contain arbitrary nested content, including further content
-tabs, and can be nested in other blocks like [admonitions][4], [details][5] or 
+tabs, and can be nested in other blocks like [admonitions][6], [details][7] or
 blockquotes:
 
 _Example_:
@@ -200,5 +216,5 @@ _Result_:
         2. Donec vitae suscipit est
         3. Nulla tempor lobortis orci
 
-  [4]: admonitions.md
-  [5]: admonitions.md#details
+  [6]: admonitions.md
+  [7]: admonitions.md#details

docs/setup/adding-a-git-repository.md

@@ -57,17 +57,18 @@ theme:
     repo: fontawesome/brands/git-alt
 ```
 
-Some popular repository icons:
+Some popular choices:
 
-- :fontawesome-brands-git: – `:fontawesome-brands-git:`
-- :fontawesome-brands-git-square: – `:fontawesome-brands-git-square:`
-- :fontawesome-brands-github: – `:fontawesome-brands-github:`
-- :fontawesome-brands-github-alt: – `:fontawesome-brands-github-alt:`
-- :fontawesome-brands-github-square: – `:fontawesome-brands-github-square:`
-- :fontawesome-brands-gitlab: – `:fontawesome-brands-gitlab:`
-- :fontawesome-brands-gitkraken: – `:fontawesome-brands-gitkraken:`
-- :fontawesome-brands-bitbucket: – `:fontawesome-brands-bitbucket:`
-- :fontawesome-solid-trash: – `:fontawesome-solid-trash:`
+- :fontawesome-brands-git: – `fontawesome/brands/git`
+- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
+- :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
+- :fontawesome-brands-github: – `fontawesome/brands/github`
+- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
+- :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
+- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
+- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
+- :fontawesome-solid-trash: – `fontawesome/solid/trash`
 
   [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
 

docs/setup/adding-social-links.md

@@ -0,0 +1,88 @@
+---
+template: overrides/main.html
+---
+
+# Adding social links
+
+The footer of your project documentation is a good place to add links to
+websites or platforms you or your company are using as additional marketing 
+channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" },
+:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or
+:fontawesome-brands-facebook:{: style="color: #3B5998" }, which can be
+configured through `mkdocs.yml`.
+
+## Configuration
+
+[:octicons-file-code-24: Source][1] · 
+:octicons-milestone-24: Default: _none_
+
+All _social links_ are rendered next to the copyright information as part of the 
+footer of your project documentation. Add a list of social links in `mkdocs.yml` 
+with:
+
+``` yaml
+extra:
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/squidfunk
+```
+
+For each entry, the following fields are available:
+
+`icon`
+
+:     :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+      This field must point to a valid icon path referencing [any icon bundled 
+      with the theme][2], or the build will not succeed. Some popular choices:
+
+      - :fontawesome-brands-behance: – `fontawesome/brands/behance`
+      - :fontawesome-brands-docker: – `fontawesome/brands/docker`
+      - :fontawesome-brands-github: – `fontawesome/brands/github`
+      - :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
+      - :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
+      - :fontawesome-brands-medium: – `fontawesome/brands/medium`
+      - :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
+      - :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
+      - :fontawesome-brands-slack: – `fontawesome/brands/slack`
+      - :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
+  [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+
+`link`
+
+:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
+    This field must contain a valid relative or absolute URL including the URI 
+    scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
+
+    === "Twitter"
+
+        ``` yaml
+        extra:
+          social:
+            - icon: fontawesome/brands/twitter
+              link: https://twitter.com/squidfunk
+        ```
+
+    === "Email address"
+
+        ``` yaml
+        extra:
+          social:
+            - icon: fontawesome/solid/paper-plane
+              link: mailto:martin.donath@squidfunk.com
+        ```
+
+`name`
+
+:   :octicons-milestone-24: Default: _domain name from_ `link`, if available – 
+    This field is used as the link's `title` attribute and can be set to a 
+    discernable name to improve accessibility:
+
+    ``` yaml
+    extra:
+      social:
+        - icon: fontawesome/brands/twitter
+          link: https://twitter.com/squidfunk
+          name: squidfunk on Twitter
+    ```

docs/setup/changing-the-colors.md

@@ -2,7 +2,7 @@
 template: overrides/main.html
 ---
 
-# Changing colors
+# Changing the colors
 
 As any good Material Design implementation, Material for MkDocs supports
 Google's original [color palette][1], which can be easily configured through 
@@ -49,8 +49,8 @@ scheme:
 </script>
 
 The _color scheme_ can also be set based on _user preference_, which makes use
-of the `prefers-color-scheme` media query. This can be done by adding the
-following to `mkdocs.yml`:
+of the `prefers-color-scheme` media query, by setting the value in `mkdocs.yml`
+to `preference`:
 
 ``` yaml
 theme:
@@ -184,8 +184,10 @@ color:
 
 ## Customization
 
+### Brand colors
+
 [:octicons-file-code-24: Source][6] ·
-:octicons-mortar-board-24: Difficulty: easy
+:octicons-mortar-board-24: Difficulty: _easy_
 
 Material for MkDocs implements colors using [CSS variables][7] (custom
 properties). If you want to customize the colors beyond the palette (e.g. to

docs/setup/changing-the-fonts.md

@@ -54,23 +54,31 @@ The typeface will be loaded in 400.
 
 ## Customization
 
-[:octicons-file-code-24: Source][2] ·
-:octicons-mortar-board-24: Difficulty: easy
-
 If you want to load fonts from other destinations or don't want to use Google
-Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines
-to `mkdocs.yml`:
+Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
+font loading as described below.
+
+### Disable font loading
+
+[:octicons-file-code-24: Source][2] ·
+:octicons-mortar-board-24: Difficulty: _none_
+
+If you want to prevent typefaces from being loaded from Google Fonts and fall
+back to system fonts, add the following lines to `mkdocs.yml`:
 
 ``` yaml
 theme:
   font: false
 ```
 
-This will prevent typefaces from being loaded from Google Fonts. As a fallback,
-common system fonts will be used automatically. Additionally, if you want to
-load a font from another destination, you may either follow the guide on [theme
-extension][6] and [override the `fonts` block][7] with a `style` tag, or use an
-[additional stylesheet][8] to add the necessary `@font-face` definition:
+### Additional fonts
+
+[:octicons-file-code-24: Source][2] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
+If you want to load an (additional) font from another destination, or override
+the fallback font, you can use an [additional stylesheet][8] to add the
+corresponding `@font-face` definition:
 
 ``` css
 @font-face {
@@ -79,9 +87,11 @@ extension][6] and [override the `fonts` block][7] with a `style` tag, or use an
 }
 ```
 
-The font can then be configured to be used as the regular or proportional font:
+The font can then be configured to be used globally as the regular or
+proportional font, or limited to be used for specific elements only, e.g.
+headlines:
 
-=== "Regular font"
+=== "Body copy"
 
     ``` css
     body, input {
@@ -89,7 +99,15 @@ The font can then be configured to be used as the regular or proportional font:
     }
     ```
 
-=== "Proportional font"
+=== "Headlines"
+
+    ``` css
+    .md-typeset h1 {
+      font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
+    }
+    ```
+
+=== "Code blocks"
 
     ``` css
     pre, code, kbd {

docs/setup/changing-the-language.md

@@ -129,8 +129,10 @@ directionality:
 
 ## Customization
 
+### Translations
+
 [:octicons-file-code-24: Source][1] ·
-:octicons-mortar-board-24: Difficulty: easy
+:octicons-mortar-board-24: Difficulty: _easy_
 
 If you want to customize some (or all) of the translations for your language,
 you may follow the guide on [theme extension][6] and create a new partial in

docs/setup/changing-the-logo-and-icons.md

@@ -0,0 +1 @@
+Icons are all inlined!

docs/setup/setting-up-navigation.md

@@ -180,17 +180,3 @@ them at your own risk._
   [7]: https://python-markdown.github.io/extensions/toc/
   [8]: https://python-markdown.github.io/extensions/toc/#usage
   [9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
-
-## Customization
-
-[:octicons-file-code-24: Source][10] ·
-:octicons-mortar-board-24: Difficulty: moderate
-
-All navigational elements are defined as partials and can be overridden through
-[theme extension][11] by [overriding partials][12] or [blocks][13], i.e.
-`site_nav` which contains both sidebars, `tabs` and `footer`.
-
-  [10]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials
-  [11]: ../customization.md#extending-the-theme
-  [12]: ../customization.md#overriding-partials
-  [13]: ../customization.md#overriding-blocks

docs/setup/setting-up-site-search.md

@@ -32,7 +32,7 @@ The following options are supported:
 
 `lang`
 
-:   :octicons-milestone-24: Default: _automatically set_ · This option allows
+:   :octicons-milestone-24: Default: _automatically set_ – This option allows
     to include the language-specific stemmers provided by [lunr-languages][5].
     Note that Material for MkDocs will set this automatically based on the
     [site language][6], but it may be overriden, e.g. to support multiple
@@ -159,7 +159,7 @@ This section explains how search can be customized to tailor it to your needs.
 ### Query transformation
 
 [:octicons-file-code-24: Source][12] · 
-:octicons-mortar-board-24: Difficulty: easy
+:octicons-mortar-board-24: Difficulty: _easy_
 
 When a user enters a query into the search box, the query is pre-processed
 before it is submitted to the search index. Material for MkDocs will apply the
@@ -233,7 +233,7 @@ and must return the processed query string to be submitted to the search index.
 ### Worker implementation
 
 [:octicons-file-code-24: Source][15] · 
-:octicons-mortar-board-24: Difficulty: challenging
+:octicons-mortar-board-24: Difficulty: _challenging_
 
 Material for MkDocs implements search as part of a [web worker][16]. If you
 want to switch the web worker with your own implementation, e.g. to submit

mkdocs.yml

@@ -131,29 +131,32 @@ nav:
     - Customization: customization.md
     #- Troubleshooting: troubleshooting.md
     - Data privacy: data-privacy.md
+  - Setup:
+    - Changing the colors: setup/changing-the-colors.md
+    - Changing the fonts: setup/changing-the-fonts.md
+    - Changing the language: setup/changing-the-language.md
+    - Changing the logo and icons: setup/changing-the-logo-and-icons.md
+    - Setting up navigation: setup/setting-up-navigation.md
+    - Setting up site search: setup/setting-up-site-search.md
+    - Adding a git repository: setup/adding-a-git-repository.md
+    - Adding social links: setup/adding-social-links.md
+    - Adding site analytics: setup/adding-site-analytics.md
+    - Adding a comment system: setup/adding-a-comment-system.md
+    - Adding an announcement bar: setup/adding-an-announcement-bar.md
+    #- Adding a landing page: setup/adding-a-landing-page.md
   - Reference:
     - Admonitions: reference/admonitions.md
     - Code blocks: reference/code-blocks.md
     - Content tabs: reference/content-tabs.md
     - Footnotes: reference/footnotes.md
     - Lists: reference/lists.md
-  - Guides:
-    - Changing colors: guides/changing-colors.md
-    - Changing the fonts: guides/changing-the-fonts.md
-    - Changing the language: guides/changing-the-language.md
-    - Setting up navigation: guides/setting-up-navigation.md
-    - Setting up site search: guides/setting-up-site-search.md
-    - Adding a git repository: guides/adding-a-git-repository.md
-    - Adding icons and emojis: guides/adding-icons-and-emojis.md
-    - Adding footer links: guides/adding-footer-links.md
-    - Adding site analytics: guides/adding-site-analytics.md
-    - Adding a comment system: guides/adding-a-comment-system.md
-    - Adding an announcement bar: guides/adding-an-announcement-bar.md
-    - Adding a landing page: guides/adding-a-landing-page.md
-  - Releases:
-    - Upgrading to 5.x: releases/5.md
-    - Upgrading to 4.x: releases/4.md
-    - Changelog: releases/changelog.md
+  # - Releases:
+  #   - Upgrading to 5.x: releases/5.md
+  #   - Upgrading to 4.x: releases/4.md
+  #   - Changelog: releases/changelog.md
+  # Changelog:
+  #  - Releases
+  #  - Migration
 
   # - Contributing: contributing.md
   # - License: license.md