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.

Bundled with the official Docker image

This plugin is already installed for your convenience when you use the official Docker image, so the installation step can be skipped. Read the getting started guide 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