Pelican Static Site Generator - Deployment Guide

Prerequisites

• Python 3.7+ - Pelican is built with Python
• pip - Python package manager for installing dependencies
• Markdown or reStructuredText - For writing content (optional, depending on your preferred markup language)
• Git - For cloning the repository (optional, if installing from source)

Installation

Option 1: Install from PyPI (Recommended)

pip install pelican

Option 2: Clone and Install from Source

git clone https://github.com/getpelican/pelican.git
cd pelican
pip install -e .

Verify Installation

pelican --version

Configuration

Basic Configuration

Create a pelicanconf.py file in your project directory:

# pelicanconf.py
AUTHOR = 'Your Name'
SITENAME = 'Your Site Name'
SITEURL = 'http://your-site-url.com'
PATH = 'content'
TIMEZONE = 'UTC'
DEFAULT_LANG = 'en'

# Theme
THEME = 'themes/notmyidea'

# Output settings
OUTPUT_PATH = 'output'
DELETE_OUTPUT_DIRECTORY = True

Optional Configuration

• Markdown Support: Install markdown package if not already available

  pip install markdown
  

• Plugins: Install desired plugins from the Pelican plugin ecosystem

Build & Run

Initialize a New Site

pelican-quickstart

This interactive command will guide you through setting up a basic Pelican site.

Create Content

Create a new article in the content directory:

mkdir -p content
echo "Title: My First Post
Date: 2024-01-15
Category: Blog

Hello, this is my first Pelican post!" > content/my-first-post.md

Build the Site

pelican content -o output -s pelicanconf.py

Run Development Server

pelican --listen

Visit http://localhost:8000 to view your site.

Production Build

For production, you might want to enable additional settings in publishconf.py:

# publishconf.py
SITEURL = 'https://yourdomain.com'
RELATIVE_URLS = False

Then build with:

pelican content -o output -s publishconf.py

Deployment

GitHub Pages

1. Add a Makefile with GitHub Pages target:

github: publish
    ghp-import -b gh-pages output
    git push origin gh-pages

2. Run: make github

Netlify

1. Connect your repository to Netlify
2. Set build command: pelican content -o output -s pelicanconf.py
3. Set publish directory: output

Vercel

1. Add vercel.json:

{
  "buildCommand": "pelican content -o output -s pelicanconf.py",
  "outputDirectory": "output",
  "framework": null
}

2. Deploy via Vercel CLI or web interface

AWS S3

1. Build your site locally
2. Sync output directory to S3 bucket:

aws s3 sync output/ s3://your-bucket-name --delete

Troubleshooting

Common Issues

Issue: Markdown not rendering

• Solution: Ensure the markdown package is installed: pip install markdown

Issue: Import errors

• Solution: Check Python version compatibility (requires Python 3.7+)

Issue: Template not found

• Solution: Verify THEME path is correct in configuration

Issue: Permission denied when writing output

• Solution: Check write permissions for output directory or change OUTPUT_PATH

Debug Mode

Run Pelican with verbose logging:

pelican --debug content -o output -s pelicanconf.py

Check Configuration

Validate your configuration file:

pelican --help

Plugin Issues

If using plugins, ensure they're properly installed and configured in pelicanconf.py:

PLUGINS = ['plugin-name']

Theme Issues

If using a custom theme, verify all required templates exist:

• index.html
• article.html
• page.html
• category.html
• author.html
• tag.html

Path Issues

Ensure all paths in configuration are correct and accessible:

# Check current working directory
import os
print(os.getcwd())