0
# Logo and Branding Management
1

2
Logo handling system that supports light/dark theme variants, custom logo positioning, and automatic asset copying to the build output directory.
3

4
## Capabilities
5

6
### Logo Path Setup
7

8
Sets up relative paths to logo images in HTML templates for proper display.
9

10
```python { .api }
11
def setup_logo_path(
12
    app: Sphinx, pagename: str, templatename: str, context: dict, doctree: Node
13
) -> None:
14
    """
15
    Set up relative paths to logos in our HTML templates.
16
    
17
    Processes logo configuration to create relative paths for light and dark
18
    theme variants. Handles both URL-based logos and local file logos,
19
    ensuring proper path resolution for the current page.
20
    
21
    Parameters:
22
    - app (Sphinx): Sphinx application instance
23
    - pagename (str): Name of the current page
24
    - templatename (str): Template being used
25
    - context (dict): Template context dictionary  
26
    - doctree (Node): Document tree for the page
27
    
28
    Updates context with theme_logo containing image_relative paths for
29
    light and dark logo variants.
30
    """
31
```
32

33
### Logo Asset Management
34

35
Copies logo images to the build output directory for proper serving.
36

37
```python { .api }
38
def copy_logo_images(app: Sphinx, exception=None) -> None:
39
    """
40
    Copy logo image to the _static directory.
41
    
42
    Processes logo configuration and copies local image files to the
43
    build output's _static directory. Skips URL-based logos and handles
44
    security validation to prevent template injection.
45
    
46
    Parameters:
47
    - app (Sphinx): Sphinx application instance
48
    - exception: Build exception (if any) - function exits early if present
49
    
50
    Raises:
51
    - ExtensionError: If logo path appears to be a Sphinx template
52
    """
53
```
54

55
## Configuration
56

57
### Basic Logo Setup
58

59
```python
60
# conf.py
61
html_theme_options = {
62
    "logo": {
63
        "text": "My Project"  # Text-only logo
64
    }
65
}
66

67
# or use html_logo for simple cases
68
html_logo = "logo.png"
69
```
70

71
### Light/Dark Logo Variants
72

73
```python
74
# conf.py
75
html_theme_options = {
76
    "logo": {
77
        "image_light": "_static/logo-light.png",  # Logo for light theme
78
        "image_dark": "_static/logo-dark.png",    # Logo for dark theme
79
        "text": "My Project",                     # Alt text and fallback
80
        "link": "https://myproject.org"          # Logo click destination
81
    }
82
}
83
```
84

85
### Logo with URL Images
86

87
```python
88
# conf.py - Using external logo images
89
html_theme_options = {
90
    "logo": {
91
        "image_light": "https://cdn.mysite.com/logo-light.svg",
92
        "image_dark": "https://cdn.mysite.com/logo-dark.svg", 
93
        "text": "My Project",
94
        "link": "/"  # Relative link to home page
95
    }
96
}
97
```
98

99
### Mixed Configuration
100

101
```python
102
# conf.py - Local and URL logos
103
html_theme_options = {
104
    "logo": {
105
        "image_light": "_static/logo-light.png",           # Local file
106
        "image_dark": "https://cdn.mysite.com/dark.svg",   # URL
107
        "text": "My Project"
108
    }
109
}
110
```
111

112
## Logo Processing
113

114
### Path Resolution
115

116
The logo system processes images as follows:
117

118
1. **URL logos**: Used directly without modification
119
2. **Local logos**: Copied to `_static/` directory and paths updated
120
3. **Fallback**: Uses `html_logo` if no theme-specific logo provided
121

122
### Relative Path Generation
123

124
For each page, the system generates appropriate relative paths:
125

126
```python
127
# Generated paths in template context
128
theme_logo = {
129
    "image_relative": {
130
        "light": "../_static/logo-light.png",  # Relative to current page
131
        "dark": "../_static/logo-dark.png"
132
    },
133
    "text": "My Project",
134
    "link": "https://myproject.org"
135
}
136
```
137

