Added documentation on keyboard navigation

docs/creating-your-site.md

@@ -60,7 +60,7 @@ theme:
 
 ### Advanced configuration
 
-Material for MkDocs comes with a lot of configuration options. The _guides_
+Material for MkDocs comes with a lot of configuration options. The _setup_
 section explains in great detail how to configure and customize colors, fonts,
 icons and much more:
 

docs/reference/admonitions.md

@@ -16,7 +16,7 @@ inclusion and nesting of arbitrary content.
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 
 The [Admonition][2] extension, which is part of the standard Markdown
-library, is integrated with Material for MkDocs and can be enabled from
+library, is integrated with Material for MkDocs and can be enabled via
 `mkdocs.yml`:
 
 ``` yaml
@@ -32,7 +32,7 @@ markdown_extensions:
 [:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
 
 The [Details][4] extension, which is part of [Python Markdown Extensions][5],
-adds the ability to __make admonitions collapsible__. It can be enabled from
+adds the ability to __make admonitions collapsible__. It can be enabled via
 `mkdocs.yml`:
 
 ``` yaml

docs/reference/code-blocks.md

@@ -123,7 +123,7 @@ them at your own risk._
 The [InlineHilite][11] extension, which is part of [Python Markdown 
 Extensions][5] also integrates with Material for MkDocs and adds support for
 __syntax highlighting of inline code blocks__. It's built on top of the
-[Highlight][3] extension and can be enabled from `mkdocs.yml`:
+[Highlight][3] extension and can be enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
@@ -157,7 +157,7 @@ markdown_extensions:
 
 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`:
+can be enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:

docs/reference/content-tabs.md

@@ -15,7 +15,7 @@ environments. Material for MkDocs allows for beautiful and functional tabs, grou
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 
 The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
-integrates with Material for MkDocs and can be enabled from `mkdocs.yml`:
+integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:

docs/reference/footnotes.md

@@ -16,7 +16,7 @@ footnotes and render them at the bottom of the page.
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 
 The [Footnotes][2] extension, which is part of the standard Markdown library,
-adds the ability to add inline footnotes to a document and can be enabled from
+adds the ability to add inline footnotes to a document and can be enabled via
 `mkdocs.yml`:
 
 ``` yaml

docs/reference/lists.md

@@ -17,7 +17,7 @@ are supported through extensions.
 
 The [Definition List][1] extension, which is part of the standard Markdown
 library, adds the ability to add definitions lists to a document and can be 
-enabled from `mkdocs.yml`:
+enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:

docs/reference/meta-tags.md

@@ -14,7 +14,7 @@ template: overrides/main.html
 
 The [Metadata][1] extension, which is part of the standard Markdown
 library, adds the ability to add custom metadata to a document and can be 
-enabled from `mkdocs.yml`:
+enabled via `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:

docs/setup/adding-social-links.md

@@ -8,8 +8,8 @@ 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
+:fontawesome-brands-facebook:{: style="color: #4267B2" }, which can be
-configured through `mkdocs.yml`.
+configured via `mkdocs.yml`.
 
 ## Configuration
 

docs/setup/changing-the-colors.md

@@ -20,7 +20,7 @@ fit your brand's identity by using [CSS variables][2].
 
 Material for MkDocs supports two _color schemes_: a light mode, which is just
 called `default`, and a dark mode, which is called `slate`. The color scheme
-can be set from `mkdocs.yml`:
+can be set via `mkdocs.yml`:
 
 ``` yaml
 theme:
@@ -192,66 +192,45 @@ color:
 Material for MkDocs implements colors using [CSS variables][7] (custom
 properties). If you want to customize the colors beyond the palette (e.g. to
 use your brand-specific colors), you can add an [additional stylesheet][8] and
-tweak the following CSS variables:
+tweak the values of the CSS variables.
+
+Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" }
+__YouTube__, and want to set the primary color to your brand's palette, just
+add:
 
 ``` css
 :root {
-
+  --md-primary-fg-color:        #EE0F0F;
-  /* Default color shades */
+  --md-primary-fg-color--light: #ECB7B7;
-  --md-default-fg-color:               hsla(0, 0%, 0%, 0.87);
+  --md-primary-fg-color--dark:  #90030C;
-  --md-default-fg-color--light:        hsla(0, 0%, 0%, 0.54);
-  --md-default-fg-color--lighter:      hsla(0, 0%, 0%, 0.32);
-  --md-default-fg-color--lightest:     hsla(0, 0%, 0%, 0.07);
-  --md-default-bg-color:               hsla(0, 0%, 100%, 1);
-  --md-default-bg-color--light:        hsla(0, 0%, 100%, 0.7);
-  --md-default-bg-color--lighter:      hsla(0, 0%, 100%, 0.3);
-  --md-default-bg-color--lightest:     hsla(0, 0%, 100%, 0.12);
-
-  /* Primary color shades */
-  --md-primary-fg-color:               hsla(231, 48%, 48%, 1);
-  --md-primary-fg-color--light:        hsla(231, 44%, 56%, 1);
-  --md-primary-fg-color--dark:         hsla(232, 54%, 41%, 1);
-  --md-primary-bg-color:               hsla(0, 0%, 100%, 1);
-  --md-primary-bg-color--light:        hsla(0, 0%, 100%, 0.7);
-
-  /* Accent color shades */
-  --md-accent-fg-color:                hsla(231, 99%, 66%, 1);
-  --md-accent-fg-color--transparent:   hsla(231, 99%, 66%, 0.1);
-  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
-  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);
 }
 ```
 
