Added docs on keys integration

docs/customization.md

@@ -96,12 +96,15 @@ The directory layout of the theme is as follows:
 
 ``` sh
 .
+├─ .icons/                             # Bundled icon sets
 ├─ assets/
 │  ├─ images/                          # Images and icons
 │  ├─ javascripts/                     # JavaScript
 │  └─ stylesheets/                     # Stylesheets
 ├─ partials/
 │  ├─ integrations/                    # Third-party integrations
+│  │  ├─ analytics.html                # - Google Analytics
+│  │  └─ disqus.html                   # - Disqus
 │  ├─ language/                        # Localized languages
 │  ├─ footer.html                      # Footer bar
 │  ├─ header.html                      # Header bar

docs/reference/code-blocks.md

@@ -133,7 +133,7 @@ markdown_extensions:
 See the section on [inline code blocks][12] for usage information.
 
   [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
-  [12]: #inline-code-blocks
+  [12]: #highlighting-inline-code-blocks
 
 ### SuperFences
 
@@ -151,6 +151,22 @@ markdown_extensions:
   [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
   [14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
+### Keys
+
+[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
+
+The [Keys][16] extension, which is part of [Python Markdown Extensions][5],
+allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
+can be enabled from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.keys
+```
+
+  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_keys.scss
+  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+
 ## Usage
 
 This section discusses how to use different syntax highlighting features with
@@ -161,7 +177,7 @@ a JavaScript syntax highlighter.
 
 Code blocks must be enclosed with two separate lines containing three backticks.
 To add code highlighting to those blocks, add the language short name directly
-after the opening block. See the [list of available lexers][15] to find the
+after the opening block. See the [list of available lexers][17] to find the
 short name for a given language.
 
 _Example_:
@@ -178,7 +194,7 @@ _Result_:
 import tensorflow as tf
 ```
 
-  [15]: https://pygments.org/docs/lexers/
+  [17]: https://pygments.org/docs/lexers/
 
 ### Adding line numbers
 
@@ -237,11 +253,11 @@ def bubble_sort(items):
                 items[j], items[j + 1] = items[j + 1], items[j]
 ```
 
-### Inline code blocks
+### Highlighting inline code blocks
 
-When [InlineHilite][16] is enabled, inline code blocks can be highlighted by
+When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
 prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
-the [language short name][15].
+the [language short name][17].
 
 _Example_:
 
@@ -253,4 +269,22 @@ _Result_:
 
 The `#!python range()` function is used to generate a sequence of numbers.
 
-  [16]: #inlinehilite
+  [18]: #inlinehilite
+
+### Displaying keyboard keys
+
+When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
+See the [Python Markdown Extensions][16] documentation for a list of all
+available keys.
+
+_Example_:
+
+```
+++ctrl+alt+del++
+```
+
+_Result_:
+
+++ctrl+alt+del++
+
+  [19]: #keys

docs/setup/adding-a-comment-system.md

@@ -0,0 +1,18 @@
+# Adding a comment system
+
+Material for MkDocs is natively integrated with [Disqus][1], a comment system
+that provides a wide range of features like social integrations, user profiles,
+as well as spam and moderation tools. Of course, other comment systems can be 
+integrated, too.
+
+  [1]: https://disqus.com/
+
+## Configuration
+
+### Comment system
+
+
+
+## Customization
+
+### Selective integration

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

@@ -6,19 +6,20 @@ template: overrides/main.html
 
 As with any other service that is offered on the web, understanding how your
 documentation is actually used can be an essential success factor. While
-Material for MkDocs natively integrates with [Google Analytics][1], other 
+Material for MkDocs natively integrates with [Google Analytics][1], [other
-analytics services can be used, too.
+analytics services][2] can be used, too.
 
   [1]: https://developers.google.com/analytics
+  [2]: #using-other-analytics-services
 
 ## Configuration
 
-### Site analytics
+### Google Analytics
 
-[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default: _none_
+[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
 
 After heading over to your [Google Analytics][1] account to [create a new
-property][3] in order to obtain a new tracking id of the form `UA-XXXXXXXX-X`,
+property][4] in order to obtain a new tracking id of the form `UA-XXXXXXXX-X`,
 add it to `mkdocs.yml`:
 
 ``` yaml
@@ -27,12 +28,10 @@ google_analytics:
   - auto
 ```
 
-Publish and refresh your site, and you should see events bubbling up.
+  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
+  [4]: https://support.google.com/analytics/answer/1042508
 
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
+### Tracking site search
-  [3]: https://support.google.com/analytics/answer/1042508
-
-### Site search analytics
 
 Besides basic page views, _site search_ can also be tracked to better understand
 how people use your documentation and what they expect to find. To enable
@@ -46,30 +45,42 @@ search tracking:
 
 ## Customization
 
-### Other analytics services
+### Using other analytics services
 
 [:octicons-file-code-24: Source][2] · 
 :octicons-mortar-board-24: Difficulty: _easy_
 
 In order to integrate another analytics service provider offering an
-asynchronous JavaScript-based tracking solution, you can [extend the theme][4]
+asynchronous JavaScript-based tracking solution, you can [extend the theme][5]
-and [override the `analytics` block][5].
+and [override the `analytics` block][6]:
 
-  [4]: ../customization.md#extending-the-theme
+``` jinja
-  [5]: ../customization.md#overriding-blocks
+{% block analytics %}
+  {# Add custom analytics integration here #}
+{% endblock %}
+```
 
-### Instant loading
+  [5]: ../customization.md#extending-the-theme
+  [6]: ../customization.md#overriding-blocks
+
+### Using instant loading
 
 [:octicons-file-code-24: Source][2] · 
 :octicons-mortar-board-24: Difficulty: _easy_
 
-If you're using [instant loading][6], you can use the `DOMContentSwitch` event
+If you're using [instant loading][7], you may use the `location$` observable
-to listen for navigation events and register a page view event with:
+which will emit the current `URL` to listen for navigation events and register
+a page view event with:
 
 ``` js
-document.addEventListener("DOMContentSwitch", function() {
+app.location$.subscribe(function(url) {
-  /* Register page event here */
+  /* Add custom page event tracking here */
 })
 ```
 
-  [6]: setting-up-navigation.md#instant-loading
+Note that this must be integrated with [additional JavaScript][8], and cannot be
+included as part of the `analytics` block, which is included in the `head` of
+the document.
+
+  [7]: setting-up-navigation.md#instant-loading
+  [8]: ../customization.md#additional-javascript

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

@@ -230,7 +230,7 @@ and must return the processed query string to be submitted to the search index.
   [13]: ../customization.md#extending-the-theme
   [14]: ../customization.md#overriding-blocks
 
-### Worker implementation
+### Custom search
 
 [:octicons-file-code-24: Source][15] · 
 :octicons-mortar-board-24: Difficulty: _challenging_