mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
fixed broken screenshots in "Hide the sidebars"
This commit is contained in:
daaf
parent
55c150f99b
commit
da94a168fc
@ -4,14 +4,14 @@ template: overrides/main.html
|
||||
|
||||
# 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
|
||||
the behavior of navigational elements, including [tabs][1] and [sections][2],
|
||||
and its flag-ship feature: [instant loading][3].
|
||||
|
||||
[1]: #navigation-tabs
|
||||
[2]: #navigation-sections
|
||||
[3]: #instant-loading
|
||||
[1]: #navigation-tabs
|
||||
[2]: #navigation-sections
|
||||
[3]: #instant-loading
|
||||
|
||||
## 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
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.instant
|
||||
```
|
||||
|
||||
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
|
||||
Single Page Application__, which is especially useful for large documentation
|
||||
are rebound automatically. This means that **Material for MkDocs behaves like a
|
||||
Single Page Application**, which is especially useful for large documentation
|
||||
sites that come with a massive search index, as the search index will now
|
||||
remain intact in-between document switches.
|
||||
|
||||
_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
|
||||
[5]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
||||
[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
|
||||
|
||||
### 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
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- 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 following lines to `mkdocs.yml`:
|
||||
|
||||
[^1]:
|
||||
[^1]:
|
||||
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
|
||||
`*.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
|
||||
include all top-level pages and sections.
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.tabs
|
||||
@ -88,9 +88,9 @@ theme:
|
||||
|
||||
[![Without tabs][8]][8]
|
||||
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
|
||||
[7]: ../assets/screenshots/navigation-tabs.png
|
||||
[8]: ../assets/screenshots/navigation.png
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
|
||||
[7]: ../assets/screenshots/navigation-tabs.png
|
||||
[8]: ../assets/screenshots/navigation.png
|
||||
|
||||
#### 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
|
||||
flags to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.tabs
|
||||
@ -118,9 +118,9 @@ theme:
|
||||
|
||||
[![Without sticky tabs][11]][11]
|
||||
|
||||
[9]: ../insiders.md
|
||||
[10]: ../assets/screenshots/navigation-tabs-sticky.png
|
||||
[11]: ../assets/screenshots/navigation-tabs-collapsed.png
|
||||
[9]: ../insiders.md
|
||||
[10]: ../assets/screenshots/navigation-tabs-sticky.png
|
||||
[11]: ../assets/screenshots/navigation-tabs-collapsed.png
|
||||
|
||||
### 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
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.sections
|
||||
@ -145,8 +145,8 @@ theme:
|
||||
|
||||
[![Without sections][8]][8]
|
||||
|
||||
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
|
||||
[13]: ../assets/screenshots/navigation-sections.png
|
||||
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
|
||||
[13]: ../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 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.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.expand
|
||||
@ -175,7 +175,7 @@ theme:
|
||||
|
||||
[![Without expansion][8]][8]
|
||||
|
||||
[14]: ../assets/screenshots/navigation-expand.png
|
||||
[14]: ../assets/screenshots/navigation-expand.png
|
||||
|
||||
### 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
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- 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
|
||||
navigation section:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
nav:
|
||||
- Section:
|
||||
- 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].
|
||||
Note that it doesn't rely on third-party plugins[^2]._
|
||||
|
||||
[^2]:
|
||||
[^2]:
|
||||
If you don't want to use the native integration, the
|
||||
[mkdocs-section-index][18] plugin might be an alternative. However, note
|
||||
that this plugin may not be compatible with all navigation-related features
|
||||
offered by Material for MkDocs.
|
||||
|
||||
[15]: ../assets/screenshots/navigation-index-on.png
|
||||
[16]: ../assets/screenshots/navigation-index-off.png
|
||||
[17]: #navitation-intergation
|
||||
[18]: https://github.com/oprypin/mkdocs-section-index
|
||||
[15]: ../assets/screenshots/navigation-index-on.png
|
||||
[16]: ../assets/screenshots/navigation-index-off.png
|
||||
[17]: #navitation-intergation
|
||||
[18]: https://github.com/oprypin/mkdocs-section-index
|
||||
|
||||
### 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
|
||||
the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- navigation.top
|
||||
@ -258,8 +258,8 @@ A demo is worth a thousand words — check it out at
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
[19]: ../assets/screenshots/back-to-top.png
|
||||
[20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button
|
||||
[19]: ../assets/screenshots/back-to-top.png
|
||||
[20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button
|
||||
|
||||
### Table of contents
|
||||
|
||||
@ -271,10 +271,10 @@ customize its appearance:
|
||||
|
||||
`permalink`{ #permalink }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
|
||||
containing the paragraph symbol `¶` or another custom symbol at the end of
|
||||
each headline, exactly like on the page you're currently viewing, which
|
||||
Material for MkDocs will make appear on hover:
|
||||
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
|
||||
containing the paragraph symbol `¶` or another custom symbol at the end of
|
||||
each headline, exactly like on the page you're currently viewing, which
|
||||
Material for MkDocs will make appear on hover:
|
||||
|
||||
=== "¶"
|
||||
|
||||
@ -294,10 +294,10 @@ customize its appearance:
|
||||
|
||||
`slugify`{ #slugify }
|
||||
|
||||
: :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][24]:
|
||||
: :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][24]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
@ -317,10 +317,10 @@ customize its appearance:
|
||||
|
||||
`toc_depth`{ #toc_depth }
|
||||
|
||||
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
|
||||
included in the table of contents. This may be useful for project
|
||||
documentation with deeply structured headings to decrease the length of the
|
||||
table of contents, or to remove the table of contents altogether:
|
||||
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
|
||||
included in the table of contents. This may be useful for project
|
||||
documentation with deeply structured headings to decrease the length of the
|
||||
table of contents, or to remove the table of contents altogether:
|
||||
|
||||
=== "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
|
||||
them at your own risk._
|
||||
|
||||
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
||||
[22]: https://python-markdown.github.io/extensions/toc/
|
||||
[23]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
||||
[22]: https://python-markdown.github.io/extensions/toc/
|
||||
[23]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
|
||||
#### 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 following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
theme:
|
||||
features:
|
||||
- toc.integrate
|
||||
@ -370,12 +370,12 @@ theme:
|
||||
|
||||
[![Separate table of contents][8]][8]
|
||||
|
||||
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
|
||||
[26]: ../assets/screenshots/toc-integrate.png
|
||||
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
|
||||
[26]: ../assets/screenshots/toc-integrate.png
|
||||
|
||||
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
|
||||
feature flags, e.g. [tabs][1] and [sections][2].
|
||||
feature flags, e.g. [tabs][1] and [sections][2].
|
||||
|
||||
### 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
|
||||
any page using the [Metadata][28] extension:
|
||||
|
||||
``` yaml
|
||||
```yaml
|
||||
---
|
||||
hide:
|
||||
- navigation # Hide navigation
|
||||
- toc # Hide table of contents
|
||||
- toc # Hide table of contents
|
||||
---
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
=== "Hide navigation"
|
||||
|
||||
[![Hide navigation][27]][27]
|
||||
[![Hide navigation][29]][29]
|
||||
|
||||
=== "Hide table of contents"
|
||||
|
||||
[![Hide table of contents][28]][28]
|
||||
[![Hide table of contents][30]][30]
|
||||
|
||||
=== "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
|
||||
[28]: ../../reference/meta-tags/#metadata
|
||||
[29]: ../assets/screenshots/hide-navigation.png
|
||||
[30]: ../assets/screenshots/hide-toc.png
|
||||
[31]: ../assets/screenshots/hide-navigation-toc.png
|
||||
[27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
|
||||
[28]: ../../reference/meta-tags/#metadata
|
||||
[29]: ../assets/screenshots/hide-navigation.png
|
||||
[30]: ../assets/screenshots/hide-toc.png
|
||||
[31]: ../assets/screenshots/hide-navigation-toc.png
|
||||
|
||||
## Customization
|
||||
|
||||
@ -426,8 +425,8 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
|
||||
`search`{ #search }
|
||||
|
||||
: This mode is active when the _search is focused_. It provides several key
|
||||
bindings to make search accessible and navigable via keyboard:
|
||||
: This mode is active when the _search is focused_. It provides several key
|
||||
bindings to make search accessible and navigable via keyboard:
|
||||
|
||||
* ++arrow-down++ , ++arrow-up++ : select next / previous result
|
||||
* ++esc++ , ++tab++ : close search dialog
|
||||
@ -435,9 +434,9 @@ to navigate your project documentation via keyboard. There're two modes:
|
||||
|
||||
`global`{ #global }
|
||||
|
||||
: 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
|
||||
are bound:
|
||||
: 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
|
||||
are bound:
|
||||
|
||||
* ++f++ , ++s++ , ++slash++ : open search dialog
|
||||
* ++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
|
||||
your custom event listener:
|
||||
|
||||
``` js
|
||||
keyboard$.subscribe(function(key) {
|
||||
```js
|
||||
keyboard$.subscribe(function (key) {
|
||||
if (key.mode === "global" && key.type === "x") {
|
||||
/* Add custom keyboard handler here */
|
||||
key.claim()
|
||||
key.claim();
|
||||
}
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
[32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||
[33]: ../customization.md#additional-javascript
|
||||
[32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||
[33]: ../customization.md#additional-javascript
|
||||
|
||||
### 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
|
||||
[35]: ../customization.md#additional-css
|
||||
[34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
|
||||
[35]: ../customization.md#additional-css
|
||||
|
||||
Loading…
Reference in New Issue
Block a user