tessl/pypi-mkdocs-awesome-pages-plugin

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

0.94x

Evaluation — 56%

↓ 0.94x

Agent success when using this tile

Overview

Eval results

Files

Navigation Processing

Name: tessl/pypi-mkdocs-awesome-pages-plugin
Rating: 0.56 (1 reviews)
Author: tessl

Advanced navigation transformation system that processes MkDocs navigation structures according to .pages configurations. This system handles ordering, filtering, structural modifications, and the integration of custom navigation with automatic file discovery.

Capabilities

Navigation Processor

The main class responsible for transforming MkDocs navigation based on configuration metadata and plugin options.

class AwesomeNavigation:
    """
    Processes and transforms MkDocs navigation based on .pages configurations.
    
    Args:
        items (List[NavigationItem]): Initial navigation items from MkDocs
        options (Options): Plugin configuration options
        files (Files): MkDocs Files collection
        explicit_sections (Set[Section]): Sections explicitly defined in mkdocs.yml
    """
    
    def __init__(
        self, items: List[NavigationItem], options: Options,
        files: Files, explicit_sections: Set[Section]
    ): ...
    
    def to_mkdocs(self) -> MkDocsNavigation:
        """
        Convert processed navigation back to MkDocs Navigation format.
        
        Returns:
            MkDocsNavigation: Final navigation with previous/next links and parent links
        """

# Type alias for navigation items
NavigationItem = Union[Page, Section, Link]

Navigation Metadata Manager

Manages metadata collection and organization for navigation processing, coordinating between different directory levels and their configurations.

class NavigationMeta:
    """
    Manages metadata for navigation sections and items.
    
    Args:
        items (List[NavigationItem]): Navigation items to process
        options (Options): Plugin configuration options
        files (Files): MkDocs Files collection
        explicit_sections (Set[Section]): Explicitly defined sections
    """
    
    def __init__(
        self, items: List[NavigationItem], options: Options,
        files: Files, explicit_sections: Set[Section]
    ): ...

Virtual Section Support

Special section class for dynamically created navigation sections that don't correspond to actual directories.

class VirtualSection(Section):
    """
    Represents dynamically created navigation sections.
    
    Extends mkdocs.structure.nav.Section to support sections created
    through .pages nav configuration that don't map to actual directories.
    """
    pass

Utility Functions

Navigation processing utilities for extracting and organizing navigation items by type.

def get_by_type(nav: List[NavigationItem], T: type) -> List[NavigationItem]:
    """
    Extract items of specific type from navigation tree.
    
    Recursively searches through navigation items and their children
    to find all items matching the specified type.
    
    Args:
        nav (List[NavigationItem]): Navigation items to search
        T (type): Type class to match (Page, Section, Link, etc.)
        
    Returns:
        List[NavigationItem]: All matching items found in the tree
    """

Usage Examples

Basic navigation processing flow:

from mkdocs_awesome_pages_plugin.navigation import AwesomeNavigation
from mkdocs_awesome_pages_plugin.options import Options

# Initialize with MkDocs navigation and plugin options
options = Options(
    filename='.pages',
    collapse_single_pages=False,
    strict=True
)

# Process navigation with configurations
awesome_nav = AwesomeNavigation(
    items=mkdocs_nav.items,
    options=options,
    files=files,
    explicit_sections=set()
)

# Convert back to MkDocs format
final_nav = awesome_nav.to_mkdocs()

Navigation item processing:

# Extract all pages from navigation
pages = get_by_type(navigation.items, Page)

# Extract all sections
sections = get_by_type(navigation.items, Section)

# Extract all links
links = get_by_type(navigation.items, Link)

Virtual section creation:

# Created automatically from .pages nav configuration:
# nav:
#   - Section Name:
#     - file1.md
#     - file2.md

# Results in VirtualSection with title "Section Name"
# containing the specified files

Processing Pipeline

The navigation processing follows a structured pipeline:

1. Metadata Collection

Recursively gather .pages configurations from all directories
Build metadata tree matching navigation structure
Validate configurations and detect conflicts

2. Ordering and Sorting

Apply local and global sorting rules
Handle natural sorting vs alphabetical
Support case-sensitive/insensitive options
Sort by filename or extracted page titles

3. Navigation Structure Application

Process nav configurations to reorder items
Handle rest entries and pattern matching
Create virtual sections for nested navigation
Apply title overrides and custom links

4. Section Processing

Handle section collapsing based on rules
Apply hide/show logic for sections
Process nested section hierarchies
Maintain explicit vs generated sections

5. Final Assembly

Convert back to MkDocs Navigation format
Establish previous/next page relationships
Set up parent-child navigation links
Validate final navigation structure

Advanced Features

Title Resolution

The system intelligently resolves page titles using this priority order:

Custom title from .pages nav configuration
Existing navigation item title
Page metadata title from frontmatter
Extracted markdown heading title
Filename-based fallback with formatting

Section Collapsing Rules

Plugin-level collapse_single_pages setting
Directory-level .pages override with collapse_single_pages
Per-section collapse setting in .pages
Automatic collapsing of single-child sections

Error Handling and Warnings

Strict mode raises exceptions for missing navigation entries
Non-strict mode shows warnings and continues processing
Context-aware error messages with file paths
Plugin ordering warnings for potential conflicts

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-awesome-pages-plugin

tessl/pypi-mkdocs-awesome-pages-plugin