0
# Main Application
1
2
Core Pelican application class and entry points for static site generation, providing the main orchestration logic, configuration management, and command-line interface.
3
4
## Capabilities
5
6
### Pelican Class
7
8
Main application class that coordinates the site generation process, managing generators, plugins, and output writing.
9
10
```python { .api }
11
class Pelican:
12
"""
13
Main Pelican application class for static site generation.
14
15
Parameters:
16
- settings (dict): Configuration dictionary containing all site settings
17
"""
18
def __init__(self, settings: dict): ...
19
20
def run(self) -> None:
21
"""
22
Execute the complete site generation process.
23
24
Runs all generators, processes content, applies themes, and writes output files.
25
"""
26
27
def init_path(self) -> None:
28
"""Initialize Python path for plugin and content discovery."""
29
30
def init_plugins(self) -> None:
31
"""Load and register enabled plugins."""
32
33
# Instance attributes available after initialization
34
settings: dict # Site configuration
35
path: str # Content source path
36
theme: str # Theme path
37
output_path: str # Output directory path
38
plugins: list # Loaded plugin instances
39
ignore_files: list # Files to ignore during processing
40
delete_outputdir: bool # Whether to clean output directory before generation
41
output_retention: list # Files to retain when cleaning output directory
42
```
43
44
### CLI Entry Points
45
46
Main command-line interface functions for running Pelican from the command line.
47
48
```python { .api }
49
def main(argv=None) -> None:
50
"""
51
Main CLI entry point for the pelican command.
52
53
Parameters:
54
- argv (optional): Command line arguments (defaults to sys.argv)
55
"""
56
57
def parse_arguments(argv=None):
58
"""
59
Parse command-line arguments and return argument namespace.
60
61
Parameters:
62
- argv (optional): Command line arguments to parse
63
64
Returns:
65
argparse.Namespace: Parsed arguments
66
"""
67
```
68
69
### Configuration Management
70
71
Functions for building configuration from command-line arguments and creating Pelican instances.
72
73
```python { .api }
74
def get_config(args) -> dict:
75
"""
76
Build configuration dictionary from parsed command-line arguments.
77
78
Parameters:
79
- args: Parsed argument namespace from parse_arguments()
80
81
Returns:
82
dict: Configuration dictionary for Pelican initialization
83
"""
84
85
def get_instance(args) -> tuple[Pelican, dict]:
86
"""
87
Create Pelican instance and settings from command-line arguments.
88
89
Parameters:
90
- args: Parsed argument namespace from parse_arguments()
91
92
Returns:
93
tuple: (Pelican instance, settings dictionary)
94
"""
95
```
96
97
### Development Features
98
99
Functions for development workflow including auto-reload and HTTP server functionality.
100
101
```python { .api }
102
def autoreload(args, excqueue=None) -> None:
103
"""
104
Run Pelican in auto-reload mode, regenerating on file changes.
105
106
Parameters:
107
- args: Parsed argument namespace
108
- excqueue (multiprocessing.Queue, optional): Exception queue for multiprocessing
109
"""
110
111
def listen(server: str, port: int, output: str, excqueue=None) -> None:
112
"""
113
Start HTTP development server for generated site.
114
115
Parameters:
116
- server (str): Server bind address (e.g., '127.0.0.1')
117
- port (int): Server port number
118
- output (str): Output directory path to serve
119
- excqueue (multiprocessing.Queue, optional): Exception queue for multiprocessing
120
"""
121
```
122
123
## Command-Line Options
124
125
The main pelican command supports these key options:
126
127
- `path`: Content source directory (positional argument)
128
- `-o, --output`: Output directory path
129
- `-s, --settings`: Settings file path (defaults to pelicanconf.py)
130
- `-t, --theme-path`: Theme directory path
131
- `-d, --delete-output-directory`: Clean output directory before generation
132
- `-r, --autoreload`: Enable auto-reload on content changes
133
- `-l, --listen`: Start development HTTP server
134
- `-p, --port`: HTTP server port (default: 8000)
135
- `-v, --verbose`: Verbose output
136
- `-q, --quiet`: Quiet output (errors only)
137
- `-D, --debug`: Debug output
138
- `--relative-urls`: Use relative URLs for development
139
- `--cache-path`: Cache directory path
140
- `--ignore-cache`: Ignore existing cache
141
- `-e, --extra-settings`: Override settings (KEY=VALUE format)
142
143
## Usage Examples
144
145
### Basic Site Generation
146
147
```python
148
from pelican import Pelican
149
from pelican.settings import read_settings
150
151
# Load settings from file
152
settings = read_settings('pelicanconf.py')
153
154
# Create and run Pelican instance
155
pelican_instance = Pelican(settings)
156
pelican_instance.run()
157
```
158
159
### Programmatic Configuration
160
161
```python
162
from pelican import Pelican
163
from pelican.settings import DEFAULT_CONFIG
164
165
# Create custom settings
166
settings = DEFAULT_CONFIG.copy()
167
settings.update({
168
'PATH': 'content',
169
'OUTPUT_PATH': 'output',
170
'SITENAME': 'My Blog',
171
'SITEURL': 'https://example.com'
172
})
173
174
# Generate site
175
pelican_instance = Pelican(settings)
176
pelican_instance.run()
177
```
178
179
### Development Workflow
180
181
```python
182
from pelican import parse_arguments, get_instance, autoreload, listen
183
import multiprocessing
184
185
# Parse command-line arguments
186
args = parse_arguments(['content', '--autoreload', '--listen'])
187
188
# Run with auto-reload and development server
189
if args.autoreload and args.listen:
190
pelican_instance, settings = get_instance(args)
191
excqueue = multiprocessing.Queue()
192
193
p1 = multiprocessing.Process(target=autoreload, args=(args, excqueue))
194
p2 = multiprocessing.Process(
195
target=listen,
196
args=(settings.get('BIND'), settings.get('PORT'), settings.get('OUTPUT_PATH'), excqueue)
197
)
198
199
p1.start()
200
p2.start()
201
```