-The colors of [code blocks][9], [admonitions][10], text links and the footer can
+See the file containing the [color definitions][6] for a list of all CSS
-be adjusted through dedicated CSS variables, which partly default to the base
+variables.
-colors or neutral colors:
-
-``` css
-:root > * {
-
-  /* Code color shades */
-  --md-code-bg-color:                  hsla(0, 0%, 96%, 1);
-  --md-code-fg-color:                  hsla(200, 18%, 26%, 1);
-
-  /* Text color shades */
-  --md-text-color:                     var(--md-default-fg-color);
-  --md-text-link-color:                var(--md-primary-fg-color);
-
-  /* Admonition color shades */
-  --md-admonition-bg-color:            var(--md-default-bg-color);
-  --md-admonition-fg-color:            var(--md-default-fg-color);
-
-  /* Footer color shades */
-  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
-  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
-  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
-  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
-  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.3);
-}
-```
 
   [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
   [7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
   [8]: ../customization.md#additional-stylesheets
-  [9]: ../reference/code-blocks.md
+
-  [10]: ../reference/admonitions.md
+
+### Custom color schemes
+
+[:octicons-file-code-24: Source][3] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
+Besides overriding specific colors, you can create your own, named color scheme
+by wrapping the definitions in the `[data-md-color-scheme="..."]`
+[attribute selector][9], which you can then set via `mkdocs.yml` as described
+in the [color schemes][10] section:
+
+``` css
+[data-md-color-scheme="youtube"] {
+  --md-primary-fg-color:        #EE0F0F;
+  --md-primary-fg-color--light: #ECB7B7;
+  --md-primary-fg-color--dark:  #90030C;
+}
+```
+
+  [9]: https://www.w3.org/TR/selectors-4/#attribute-selectors
+  [10]: #color-scheme

docs/setup/changing-the-fonts.md

@@ -39,7 +39,7 @@ The typeface will be loaded in 300, 400, _400i_ and __700__.
 :octicons-milestone-24: Default: [`Roboto Mono`][4]
 
 The _proportional font_ is used for code blocks and can be configured separately.
-Just like the regular font, it can be set to any valid [Google Font][1] from
+Just like the regular font, it can be set to any valid [Google Font][1] via
 `mkdocs.yml` with:
 
 ``` yaml

docs/setup/changing-the-language.md

@@ -14,7 +14,7 @@ search can be configured to use a language-specific stemmer (if available).
 
 [:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
 
-You can set the _site language_ from `mkdocs.yml` with:
+You can set the _site language_ in `mkdocs.yml` with:
 
 ``` yaml
 theme:
@@ -129,7 +129,7 @@ directionality:
 
 ## Customization
 
-### Translations
+### Custom translations
 
 [:octicons-file-code-24: Source][1] ·
 :octicons-mortar-board-24: Difficulty: _easy_
@@ -137,8 +137,9 @@ directionality:
 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
 `partials/language`, e.g. `en-custom.html`. Next, look up the translation you
-want to change in the [base translation][1] and add it to the partial you just
+want to change in the [base translation][1] and add it to the partial.
-created. Say, you want to change "__Table of contents__" to "__On this page__":
+
+Let's say you want to change "__Table of contents__" to "__On this page__":
 
 ``` jinja
 {% macro t(key) %}{{ {

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

@@ -20,7 +20,7 @@ additional icons][1] with very little effort.
 
 There're two ways to specify a _logo_: it must be a valid path to [any icon 
 bundled with the theme][3], or to a user-provided image located in the `docs`
-folder. Both can be set from `mkdocs.yml`:
+folder. Both can be set via `mkdocs.yml`:
 
 === "Icon"
 
@@ -46,7 +46,7 @@ folder. Both can be set from `mkdocs.yml`:
 :octicons-milestone-24: Default: `assets/images/favicon.png`
 
 The _favicon_ can be changed to a path pointing to a user-provided image, which 
-must be located in the `docs` folder. It can be set from `mkdocs.yml`:
+must be located in the `docs` folder. It can be set via `mkdocs.yml`:
 
 ``` yaml
 theme:

docs/setup/setting-up-navigation.md

@@ -18,7 +18,7 @@ behavior of navigational elements, some of those through _feature flags_.
 
 When _instant loading_ is activated, clicks on all internal links will be
 intercepted and dispatched via [XHR][2] without fully reloading the page. It
-can be enabled from `mkdocs.yml` with:
+can be enabled via `mkdocs.yml` with:
 
 ``` yaml
 theme:
@@ -41,7 +41,7 @@ intact in-between document switches.
 
 When _tabs_ are activated, top-level sections are rendered in a menu layer
 below the header on big screens (but not when the sidebar is hidden). It can be
-enabled from `mkdocs.yml` with:
+enabled via `mkdocs.yml` with:
 
 ``` yaml
 theme:
@@ -180,3 +180,52 @@ 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
+
+### Keyboard shortcuts
+
+[:octicons-file-code-24: Source][10] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
+Material for MkDocs includes several keyboard shortcuts that make it possible
+to navigate your project documentation via keyboard. There're two modes:
+
+`search`{: #search }
+
+:   This mode is active when the _search is focused_. It provides several key
+    bindings to make search accessible and navigable via keyboard:
+
+    - ++arrow-down++ , ++arrow-up++ : select next / previous result
+    - ++esc++ , ++tab++ : close search dialog
+    - ++enter++ : follow selected result
+
+`global`{: #global }
+
+:   This mode is the active when _search is not active_, i.e. when there's no
+    other focussed element that is suceptible to keyboard input. The following
+    keys are bound:
+
+    - ++f++ , ++s++ , ++slash++ : open search dialog
+    - ++p++ , ++comma++ : go to previous page
+    - ++n++ , ++period++ : go to next page
+
+Let's say you want to bind some action to the ++x++ key. By using [additional
+JavaScript][11], you can subscribe to the `keyboard$` observable and attach
+your custom event listener:
+
+``` js
+app.keyboard$.subscribe(key => {
+  if (key.mode === "global" && key.type === "x") {
+    /* Add custom keyboard handler here */
+    key.claim()
+  }
+})
+```
+
+The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
+on the underlying event, so the key press will not propagate further and touch
+other event listeners.
+
+  [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+  [11]: ../customization.md#additional-javascript

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.daf2a690.min.css",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.8025dbd5.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.daf2a690.min.css.map",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.8025dbd5.min.css.map",
   "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.93b89301.min.css",
   "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.93b89301.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.a53427c9.min.css",

material/base.html

@@ -41,7 +41,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.daf2a690.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.8025dbd5.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.a53427c9.min.css' | url }}">
       {% endif %}

material/overrides/main.html

@@ -59,7 +59,7 @@
         if (ev.target instanceof HTMLElement) {
           var el = ev.target.closest("a[href^=http]")
           if (el)
-            ga('send', 'event', 'outbound', 'click', el.href)
+            ga("send", "event", "outbound", "click", el.href)
         }
       })
     })

