0
# Settings and Configuration
1

2
Configuration system providing default settings, file-based configuration loading, and runtime setting management for all aspects of site generation including paths, URLs, themes, and plugin behavior.
3

4
## Capabilities
5

6
### Settings Loading
7

8
Functions for loading and managing Pelican configuration from files and runtime overrides.
9

10
```python { .api }
11
def read_settings(path: str = None, override: dict = None) -> dict:
12
    """
13
    Load settings from configuration file with optional overrides.
14
    
15
    Parameters:
16
    - path (str, optional): Path to settings file (defaults to pelicanconf.py in current directory)
17
    - override (dict, optional): Dictionary of settings to override loaded values
18
    
19
    Returns:
20
    dict: Complete settings dictionary with defaults, file settings, and overrides merged
21
    """
22

23
def load_source(name: str, path: str) -> ModuleType:
24
    """
25
    Load Python module from file path.
26
    
27
    Parameters:
28
    - name (str): Module name for import system
29
    - path (str): File path to Python module
30
    
31
    Returns:
32
    ModuleType: Loaded Python module object
33
    """
34
```
35

36
### Settings Types
37

38
Type definitions and constants for configuration management.
39

40
```python { .api }
41
Settings = dict[str, Any]  # Type alias for settings dictionary
42

43
DEFAULT_CONFIG: dict  # Default configuration dictionary with all standard settings
44
DEFAULT_THEME: str    # Path to default theme directory
45
```
46

47
## Core Configuration Categories
48

49
### Content and Path Settings
50

51
Configure content source paths, organization, and file handling:
52

53
```python
54
# Content source paths
55
PATH = 'content'                    # Main content directory
56
ARTICLE_PATHS = ['']               # Article subdirectories (relative to PATH)
57
ARTICLE_EXCLUDES = []              # Exclude patterns for articles
58
PAGE_PATHS = ['pages']             # Page subdirectories
59
PAGE_EXCLUDES = []                 # Exclude patterns for pages
60
STATIC_PATHS = ['images']          # Static file subdirectories
61
STATIC_EXCLUDES = []               # Exclude patterns for static files
62
IGNORE_FILES = ['.#*']             # Global ignore patterns
63
```
64

65
### Output and URL Settings
66

67
Configure output paths and URL structure:
68

69
```python
70
# Output configuration
71
OUTPUT_PATH = 'output'             # Output directory
72
DELETE_OUTPUT_DIRECTORY = False    # Clean output before generation
73
OUTPUT_RETENTION = []              # Files to retain when cleaning
74

75
# URL patterns for articles
76
ARTICLE_URL = '{slug}.html'
77
ARTICLE_SAVE_AS = '{slug}.html'
78
ARTICLE_LANG_URL = '{slug}-{lang}.html'
79
ARTICLE_LANG_SAVE_AS = '{slug}-{lang}.html'
80

81
# URL patterns for pages
82
PAGE_URL = 'pages/{slug}.html'
83
PAGE_SAVE_AS = 'pages/{slug}.html'
84
PAGE_LANG_URL = 'pages/{slug}-{lang}.html'
85
PAGE_LANG_SAVE_AS = 'pages/{slug}-{lang}.html'
86

87
# URL patterns for categories, tags, authors
88
CATEGORY_URL = 'category/{slug}.html'
89
CATEGORY_SAVE_AS = 'category/{slug}.html'
90
TAG_URL = 'tag/{slug}.html'
91
TAG_SAVE_AS = 'tag/{slug}.html'
92
AUTHOR_URL = 'author/{slug}.html'
93
AUTHOR_SAVE_AS = 'author/{slug}.html'
94

95
# Archive URL patterns
96
YEAR_ARCHIVE_URL = ''              # Year archive URL pattern
97
MONTH_ARCHIVE_URL = ''             # Month archive URL pattern
98
DAY_ARCHIVE_URL = ''               # Day archive URL pattern
99
```
100

101
### Site Information
102

103
Basic site metadata and branding:
104

105
```python
106
SITENAME = 'A Pelican Blog'        # Site title
107
SITEURL = ''                       # Site base URL (for absolute URLs)
108
AUTHOR = ''                        # Default author name
109
DEFAULT_LANG = 'en'                # Default content language
110
TIMEZONE = 'UTC'                   # Site timezone
111
```
112

113
### Theme and Template Settings
114

115
Configure theming and template rendering:
116

117
```python
118
THEME = DEFAULT_THEME              # Theme directory path
119
THEME_STATIC_DIR = 'theme'         # Theme static files directory name
120
THEME_STATIC_PATHS = ['static']    # Theme static source directories
121
THEME_TEMPLATES_OVERRIDES = []     # Additional template directories
122

123
# Template configuration
124
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives']
125
TEMPLATE_PAGES = {}                # Custom template pages
126
PAGINATED_TEMPLATES = {            # Templates with pagination
127
    'index': None,
128
    'tag': None,
129
    'category': None,
130
    'author': None,
131
}
132

133
# Jinja2 environment settings
134
JINJA_ENVIRONMENT = {
135
    'trim_blocks': True,
136
    'lstrip_blocks': True,
137
    'extensions': [],
138
}
139
JINJA_FILTERS = {}                 # Custom Jinja2 filters
140
JINJA_GLOBALS = {}                 # Custom Jinja2 global variables
141
JINJA_TESTS = {}                   # Custom Jinja2 tests
142
```
143

