{"id":5659,"library":"mkdocs-awesome-pages-plugin","title":"MkDocs Awesome Pages Plugin (Pre-v3)","description":"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`.","status":"deprecated","version":"2.10.1","language":"en","source_language":"en","source_url":"https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/","tags":["mkdocs","plugin","navigation","pages","documentation"],"install":[{"cmd":"pip install mkdocs-awesome-pages-plugin","lang":"bash","label":"Install specific version (deprecated)"},{"cmd":"pip install mkdocs-awesome-nav","lang":"bash","label":"Install current version (recommended)"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"MkDocs","optional":false}],"imports":[{"note":"MkDocs plugins are referenced by their entrypoint name (e.g., 'awesome-pages') in `mkdocs.yml`, not their full PyPI package name.","wrong":"plugins:\n  - mkdocs-awesome-pages-plugin","symbol":"awesome-pages","correct":"plugins:\n  - awesome-pages"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Awesome Docs\n\nplugins:\n  - awesome-pages\n\n# docs/index.md\n# My Home Page\n\n# docs/section/.pages\n# title: Section Title for Menu\n# nav:\n#   - page-one.md\n#   - page-two.md\n#   - sub-section/\n\n# docs/section/page-one.md\n# Content for Page One\n","lang":"yaml","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions >= 3.0.0 (under the new `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`.","message":"This package (`mkdocs-awesome-pages-plugin`) is deprecated. Development has moved to the `mkdocs-awesome-nav` package.","severity":"deprecated","affected_versions":"All versions of `mkdocs-awesome-pages-plugin` (2.x.x series)"},{"fix":"Always use the registered entrypoint name, which is `awesome-pages`, in your `mkdocs.yml` configuration: `plugins: - awesome-pages`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}