src/assets/stylesheets/main/extensions/markdown/_codehilite.scss

@@ -76,7 +76,7 @@ $codehilite-name-variable: #3E61A2;
 $codehilite-name-variable-class: #3E61A2;
 $codehilite-name-variable-instance: #3E61A2;
 $codehilite-name-variable-global: #3E61A2;
-$codehilite-name-extension: #EC407A;
+$codehilite-name-extension: inherit;
 
 // Numbers
 $codehilite-literal-number: #E74C3C;

src/overrides/home.html

@@ -44,19 +44,15 @@
       display: none;
     }
 
-    /* [tablet landscape +]: Display content and image next to each other */
-    @media screen and (min-width: 60em) {
-
     /* Hide table of contents */
+    @media screen and (min-width: 60em) {
       .md-sidebar--secondary {
         display: none;
       }
     }
 
-    /* [screen +]: Adjust spacing */
-    @media screen and (min-width: 76.25em) {
-
     /* Hide navigation */
+    @media screen and (min-width: 76.25em) {
       .md-sidebar--primary {
         display: none;
       }

src/overrides/main.html

@@ -103,7 +103,7 @@
         if (ev.target instanceof HTMLElement) {
           var el = ev.target.closest("a[href^=http]")
           if (el)
-            ga('send', 'event', 'outbound', 'click', el.href)
+            ga("send", "event", "outbound", "click", el.href)
         }
       })
     })