0
# Template and Context Management
1
2
Template processing functionality that manages Jinja2 template rendering, asset injection, and HTML context preparation for each page during the Sphinx build process.
3
4
## Capabilities
5
6
### Template Processing
7
8
Updates template names and manages assets for each page during the build process.
9
10
```python { .api }
11
def update_and_remove_templates(
12
app: Sphinx, pagename: str, templatename: str, context, doctree
13
) -> None:
14
"""
15
Update template names and assets for page build.
16
17
This function processes templates for various theme sections:
18
- Navigation bar sections (start, center, persistent, end)
19
- Article header and footer sections
20
- Content footer items
21
- Primary and secondary sidebar sections
22
- Removes duplicate CSS files
23
- Adds favicon links to page headers
24
- Injects JavaScript variables for theme functionality
25
26
Parameters:
27
- app (Sphinx): Sphinx application instance
28
- pagename (str): Name of the current page being processed
29
- templatename (str): Name of the template being used
30
- context: Template context dictionary with page variables
31
- doctree: Document tree for the current page
32
"""
33
```
34
35
### Canonical URL Fixing
36
37
Fixes canonical URLs when using Sphinx's directory HTML builder.
38
39
```python { .api }
40
def _fix_canonical_url(
41
app: Sphinx, pagename: str, templatename: str, context: dict, doctree
42
) -> None:
43
"""
44
Fix the canonical URL when using the dirhtml builder.
45
46
Sphinx builds incorrect canonical URLs ending with ".html" when using
47
the dirhtml builder. This function detects and corrects the URL for
48
each page.
49
50
Parameters:
51
- app (Sphinx): Sphinx application instance
52
- pagename (str): Name of the current page
53
- templatename (str): Template being used
54
- context (dict): Page context with URL information
55
- doctree: Document tree for the page
56
"""
57
```
58
59
## Template Sections
60
61
The theme supports customizable template sections:
62
63
### Navigation Bar Templates
64
- `theme_navbar_start`: Left side of navigation bar
65
- `theme_navbar_center`: Center of navigation bar
66
- `theme_navbar_persistent`: Always visible navigation elements
67
- `theme_navbar_end`: Right side of navigation bar
68
69
### Article Templates
70
- `theme_article_header_start`: Beginning of article header
71
- `theme_article_header_end`: End of article header
72
- `theme_article_footer_items`: Article footer elements
73
74
### Content Templates
75
- `theme_content_footer_items`: Content area footer elements
76
77
### Footer Templates
78
- `theme_footer_start`: Left side of page footer
79
- `theme_footer_center`: Center of page footer
80
- `theme_footer_end`: Right side of page footer
81
82
### Sidebar Templates
83
- `theme_primary_sidebar_end`: End of primary sidebar
84
- `sidebars`: General sidebar configuration
85
86
## Usage Examples
87
88
### Custom Navigation Bar
89
90
```python
91
# conf.py
92
html_theme_options = {
93
"navbar_start": ["navbar-logo"],
94
"navbar_center": ["navbar-nav", "search-field"],
95
"navbar_end": ["navbar-icon-links"],
96
"navbar_persistent": ["search-button"]
97
}
98
```
99
100
### Custom Article Layout
101
102
```python
103
# conf.py
104
html_theme_options = {
105
"article_header_start": ["breadcrumbs"],
106
"article_header_end": ["edit-this-page"],
107
"article_footer_items": ["prev-next", "show-source"]
108
}
109
```
110
111
### Sidebar Configuration
112
113
```python
114
# conf.py
115
html_theme_options = {
116
"primary_sidebar_end": ["custom-sidebar.html"],
117
"secondary_sidebar_items": ["page-toc", "edit-this-page"]
118
}
119
120
# Page-specific sidebar configuration
121
html_theme_options = {
122
"secondary_sidebar_items": {
123
"index": ["search-field"],
124
"user-guide/**": ["page-toc", "edit-this-page"],
125
"api/**": ["page-toc"]
126
}
127
}
128
```
129
130
### Favicon Configuration
131
132
```python
133
# conf.py
134
html_theme_options = {
135
"favicons": [
136
{
137
"rel": "icon",
138
"sizes": "16x16",
139
"href": "favicon-16x16.png",
140
},
141
{
142
"rel": "icon",
143
"sizes": "32x32",
144
"href": "favicon-32x32.png",
145
},
146
{
147
"rel": "apple-touch-icon",
148
"sizes": "180x180",
149
"href": "apple-touch-icon-180x180.png"
150
},
151
{
152
"rel": "mask-icon",
153
"href": "safari-pinned-tab.svg",
154
"color": "#5bbad5"
155
}
156
]
157
}
158
```
159
160
### Theme Switcher Integration
161
162
```python
163
# conf.py - Theme switcher with version matching
164
html_theme_options = {
165
"switcher": {
166
"json_url": "https://myproject.org/en/switcher.json",
167
"version_match": "v1.0.0"
168
},
169
"show_version_warning_banner": True
170
}
171
```
172
173
The switcher JSON format:
174
```json
175
[
176
{
177
"name": "v1.0 (stable)",
178
"version": "v1.0.0",
179
"url": "https://myproject.org/en/v1.0/"
180
},
181
{
182
"name": "v1.1 (latest)",
183
"version": "v1.1.0",
184
"url": "https://myproject.org/en/latest/"
185
}
186
]
187
```
188
189
## Asset Management
190
191
The template system automatically:
192
193
- Removes duplicate CSS files to prevent conflicts
194
- Adds favicons with proper type and size attributes
195
- Injects JavaScript variables for theme functionality
196
- Manages version information for theme switcher
197
- Handles theme-specific CSS and JavaScript assets
198
199
## Context Variables
200
201
The template system injects several variables into the page context:
202
203
- `theme_version`: Current theme version
204
- `pagename`: Current page name for JavaScript
205
- `theme_switcher_*`: Version switcher configuration
206
- `show_version_warning_banner`: Whether to show version warnings
207
- Theme-specific template lists for each customizable section