Awesome pages

The mkdocs-awesome-pages-plugin 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.

Installation

Install the plugin using pip:

pip install mkdocs-awesome-pages-plugin

Configuration

Add the following lines to mkdocs.yml:

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:

title: Lorem ipsum dolor sit amet

Changing the order of pages

The order of pages and subsections can be configured with:

arrange:
  - page-1.md
  - page-2.md
  - subdirectory

Excluding a directory

A directory can be hidden (i.e. excluded) with:

hide: true

Collapsing single-page directories

Directories which contain a single page can be collapsed with:

collapse: true

1.8 KiB Raw Blame History