or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdnavigation-processing.mdpages-configuration.mdplugin-configuration.mdrest-patterns.md
tile.json

tessl/pypi-mkdocs-awesome-pages-plugin

An MkDocs plugin that simplifies configuring page titles and their order through .pages configuration files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mkdocs-awesome-pages-plugin@2.10.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocs-awesome-pages-plugin@2.10.0

index.mddocs/

MkDocs Awesome Pages Plugin

A comprehensive MkDocs plugin that simplifies navigation configuration and page ordering in MkDocs documentation sites. This plugin offers advanced navigation customization features including dynamic page ordering, title customization, directory collapsing, and filtering capabilities through simple .pages configuration files placed in documentation directories.

Package Information

  • Package Name: mkdocs-awesome-pages-plugin
  • Language: Python
  • Installation: pip install mkdocs-awesome-pages-plugin
  • Requirements: Python >=3.8.1, MkDocs >=1.0
  • Dependencies: wcmatch>=7, natsort>=8.1.0

Core Imports

from mkdocs_awesome_pages_plugin.plugin import AwesomePagesPlugin
from mkdocs_awesome_pages_plugin.utils import dirname, basename, normpath, join_paths, cd
from mkdocs_awesome_pages_plugin.meta import Meta, MetaNavItem, MetaNavRestItem
from mkdocs_awesome_pages_plugin.navigation import AwesomeNavigation
from mkdocs_awesome_pages_plugin.options import Options

Plugin registration (in mkdocs.yml):

plugins:
  - awesome-pages:
      filename: .pages
      collapse_single_pages: false
      strict: true
      order: null
      sort_type: null  
      order_by: null
      ignore_case: false

Basic Usage

Enable the plugin in your mkdocs.yml configuration:

plugins:
  - search
  - awesome-pages

Create a .pages file in any documentation directory to customize navigation:

# Simple navigation ordering
nav:
  - introduction.md
  - ...  # Include all other files
  - summary.md

# With custom titles
nav:
  - Overview: introduction.md
  - ...
  - Final Thoughts: summary.md

Advanced .pages configuration with sorting and filtering:

title: "API Documentation"
nav:
  - overview.md
  - ... | flat | glob=tutorial-*.md  # Filter and flatten
  - ...  # Remaining files
order: asc
sort_type: natural
order_by: title
ignore_case: true
collapse_single_pages: true
hide: false

Architecture

The plugin follows a modular architecture with clear separation of concerns:

  • AwesomePagesPlugin: Main plugin class implementing MkDocs plugin hooks
  • Meta System: Handles .pages file parsing and configuration metadata
  • Navigation Processing: Transforms MkDocs navigation based on configurations
  • Options Management: Centralizes plugin configuration options
  • Utilities: Common path and file operations

The plugin integrates with MkDocs through three main hooks: on_config, on_files, and on_nav, providing a complete navigation customization pipeline.

Capabilities

Plugin Configuration

Core plugin class and configuration options for integrating with MkDocs, including all available settings and their effects on navigation processing.

class AwesomePagesPlugin(BasePlugin):
    config_scheme = (
        ("filename", config_options.Type(str, default=".pages")),
        ("collapse_single_pages", config_options.Type(bool, default=False)),
        ("strict", config_options.Type(bool, default=True)),
        ("order", config_options.Choice(["asc", "desc"], default=None)),
        ("sort_type", config_options.Choice(["natural"], default=None)),
        ("order_by", config_options.Choice(["filename", "title"], default=None)),
        ("ignore_case", config_options.Type(bool, default=False)),
    )

Plugin Configuration

Pages File Configuration

Meta configuration system for .pages files, including all supported attributes, validation, and advanced features like rest entries with pattern matching.

class Meta:
    def __init__(
        self, *, title: str = None, arrange: List[str] = None, 
        nav: List[MetaNavItem] = None, path: str = None,
        collapse: bool = None, collapse_single_pages: bool = None,
        hide: bool = None, ignore_case: bool = None,
        order: str = None, sort_type: str = None, order_by: str = None
    ): ...
    
    @staticmethod
    def load_from(path: str) -> "Meta": ...
    
    @staticmethod  
    def try_load_from_files(rel_path: str, files: Files) -> "Meta": ...

Pages Configuration

Navigation Processing

Advanced navigation transformation system that processes MkDocs navigation structures according to .pages configurations, including ordering, filtering, and structural modifications.

class AwesomeNavigation:
    def __init__(
        self, items: List[NavigationItem], options: Options,
        files: Files, explicit_sections: Set[Section]
    ): ...
    
    def to_mkdocs(self) -> MkDocsNavigation: ...

NavigationItem = Union[Page, Section, Link]

Navigation Processing

Rest Entry Patterns

Pattern matching system for "..." rest entries in navigation configurations, supporting glob patterns, regular expressions, and flattening options.

class MetaNavRestItem(MetaNavItem):
    def __init__(self, value: str): ...
    def matches(self, path: str) -> bool: ...
    
    @staticmethod
    def is_rest(item: Any) -> bool: ...

class RestType(Enum):
    GLOB = "glob"
    REGEX = "regex" 
    ALL = "all"

Rest Patterns

Utility Functions

Common path manipulation and context management utilities used throughout the plugin for file and directory operations.

def dirname(path: Optional[str]) -> Optional[str]: ...
def basename(path: Optional[str]) -> Optional[str]: ...
def normpath(path: Optional[str]) -> Optional[str]: ...
def join_paths(path1: Optional[str], path2: Optional[str]) -> Optional[str]: ...

class cd:
    def __init__(self, new_path: str): ...
    def __enter__(self): ...
    def __exit__(self, exception_type, value, traceback): ...

Types

class Options:
    def __init__(
        self, *, filename: str, collapse_single_pages: bool,
        strict: bool, order: str = None, sort_type: str = None,
        order_by: str = None, ignore_case: bool = None
    ): ...

class MetaNavItem:
    def __init__(self, value: Union[str, List["MetaNavItem"]], title: str = None): ...
    
    @staticmethod
    def from_yaml(item: Union[str, dict], context: str) -> "MetaNavItem": ...

class RestItemList:
    def append(self, item: MetaNavRestItem): ...
    def __iter__(self) -> Iterator[MetaNavRestItem]: ...
    def __len__(self) -> int: ...

class NavigationMeta:
    def __init__(
        self, items: List[NavigationItem], options: Options,
        files: Files, explicit_sections: Set[Section]
    ): ...

# Exceptions and Warnings
class DuplicateRestItemError(Exception): ...
class NavEntryNotFound(Warning): ...
class TitleInRootHasNoEffect(Warning): ...
class HideInRootHasNoEffect(Warning): ...
class NavPluginOrder(Warning): ...