0
# Pelican
1
2
A comprehensive Python static site generator that transforms text files written in Markdown, reStructuredText, or HTML into complete websites. Pelican provides powerful features for content management, theme customization, plugin extensibility, and automated site generation with built-in development server and deployment capabilities.
3
4
## Package Information
5
6
- **Package Name**: pelican
7
- **Language**: Python
8
- **Installation**: `pip install pelican`
9
- **Optional Markdown support**: `pip install pelican[markdown]`
10
11
## Core Imports
12
13
```python
14
import pelican
15
from pelican import Pelican
16
```
17
18
Common for content processing:
19
20
```python
21
from pelican.contents import Article, Page, Content
22
from pelican.generators import ArticlesGenerator, PagesGenerator
23
from pelican.settings import read_settings
24
```
25
26
## Basic Usage
27
28
```python
29
from pelican import Pelican
30
from pelican.settings import read_settings
31
32
# Load configuration
33
settings = read_settings('pelicanconf.py')
34
35
# Create and run Pelican instance
36
pelican_instance = Pelican(settings)
37
pelican_instance.run()
38
```
39
40
Command-line usage:
41
42
```bash
43
# Generate site from content directory
44
pelican content
45
46
# Generate with custom output directory and theme
47
pelican content -o output -t my-theme
48
49
# Run development server with auto-reload
50
pelican --autoreload --listen
51
52
# Quick project setup
53
pelican-quickstart
54
```
55
56
## Architecture
57
58
Pelican's modular architecture separates concerns through distinct components:
59
60
- **Pelican Class**: Main orchestrator managing the generation pipeline
61
- **Generators**: Specialized classes that process different content types (articles, pages, static files)
62
- **Readers**: Parse different markup formats (Markdown, reStructuredText, HTML)
63
- **Content Classes**: Represent different content types with metadata and processing logic
64
- **Writers**: Handle output file generation and theme rendering
65
- **Plugin System**: Signal-based architecture for extensibility
66
67
This design enables flexible content processing pipelines while maintaining separation between content parsing, processing, and output generation.
68
69
## Capabilities
70
71
### Main Application
72
73
Core Pelican class and application entry points for site generation, configuration management, and command-line interface.
74
75
```python { .api }
76
class Pelican:
77
def __init__(self, settings: dict): ...
78
def run(self) -> None: ...
79
80
def main(argv=None) -> None: ...
81
def parse_arguments(argv=None): ...
82
def get_config(args) -> dict: ...
83
def get_instance(args) -> tuple[Pelican, dict]: ...
84
```
85
86
[Main Application](./main-application.md)
87
88
### Content Management
89
90
Content classes for articles, pages, and static files with metadata processing, URL generation, and template assignment.
91
92
```python { .api }
93
class Content:
94
def __init__(self, content: str, metadata: dict = None, settings: dict = None, source_path: str = None): ...
95
96
class Article(Content): ...
97
class Page(Content): ...
98
class Static(Content): ...
99
```
100
101
[Content Management](./content-management.md)
102
103
### Content Generation
104
105
Generator classes that process different content types and produce output files through theme rendering and pagination.
106
107
```python { .api }
108
class Generator:
109
def __init__(self, context, settings, path, theme, output_path): ...
110
111
class ArticlesGenerator(CachingGenerator): ...
112
class PagesGenerator(CachingGenerator): ...
113
class StaticGenerator(Generator): ...
114
class TemplatePagesGenerator(Generator): ...
115
```
116
117
[Content Generation](./content-generation.md)
118
119
### Content Reading
120
121
Reader classes for parsing different markup formats with metadata extraction and content processing.
122
123
```python { .api }
124
class Readers:
125
def __init__(self, settings: dict, cache_name: str = ""): ...
126
def read_file(self, base_path: str, path: str, content_class=Content, fmt=None): ...
127
128
class BaseReader: ...
129
class RstReader(BaseReader): ...
130
class MarkdownReader(BaseReader): ...
131
class HTMLReader(BaseReader): ...
132
```
133
134
[Content Reading](./content-reading.md)
135
136
### Settings and Configuration
137
138
Configuration system with default settings, file-based configuration loading, and runtime setting management.
139
140
```python { .api }
141
def read_settings(path: str = None, override: dict = None) -> dict: ...
142
143
DEFAULT_CONFIG: dict
144
Settings = dict[str, Any]
145
```
146
147
[Settings and Configuration](./settings-configuration.md)
148
149
### Command-Line Tools
150
151
Specialized CLI tools for site setup, content import, theme management, and plugin utilities.
152
153
```python { .api }
154
def main() -> None: ... # pelican-quickstart
155
def main() -> None: ... # pelican-import
156
def main() -> None: ... # pelican-themes
157
def list_plugins() -> None: ... # pelican-plugins
158
```
159
160
[Command-Line Tools](./cli-tools.md)
161
162
### Plugin System
163
164
Signal-based plugin architecture enabling extensibility through custom generators, content processors, and output handlers.
165
166
```python { .api }
167
from pelican.plugins import signals
168
169
# Available signals
170
signals.initialized
171
signals.finalized
172
signals.all_generators_finalized
173
signals.get_generators
174
signals.get_writer
175
```
176
177
[Plugin System](./plugin-system.md)
178
179
### Utilities
180
181
Helper functions for content processing, URL handling, caching, date formatting, and file operations.
182
183
```python { .api }
184
def slugify(value: str, substitutions: tuple = ()) -> str: ...
185
def truncate_html_words(s: str, num: int) -> str: ...
186
def clean_output_dir(path: str, retention: list = None) -> None: ...
187
def copy(source: str, destination: str, ignores: list = None) -> None: ...
188
```
189
190
[Utilities](./utilities.md)