138
## Usage Examples
139

140
### Comprehensive Logo Configuration
141

142
```python
143
# conf.py
144
html_theme_options = {
145
    "logo": {
146
        # Image variants
147
        "image_light": "images/logo-light.svg",
148
        "image_dark": "images/logo-dark.svg", 
149
        
150
        # Display text and link
151
        "text": "PyData Sphinx Theme",
152
        "link": "https://pydata-sphinx-theme.readthedocs.io",
153
    },
154
    
155
    # Additional branding 
156
    "show_nav_level": 1,
157
    "navbar_start": ["navbar-logo"],
158
    "navbar_align": "left"
159
}
160

161
# Ensure logo images are in _static or source directory
162
html_static_path = ['_static', 'images']
163
```
164

165
### Conditional Logo Display
166

167
```python
168
# conf.py - Different logos per section
169
import os
170

171
if os.getenv('BUILD_CONTEXT') == 'production':
172
    logo_config = {
173
        "image_light": "logos/prod-light.png", 
174
        "image_dark": "logos/prod-dark.png",
175
        "link": "https://prod.mysite.com"
176
    }
177
else:
178
    logo_config = {
179
        "image_light": "logos/dev-light.png",
180
        "image_dark": "logos/dev-dark.png", 
181
        "link": "https://dev.mysite.com"
182
    }
183

184
html_theme_options = {
185
    "logo": logo_config
186
}
187
```
188

189
### Logo with Custom Styling
190

191
```python
192
# conf.py - Logo configuration with custom CSS classes
193
html_theme_options = {
194
    "logo": {
195
        "image_light": "_static/logo.svg",
196
        "text": "My Project",
197
        "link": "/",
198
    }
199
}
200

201
# Custom CSS to style the logo
202
html_css_files = ['custom-logo.css']
203
```
204

205
```css
206
/* custom-logo.css */
207
.navbar-brand img {
208
    max-height: 40px;
209
    width: auto;
210
}
211

212
.navbar-brand {
213
    font-weight: bold;
214
    font-size: 1.2em;
215
}
216
```
217

218
### Favicon Integration
219

220
```python
221
# conf.py - Coordinate logos with favicons
222
html_theme_options = {
223
    "logo": {
224
        "image_light": "_static/logo-light.svg",
225
        "image_dark": "_static/logo-dark.svg",
226
    },
227
    "favicons": [
228
        {
229
            "rel": "icon",
230
            "sizes": "16x16", 
231
            "href": "favicon-16x16.png",
232
        },
233
        {
234
            "rel": "icon", 
235
            "sizes": "32x32",
236
            "href": "favicon-32x32.png",
237
        }
238
    ]
239
}
240
```
241

242
## Security Considerations
243

244
The logo system includes security protections:
245

246
- **Template injection prevention**: Paths ending with `_t` are rejected
247
- **Path validation**: Local paths are validated before copying
248
- **Asset isolation**: Logos are copied to the secure `_static` directory
249

250
## File Format Support
251

252
Supported logo formats:
253
- **SVG**: Recommended for scalability
254
- **PNG**: Good for detailed logos with transparency
255
- **JPG/JPEG**: Suitable for photographic logos
256
- **GIF**: Supported but not recommended for logos
257

258
## Error Handling
259

260
The system handles various error conditions:
261

262
- **Missing files**: Warnings logged, build continues
263
- **Invalid templates**: `ExtensionError` raised for security
264
- **Network failures**: URL logos fail gracefully
265
- **Path errors**: Warnings logged with helpful messages
266

267
## Template Context Variables
268

269
The logo system provides these template variables:
270

271
- `theme_logo.image_relative.light`: Relative path to light logo
272
- `theme_logo.image_relative.dark`: Relative path to dark logo  
273
- `theme_logo.text`: Logo text/alt text
274
- `theme_logo.link`: Logo click destination URL
275
- `logo` or `logo_url`: Sphinx's default logo (fallback)