diff --git a/CHANGELOG b/CHANGELOG index 4e49d07a3..79a99c323 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-5.5.5+insiders-1.2.0 (2020-08-11) + + * Added feature to expand navigation by default + mkdocs-material-5.5.5 (2020-08-11) * Fixed missing vendor and worker distribution files diff --git a/docs/changelog.md b/docs/changelog.md index 9be7c4872..564852274 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 1.2.0 _ August 11, 2020 + +* Added feature to expand navigation by default + ### 1.1.0 _ August 3, 2020 * Added highlighting of search results diff --git a/docs/insiders.md b/docs/insiders.md index 29d2be6a0..96af7fd42 100644 --- a/docs/insiders.md +++ b/docs/insiders.md @@ -93,11 +93,11 @@ New features and improvements for _search_, including: New features and improvements for _content and toc_, including: - [x] Highlighting of matched search terms in content area +- [x] Navigation can always be expanded via configuration - [ ] Better support for wide screens, i.e. more horizontal space - [ ] Table of contents can be moved into navigation for more space - [ ] Table of contents shows which sections have search results - [ ] Table of contents auto-collapses and expands only the active section -- [ ] Navigation can be always expanded via configuration - [ ] ... more to come ### Bhut Jolokia diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 7077ae380..57bf4fb03 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -35,9 +35,28 @@ remain intact in-between document switches. [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts [2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest +### Navigation expansion + +[: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 } + +When `navigation.expand` is activated, the left sidebar will expand all +collapsible subsections by default, so the user doesn't have to do it manually. +It can be enabled via `mkdocs.yml` with: + +``` yaml +theme: + features: + - navigation.expand +``` + + [3]: ../insiders.md + ### Navigation tabs -[:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag +[:octicons-file-code-24: Source][4] · :octicons-unlock-24: Feature flag When _tabs_ are activated, top-level sections are rendered in a menu layer below the header on big screens (but not when the sidebar is hidden). It can be @@ -50,7 +69,7 @@ theme: ``` Note that all __top-level pages__ (i.e. all top-level entries that directly -refer to an `*.md` file) defined inside the [`nav`][4] entry of `mkdocs.yml` +refer to an `*.md` file) defined inside the [`nav`][5] entry of `mkdocs.yml` will be grouped under the first tab which will receive the title of the first page. @@ -88,18 +107,18 @@ sections. This is illustrated in the following example: ``` 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`][5] +is plausible on mobile devices. As another example, see the [`mkdocs.yml`][6] used to render these pages. - [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html - [4]: https://www.mkdocs.org/user-guide/configuration/#nav - [5]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml + [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html + [5]: https://www.mkdocs.org/user-guide/configuration/#nav + [6]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml ### Table of contents -[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7] +[:octicons-file-code-24: Source][7] · [:octicons-workflow-24: Extension][8] -The [Table of contents][8] extension, which is part of the standard Markdown +The [Table of contents][9] extension, which is part of the standard Markdown library, provides some options that are supported by Material for MkDocs to customize its appearance: @@ -131,7 +150,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][9]: + like for example those from [Python Markdown Extensions][10]: === "Unicode" @@ -176,16 +195,16 @@ _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._ - [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html - [7]: https://python-markdown.github.io/extensions/toc/ - [8]: https://python-markdown.github.io/extensions/toc/#usage - [9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ + [7]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html + [8]: https://python-markdown.github.io/extensions/toc/ + [9]: https://python-markdown.github.io/extensions/toc/#usage + [10]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ ## Customization ### Keyboard shortcuts -[:octicons-file-code-24: Source][10] · +[:octicons-file-code-24: Source][11] · :octicons-mortar-board-24: Difficulty: _easy_ Material for MkDocs includes several keyboard shortcuts that make it possible @@ -211,7 +230,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][11], you can subscribe to the `keyboard$` observable and attach +JavaScript][12], you can subscribe to the `keyboard$` observable and attach your custom event listener: ``` js @@ -227,5 +246,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. - [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts - [11]: ../customization.md#additional-javascript + [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts + [12]: ../customization.md#additional-javascript