0
# Navigation Processing
1

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

4
## Capabilities
5

6
### Navigation Processor
7

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

10
```python { .api }
11
class AwesomeNavigation:
12
    """
13
    Processes and transforms MkDocs navigation based on .pages configurations.
14
    
15
    Args:
16
        items (List[NavigationItem]): Initial navigation items from MkDocs
17
        options (Options): Plugin configuration options
18
        files (Files): MkDocs Files collection
19
        explicit_sections (Set[Section]): Sections explicitly defined in mkdocs.yml
20
    """
21
    
22
    def __init__(
23
        self, items: List[NavigationItem], options: Options,
24
        files: Files, explicit_sections: Set[Section]
25
    ): ...
26
    
27
    def to_mkdocs(self) -> MkDocsNavigation:
28
        """
29
        Convert processed navigation back to MkDocs Navigation format.
30
        
31
        Returns:
32
            MkDocsNavigation: Final navigation with previous/next links and parent links
33
        """
34

35
# Type alias for navigation items
36
NavigationItem = Union[Page, Section, Link]
37
```
38

39
### Navigation Metadata Manager
40

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

43
```python { .api }
44
class NavigationMeta:
45
    """
46
    Manages metadata for navigation sections and items.
47
    
48
    Args:
49
        items (List[NavigationItem]): Navigation items to process
50
        options (Options): Plugin configuration options
51
        files (Files): MkDocs Files collection
52
        explicit_sections (Set[Section]): Explicitly defined sections
53
    """
54
    
55
    def __init__(
56
        self, items: List[NavigationItem], options: Options,
57
        files: Files, explicit_sections: Set[Section]
58
    ): ...
59
```
60

61
### Virtual Section Support
62

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

65
```python { .api }
66
class VirtualSection(Section):
67
    """
68
    Represents dynamically created navigation sections.
69
    
70
    Extends mkdocs.structure.nav.Section to support sections created
71
    through .pages nav configuration that don't map to actual directories.
72
    """
73
    pass
74
```
75

76
### Utility Functions
77

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

80
```python { .api }
81
def get_by_type(nav: List[NavigationItem], T: type) -> List[NavigationItem]:
82
    """
83
    Extract items of specific type from navigation tree.
84
    
85
    Recursively searches through navigation items and their children
86
    to find all items matching the specified type.
87
    
88
    Args:
89
        nav (List[NavigationItem]): Navigation items to search
90
        T (type): Type class to match (Page, Section, Link, etc.)
91
        
92
    Returns:
93
        List[NavigationItem]: All matching items found in the tree
94
    """
95
```
96

97
### Usage Examples
98

99
Basic navigation processing flow:
100

101
```python
102
from mkdocs_awesome_pages_plugin.navigation import AwesomeNavigation
103
from mkdocs_awesome_pages_plugin.options import Options
104

105
# Initialize with MkDocs navigation and plugin options
106
options = Options(
107
    filename='.pages',
108
    collapse_single_pages=False,
109
    strict=True
110
)
111

112
# Process navigation with configurations
113
awesome_nav = AwesomeNavigation(
114
    items=mkdocs_nav.items,
115
    options=options,
116
    files=files,
117
    explicit_sections=set()
118
)
119

120
# Convert back to MkDocs format
121
final_nav = awesome_nav.to_mkdocs()
122
```
123

124
Navigation item processing:
125

126
```python
127
# Extract all pages from navigation
128
pages = get_by_type(navigation.items, Page)
129

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

133
# Extract all links
134
links = get_by_type(navigation.items, Link)
135
```
136

137
Virtual section creation:
138

139
```python
140
# Created automatically from .pages nav configuration:
141
# nav:
142
#   - Section Name:
143
#     - file1.md
144
#     - file2.md
145

146
# Results in VirtualSection with title "Section Name"
147
# containing the specified files
148
```
149

150
## Processing Pipeline
151

152
The navigation processing follows a structured pipeline:
153

154
### 1. Metadata Collection
155
- Recursively gather `.pages` configurations from all directories
156
- Build metadata tree matching navigation structure
157
- Validate configurations and detect conflicts
158

159
### 2. Ordering and Sorting
160
- Apply local and global sorting rules
161
- Handle natural sorting vs alphabetical
162
- Support case-sensitive/insensitive options
163
- Sort by filename or extracted page titles
164

165
### 3. Navigation Structure Application
166
- Process `nav` configurations to reorder items
167
- Handle rest entries and pattern matching
168
- Create virtual sections for nested navigation
169
- Apply title overrides and custom links
170

171
### 4. Section Processing
172
- Handle section collapsing based on rules
173
- Apply hide/show logic for sections
174
- Process nested section hierarchies
175
- Maintain explicit vs generated sections
176

177
### 5. Final Assembly
178
- Convert back to MkDocs Navigation format
179
- Establish previous/next page relationships
180
- Set up parent-child navigation links
181
- Validate final navigation structure
182

183
## Advanced Features
184

185
### Title Resolution
186
The system intelligently resolves page titles using this priority order:
187
1. Custom title from `.pages` nav configuration
188
2. Existing navigation item title
189
3. Page metadata title from frontmatter
190
4. Extracted markdown heading title
191
5. Filename-based fallback with formatting
192

193
### Section Collapsing Rules
194
- Plugin-level `collapse_single_pages` setting
195
- Directory-level `.pages` override with `collapse_single_pages`
196
- Per-section `collapse` setting in `.pages`
197
- Automatic collapsing of single-child sections
198

199
### Error Handling and Warnings
200
- Strict mode raises exceptions for missing navigation entries
201
- Non-strict mode shows warnings and continues processing
202
- Context-aware error messages with file paths
203
- Plugin ordering warnings for potential conflicts