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)