Easy Pelican with GitHub Actions

I had a very convoluted and complex workflow to write my blog and publish it to GitHub Pages. Though I knew that there should be a simple way of building and publishing the Pelican blog to GitHub Pages, I didn't invest time to figure it out. I was recently exploring how other blogging frameworks publish to GitHub Pages. I found a great reference on how this is done for Hugo. I decided to take the same approach for my site as well. Follow these simple steps and you should be fine.

Prerequisites

I make a few assumptions about the way you have organized your Pelican project.

  1. Your project is at the root of your GitHub repo. If it is under a subdirectory, plase adjust the actions file accordingly.
  2. You are hosting your GitHub Pages from the master or main branch.
  3. The build step uses a temporary directory alled public. If you already have a public directory in your repo, modify the workflow YAML below to make use of a different directory instead of public.

Step 1: Add GitHub Actions file

Create a file called .github/workflows/pelican.yaml. Copy and paste the content below into that file.

# Sample workflow for building and deploying a Pelican site to GitHub Pages
name: Deploy Pelican site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main
      - master

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Install Python Dependencies
        run: python3 -m pip install -r requirements.txt
      - name: Build with Pelican
        run: |
          mkdir public
          python3 -m pelican -o public
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

This file is easy to follow. There are two stages: build and deploy. In the build stage we run Pelican command to produce the output in the public directory. Then we zip this directory to create an artifact that contains all the generated contents. This artifact is then uploaded to GitHub.

In the deploy step, we take the artifact zip file and use a GitHub Action called actions/deploy-pages@v4 to deploy it.

Step 2: Verify the GitHub Action

When you visit the "Actions" tab in your repo, you will see a new action "Deploy Pelican site to Pages" (that is the name we have given for the workflow above). That action will be triggered any time when you merge and push your changes next time on your main or master branch next time.

Thats all you need to automatically publish your Pelican site to GitHub Pages.

Verifying your pages locally

Pelican has made verifying your pages locally so simple. You can use the command python3 -m pelican -l -r to locally build and verify your site with automatic reload. When the local server starts up it will print the URL to view the contents. It is usually http://localhost:8000/.

links

social