Skip to content

Commit

Permalink
Added reference to mkdocs-section-index plugin
Browse files Browse the repository at this point in the history
  • Loading branch information
@squidfunk
squidfunk committed Jan 31, 2021
1 parent 1545ed6 commit accc2a3
Showing 1 changed file with 49 additions and 41 deletions.
90 changes: 49 additions & 41 deletions docs/setup/setting-up-navigation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,9 +168,9 @@ theme:
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }

When _section indexes_ are enabled, documents can be directly attached to
sections, which is especially useful for providing overview pages. This can be
enabled via `mkdocs.yml` with:
When _section index pages_ are enabled, documents can be directly attached to
sections, which is particularly useful for providing overview pages. This can
be enabled via `mkdocs.yml` with:

``` yaml
theme:
Expand All @@ -186,9 +186,9 @@ theme:

[![Without expansion][16]][16]

In order to link a page to the section, create a new Markdown document with the
name `index.md` in the respective folder, and add it to the beginning of your
navigation section like so:
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
nav:
Expand All @@ -200,17 +200,25 @@ nav:
```

_This feature flag can be combined with all other feature flags, e.g. [tabs][1]
and [sections][2], except for when integrating the table of contents into the
navigation with_ `toc.integrate`.
and [sections][2], except for table of contents [navigation integration][17].
Note that it doesn't rely on third-party plugins[^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 features offered by Material
for MkDocs, e.g. [tabs][1] and [sections][2].

[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

### Table of contents

[:octicons-file-code-24: Source][17] · [:octicons-workflow-24: Extension][18]
[:octicons-file-code-24: Source][19] · [:octicons-workflow-24: Extension][20]

The [Table of contents][19] extension, which is part of the standard Markdown
The [Table of contents][21] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance:

Expand Down Expand Up @@ -242,7 +250,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][20]:
like for example those from [Python Markdown Extensions][22]:

=== "Unicode"

Expand Down Expand Up @@ -283,25 +291,25 @@ customize its appearance:
toc_depth: 0
```

Note that MkDocs will not generate [anchor links][21] for levels outside
Note that MkDocs will not generate [anchor links][23] for levels outside
the range defined with `toc_depth`. However, Material for MkDocs also allows
to [hide the table of contents][22] on a specific page while keeping
to [hide the table of contents][24] 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._

[17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[18]: https://python-markdown.github.io/extensions/toc/
[19]: https://python-markdown.github.io/extensions/toc/#usage
[20]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
[21]: #permalink
[22]: #hide-the-sidebars
[19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[20]: https://python-markdown.github.io/extensions/toc/
[21]: https://python-markdown.github.io/extensions/toc/#usage
[22]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
[23]: #permalink
[24]: #hide-the-sidebars

#### Navigation integration

[:octicons-file-code-24: Source][23] ·
[:octicons-file-code-24: Source][25] ·
:octicons-unlock-24: Feature flag

When _integration_ is enabled, the table of contents is rendered as part of
Expand All @@ -316,27 +324,27 @@ theme:

=== "Integrate table of contents"

[![Integrate table of contents][24]][24]
[![Integrate table of contents][26]][26]

=== "Separate table of contents"

[![Separate table of contents][8]][8]

[23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
[24]: ../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].

### Hide the sidebars

[:octicons-file-code-24: Source][25] ·
[:octicons-file-code-24: Source][27] ·
:octicons-note-24: Metadata

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][26] extension:
any page using the [Metadata][28] extension:

``` yaml
---
Expand All @@ -350,27 +358,27 @@ hide:

=== "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]

[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[26]: ../../reference/meta-tags/#metadata
[27]: ../assets/screenshots/hide-navigation.png
[28]: ../assets/screenshots/hide-toc.png
[29]: ../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

### Keyboard shortcuts

[:octicons-file-code-24: Source][30] ·
[:octicons-file-code-24: Source][32] ·
:octicons-mortar-board-24: Difficulty: _easy_

Material for MkDocs includes several keyboard shortcuts that make it possible
Expand All @@ -396,7 +404,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][31], you can subscribe to the `keyboard$` observable and attach
JavaScript][33], you can subscribe to the `keyboard$` observable and attach
your custom event listener:

``` js
Expand All @@ -412,12 +420,12 @@ 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.

[30]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[31]: ../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

[:octicons-file-code-24: Source][32] ·
[:octicons-file-code-24: Source][34] ·
:octicons-mortar-board-24: Difficulty: _easy_

The width of the content area is set so the length of each line doesn't exceed
Expand All @@ -426,7 +434,7 @@ is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it
stretch to the entire available space.

This can easily be achieved with an [additional stylesheet][33] and a few lines
This can easily be achieved with an [additional stylesheet][35] and a few lines
of CSS:

=== "Increase width"
Expand All @@ -445,5 +453,5 @@ of CSS:
}
```

[32]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
[33]: ../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

0 comments on commit accc2a3

Please sign in to comment.