144
### Feed Settings
145

146
Configure RSS/Atom feed generation:
147

148
```python
149
FEED_ALL_ATOM = 'feeds/all.atom.xml'      # Main Atom feed
150
FEED_ALL_RSS = None                        # Main RSS feed (disabled by default)
151
CATEGORY_FEED_ATOM = 'feeds/{slug}.atom.xml'  # Category-specific Atom feeds
152
CATEGORY_FEED_RSS = None                   # Category-specific RSS feeds
153
AUTHOR_FEED_ATOM = 'feeds/{slug}.atom.xml'    # Author-specific Atom feeds
154
AUTHOR_FEED_RSS = 'feeds/{slug}.rss.xml'      # Author-specific RSS feeds
155
TRANSLATION_FEED_ATOM = 'feeds/all-{lang}.atom.xml'  # Translation feeds
156
FEED_MAX_ITEMS = 100                       # Maximum items per feed
157
RSS_FEED_SUMMARY_ONLY = True              # Include only summary in RSS
158
FEED_APPEND_REF = False                    # Append reference links to feeds
159
```
160

161
### Pagination Settings
162

163
Configure content pagination:
164

165
```python
166
DEFAULT_PAGINATION = False         # Number of items per page (False = no pagination)
167
DEFAULT_ORPHANS = 0               # Minimum items on last page
168
PAGINATION_PATTERNS = [            # URL patterns for paginated pages
169
    (1, '{name}{extension}', '{name}{extension}'),
170
    (2, '{name}{number}{extension}', '{name}{number}{extension}'),
171
]
172
```
173

174
### Markup Processing Settings
175

176
Configure content processing for different markup formats:
177

178
```python
179
# Markdown configuration
180
MARKDOWN = {
181
    'extension_configs': {
182
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
183
        'markdown.extensions.extra': {},
184
        'markdown.extensions.meta': {},
185
    },
186
    'output_format': 'html5',
187
}
188

189
# reStructuredText configuration
190
DOCUTILS_SETTINGS = {}            # Custom docutils settings
191

192
# Plugin configuration
193
PLUGINS = []                      # List of enabled plugins
194
PLUGIN_PATHS = []                 # Additional plugin search paths
195
```
196

197
### Caching and Performance
198

199
Configure caching and performance optimization:
200

201
```python
202
CACHE_CONTENT = False             # Enable content caching
203
CACHE_PATH = 'cache'              # Cache directory path
204
LOAD_CONTENT_CACHE = True         # Load existing cache on startup
205
CHECK_MODIFIED_METHOD = 'mtime'   # Method for checking file modifications
206
CONTENT_CACHING_LAYER = 'reader'  # Caching layer (reader or generator)
207
```
208

209
### Development Settings
210

211
Settings for development workflow:
212

213
```python
214
RELATIVE_URLS = False             # Use relative URLs (useful for development)
215
BIND = '127.0.0.1'               # Development server bind address
216
PORT = 8000                      # Development server port
217
```
218

219
## Usage Examples
220

221
### Basic Configuration File
222

223
```python
224
# pelicanconf.py - Basic site configuration
225
AUTHOR = 'John Doe'
226
SITENAME = 'My Personal Blog'
227
SITEURL = 'https://example.com'
228

229
PATH = 'content'
230
OUTPUT_PATH = 'output'
231

232
TIMEZONE = 'America/New_York'
233
DEFAULT_LANG = 'en'
234

235
# Feed generation
236
FEED_ALL_ATOM = 'feeds/all.atom.xml'
237
CATEGORY_FEED_ATOM = 'feeds/{slug}.atom.xml'
238

239
# Pagination
240
DEFAULT_PAGINATION = 10
241

242
# Theme
243
THEME = 'themes/my-custom-theme'
244

245
# Static paths
246
STATIC_PATHS = ['images', 'extra/CNAME']
247
EXTRA_PATH_METADATA = {
248
    'extra/CNAME': {'path': 'CNAME'},
249
}
250
```
251

252
### Loading Settings Programmatically
253

254
```python
255
from pelican.settings import read_settings
256

257
# Load default settings file
258
settings = read_settings()  # Looks for pelicanconf.py
259

260
# Load specific settings file
261
settings = read_settings('mysite.conf')
262

263
# Load with overrides
264
settings = read_settings('pelicanconf.py', override={
265
    'OUTPUT_PATH': 'dist',
266
    'SITEURL': 'https://staging.example.com'
267
})
268

269
# Access settings
270
print(settings['SITENAME'])
271
print(settings['OUTPUT_PATH'])
272
```
273

274
### Advanced Configuration
275

