0
# Plugin Configuration
1

2
Core plugin class and configuration options for integrating the awesome-pages plugin with MkDocs. This includes all available settings and their effects on navigation processing.
3

4
## Capabilities
5

6
### Main Plugin Class
7

8
The primary plugin implementation that handles the MkDocs plugin lifecycle and coordinates all navigation processing activities.
9

10
```python { .api }
11
class AwesomePagesPlugin(BasePlugin):
12
    """
13
    Main plugin class extending MkDocs BasePlugin.
14
    
15
    Class Attributes:
16
    - DEFAULT_META_FILENAME: str = '.pages'
17
    - REST_PLACEHOLDER: str = 'AWESOME_PAGES_REST'
18
    """
19
    
20
    config_scheme = (
21
        ("filename", config_options.Type(str, default=".pages")),
22
        ("collapse_single_pages", config_options.Type(bool, default=False)),
23
        ("strict", config_options.Type(bool, default=True)),
24
        ("order", config_options.Choice(["asc", "desc"], default=None)),
25
        ("sort_type", config_options.Choice(["natural"], default=None)),
26
        ("order_by", config_options.Choice(["filename", "title"], default=None)),
27
        ("ignore_case", config_options.Type(bool, default=False)),
28
    )
29
    
30
    def __init__(self): ...
31
    
32
    def on_config(self, config: Config) -> Config:
33
        """Process MkDocs configuration and detect plugin ordering issues."""
34
    
35
    def on_files(self, files: Files, config: Config) -> Files:
36
        """Add .pages config files to the Files collection."""
37
    
38
    def on_nav(self, nav: MkDocsNavigation, config: Config, files: Files) -> MkDocsNavigation:
39
        """Transform navigation based on .pages configurations."""
40
```
41

42
### Configuration Options
43

44
Individual configuration options that control plugin behavior globally across all documentation directories.
45

46
```python { .api }
47
class Options:
48
    """
49
    Container for plugin configuration options.
50
    
51
    Args:
52
        filename (str): Name of configuration files to look for (default: '.pages')
53
        collapse_single_pages (bool): Automatically collapse sections with single pages
54
        strict (bool): Raise errors for missing navigation entries vs warnings
55
        order (str, optional): Default sort order ('asc' or 'desc')
56
        sort_type (str, optional): Sort algorithm ('natural' for natural sorting)
57
        order_by (str, optional): Sort by attribute ('filename' or 'title')
58
        ignore_case (bool, optional): Case-insensitive sorting
59
    """
60
    
61
    def __init__(
62
        self, *, filename: str, collapse_single_pages: bool,
63
        strict: bool, order: str = None, sort_type: str = None,
64
        order_by: str = None, ignore_case: bool = None
65
    ): ...
66
```
67

68
### Usage Examples
69

70
Basic plugin configuration in `mkdocs.yml`:
71

72
```yaml
73
plugins:
74
  - search
75
  - awesome-pages
76
```
77

78
Advanced plugin configuration with custom options:
79

80
```yaml
81
plugins:
82
  - awesome-pages:
83
      filename: .navigation  # Use custom config filename
84
      collapse_single_pages: true  # Auto-collapse single-page sections
85
      strict: false  # Show warnings instead of errors for missing entries
86
      order: asc  # Default ascending sort order
87
      sort_type: natural  # Use natural sorting (1, 2, 10 vs 1, 10, 2)
88
      order_by: title  # Sort by page title instead of filename
89
      ignore_case: true  # Case-insensitive sorting
90
```
91

92
Configuration option effects:
93

94
```python
95
# With strict=True (default)
96
# Missing nav entry raises NavEntryNotFound exception
97

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

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

104
# With order=asc, sort_type=natural, order_by=title
105
# Pages sorted naturally by title in ascending order
106
```
107

108
### Warning Classes
109

110
Warning classes that alert users to potential configuration issues or ineffective settings.
111

112
```python { .api }
113
class NavPluginOrder(Warning):
114
    """
115
    Warning for plugin ordering issues.
116
    
117
    Args:
118
        plugin_name (str): Name of the plugin that might conflict
119
    """
120
    
121
    def __init__(self, plugin_name: str): ...
122

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

128
class HideInRootHasNoEffect(Warning):
129
    """Warning when hide attribute is used in root .pages file."""
130
    
131
    def __init__(self, filename: str): ...
132
```
133

134
## Plugin Integration
135

136
The plugin integrates with MkDocs through the standard plugin system:
137

138
1. **Registration**: Registered in `pyproject.toml` under `[tool.poetry.plugins."mkdocs.plugins"]`
139
2. **Configuration**: Uses MkDocs config_options for validation and type checking
140
3. **Lifecycle**: Implements three main hooks (`on_config`, `on_files`, `on_nav`)
141
4. **File Processing**: Extends MkDocs Files collection to include .pages config files
142
5. **Navigation**: Transforms MkDocs Navigation objects based on configurations