0
# Theme Configuration
1

2
Comprehensive configuration system with 19 options controlling navigation behavior, styling, and responsive design features.
3

4
## Configuration Usage
5

6
Set options in your Sphinx `conf.py`:
7

8
```python
9
html_theme_options = {
10
    'collapse_navigation': True,
11
    'sticky_navigation': True,
12
    'navigation_depth': 4,
13
    'includehidden': True,
14
    'titles_only': False,
15
    'logo_only': False,
16
    'prev_next_buttons_location': 'bottom',
17
    'style_external_links': False,
18
    'style_nav_header_background': '',
19
    'vcs_pageview_mode': '',
20
    'flyout_display': 'hidden',
21
    'version_selector': True,
22
    'language_selector': True
23
}
24
```
25

26
## Configuration Options
27

28
### Navigation Behavior
29

30
#### collapse_navigation
31

32
```python { .api }
33
'collapse_navigation': bool  # Default: True
34
```
35

36
Controls whether navigation menu items are collapsed by default. When `True`, only the current page's section is expanded, keeping the sidebar compact. When `False`, all navigation sections remain expanded.
37

38
#### sticky_navigation
39

40
```python { .api }
41
'sticky_navigation': bool  # Default: True
42
```
43

44
Enables sticky navigation behavior where the sidebar follows the user's scroll position. When `True`, the navigation stays visible as users scroll through long pages.
45

46
#### navigation_depth
47

48
```python { .api }
49
'navigation_depth': int  # Default: 4
50
```
51

52
Sets the maximum depth of navigation tree to display in the sidebar. Deeper nested pages will not appear in the navigation menu.
53

54
#### includehidden
55

56
```python { .api }
57
'includehidden': bool  # Default: True
58
```
59

60
Whether to include hidden toctree entries in the navigation. When `True`, pages marked as hidden in the toctree directive will still appear in the sidebar.
61

62
#### titles_only
63

64
```python { .api }
65
'titles_only': bool  # Default: False
66
```
67

68
When `True`, displays only page titles in navigation without showing subsection headers within each page.
69

70
### Visual Appearance
71

72
#### logo_only
73

74
```python { .api }
75
'logo_only': bool  # Default: False
76
```
77

78
When `True`, displays only the logo in the navigation header without the project title text.
79

80
#### style_external_links
81

82
```python { .api }
83
'style_external_links': bool  # Default: False
84
```
85

86
When `True`, applies special styling to external links to distinguish them from internal links.
87

88
#### style_nav_header_background
89

90
```python { .api }
91
'style_nav_header_background': str  # Default: ''
92
```
93

94
Custom CSS styling for the navigation header background. Accepts any valid CSS background property value.
95

96
### Page Navigation
97

98
#### prev_next_buttons_location
99

100
```python { .api }
101
'prev_next_buttons_location': str  # Default: 'bottom'
102
```
103

104
Controls placement of previous/next page navigation buttons. Valid values:
105
- `'bottom'`: At the bottom of the page content
106
- `'top'`: At the top of the page content  
107
- `'both'`: At both top and bottom
108
- `'none'`: Hide prev/next buttons
109

110
### Version and Language Controls
111

112
#### version_selector
113

114
```python { .api }
115
'version_selector': bool  # Default: True
116
```
117

118
Shows version selector dropdown in the navigation when multiple versions are available (typically in Read the Docs environment).
119

120
#### language_selector
121

122
```python { .api }
123
'language_selector': bool  # Default: True
124
```
125

126
Shows language selector dropdown in the navigation when multiple languages are available (typically in Read the Docs environment).
127

128
#### flyout_display
129

130
```python { .api }
131
'flyout_display': str  # Default: 'hidden'
132
```
133

134
Controls the display behavior of the flyout menu for versions and languages. Valid values:
135
- `'hidden'`: Hide flyout menu by default
136
- `'attached'`: Show flyout menu attached to navigation
137
- `'floating'`: Show flyout menu as floating element
138

139
### Version Control Integration
140

141
#### vcs_pageview_mode
142

143
```python { .api }
144
'vcs_pageview_mode': str  # Default: ''
145
```
146

147
Sets the version control page view mode for Read the Docs integration. This affects how edit/view source links are generated.
148

149
## Deprecated Options
150

151
The following options are deprecated and will generate warnings:
152

153
### canonical_url (Deprecated)
154

155
```python { .api }
156
'canonical_url': str  # DEPRECATED
157
```
158

159
**Replacement**: Use Sphinx's built-in `html_baseurl` configuration option instead.
160

161
**Warning**: "The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead."
162

163
### analytics_id (Deprecated)
164

165
```python { .api }
166
'analytics_id': str  # DEPRECATED
167
```
168

169
**Replacement**: Use the `sphinxcontrib-googleanalytics` extension instead.
170

171
**Warning**: "The analytics_id option is deprecated, use the sphinxcontrib-googleanalytics extension instead."
172

173
### analytics_anonymize_ip (Deprecated)
174

175
```python { .api }
176
'analytics_anonymize_ip': bool  # DEPRECATED
177
```
178

179
**Replacement**: Use the `sphinxcontrib-googleanalytics` extension instead.
180

181
**Warning**: "The analytics_anonymize_ip option is deprecated, use the sphinxcontrib-googleanalytics extension instead."
182

183
## Theme Configuration File
184

185
The theme inherits from Sphinx's basic theme with the following configuration:
186

187
```ini { .api }
188
[theme]
189
inherit = basic
190
stylesheet = css/theme.css
191
pygments_style = default
192

193
[options]
194
# All 19 configuration options with their defaults
195
canonical_url =
196
analytics_id =
197
analytics_anonymize_ip = False
198
collapse_navigation = True
199
sticky_navigation = True
200
navigation_depth = 4
201
includehidden = True
202
titles_only =
203
logo_only =
204
prev_next_buttons_location = bottom
205
style_external_links = False
206
style_nav_header_background =
207
vcs_pageview_mode =
208
flyout_display = hidden
209
version_selector = True
210
language_selector = True
211
```
212

213
## Usage Examples
214

215
### Minimal Configuration
216

217
```python
218
# Basic responsive theme with defaults
219
html_theme = 'sphinx_rtd_theme'
220
```
221

222
### Custom Navigation
223

224
```python
225
html_theme_options = {
226
    'collapse_navigation': False,  # Keep all sections expanded
227
    'navigation_depth': 2,         # Show only 2 levels deep
228
    'titles_only': True,           # Show only page titles
229
    'prev_next_buttons_location': 'both'  # Buttons top and bottom
230
}
231
```
232

233
### Branding Customization
234

235
```python
236
html_theme_options = {
237
    'logo_only': True,  # Show only logo, not project title
238
    'style_nav_header_background': '#2c3e50',  # Custom header color
239
    'style_external_links': True   # Highlight external links
240
}
241
```
242

243
### Read the Docs Integration
244

245
```python
246
html_theme_options = {
247
    'version_selector': True,      # Show version dropdown
248
    'language_selector': True,     # Show language dropdown
249
    'flyout_display': 'attached',  # Attach flyout to nav
250
    'vcs_pageview_mode': 'edit'    # Show edit links
251
}
252
```
253

254
### Mobile-Optimized
255

256
```python
257
html_theme_options = {
258
    'sticky_navigation': True,     # Keep nav visible on mobile
259
    'collapse_navigation': True,   # Compact navigation
260
    'navigation_depth': 3,         # Limit depth for mobile
261
    'titles_only': False          # Show subsections for context
262
}
263
```