0
# MkDocs Awesome Pages Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: mkdocs-awesome-pages-plugin
7
- **Language**: Python
8
- **Installation**: `pip install mkdocs-awesome-pages-plugin`
9
- **Requirements**: Python >=3.8.1, MkDocs >=1.0
10
- **Dependencies**: wcmatch>=7, natsort>=8.1.0
11

12
## Core Imports
13

14
```python
15
from mkdocs_awesome_pages_plugin.plugin import AwesomePagesPlugin
16
from mkdocs_awesome_pages_plugin.utils import dirname, basename, normpath, join_paths, cd
17
from mkdocs_awesome_pages_plugin.meta import Meta, MetaNavItem, MetaNavRestItem
18
from mkdocs_awesome_pages_plugin.navigation import AwesomeNavigation
19
from mkdocs_awesome_pages_plugin.options import Options
20
```
21

22
Plugin registration (in mkdocs.yml):
23

24
```yaml
25
plugins:
26
  - awesome-pages:
27
      filename: .pages
28
      collapse_single_pages: false
29
      strict: true
30
      order: null
31
      sort_type: null  
32
      order_by: null
33
      ignore_case: false
34
```
35

36
## Basic Usage
37

38
Enable the plugin in your `mkdocs.yml` configuration:
39

40
```yaml
41
plugins:
42
  - search
43
  - awesome-pages
44
```
45

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

48
```yaml
49
# Simple navigation ordering
50
nav:
51
  - introduction.md
52
  - ...  # Include all other files
53
  - summary.md
54

55
# With custom titles
56
nav:
57
  - Overview: introduction.md
58
  - ...
59
  - Final Thoughts: summary.md
60
```
61

62
Advanced `.pages` configuration with sorting and filtering:
63

64
```yaml
65
title: "API Documentation"
66
nav:
67
  - overview.md
68
  - ... | flat | glob=tutorial-*.md  # Filter and flatten
69
  - ...  # Remaining files
70
order: asc
71
sort_type: natural
72
order_by: title
73
ignore_case: true
74
collapse_single_pages: true
75
hide: false
76
```
77

78
## Architecture
79

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

82
- **AwesomePagesPlugin**: Main plugin class implementing MkDocs plugin hooks
83
- **Meta System**: Handles `.pages` file parsing and configuration metadata
84
- **Navigation Processing**: Transforms MkDocs navigation based on configurations
85
- **Options Management**: Centralizes plugin configuration options
86
- **Utilities**: Common path and file operations
87

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

90
## Capabilities
91

92
### Plugin Configuration
93

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

96
```python { .api }
97
class AwesomePagesPlugin(BasePlugin):
98
    config_scheme = (
99
        ("filename", config_options.Type(str, default=".pages")),
100
        ("collapse_single_pages", config_options.Type(bool, default=False)),
101
        ("strict", config_options.Type(bool, default=True)),
102
        ("order", config_options.Choice(["asc", "desc"], default=None)),
103
        ("sort_type", config_options.Choice(["natural"], default=None)),
104
        ("order_by", config_options.Choice(["filename", "title"], default=None)),
105
        ("ignore_case", config_options.Type(bool, default=False)),
106
    )
107
```
108

109
[Plugin Configuration](./plugin-configuration.md)
110

111
### Pages File Configuration
112

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

115
```python { .api }
116
class Meta:
117
    def __init__(
118
        self, *, title: str = None, arrange: List[str] = None, 
119
        nav: List[MetaNavItem] = None, path: str = None,
120
        collapse: bool = None, collapse_single_pages: bool = None,
121
        hide: bool = None, ignore_case: bool = None,
122
        order: str = None, sort_type: str = None, order_by: str = None
123
    ): ...
124
    
125
    @staticmethod
126
    def load_from(path: str) -> "Meta": ...
127
    
128
    @staticmethod  
129
    def try_load_from_files(rel_path: str, files: Files) -> "Meta": ...
130
```
131

132
[Pages Configuration](./pages-configuration.md)
133

134
### Navigation Processing
135

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

138
```python { .api }
139
class AwesomeNavigation:
140
    def __init__(
141
        self, items: List[NavigationItem], options: Options,
142
        files: Files, explicit_sections: Set[Section]
143
    ): ...
144
    
145
    def to_mkdocs(self) -> MkDocsNavigation: ...
146

147
NavigationItem = Union[Page, Section, Link]
148
```
149

150
[Navigation Processing](./navigation-processing.md)
151

152
### Rest Entry Patterns
153

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

156
```python { .api }
157
class MetaNavRestItem(MetaNavItem):
158
    def __init__(self, value: str): ...
159
    def matches(self, path: str) -> bool: ...
160
    
161
    @staticmethod
162
    def is_rest(item: Any) -> bool: ...
163

164
class RestType(Enum):
165
    GLOB = "glob"
166
    REGEX = "regex" 
167
    ALL = "all"
168
```
169

170
[Rest Patterns](./rest-patterns.md)
171

172
### Utility Functions
173

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

176
```python { .api }
177
def dirname(path: Optional[str]) -> Optional[str]: ...
178
def basename(path: Optional[str]) -> Optional[str]: ...
179
def normpath(path: Optional[str]) -> Optional[str]: ...
180
def join_paths(path1: Optional[str], path2: Optional[str]) -> Optional[str]: ...
181

182
class cd:
183
    def __init__(self, new_path: str): ...
184
    def __enter__(self): ...
185
    def __exit__(self, exception_type, value, traceback): ...
186
```
187

188
## Types
189

190
```python { .api }
191
class Options:
192
    def __init__(
193
        self, *, filename: str, collapse_single_pages: bool,
194
        strict: bool, order: str = None, sort_type: str = None,
195
        order_by: str = None, ignore_case: bool = None
196
    ): ...
197

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

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

209
class NavigationMeta:
210
    def __init__(
211
        self, items: List[NavigationItem], options: Options,
212
        files: Files, explicit_sections: Set[Section]
213
    ): ...
214

215
# Exceptions and Warnings
216
class DuplicateRestItemError(Exception): ...
217
class NavEntryNotFound(Warning): ...
218
class TitleInRootHasNoEffect(Warning): ...
219
class HideInRootHasNoEffect(Warning): ...
220
class NavPluginOrder(Warning): ...
221
```