Updated documentation with more screenshots and examples
@ -1,3 +1,8 @@
|
||||
mkdocs-material-6.1.4+insiders-1.9.0 (2020-11-07)
|
||||
|
||||
* Added support for hidding navigation and table of contents on any page
|
||||
* Removed autohiding table of contents when empty
|
||||
|
||||
mkdocs-material-6.1.4 (2020-11-07)
|
||||
|
||||
* Fixed sidebar jitter when scrolling footer into view
|
||||
|
BIN
docs/assets/screenshots/hide-navigation-toc.png
Normal file
After Width: | Height: | Size: 117 KiB |
BIN
docs/assets/screenshots/hide-navigation.png
Normal file
After Width: | Height: | Size: 134 KiB |
BIN
docs/assets/screenshots/hide-toc.png
Normal file
After Width: | Height: | Size: 125 KiB |
BIN
docs/assets/screenshots/navigation-expand.png
Normal file
After Width: | Height: | Size: 174 KiB |
Before Width: | Height: | Size: 114 KiB After Width: | Height: | Size: 174 KiB |
BIN
docs/assets/screenshots/navigation-tabs.png
Normal file
After Width: | Height: | Size: 153 KiB |
BIN
docs/assets/screenshots/navigation.png
Normal file
After Width: | Height: | Size: 160 KiB |
Before Width: | Height: | Size: 127 KiB After Width: | Height: | Size: 138 KiB |
@ -90,13 +90,11 @@ The unit price is 12.50.
|
||||
|
||||
### Using variables in snippets
|
||||
|
||||
You may want to use variables in snippets, for example, when describing the same
|
||||
procedure in multiple contexts where only one piece of information differs. This
|
||||
does not work with snippets that are included using the [Snippets][2] extension.
|
||||
Instead, you can use the [macros][3] plugin for defining snippets.
|
||||
|
||||
To this end, add the snippet location using the `include_dir` parameter to the
|
||||
plugin's configuration in `mkdocs.yml`, for example:
|
||||
In order to use variables in snippets, e.g., when using the same snippet in
|
||||
multiple contexts. This does not work with snippets that are included using the
|
||||
[Snippets][2] extension. Instead, you can use the [macros][3] plugin for
|
||||
defining snippets. Add the snippet location using the `include_dir` parameter
|
||||
to the plugin configuration in `mkdocs.yml`, for example:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
@ -105,14 +103,13 @@ plugins:
|
||||
include_dir: snippets
|
||||
```
|
||||
|
||||
In your Markdown file, you can include snippets with Jinja's [`include`][4]
|
||||
function:
|
||||
In your Markdown file, include snippets with Jinja's [`include`][4] function:
|
||||
|
||||
``` markdown
|
||||
{% include "definitions.md" %}
|
||||
```
|
||||
|
||||
This example illustrates the behavior:
|
||||
_Example_:
|
||||
|
||||
=== "snippets/definitions.md"
|
||||
|
||||
|
@ -92,6 +92,6 @@ In order to integrate another JavaScript-based comment system provider, you can
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L318-L321
|
||||
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L325-L328
|
||||
[9]: ../customization.md#extending-the-theme
|
||||
[10]: ../customization.md#overriding-blocks
|
||||
|
@ -93,7 +93,7 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
|
||||
edit_uri: ""
|
||||
```
|
||||
|
||||
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L285-L294
|
||||
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L292-L301
|
||||
[6]: https://github.com/
|
||||
[7]: https://about.gitlab.com/
|
||||
[8]: https://bitbucket.org/
|
||||
|
@ -30,7 +30,7 @@ theme:
|
||||
|
||||
The typeface will be loaded in 300, 400, _400i_ and __700__.
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L100-L125
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L107-L132
|
||||
[3]: https://fonts.google.com/specimen/Roboto
|
||||
|
||||
### Proportional font
|
||||
|
@ -94,7 +94,7 @@ work properly. Material for MkDocs relies on [lunr-languages][4] to provide this
|
||||
functionality. See the guide detailing how to [set up site search][5] for
|
||||
more information.
|
||||
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L90-L112
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
|
||||
[4]: https://github.com/MihaiValentin/lunr-languages
|
||||
[5]: setting-up-site-search.md
|
||||
|
||||
@ -132,7 +132,7 @@ directionality:
|
||||
})
|
||||
</script>
|
||||
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L178
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
|
||||
|
||||
## Customization
|
||||
|
||||
|
@ -53,7 +53,7 @@ theme:
|
||||
favicon: images/favicon.png
|
||||
```
|
||||
|
||||
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L53-L54
|
||||
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L60-L61
|
||||
|
||||
### Icons
|
||||
|
||||
|
@ -55,8 +55,16 @@ theme:
|
||||
- navigation.tabs
|
||||
```
|
||||
|
||||
=== "With tabs"
|
||||
|
||||
[![With tabs][7]][7]
|
||||
|
||||
=== "Without tabs"
|
||||
|
||||
[![Without tabs][8]][8]
|
||||
|
||||
Note that all __top-level pages__ (i.e. all top-level entries that directly
|
||||
refer to an `*.md` file) defined inside the [`nav`][7] entry of `mkdocs.yml`
|
||||
refer to an `*.md` file) defined inside the [`nav`][9] entry of `mkdocs.yml`
|
||||
will be grouped under the first tab which will receive the title of the first
|
||||
page.
|
||||
|
||||
@ -93,19 +101,21 @@ sections. This is illustrated in the following example:
|
||||
- Page 2.3
|
||||
```
|
||||
|
||||
Note that tabs are only shown for larger screens, so make sure that navigation
|
||||
is plausible on mobile devices. As another example, see the [`mkdocs.yml`][8]
|
||||
used to render these pages.
|
||||
Also note that tabs are only shown for larger screens, so make sure that
|
||||
navigation is plausible on mobile devices. As another example, see the
|
||||
[`mkdocs.yml`][10] used to render these pages.
|
||||
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
|
||||
[7]: https://www.mkdocs.org/user-guide/configuration/#nav
|
||||
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
|
||||
[7]: ../assets/screenshots/navigation-tabs.png
|
||||
[8]: ../assets/screenshots/navigation.png
|
||||
[9]: https://www.mkdocs.org/user-guide/configuration/#nav
|
||||
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
|
||||
|
||||
### Navigation sections
|
||||
|
||||
[:octicons-file-code-24: Source][9] ·
|
||||
[:octicons-file-code-24: Source][11] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
|
||||
|
||||
When _sections_ are enabled, top-level sections are rendered as groups in the
|
||||
sidebar on big screens (but not when the sidebar is hidden). It can be enabled
|
||||
@ -117,20 +127,26 @@ theme:
|
||||
- navigation.sections
|
||||
```
|
||||
|
||||
=== "With sections"
|
||||
|
||||
[![With sections][12]][12]
|
||||
|
||||
=== "Without sections"
|
||||
|
||||
[![Without sections][8]][8]
|
||||
|
||||
[11]: ../insiders.md
|
||||
[12]: ../assets/screenshots/navigation-sections.png
|
||||
|
||||
Both feature flags, _tabs_ and _sections_, can be combined with each other. If
|
||||
both feature flags are enabled, sections are rendered for 2nd level navigation
|
||||
items.
|
||||
|
||||
[![Search highlighting][10]][10]
|
||||
|
||||
[9]: ../insiders.md
|
||||
[10]: ../assets/screenshots/navigation-sections.png
|
||||
|
||||
### Navigation expansion
|
||||
|
||||
[:octicons-file-code-24: Source][9] ·
|
||||
[:octicons-file-code-24: Source][11] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
|
||||
|
||||
When _expansion_ is enabled, the left sidebar will expand all collapsible
|
||||
subsections by default, so the user doesn't have to open subsections manually.
|
||||
@ -142,11 +158,21 @@ theme:
|
||||
- navigation.expand
|
||||
```
|
||||
|
||||
=== "With expansion"
|
||||
|
||||
[![With expansion][13]][13]
|
||||
|
||||
=== "Without expansion"
|
||||
|
||||
[![Without expansion][8]][8]
|
||||
|
||||
[13]: ../assets/screenshots/navigation-expand.png
|
||||
|
||||
### Table of contents
|
||||
|
||||
[:octicons-file-code-24: Source][11] · [:octicons-workflow-24: Extension][12]
|
||||
[:octicons-file-code-24: Source][14] · [:octicons-workflow-24: Extension][15]
|
||||
|
||||
The [Table of contents][13] extension, which is part of the standard Markdown
|
||||
The [Table of contents][16] extension, which is part of the standard Markdown
|
||||
library, provides some options that are supported by Material for MkDocs to
|
||||
customize its appearance:
|
||||
|
||||
@ -178,7 +204,7 @@ customize its appearance:
|
||||
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
|
||||
customization of the slug function. For some languages, the default may not
|
||||
produce good and readable identifiers. Consider using another slug function
|
||||
like for example those from [Python Markdown Extensions][14]:
|
||||
like for example those from [Python Markdown Extensions][17]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
@ -219,39 +245,63 @@ customize its appearance:
|
||||
toc_depth: 0
|
||||
```
|
||||
|
||||
Note that MkDocs will not generate [anchor links][18] for levels outside
|
||||
the range defined with `toc_depth`. However, Material for MkDocs also allows
|
||||
to [hide the table of contents][19] on a specific page while keeping
|
||||
permalinks.
|
||||
|
||||
_Material for MkDocs doesn't provide official support for the other options of
|
||||
this extension, so they may be supported but can also yield weird results. Use
|
||||
them at your own risk._
|
||||
|
||||
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
||||
[12]: https://python-markdown.github.io/extensions/toc/
|
||||
[13]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[14]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
[14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
||||
[15]: https://python-markdown.github.io/extensions/toc/
|
||||
[16]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[17]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
[18]: #permalink
|
||||
[19]: #hide-the-sidebars
|
||||
|
||||
#### Automatic hiding
|
||||
### Hide the sidebars
|
||||
|
||||
[:octicons-file-code-24: Source][3] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
|
||||
[:octicons-file-code-24: Source][11] ·
|
||||
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
|
||||
|
||||
When _autohiding_ is enabled, the table of contents is automatically hidden
|
||||
when the current page defines no headings, or only a single `h1` heading to be
|
||||
rendered, so content stretches.
|
||||
|
||||
It can be enabled via `mkdocs.yml` with:
|
||||
Sometimes it's desirable to hide the navigation sidebar or table of contents,
|
||||
especially when there's a single navigation item. This can be done for any
|
||||
page using the [Metadata][20] extension:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- toc.autohide
|
||||
---
|
||||
hide:
|
||||
- navigation # Hide navigation
|
||||
- toc # Hide table of contents
|
||||
---
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
=== "Hide navigation"
|
||||
|
||||
[![Hide navigation][21]][21]
|
||||
|
||||
=== "Hide table of contents"
|
||||
|
||||
[![Hide table of contents][22]][22]
|
||||
|
||||
=== "Hide both"
|
||||
|
||||
[![Hide navigation and table of contents][23]][23]
|
||||
|
||||
[20]: ../../reference/meta-tags/#metadata
|
||||
[21]: ../assets/screenshots/hide-navigation.png
|
||||
[22]: ../assets/screenshots/hide-toc.png
|
||||
[23]: ../assets/screenshots/hide-navigation-toc.png
|
||||
|
||||
## Customization
|
||||
|
||||
### Keyboard shortcuts
|
||||
|
||||
[:octicons-file-code-24: Source][15] ·
|
||||
[:octicons-file-code-24: Source][24] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
Material for MkDocs includes several keyboard shortcuts that make it possible
|
||||
@ -277,7 +327,7 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
* ++n++ , ++period++ : go to next page
|
||||
|
||||
Let's say you want to bind some action to the ++x++ key. By using [additional
|
||||
JavaScript][16], you can subscribe to the `keyboard$` observable and attach
|
||||
JavaScript][25], you can subscribe to the `keyboard$` observable and attach
|
||||
your custom event listener:
|
||||
|
||||
``` js
|
||||
@ -293,5 +343,5 @@ The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
|
||||
on the underlying event, so the keypress will not propagate further and touch
|
||||
other event listeners.
|
||||
|
||||
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||
[16]: ../customization.md#additional-javascript
|
||||
[24]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||
[25]: ../customization.md#additional-javascript
|
||||
|
@ -204,7 +204,7 @@ combination with @squidfunk's [iframe-worker][15] polyfill.
|
||||
|
||||
For setup instructions, refer to the [official documentation][16].
|
||||
|
||||
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L360-L372
|
||||
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L368-L369
|
||||
[14]: https://github.com/wilhelmer/mkdocs-localsearch/
|
||||
[15]: https://github.com/squidfunk/iframe-worker
|
||||
[16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
|
||||
|