Pages Configuration

class Meta:
    """
    Represents .pages file configuration and metadata.
    
    Class Attributes:
        TITLE_ATTRIBUTE: str = 'title'
        NAV_ATTRIBUTE: str = 'nav'
        ARRANGE_ATTRIBUTE: str = 'arrange'
        ARRANGE_REST_TOKEN: str = '...'
        COLLAPSE_ATTRIBUTE: str = 'collapse'
        COLLAPSE_SINGLE_PAGES_ATTRIBUTE: str = 'collapse_single_pages'
        HIDE_ATTRIBUTE: str = 'hide'
        IGNORE_CASE_ATTRIBUTE: str = 'ignore_case'
        ORDER_ATTRIBUTE: str = 'order'
        SORT_TYPE_ATTRIBUTE: str = 'sort_type'
        ORDER_BY_ATTRIBUTE: str = 'order_by'
        ORDER_ASC: str = 'asc'
        ORDER_DESC: str = 'desc'
        SORT_NATURAL: str = 'natural'
        ORDER_BY_FILENAME: str = 'filename'
        ORDER_BY_TITLE: str = 'title'
    
    Args:
        title (str, optional): Custom title for the section
        arrange (List[str], optional): Simple page ordering (deprecated, use nav)
        nav (List[MetaNavItem], optional): Navigation structure definition
        path (str, optional): Path to the configuration file
        collapse (bool, optional): Collapse single-page sections locally
        collapse_single_pages (bool, optional): Override plugin setting
        hide (bool, optional): Hide this section from navigation
        ignore_case (bool, optional): Case-insensitive sorting locally
        order (str, optional): Local sort order ('asc' or 'desc')
        sort_type (str, optional): Local sort algorithm ('natural')
        order_by (str, optional): Local sort attribute ('filename' or 'title')
    """
    
    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":
        """
        Load metadata from a .pages file path.
        
        Args:
            path (str): Absolute path to .pages file
            
        Returns:
            Meta: Parsed configuration object
            
        Raises:
            FileNotFoundError: If file doesn't exist
            TypeError: If configuration format is invalid
            DuplicateRestItemError: If duplicate rest entries found
        """
    
    @staticmethod
    def try_load_from_files(rel_path: str, files: Files) -> "Meta":
        """
        Try to load metadata from Files collection.
        
        Args:
            rel_path (str, optional): Relative path to .pages file
            files (Files): MkDocs Files collection
            
        Returns:
            Meta: Parsed configuration or empty Meta if not found
        """

class MetaNavItem:
    """
    Represents a navigation item from .pages configuration.
    
    Args:
        value (Union[str, List[MetaNavItem]]): File/directory name or nested items
        title (str, optional): Custom title for the navigation entry
    """
    
    def __init__(self, value: Union[str, List["MetaNavItem"]], title: str = None): ...
    
    def __eq__(self, other: object) -> bool:
        """Equality comparison for navigation items."""
    
    def __hash__(self) -> int:
        """Hash implementation for set/dict usage."""
    
    @staticmethod
    def from_yaml(item: Union[str, dict], context: str) -> "MetaNavItem":
        """
        Create navigation item from YAML data.
        
        Args:
            item (Union[str, dict]): YAML item (string or title: value dict)
            context (str): Context path for error reporting
            
        Returns:
            MetaNavItem: Parsed navigation item
            
        Raises:
            TypeError: If item format is invalid
        """

class DuplicateRestItemError(Exception):
    """
    Raised when duplicate rest entries are found in configuration.
    
    Args:
        item (str): The duplicate rest entry value
        context (str): Context path where duplicate was found
    """
    
    def __init__(self, item: str, context: str): ...

# .pages
nav:
  - introduction.md
  - ...  # Include all other files here
  - conclusion.md

# .pages
title: "API Documentation"

nav:
  - Overview: introduction.md
  - Getting Started: setup.md
  - ... | flat | glob=tutorial-*.md  # Filtered rest entries
  - ...  # Remaining files
  - FAQ: faq.md

# Sorting and display options
order: asc
sort_type: natural
order_by: title
ignore_case: true

# Section behavior
collapse: false
collapse_single_pages: true
hide: false

nav:
  # Simple file reference
  - simple-file.md
  
  # File with custom title
  - Custom Title: some-file.md
  
  # External link
  - External Link: https://example.com
  
  # Nested section
  - Section Name:
    - nested-file.md
    - Another File: another-nested.md
  
  # Rest entries with patterns
  - ...  # All remaining files
  - ... | flat  # Flatten nested structure
  - ... | glob=api-*.md  # Only files matching pattern
  - ... | regex=test.*\.md  # Files matching regex

# Title override
title: "Custom Section Name"  # Overrides directory name

# Hiding sections
hide: true  # Section won't appear in navigation

# Collapsing behavior
collapse: true  # Single-page sections are collapsed
collapse_single_pages: false  # Override plugin setting

# Sorting options
order: desc  # Sort in descending order
sort_type: natural  # Natural number sorting (1, 2, 10 vs 1, 10, 2)
order_by: filename  # Sort by filename instead of title
ignore_case: true  # Case-insensitive sorting