An MkDocs plugin that simplifies configuring page titles and their order
Branch: master
Clone or download

README.md

MkDocs Awesome Pages Plugin Build Status

An MkDocs plugin that simplifies configuring page titles and their order

The awesome-pages plugin allows you to customize how your pages show up the navigation of your MkDocs without having to configure the full structure in your mkdocs.yml. It gives you detailed control using a small configuration file directly placed in the relevant directory of your documentation.

Note: This plugin works best without a nav or pages entry in your mkdocs.yml. Having a nav entry is supported, but you might not get the results you expect, especially if your nav structure doesn't match the file structure.


Installation

Note: This package requires Python >=3.5 and MkDocs version 1.0 or higher.
If you're still on MkDocs 0.17 use version 1 of this plugin.

Install the package with pip:

pip install mkdocs-awesome-pages-plugin

Enable the plugin in your mkdocs.yml:

plugins:
    - search
    - awesome-pages

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

More information about plugins in the MkDocs documentation


Features

Collapse Single Nested Pages

Note: This feature is disabled by default. More on how to use it below

If you have directories that only contain a single page, awesome-pages can "collapse" them, so the folder doesn't show up in the navigation.

For example if you have the following file structure:

docs/
├─ section1/
│  ├─ img/
│  │  ├─ image1.png
│  │  └─ image2.png
│  └─ index.md # Section 1
└─ section2/
   └─ index.md # Section 2

The pages will appear in your navigation at the root level:

  • Section 1
  • Section 2

Instead of how MkDocs would display them by default:

  • Section 1
    • Index
  • Section 2
    • Index

For all pages

Collapsing can be enabled globally using the collapse_single_pages option in mkdocs.yml

For a sub-section

If you only want to collapse certain pages, create a YAML file called .pages in the directory and set collapse_single_pages to true:

collapse_single_pages: true

You may also enable collapsing globally using the plugin option and then use the .pages file to prevent certain sub-sections from being collapsed by setting collapse_single_pages to false.

Note: This feature works recursively. That means it will also collapse multiple levels of single pages.

For a single page

If you want to enable or disable collapsing of a single page, without applying the setting recursively, create a YAML file called .pages in the directory and set collapse to true or false:

collapse: true

Set Directory Title

Create a YAML file named .pages in a directory and set the title to override the title of that directory in the navigation:

title: Page Title

Arrange Pages

Create a YAML file named .pages in a directory and set the arrange attribute to change the order of how child pages appear in the navigation. This works for actual pages as well as subdirectories.

title: Page Title
arrange:
    - page1.md
    - page2.md
    - subdirectory

If you only specify some pages, they will be positioned at the beginning, followed by the other pages in their original order.

You may also include a ... entry at some position to specify where the rest of the pages should be inserted:

arrange:
    - introduction.md
    - ...
    - summary.md

In this example introduction.md is positioned at the beginning, summary.md at the end, and any other pages in between.


Options

You may customize the plugin by passing options in mkdocs.yml:

plugins:
    - awesome-pages:
        filename: .index
        collapse_single_pages: true

filename

Name of the file used to configure pages of a directory. Default is .pages

collapse_single_pages

Enable the collapsing of single nested pages. Default is false


Contributing

From reporting a bug to submitting a pull request: every contribution is appreciated and welcome. Report bugs, ask questions and request features using Github issues. If you want to contribute to the code of this project, please read the Contribution Guidelines.