MkDocs Awesome Pages Plugin (Pre-v3)

2.10.1 · deprecated · verified Sun Apr 12

This is an MkDocs plugin that simplifies configuring page titles and their order using `.pages` files. This package represents versions prior to 3.0.0. As of version 3.0.0, the plugin has been completely rewritten, renamed to `mkdocs-awesome-nav`, and is distributed under a new PyPI package. This specific package (`mkdocs-awesome-pages-plugin`) is no longer actively developed and is considered deprecated in favor of `mkdocs-awesome-nav`.

Warnings

breaking Breaking Change: Plugin Renamed and Rewritten in v3.0.0. Version 3.0.0 of this plugin was a complete rewrite, renamed to `mkdocs-awesome-nav`, and released under a new PyPI package. The new version introduces a different approach to navigation generation, leading to breaking changes in configuration and behavior.
Fix: Migrate to `mkdocs-awesome-nav`. Install `pip install mkdocs-awesome-nav` and consult its documentation for updated configuration details and `.pages` file syntax. If you must use the old behavior, pin your `mkdocs-awesome-pages-plugin` version to `<3.0.0`.
deprecated This package (`mkdocs-awesome-pages-plugin`) is deprecated. Development has moved to the `mkdocs-awesome-nav` package.
Fix: Upgrade to `mkdocs-awesome-nav` for new features, bug fixes, and ongoing support. The new package is `mkdocs-awesome-nav`.
gotcha Incorrect Plugin Name in `mkdocs.yml`. A common mistake is to specify the full PyPI package name (`mkdocs-awesome-pages-plugin`) in the `plugins` section of `mkdocs.yml`.
Fix: Always use the registered entrypoint name, which is `awesome-pages`, in your `mkdocs.yml` configuration: `plugins: - awesome-pages`.

Install

pip install mkdocs-awesome-pages-plugin Install specific version (deprecated)
pip install mkdocs-awesome-nav Install current version (recommended)

Imports

awesome-pages
```
plugins:
  - awesome-pages
```
MkDocs plugins are referenced by their entrypoint name (e.g., 'awesome-pages') in `mkdocs.yml`, not their full PyPI package name.

Quickstart

To use the plugin, add `awesome-pages` to the `plugins` section of your `mkdocs.yml` file. Then, define page titles, order, and hierarchy within your documentation directories using `.pages` files, where `nav` specifies the order and `title` sets the section's name in the navigation.

# mkdocs.yml
site_name: My Awesome Docs

plugins:
  - awesome-pages

# docs/index.md
# My Home Page

# docs/section/.pages
# title: Section Title for Menu
# nav:
#   - page-one.md
#   - page-two.md
#   - sub-section/

# docs/section/page-one.md
# Content for Page One

view raw JSON →