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:
parent
6295251c24
commit
d6e058392d
@ -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:
|
||||
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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) %}{{ {
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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",
|
||||
|
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -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 %}
|
||||
|
@ -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)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
@ -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;
|
||||
|
@ -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;
|
||||
}
|
||||
|
@ -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)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
Loading…
Reference in New Issue
Block a user