1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Added documentation on keyboard navigation

This commit is contained in:
squidfunk 2020-07-23 13:17:50 +02:00
parent 6295251c24
commit d6e058392d
21 changed files with 114 additions and 89 deletions

View File

@ -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:

View File

@ -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

View File

@ -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:

View File

@ -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:

View File

@ -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

View File

@ -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:

View File

@ -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:

View File

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

View File

@ -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 {
/* Default color shades */
--md-default-fg-color: hsla(0, 0%, 0%, 0.87);
--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);
--md-primary-fg-color: #EE0F0F;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
```
The colors of [code blocks][9], [admonitions][10], text links and the footer can
be adjusted through dedicated CSS variables, which partly default to the base
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);
}
```
See the file containing the [color definitions][6] for a list of all CSS
variables.
[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

View File

@ -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

View File

@ -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
created. Say, you want to change "__Table of contents__" to "__On this page__":
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
{% macro t(key) %}{{ {

View File

@ -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:

View File

@ -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

View File

@ -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.map": "assets/stylesheets/main.daf2a690.min.css.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.8025dbd5.min.css",
"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",

View File

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

View File

@ -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)
}
})
})

View File

@ -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;

View File

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

View File

@ -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)
}
})
})