0
# Pages Configuration
1

2
Meta configuration system for `.pages` files that control navigation structure, ordering, and appearance at the directory level. These YAML configuration files are placed in documentation directories to customize how that directory's content appears in navigation.
3

4
## Capabilities
5

6
### Meta Configuration Class
7

8
The core class that represents parsed `.pages` file configuration with validation and loading capabilities.
9

10
```python { .api }
11
class Meta:
12
    """
13
    Represents .pages file configuration and metadata.
14
    
15
    Class Attributes:
16
        TITLE_ATTRIBUTE: str = 'title'
17
        NAV_ATTRIBUTE: str = 'nav'
18
        ARRANGE_ATTRIBUTE: str = 'arrange'
19
        ARRANGE_REST_TOKEN: str = '...'
20
        COLLAPSE_ATTRIBUTE: str = 'collapse'
21
        COLLAPSE_SINGLE_PAGES_ATTRIBUTE: str = 'collapse_single_pages'
22
        HIDE_ATTRIBUTE: str = 'hide'
23
        IGNORE_CASE_ATTRIBUTE: str = 'ignore_case'
24
        ORDER_ATTRIBUTE: str = 'order'
25
        SORT_TYPE_ATTRIBUTE: str = 'sort_type'
26
        ORDER_BY_ATTRIBUTE: str = 'order_by'
27
        ORDER_ASC: str = 'asc'
28
        ORDER_DESC: str = 'desc'
29
        SORT_NATURAL: str = 'natural'
30
        ORDER_BY_FILENAME: str = 'filename'
31
        ORDER_BY_TITLE: str = 'title'
32
    
33
    Args:
34
        title (str, optional): Custom title for the section
35
        arrange (List[str], optional): Simple page ordering (deprecated, use nav)
36
        nav (List[MetaNavItem], optional): Navigation structure definition
37
        path (str, optional): Path to the configuration file
38
        collapse (bool, optional): Collapse single-page sections locally
39
        collapse_single_pages (bool, optional): Override plugin setting
40
        hide (bool, optional): Hide this section from navigation
41
        ignore_case (bool, optional): Case-insensitive sorting locally
42
        order (str, optional): Local sort order ('asc' or 'desc')
43
        sort_type (str, optional): Local sort algorithm ('natural')
44
        order_by (str, optional): Local sort attribute ('filename' or 'title')
45
    """
46
    
47
    def __init__(
48
        self, *, title: str = None, arrange: List[str] = None,
49
        nav: List[MetaNavItem] = None, path: str = None,
50
        collapse: bool = None, collapse_single_pages: bool = None,
51
        hide: bool = None, ignore_case: bool = None,
52
        order: str = None, sort_type: str = None, order_by: str = None
53
    ): ...
54
    
55
    @staticmethod
56
    def load_from(path: str) -> "Meta":
57
        """
58
        Load metadata from a .pages file path.
59
        
60
        Args:
61
            path (str): Absolute path to .pages file
62
            
63
        Returns:
64
            Meta: Parsed configuration object
65
            
66
        Raises:
67
            FileNotFoundError: If file doesn't exist
68
            TypeError: If configuration format is invalid
69
            DuplicateRestItemError: If duplicate rest entries found
70
        """
71
    
72
    @staticmethod
73
    def try_load_from_files(rel_path: str, files: Files) -> "Meta":
74
        """
75
        Try to load metadata from Files collection.
76
        
77
        Args:
78
            rel_path (str, optional): Relative path to .pages file
79
            files (Files): MkDocs Files collection
80
            
81
        Returns:
82
            Meta: Parsed configuration or empty Meta if not found
83
        """
84
```
85

86
### Navigation Item Classes
87

88
Classes that represent different types of navigation items parsed from `.pages` configurations.
89

90
```python { .api }
91
class MetaNavItem:
92
    """
93
    Represents a navigation item from .pages configuration.
94
    
95
    Args:
96
        value (Union[str, List[MetaNavItem]]): File/directory name or nested items
97
        title (str, optional): Custom title for the navigation entry
98
    """
99
    
100
    def __init__(self, value: Union[str, List["MetaNavItem"]], title: str = None): ...
101
    
102
    def __eq__(self, other: object) -> bool:
103
        """Equality comparison for navigation items."""
104
    
105
    def __hash__(self) -> int:
106
        """Hash implementation for set/dict usage."""
107
    
108
    @staticmethod
109
    def from_yaml(item: Union[str, dict], context: str) -> "MetaNavItem":
110
        """
111
        Create navigation item from YAML data.
112
        
113
        Args:
114
            item (Union[str, dict]): YAML item (string or title: value dict)
115
            context (str): Context path for error reporting
116
            
117
        Returns:
118
            MetaNavItem: Parsed navigation item
119
            
120
        Raises:
121
            TypeError: If item format is invalid
122
        """
123
```
124

125
### Exception Handling
126

127
Exception classes for configuration validation and error handling.
128

129
```python { .api }
130
class DuplicateRestItemError(Exception):
131
    """
132
    Raised when duplicate rest entries are found in configuration.
133
    
134
    Args:
135
        item (str): The duplicate rest entry value
136
        context (str): Context path where duplicate was found
137
    """
138
    
139
    def __init__(self, item: str, context: str): ...
140
```
141

142
### Usage Examples
143

144
Basic `.pages` file with navigation ordering:
145

146
```yaml
147
# .pages
148
nav:
149
  - introduction.md
150
  - ...  # Include all other files here
151
  - conclusion.md
152
```
153

154
Advanced `.pages` file with all options:
155

156
```yaml
157
# .pages
158
title: "API Documentation"
159

160
nav:
161
  - Overview: introduction.md
162
  - Getting Started: setup.md
163
  - ... | flat | glob=tutorial-*.md  # Filtered rest entries
164
  - ...  # Remaining files
165
  - FAQ: faq.md
166

167
# Sorting and display options
168
order: asc
169
sort_type: natural
170
order_by: title
171
ignore_case: true
172

173
# Section behavior
174
collapse: false
175
collapse_single_pages: true
176
hide: false
177
```
178

179
Navigation item types:
180

181
```yaml
182
nav:
183
  # Simple file reference
184
  - simple-file.md
185
  
186
  # File with custom title
187
  - Custom Title: some-file.md
188
  
189
  # External link
190
  - External Link: https://example.com
191
  
192
  # Nested section
193
  - Section Name:
194
    - nested-file.md
195
    - Another File: another-nested.md
196
  
197
  # Rest entries with patterns
198
  - ...  # All remaining files
199
  - ... | flat  # Flatten nested structure
200
  - ... | glob=api-*.md  # Only files matching pattern
201
  - ... | regex=test.*\.md  # Files matching regex
202
```
203

204
Configuration attribute effects:
205

206
```yaml
207
# Title override
208
title: "Custom Section Name"  # Overrides directory name
209

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

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

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

224
## Configuration Validation
225

226
The Meta class performs comprehensive validation on loaded configurations:
227

228
- **Type checking**: All attributes must be correct types (bool, str, list)
229
- **Value validation**: Enum values like order must be 'asc' or 'desc'
230
- **Structure validation**: Nav items must follow proper YAML structure
231
- **Duplicate detection**: Rest entries cannot be duplicated within same config
232
- **Context tracking**: All errors include file path context for debugging