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

Updated documentation with more screenshots and examples

This commit is contained in:
squidfunk 2020-11-07 18:01:46 +01:00
parent acc4a273c4
commit 0f79516ac6
17 changed files with 108 additions and 56 deletions

View File

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

Binary file not shown.

After

Width:  |  Height:  |  Size: 117 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 174 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 114 KiB

After

Width:  |  Height:  |  Size: 174 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 153 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 160 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 127 KiB

After

Width:  |  Height:  |  Size: 138 KiB

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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