276
```python
277
# pelicanconf.py - Advanced configuration
278
import os
279

280
# Site information
281
AUTHOR = 'Jane Smith'
282
SITENAME = 'Tech Blog'
283
SITEURL = 'https://techblog.example.com'
284
SITESUBTITLE = 'Thoughts on technology and programming'
285

286
# Content organization
287
PATH = 'content'
288
ARTICLE_PATHS = ['posts']
289
PAGE_PATHS = ['pages']
290
STATIC_PATHS = ['images', 'files', 'extra']
291

292
# URL structure
293
ARTICLE_URL = '{date:%Y}/{date:%m}/{slug}/'
294
ARTICLE_SAVE_AS = '{date:%Y}/{date:%m}/{slug}/index.html'
295
PAGE_URL = '{slug}/'
296
PAGE_SAVE_AS = '{slug}/index.html'
297

298
# Custom pagination
299
DEFAULT_PAGINATION = 5
300
PAGINATION_PATTERNS = [
301
    (1, '{name}/', '{name}/index.html'),
302
    (2, '{name}/page/{number}/', '{name}/page/{number}/index.html'),
303
]
304

305
# Markdown configuration
306
MARKDOWN = {
307
    'extension_configs': {
308
        'markdown.extensions.codehilite': {
309
            'css_class': 'highlight',
310
            'use_pygments': True,
311
        },
312
        'markdown.extensions.extra': {},
313
        'markdown.extensions.meta': {},
314
        'markdown.extensions.toc': {
315
            'permalink': True,
316
            'title': 'Table of Contents'
317
        },
318
    },
319
    'output_format': 'html5',
320
}
321

322
# Plugin configuration
323
PLUGINS = ['pelican-seo', 'sitemap', 'related_posts']
324
PLUGIN_PATHS = ['plugins']
325

326
# Custom Jinja2 filters
327
def format_date(date):
328
    return date.strftime('%B %d, %Y')
329

330
JINJA_FILTERS = {
331
    'format_date': format_date,
332
}
333

334
# Environment-specific settings
335
if os.environ.get('PELICAN_ENV') == 'production':
336
    SITEURL = 'https://techblog.example.com'
337
    RELATIVE_URLS = False
338
    DELETE_OUTPUT_DIRECTORY = True
339
else:
340
    SITEURL = 'http://localhost:8000'
341
    RELATIVE_URLS = True
342
    DELETE_OUTPUT_DIRECTORY = False
343
```
344

345
### Settings Validation and Access
346

347
```python
348
from pelican.settings import read_settings, DEFAULT_CONFIG
349

350
# Load settings with validation
351
def validate_settings(settings):
352
    """Validate required settings."""
353
    required = ['SITENAME', 'AUTHOR', 'PATH']
354
    for key in required:
355
        if not settings.get(key):
356
            raise ValueError(f"Required setting {key} is missing")
357
    return settings
358

359
# Load and validate settings
360
settings = read_settings('pelicanconf.py')
361
settings = validate_settings(settings)
362

363
# Safe setting access with defaults
364
def get_setting(settings, key, default=None):
365
    """Get setting with fallback to default."""
366
    return settings.get(key, DEFAULT_CONFIG.get(key, default))
367

368
# Use in generator or plugin
369
site_name = get_setting(settings, 'SITENAME', 'Unknown Site')
370
pagination = get_setting(settings, 'DEFAULT_PAGINATION', False)
371
```
372

373
### Dynamic Configuration
374

375
```python
376
# pelicanconf.py - Dynamic configuration based on content
377
import os
378
from pathlib import Path
379

380
# Dynamic path detection
381
content_dir = Path('content')
382
if content_dir.exists():
383
    # Discover article subdirectories
384
    ARTICLE_PATHS = [
385
        str(p.relative_to(content_dir)) 
386
        for p in content_dir.iterdir() 
387
        if p.is_dir() and not p.name.startswith('.')
388
    ]
389
else:
390
    ARTICLE_PATHS = ['']
391

392
# Dynamic plugin loading
393
available_plugins = []
394
plugin_dir = Path('plugins')
395
if plugin_dir.exists():
396
    available_plugins = [
397
        p.name for p in plugin_dir.iterdir() 
398
        if p.is_dir() and (p / '__init__.py').exists()
399
    ]
400

401
PLUGINS = available_plugins
402

403
# Environment-based configuration
404
class Config:
405
    """Configuration class for different environments."""
406
    
407
    # Base configuration
408
    SITENAME = 'My Blog'
409
    AUTHOR = 'Author Name'
410
    PATH = 'content'
411
    
412
    @classmethod
413
    def development(cls):
414
        """Development environment settings."""
415
        return {
416
            'SITEURL': 'http://localhost:8000',
417
            'RELATIVE_URLS': True,
418
            'DELETE_OUTPUT_DIRECTORY': False,
419
            'DEBUG': True,
420
        }
421
    
422
    @classmethod
423
    def production(cls):
424
        """Production environment settings."""
425
        return {
426
            'SITEURL': 'https://example.com',
427
            'RELATIVE_URLS': False,
428
            'DELETE_OUTPUT_DIRECTORY': True,
429
            'DEBUG': False,
430
        }
431

432
# Apply environment-specific settings
433
env = os.environ.get('PELICAN_ENV', 'development')
434
if env == 'production':
435
    globals().update(Config.production())
436
else:
437
    globals().update(Config.development())
438
```