Pelican

Pelican is a static site generator powered by Python that requires no database or server-side logic.

Installation on MacOS

This guide will explain to you Pelican and walk you through setting up a development environment by installing it on your MacOS machine.

What is Pelican?

Pelican is a Static Site Generator (SSG), and its name is an anagram of the French word calepin, meaning notebook.

An SSG is a tool that generates a complete static website composed of HTML and CSS files (and sometimes client-side JavaScript). It takes raw data, such as Markdown files, and combines it with templates to create your website.

This method is highly efficient for building websites, particularly blogs. Once you install the tool, all you need to do is write your articles. Simple and effective!

In this post, we’ll guide you through setting up Pelican and getting started.

Installation

Pelican is written in Python, so some familiarity with the language is helpful.

Installing Pelican is straightforward—just a single pip command, and you're ready to go!

Before you begin, it’s a good practice to create a virtual environment. While not required, a virtual environment helps keep project dependencies isolated, preventing conflicts between different projects.

Here’s how to set one up:

mkdir blog
cd blog
python -m venv .venv
source .venv/bin/activate

Now, you’re ready to install Pelican using pip:

pip install pelican
# If you plan to write your articles in Markdown, use:
pip install 'pelican[markdown]'

Conclusion

By following these short steps, you've successfully set up Pelican on your development environment. With this tool, you're now ready to start building and managing modern websites efficiently.

Happy me! 🌱

Step-by-Step

With Pelican installed, it's time to create the structure of your blog and configure it using the pelican-quickstart command.

Initial Setup

Running pelican-quickstart will guide you through setting up the basic framework for your blog. Below is an example of the process and the choices I made:

Welcome to pelican-quickstart v4.8.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files needed by Pelican.
    
> Where do you want to create your new web site? [.] 
> What will be the title of this web site? My Awesome Blog
> Who will be the author of this web site? Your Name
> What will be the default language of this web site? [en] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) https://example.com
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10] 10
> What is your time zone? [Europe/London] Europe/Brussels
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) N
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) N
Done. Your new project is available.

Explanation of Choices

After answering these questions, Pelican generates the basic structure and configuration files for your blog.

Blog Structure Overview

Here’s what the structure looks like:

blog/
├── .venv/                # Virtual environment
├── content/              # Directory for your articles and pages
 │   └── (images)/        # Directory for storing images
 │   └── (pages)/         # For non-chronological content (optional)
├── output/               # Directory for the generated site
├── tasks.py              # Automation tasks
├── Makefile              # Makefile for easier commands
├── pelicanconf.py        # Main configuration file
└── publishconf.py        # Configuration for publishing

Creating Content

I’ll be using Markdown for writing posts, though Pelican also supports reStructuredText.

All blog posts go into the content/ directory. If you have static pages (like an About or Contact page), place them in the content/pages/ directory.

Here’s an example of a simple first article:

Title: Hello, World
Date: 2024-08-17 12:42
Tags: hello
Category: hello
Authors: Your Name
Summary: A short introduction to my blog

# Hello, world!

Welcome to my blog, folks!

The first few lines are metadata that provides information about your article, which templates can use. Depending on the theme, you might be able to include additional metadata.

Publishing Your Blog

The Canonical Way

To generate your website, use the following command:

pelican content/

This command processes your content and generates the static files in the specified output directory.

Automating the Process

If you opted to generate a tasks.py/Makefile, you can use the predefined commands to simplify your workflow. For example, to start the development server and regenerate content on changes, use:

make devserver

This command will:

Customizing with Themes

The default design might not be very exciting, but don’t worry—you can easily change it by using a theme.

Pelican offers a wide range of themes, which you can browse here. Once you find one you like, you can integrate it into your blog.

Installing a Theme

For this example, let’s say you’ve chosen the Attila theme.

  1. Create a themes/ directory in your blog/ folder.
  2. Download the theme and place it in the themes/ directory.

Here’s what your updated structure might look like:

blog/
├── .venv/                
├── content/
 │   └── (images)/        
 │   └── (pages)/        
 │   └── hello.md 
├── output/
 │   └── ...
├── themes/
 │   └── attila/
 │       └── ...
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main configuration file
└── publishconf.py       # Settings for publishing

Next, install the theme using Pelican's built-in command:

pelican-themes -U themes/attila/

You can verify that the theme was installed with:

pelican-themes -l

Finally, update your pelicanconf.py file to use the new theme:

THEME = 'attila'

And that’s it! Your blog is now set up with a stylish new theme, ready to go live.

Happy me! 🌱