mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
77 lines
1.8 KiB
Markdown
77 lines
1.8 KiB
Markdown
# Awesome pages
|
|
|
|
The [mkdocs-awesome-pages-plugin][1] omits the need to specify all pages in the
|
|
`nav` entry of `mkdocs.yml` and gives you control over page visibility, titles
|
|
and order on a directory level.
|
|
|
|
!!! success "Bundled with the official Docker image"
|
|
|
|
This plugin is already installed for your convenience when you use the
|
|
official [Docker image][2], so the installation step can be skipped. Read
|
|
the [getting started guide][3] to get up and running with Docker.
|
|
|
|
[1]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
|
|
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
|
[3]: ../getting-started.md#with-docker-recommended
|
|
|
|
## Installation
|
|
|
|
Install the plugin using `pip`:
|
|
|
|
``` sh
|
|
pip install mkdocs-awesome-pages-plugin
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Add the following lines to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
plugins:
|
|
- search # necessary for search to work
|
|
- awesome-pages
|
|
```
|
|
|
|
## Usage
|
|
|
|
If the `nav` entry in `mkdocs.yml` is omitted, MkDocs will automatically include
|
|
all pages in a specific order. This plugin allows for more fine-grained control
|
|
on a per-directory basis. In order to configure behavior for a specific
|
|
directory, create a YAML file named `.pages` in it and set one of the following
|
|
options.
|
|
|
|
### Setting a directory title
|
|
|
|
The directory title, which is shown as part of the navigation, can be set with:
|
|
|
|
``` yaml
|
|
title: Lorem ipsum dolor sit amet
|
|
```
|
|
|
|
### Changing the order of pages
|
|
|
|
The order of pages and subsections can be configured with:
|
|
|
|
``` yaml
|
|
arrange:
|
|
- page-1.md
|
|
- page-2.md
|
|
- subdirectory
|
|
```
|
|
|
|
### Excluding a directory
|
|
|
|
A directory can be hidden (i.e. excluded) with:
|
|
|
|
``` yaml
|
|
hide: true
|
|
```
|
|
|
|
### Collapsing single-page directories
|
|
|
|
Directories which contain a single page can be collapsed with:
|
|
|
|
``` yaml
|
|
collapse: true
|
|
```
|