Felipe Arcaro's blog

Introduction to Pelican

This article is part of a series.

Getting started with Pelican - Static site generator written in Python

  1. [ Introduction to Pelican ]
  2. Adding different Pelican themes to your static website

TL;DR

In order to create a static website with Pelican, do the following:

  • Create a project folder
  • Install Pelican and Markdown packages running pip install "pelican[markdown]"
  • Run pelican-quickstart and answer the questions that will pop up
  • Create an article named my_article.md with the following content:
Title: This is my first article
Date: 2010-12-03 10:20
Category: Cool

Cool content goes here.
  • Run pelican -r -l, open a browser, and navigate to http://localhost:8000/ to see the website running locally

What is Pelican?

Pelican is a static site generator written in Python.

Here are some of the things I really like about it:

  • We can write content in reStructuredText or Markdown formats using whatever tool we're comfortable with (I use Obsidian, by the way)
  • It includes a simple CLI tool to generate our website and do some other cool things
  • It generates a static website that can be easily hosted anywhere (even on AWS S3!)
  • It has really cool open-source community themes and plugins

What is a static website?

Okay, but what is a static website?

A static website is a fixed type of site that doesn't change content – it doesn't update based on user interactions or real-time data (no databases!). It's generally made up of HTML, CSS, and sometimes JavaScript files.

For non-tech people, a static website can be understood as a printed brochure. It's like a picture of information that doesn't change unless someone physically changes the words or pictures on the paper (the developer).

Because it is so simple, it is normally faster, more reliable, secure, and definitely fun to play with.

Why Pelican?

I've always struggled with choosing the best writing tool. I've experimented with MailChimp, Medium, Ulysses, Evernote, Notion, Google Docs, and others, and I often find myself switching between them – ultimately spending more time doing that than effectively writing.

Another thing I've struggled with was deciding on the best way to save and possibly even version control my notes because, at the end of the day, all these other tools would still be responsible for holding my data.

I've settled with writing my notes/articles as Markdown files (I use Obsidian for that) and storing these files automatically with iCloud for Mac.

And when I am done with an article or need to edit an article I'd already published, I can simply use Pelican to (re)generate the blog pages.

Setting it up

As I already mentioned, Pelican is built in Python, so we simply need to install it as a package with PyPI (Python Package Index) and run a few CLI commands. Here are the steps we need to go through:

  • Create a project folder
  • Install Pelican and Markdown packages (recommended to do it in a Python virtual environment)
# Create a Python virtual environment
python -m venv env-pelican

# Activate it on Linux/Mac
source env-pelican/bin/activate

# Activate it on Windows
./env-pelican/Scripts/activate

# Install Pelican package
python -m pip install "pelican[markdown]"
  • Run pelican-quickstart and answer the questions that will pop up
  • Create an article named my_article.md with the following content (you can learn more about Pelican's supported metadata here)
Title: This is my first article
Date: 2010-12-03 10:20
Category: Cool

Cool content goes here.
  • Run pelican -r -l, open a browser, and navigate to http://localhost:8000/ to see the website running locally
    • -r flag relaunches pelican each time a modification occurs on the content files
    • -l flag serves content files via HTTP and port 8000

Here's how your static website will look like:

pelican-website