Pelican: Static Site Generation with Python

If you're looking for a simple, lightweight, and flexible way to build a website, Pelican might be just what you need. Pelican is a Python-based static site generator that makes it easy to create and maintain a website using plain text files and a few simple templates.

What is Pelican?

Pelican is a static site generator, which means that it generates a complete website as a set of static HTML, CSS, and JavaScript files. Unlike dynamic websites that rely on a web server and a database to generate content on the fly, static sites can be hosted on any web server and require no server-side processing. This makes them fast, reliable, and easy to deploy.

Pelican is written in Python and uses the Jinja2 templating engine to generate pages from a set of templates and content files. It supports a wide range of content formats, including Markdown, reStructuredText, and HTML, and provides a flexible system for organizing and categorizing your content.

Getting Started with Pelican

To get started with Pelican, you'll need to install it on your computer. Pelican is available on PyPI, so you can install it using pip:

pip install pelican

Once you have Pelican installed, you can create a new Pelican site using the pelican-quickstart command:

pelican-quickstart

This command will ask you a series of questions to set up your site, such as the location of your content, the URL of your site, and the theme you want to use. Once you've answered all the questions, Pelican will generate a set of files and directories for your site, including a content directory for your content files, a themes directory for your site theme, and a pelicanconf.py file that contains your site's configuration.

Getting Started with a template

If you'd like to have a headstart, you can also use the following template to get started with Pelican.

git clone git@github.com:code-wizardry/pelican-template.git

Simply follow the instructions in the README.md file on this site to get started.

Configuring Your Site with pelicanconf.py

Pelican uses a Python file called pelicanconf.py to store your site's configuration. This file contains a series of variables that you can use to customize the behavior of your site, such as the location of your content, the URL of your site, and the theme you want to use. You can also use this file to configure Pelican's plugins and add custom Python code to your site. Linking to your social media accounts is also possible.

Creating Content with Pelican

Once you have your Pelican site set up, you can start creating content. Pelican uses plain text files for your content, which makes it easy to create and edit content using your favorite text editor. You can write your content in Markdown, reStructuredText, or HTML, depending on your preference.

To create a new content file, simply create a new file in the content directory with a .md, .rst, or .html extension. Pelican will automatically detect the file and use it to generate a page on your site.

Customizing Your Site with Themes

One of the great things about Pelican is that it supports a wide range of themes that you can use to customize the look and feel of your site. Pelican themes are built using Jinja2 templates and static assets like CSS and JavaScript, and they can be easily installed and configured using your pelicanconf.py file.

To install a Pelican theme, simply download the theme files and put them in your themes directory. Then, update your pelicanconf.py file to specify the name of the theme you want to use:

THEME = 'mytheme'

You can also customize the appearance and behavior of your theme by modifying the theme's templates and stylesheets. Pelican provides a wide range of template variables that you can use to access your site's metadata and content, such as ARTICLE_TITLE, PAGE_AUTHOR, and SITE_NAME.

Generating Your Site

Once you've created your content and customized your theme, you can generate your site using the pelican command:

pelican -l

This command will generate your site as a set of static HTML.

During development, you can use the -r option to regenerate your site whenever you make changes to your content or theme:

pelican -l -r

Once you are happy with your site, you can minify the html with the -s publishconf.py option and deploy it to any web server that supports static sites.

pelican -s publishconf.py

Deploying Pelican to Google Cloud Run

Once you've generated your Pelican site, you can deploy it to Google Cloud Run, which is a fully managed serverless platform that makes it easy to deploy and run containerized applications.

Docker

To deploy your Pelican site to Google Cloud Run, you'll need to create a Docker container that includes your site files and any dependencies you need. You can use the python:3.9-slim-buster base image to create a container with Python and Pelican preinstalled:

FROM python:3.10.0-alpine

COPY /src /app
COPY /requirements.txt /app

WORKDIR /app

RUN pip install -r requirements.txt

RUN ["pelican", "-s", "publishconf.py"]

CMD ["pelican", "-l", "-r"]

This Dockerfile sets up a working directory at /app, installs any dependencies listed in requirements.txt, copies your Pelican site files into the container and runs pelican -s publishconf.py with the RUN command in order to create the necessary outputs.

It then starts the Pelican server with the CMD command pelican -l -r.

Google Cloud Build

Once you've created your Docker container, you can deploy it to Google Cloud Run. (You can follow this quickstart, if you need help with that.)

Therefore, you just need a Google Cloud project, so that you can link your GitHub repository to Google Cloud Build. Then you need to create a trigger for Cloud Build, along with a cloudbuild.yaml file.

The cloudbuild.yaml file could look like this:

steps:
    - name: gcr.io/cloud-builders/docker
      args: ['build', '--build-arg', 'NODEENV=$_ENV', '-t', 'gcr.io/$PROJECT_ID/pelican-blog:latest', '.']
      # PUSH IMAGE TO REPO
    - name: 'gcr.io/cloud-builders/docker'
      args: ['push', 'gcr.io/$PROJECT_ID/pelican-blog:latest']
      # DEPLOY CLOUD RUN
    - name: 'gcr.io/cloud-builders/gcloud'
      args:
          [
              'run',
              'deploy',
              'pelican-blog-${_URL}',
              '--image',
              'gcr.io/$PROJECT_ID/pelican-blog:latest',
              '--region',
              'europe-west1',
              '--platform',
              'managed',
              '--allow-unauthenticated',
              '--set-env-vars',
              'NODE_ENV=${_ENV}',
          ]

Pelican Configuration

❗️Make sure to bind the correct IP-Address to the Pelican server, so that it can be accessed from the outside. Also make sure to set the port to 8080.

This can be done in the pelicanconf.py file:

BIND = "0.0.0.0"
PORT = 8080

Conclusion

Pelican is a powerful and flexible static site generator that makes it easy to create and maintain a website using Python. Whether you're a developer, writer, or designer, Pelican provides a simple and straightforward way to build a website that looks great and works reliably.

With its support for a wide range of content formats, flexible theming system, and easy deployment options like Google Cloud Run, Pelican is a great choice for anyone who wants to create a website quickly and easily.

So why not give it a try and see what you can build?