Plugin Configuration

class AwesomePagesPlugin(BasePlugin):
    """
    Main plugin class extending MkDocs BasePlugin.
    
    Class Attributes:
    - DEFAULT_META_FILENAME: str = '.pages'
    - REST_PLACEHOLDER: str = 'AWESOME_PAGES_REST'
    """
    
    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)),
    )
    
    def __init__(self): ...
    
    def on_config(self, config: Config) -> Config:
        """Process MkDocs configuration and detect plugin ordering issues."""
    
    def on_files(self, files: Files, config: Config) -> Files:
        """Add .pages config files to the Files collection."""
    
    def on_nav(self, nav: MkDocsNavigation, config: Config, files: Files) -> MkDocsNavigation:
        """Transform navigation based on .pages configurations."""

class Options:
    """
    Container for plugin configuration options.
    
    Args:
        filename (str): Name of configuration files to look for (default: '.pages')
        collapse_single_pages (bool): Automatically collapse sections with single pages
        strict (bool): Raise errors for missing navigation entries vs warnings
        order (str, optional): Default sort order ('asc' or 'desc')
        sort_type (str, optional): Sort algorithm ('natural' for natural sorting)
        order_by (str, optional): Sort by attribute ('filename' or 'title')
        ignore_case (bool, optional): Case-insensitive sorting
    """
    
    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
    ): ...

plugins:
  - search
  - awesome-pages

plugins:
  - awesome-pages:
      filename: .navigation  # Use custom config filename
      collapse_single_pages: true  # Auto-collapse single-page sections
      strict: false  # Show warnings instead of errors for missing entries
      order: asc  # Default ascending sort order
      sort_type: natural  # Use natural sorting (1, 2, 10 vs 1, 10, 2)
      order_by: title  # Sort by page title instead of filename
      ignore_case: true  # Case-insensitive sorting

# With strict=True (default)
# Missing nav entry raises NavEntryNotFound exception

# With strict=False  
# Missing nav entry shows warning and continues processing

# With collapse_single_pages=True
# Sections with only one child are automatically collapsed

# With order=asc, sort_type=natural, order_by=title
# Pages sorted naturally by title in ascending order

class NavPluginOrder(Warning):
    """
    Warning for plugin ordering issues.
    
    Args:
        plugin_name (str): Name of the plugin that might conflict
    """
    
    def __init__(self, plugin_name: str): ...

class TitleInRootHasNoEffect(Warning):
    """Warning when title attribute is used in root .pages file."""
    
    def __init__(self, filename: str): ...

class HideInRootHasNoEffect(Warning):
    """Warning when hide attribute is used in root .pages file."""
    
    def __init__(self, filename: str): ...