OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

fixed broken screenshots in "Hide the sidebars"

Browse Source
This commit is contained in:
daaf
2021-03-13 15:16:50 -05:00
parent 55c150f99b
commit da94a168fc
1 changed files with 77 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
docs/setup/setting-up-navigation.md
View File

@@ -4,14 +4,14 @@ template: overrides/main.html
# Setting up navigation # Setting up navigation
A clear and concise navigation structure is an important aspect of good project A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides a multitude of options to configure documentation. Material for MkDocs provides a multitude of options to configure
the behavior of navigational elements, including [tabs][1] and [sections][2], the behavior of navigational elements, including [tabs][1] and [sections][2],
and its flag-ship feature: [instant loading][3]. and its flag-ship feature: [instant loading][3].
[1]: #navigation-tabs [1]: #navigation-tabs
[2]: #navigation-sections [2]: #navigation-sections
[3]: #instant-loading [3]: #instant-loading
## Configuration ## Configuration
@@ -24,22 +24,22 @@ When _instant loading_ is enabled, clicks on all internal links will be
intercepted and dispatched via [XHR][5] without fully reloading the page. Add intercepted and dispatched via [XHR][5] without fully reloading the page. Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.instant - navigation.instant
``` ```
The resulting page is parsed and injected and all event handlers and components The resulting page is parsed and injected and all event handlers and components
are rebound automatically. This means that __Material for MkDocs behaves like a are rebound automatically. This means that **Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation Single Page Application**, which is especially useful for large documentation
sites that come with a massive search index, as the search index will now sites that come with a massive search index, as the search index will now
remain intact in-between document switches. remain intact in-between document switches.
_Material for MkDocs is the only MkDocs theme offering this feature._ _Material for MkDocs is the only MkDocs theme offering this feature._
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest [5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Anchor tracking ### Anchor tracking
@@ -51,7 +51,7 @@ When _anchor tracking_ is enabled, the URL in the address bar is automatically
updated with the active anchor as highlighted in the table of contents. Add the updated with the active anchor as highlighted in the table of contents. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.tracking - navigation.tracking
@@ -65,7 +65,7 @@ When _tabs_ are enabled, top-level sections are rendered in a menu layer below
the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
[^1]: [^1]:
Prior to version 6.2, navigation tabs had a slightly different behavior. Prior to version 6.2, navigation tabs had a slightly different behavior.
All top-level pages (i.e. all top-level entries that directly refer to an All top-level pages (i.e. all top-level entries that directly refer to an
`*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped `*.md` file) defined inside the `nav` entry of `mkdocs.yml` were grouped
@@ -74,7 +74,7 @@ the following lines to `mkdocs.yml`:
as was reported in #1884 and #2072. From version 6.2 on, navigation tabs as was reported in #1884 and #2072. From version 6.2 on, navigation tabs
include all top-level pages and sections. include all top-level pages and sections.
``` yaml ```yaml
theme: theme:
features: features:
- navigation.tabs - navigation.tabs
@@ -88,9 +88,9 @@ theme:
[![Without tabs][8]][8] [![Without tabs][8]][8]
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[7]: ../assets/screenshots/navigation-tabs.png [7]: ../assets/screenshots/navigation-tabs.png
[8]: ../assets/screenshots/navigation.png [8]: ../assets/screenshots/navigation.png
#### Sticky navigation tabs #### Sticky navigation tabs
@@ -103,7 +103,7 @@ When _sticky tabs_ are enabled, navigation tabs will lock below the header and
always remain visible when scrolling down. Just add the following two feature always remain visible when scrolling down. Just add the following two feature
flags to `mkdocs.yml`: flags to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.tabs - navigation.tabs
@@ -118,9 +118,9 @@ theme:
[![Without sticky tabs][11]][11] [![Without sticky tabs][11]][11]
[9]: ../insiders.md [9]: ../insiders.md
[10]: ../assets/screenshots/navigation-tabs-sticky.png [10]: ../assets/screenshots/navigation-tabs-sticky.png
[11]: ../assets/screenshots/navigation-tabs-collapsed.png [11]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections ### Navigation sections
@@ -131,7 +131,7 @@ When _sections_ are enabled, top-level sections are rendered as groups in the
sidebar for viewports above `1220px`, but remain as-is on mobile. Add the sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.sections - navigation.sections
@@ -145,8 +145,8 @@ theme:
[![Without sections][8]][8] [![Without sections][8]][8]
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[13]: ../assets/screenshots/navigation-sections.png [13]: ../assets/screenshots/navigation-sections.png
Both feature flags, _tabs_ and _sections_, can be combined with each other. If Both feature flags, _tabs_ and _sections_, can be combined with each other. If
both feature flags are enabled, sections are rendered for level 2 navigation both feature flags are enabled, sections are rendered for level 2 navigation
@@ -161,7 +161,7 @@ When _expansion_ is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually. subsections by default, so the user doesn't have to open subsections manually.
Add the following lines to `mkdocs.yml`: Add the following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.expand - navigation.expand
@@ -175,7 +175,7 @@ theme:
[![Without expansion][8]][8] [![Without expansion][8]][8]
[14]: ../assets/screenshots/navigation-expand.png [14]: ../assets/screenshots/navigation-expand.png
### Section index pages ### Section index pages
@@ -188,7 +188,7 @@ When _section index pages_ are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. Add the sections, which is particularly useful for providing overview pages. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.indexes - navigation.indexes
@@ -206,7 +206,7 @@ In order to link a page to a section, create a new document with the name
`index.md` in the respective folder, and add it to the beginning of your `index.md` in the respective folder, and add it to the beginning of your
navigation section: navigation section:
``` yaml ```yaml
nav: nav:
- Section: - Section:
- section/index.md - section/index.md
@@ -219,16 +219,16 @@ _This feature flag can be combined with all other feature flags, e.g. [tabs][1]
and [sections][2], except for table of contents [navigation integration][17]. and [sections][2], except for table of contents [navigation integration][17].
Note that it doesn't rely on third-party plugins[^2]._ Note that it doesn't rely on third-party plugins[^2]._
[^2]: [^2]:
If you don't want to use the native integration, the If you don't want to use the native integration, the
[mkdocs-section-index][18] plugin might be an alternative. However, note [mkdocs-section-index][18] plugin might be an alternative. However, note
that this plugin may not be compatible with all navigation-related features that this plugin may not be compatible with all navigation-related features
offered by Material for MkDocs. offered by Material for MkDocs.
[15]: ../assets/screenshots/navigation-index-on.png [15]: ../assets/screenshots/navigation-index-on.png
[16]: ../assets/screenshots/navigation-index-off.png [16]: ../assets/screenshots/navigation-index-off.png
[17]: #navitation-intergation [17]: #navitation-intergation
[18]: https://github.com/oprypin/mkdocs-section-index [18]: https://github.com/oprypin/mkdocs-section-index
### Back-to-top button ### Back-to-top button
@@ -240,7 +240,7 @@ A _back-to-top button_ can be shown when the user, after scrolling down, starts
to scroll up again. It's rendered in the lower right corner of the viewport. Add to scroll up again. It's rendered in the lower right corner of the viewport. Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- navigation.top - navigation.top
@@ -258,8 +258,8 @@ A demo is worth a thousand words — check it out at
</figcaption> </figcaption>
</figure> </figure>
[19]: ../assets/screenshots/back-to-top.png [19]: ../assets/screenshots/back-to-top.png
[20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button [20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button
### Table of contents ### Table of contents
@@ -271,10 +271,10 @@ customize its appearance:
`permalink`{ #permalink } `permalink`{ #permalink }
: :octicons-milestone-24: Default: `false` – This option adds an anchor link : :octicons-milestone-24: Default: `false` – This option adds an anchor link
containing the paragraph symbol `` or another custom symbol at the end of containing the paragraph symbol `¶` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover: Material for MkDocs will make appear on hover:
=== "¶" === "¶"
@@ -294,10 +294,10 @@ customize its appearance:
`slugify`{ #slugify } `slugify`{ #slugify }
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][24]: like for example those from [Python Markdown Extensions][24]:
=== "Unicode" === "Unicode"
@@ -317,10 +317,10 @@ customize its appearance:
`toc_depth`{ #toc_depth } `toc_depth`{ #toc_depth }
: :octicons-milestone-24: Default: `6` – Define the range of levels to be : :octicons-milestone-24: Default: `6` – Define the range of levels to be
included in the table of contents. This may be useful for project included in the table of contents. This may be useful for project
documentation with deeply structured headings to decrease the length of the documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether: table of contents, or to remove the table of contents altogether:
=== "Hide levels 4-6" === "Hide levels 4-6"
@@ -342,10 +342,10 @@ _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 this extension, so they may be supported but can also yield weird results. Use
them at your own risk._ them at your own risk._
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[22]: https://python-markdown.github.io/extensions/toc/ [22]: https://python-markdown.github.io/extensions/toc/
[23]: https://python-markdown.github.io/extensions/toc/#usage [23]: https://python-markdown.github.io/extensions/toc/#usage
[24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ [24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
#### Navigation integration #### Navigation integration
@@ -356,7 +356,7 @@ When _integration_ is enabled, the table of contents is rendered as part of
the navigation for viewports above `1220px`, but remains as-is on mobile. Add the navigation for viewports above `1220px`, but remains as-is on mobile. Add
the following lines to `mkdocs.yml`: the following lines to `mkdocs.yml`:
``` yaml ```yaml
theme: theme:
features: features:
- toc.integrate - toc.integrate
@@ -370,12 +370,12 @@ theme:
[![Separate table of contents][8]][8] [![Separate table of contents][8]][8]
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
[26]: ../assets/screenshots/toc-integrate.png [26]: ../assets/screenshots/toc-integrate.png
The content section will now always stretch to the right side, resulting in The content section will now always stretch to the right side, resulting in
more space for your content. This feature flag can be combined with all other more space for your content. This feature flag can be combined with all other
feature flags, e.g. [tabs][1] and [sections][2]. feature flags, e.g. [tabs][1] and [sections][2].
### Hide the sidebars ### Hide the sidebars
@@ -386,33 +386,32 @@ Sometimes it's desirable to hide the navigation and/or table of contents
sidebar, especially when there's a single navigation item. This can be done for sidebar, especially when there's a single navigation item. This can be done for
any page using the [Metadata][28] extension: any page using the [Metadata][28] extension:
``` yaml ```yaml
--- ---
hide: hide:
- navigation # Hide navigation - navigation # Hide navigation
- toc # Hide table of contents - toc # Hide table of contents
--- ---
...
``` ```
=== "Hide navigation" === "Hide navigation"
[![Hide navigation][27]][27] [![Hide navigation][29]][29]
=== "Hide table of contents" === "Hide table of contents"
[![Hide table of contents][28]][28] [![Hide table of contents][30]][30]
=== "Hide both" === "Hide both"
[![Hide navigation and table of contents][29]][29] [![Hide navigation and table of contents][31]][31]
[27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html [27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[28]: ../../reference/meta-tags/#metadata [28]: ../../reference/meta-tags/#metadata
[29]: ../assets/screenshots/hide-navigation.png [29]: ../assets/screenshots/hide-navigation.png
[30]: ../assets/screenshots/hide-toc.png [30]: ../assets/screenshots/hide-toc.png
[31]: ../assets/screenshots/hide-navigation-toc.png [31]: ../assets/screenshots/hide-navigation-toc.png
## Customization ## Customization
@@ -426,8 +425,8 @@ to navigate your project documentation via keyboard. There're two modes:
`search`{ #search } `search`{ #search }
: This mode is active when the _search is focused_. It provides several key : This mode is active when the _search is focused_. It provides several key
bindings to make search accessible and navigable via keyboard: bindings to make search accessible and navigable via keyboard:
* ++arrow-down++ , ++arrow-up++ : select next / previous result * ++arrow-down++ , ++arrow-up++ : select next / previous result
* ++esc++ , ++tab++ : close search dialog * ++esc++ , ++tab++ : close search dialog
@@ -435,9 +434,9 @@ to navigate your project documentation via keyboard. There're two modes:
`global`{ #global } `global`{ #global }
: This mode is active when _search is not focussed_ and when there's no other : This mode is active when _search is not focussed_ and when there's no other
focussed element that is susceptible to keyboard input. The following keys focussed element that is susceptible to keyboard input. The following keys
are bound: are bound:
* ++f++ , ++s++ , ++slash++ : open search dialog * ++f++ , ++s++ , ++slash++ : open search dialog
* ++p++ , ++comma++ : go to previous page * ++p++ , ++comma++ : go to previous page
@@ -447,21 +446,21 @@ Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript][33], you can subscribe to the `keyboard$` observable and attach JavaScript][33], you can subscribe to the `keyboard$` observable and attach
your custom event listener: your custom event listener:
``` js ```js
keyboard$.subscribe(function(key) { keyboard$.subscribe(function (key) {
if (key.mode === "global" && key.type === "x") { if (key.mode === "global" && key.type === "x") {
/* Add custom keyboard handler here */ /* Add custom keyboard handler here */
key.claim() key.claim();
} }
}) });
``` ```
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()` The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
on the underlying event, so the keypress will not propagate further and touch on the underlying event, so the keypress will not propagate further and touch
other event listeners. other event listeners.
[32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts [32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[33]: ../customization.md#additional-javascript [33]: ../customization.md#additional-javascript
### Content area width ### Content area width
@@ -493,5 +492,5 @@ of CSS:
} }
``` ```
[34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss [34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
[35]: ../customization.md#additional-css [35]: ../customization.md#additional-css