mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-24 07:30:12 +01:00
Added reference to mkdocs-section-index plugin
This commit is contained in:
squidfunk
parent
1545ed6294
commit
accc2a34d1
@ -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:
|
||||
@ -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:
|
||||
@ -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:
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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
|
||||
@ -316,14 +324,14 @@ 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
|
||||
@ -331,12 +339,12 @@ 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
|
||||
---
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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"
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user