diff --git a/CHANGELOG b/CHANGELOG index 813cb266b..4c00d76bb 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -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 diff --git a/docs/assets/screenshots/hide-navigation-toc.png b/docs/assets/screenshots/hide-navigation-toc.png new file mode 100644 index 000000000..7f94fbeea Binary files /dev/null and b/docs/assets/screenshots/hide-navigation-toc.png differ diff --git a/docs/assets/screenshots/hide-navigation.png b/docs/assets/screenshots/hide-navigation.png new file mode 100644 index 000000000..923631720 Binary files /dev/null and b/docs/assets/screenshots/hide-navigation.png differ diff --git a/docs/assets/screenshots/hide-toc.png b/docs/assets/screenshots/hide-toc.png new file mode 100644 index 000000000..8851770b6 Binary files /dev/null and b/docs/assets/screenshots/hide-toc.png differ diff --git a/docs/assets/screenshots/navigation-expand.png b/docs/assets/screenshots/navigation-expand.png new file mode 100644 index 000000000..ff285ee29 Binary files /dev/null and b/docs/assets/screenshots/navigation-expand.png differ diff --git a/docs/assets/screenshots/navigation-sections.png b/docs/assets/screenshots/navigation-sections.png index 5f565c2ff..f4eccbfc9 100644 Binary files a/docs/assets/screenshots/navigation-sections.png and b/docs/assets/screenshots/navigation-sections.png differ diff --git a/docs/assets/screenshots/navigation-tabs.png b/docs/assets/screenshots/navigation-tabs.png new file mode 100644 index 000000000..983ba457e Binary files /dev/null and b/docs/assets/screenshots/navigation-tabs.png differ diff --git a/docs/assets/screenshots/navigation.png b/docs/assets/screenshots/navigation.png new file mode 100644 index 000000000..0af9dd1ad Binary files /dev/null and b/docs/assets/screenshots/navigation.png differ diff --git a/docs/assets/screenshots/versioning.png b/docs/assets/screenshots/versioning.png index 37212b0f6..09898efb7 100644 Binary files a/docs/assets/screenshots/versioning.png and b/docs/assets/screenshots/versioning.png differ diff --git a/docs/reference/variables.md b/docs/reference/variables.md index 6fb278b55..76b3e1c3c 100644 --- a/docs/reference/variables.md +++ b/docs/reference/variables.md @@ -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" diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 66afd634a..bdc2057a7 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.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 diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index e6e4fa765..0dca2db4c 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -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/ diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index b697e1916..0d41b6c18 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -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 diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md index 04c92dbbe..48968520c 100644 --- a/docs/setup/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -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: }) - [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 diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md index 0d5ff7820..bbf0a9426 100644 --- a/docs/setup/changing-the-logo-and-icons.md +++ b/docs/setup/changing-the-logo-and-icons.md @@ -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 diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index c11a6bf64..201ec0c9e 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -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 diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 08249e2a9..7d2872486 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -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