From 5ecf99c249b43539727e1af28892d9f790974b5f Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 22 Jul 2020 11:57:41 +0200 Subject: [PATCH] Added docs on keys integration --- docs/customization.md | 3 ++ docs/reference/code-blocks.md | 48 ++++++++++++++++++---- docs/setup/adding-a-comment-system.md | 18 +++++++++ docs/setup/setting-up-site-analytics.md | 53 +++++++++++++++---------- docs/setup/setting-up-site-search.md | 2 +- 5 files changed, 95 insertions(+), 29 deletions(-) diff --git a/docs/customization.md b/docs/customization.md index 1f66e4e08..e74774733 100644 --- a/docs/customization.md +++ b/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 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 58efa14a1..1a9cffd4c 100644 --- a/docs/reference/code-blocks.md +++ b/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 diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index e69de29bb..6b5cf7f44 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/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 diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 696b283ba..2d3506a8c 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/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 -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 diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index a294d2e41..2e0094431 100644 --- a/docs/setup/setting-up-site-search.md +++ b/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_