mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-09-24 03:18:21 +02:00
Added docs on keys integration
This commit is contained in:
squidfunk
parent
4a50cab8c8
commit
5ecf99c249
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
analytics services can be used, too.
|
||||
Material for MkDocs natively integrates with [Google Analytics][1], [other
|
||||
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
|
||||
[3]: https://support.google.com/analytics/answer/1042508
|
||||
|
||||
### Site search analytics
|
||||
### Tracking site search
|
||||
|
||||
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]
|
||||
and [override the `analytics` block][5].
|
||||
asynchronous JavaScript-based tracking solution, you can [extend the theme][5]
|
||||
and [override the `analytics` block][6]:
|
||||
|
||||
[4]: ../customization.md#extending-the-theme
|
||||
[5]: ../customization.md#overriding-blocks
|
||||
``` jinja
|
||||
{% 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
|
||||
to listen for navigation events and register a page view event with:
|
||||
If you're using [instant loading][7], you may use the `location$` observable
|
||||
which will emit the current `URL` to listen for navigation events and register
|
||||
a page view event with:
|
||||
|
||||
``` js
|
||||
document.addEventListener("DOMContentSwitch", function() {
|
||||
/* Register page event here */
|
||||
app.location$.subscribe(function(url) {
|
||||
/* 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
|
||||
|
||||
@ -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_
|
||||
|
||||
Loading…
Reference in New Issue
Block a user