Skip to content

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.


Install the plugin using pip:

pip install mkdocs-awesome-pages-plugin


Add the following lines to mkdocs.yml:

  - search # necessary for search to work
  - awesome-pages


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:

  - 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