turbopelican 0.4.1

An uber-quick tool to create a Pelican static-site and deploy it to GitHub Pages.

turbopelican

An uber-quick tool to create a Pelican static-site and deploy it to GitHub Pages.

• Explanation
• Usage
  • Configuration
• Development

Explanation

GitHub lets you host static websites at your own subdomain. If your GitHub username is mrjohndoe, you can host a website at https://mrjohndoe.github.io. The same applies for organizations. If your GitHub organization is called MySpecialOrg, you can host a website at https://myspecialorg.github.io.

turbopelican is a tool which swiftly creates a static website to deploy at your subdomain. Any developer with a GitHub account and uv installed (see here) can deploy a website in minutes.

Usage

Before you run turbopelican, create a new repository where you will keep the source for your website.

ℹ️ NOTE: Make sure that the site-url uses the GitHub repository's name. For example, if you want the website to be https://johndoe.github.io, your GitHub repository will need to be called johndoe.github.io.

After your repository is created, copy the git repository URL. You'll need it later.

Then enter your settings for your repository, and under "Code and automation" click "Pages". The section "Build and deployment" allows you to choose a source. Chose "GitHub actions".

Next, you need to run turbopelican. Users are recommended to run turbopelican using uvx:

$ uvx turbopelican init turbopelican.github.io
Who is the website author? [Ilya Simpson]
What is the name of the website? [turbopelican.github.io] Time to Clock Back
What timezone will your website use? [Pacific/Auckland]
What language will your website use? [en]
What is your website URL? [https://turbopelican.github.io]
Initialized empty Git repository in /home/elliot/projects/turbopelican.github.io/.git/
Using CPython 3.11.11
Creating virtual environment at: .venv
Resolved 23 packages in 0.66ms
Installed 21 packages in 13ms
 + anyio==4.9.0
 + blinker==1.9.0
 + docutils==0.21.2
 + feedgenerator==2.1.0
 + idna==3.10
 + jinja2==3.1.6
 + markdown==3.7
 + markdown-it-py==3.0.0
 + markupsafe==3.0.2
 + mdurl==0.1.2
 + ordered-set==4.1.0
 + pelican==4.11.0
 + pygments==2.18.0
 + python-dateutil==2.9.0.post0
 + pytz==2025.1
 + rich==13.9.4
 + six==1.17.0
 + sniffio==1.3.1
 + typing-extensions==4.12.2
 + unidecode==1.3.8
 + watchfiles==1.0.4

You can use the defaults, or choose your own values. In the example above, I have decided to give the website a non-default name, but I have left the other settings. turbopelican then creates a new repository mypersonalsite, with everything ready to push to GitHub.

ℹ️ NOTE: Make sure that the site-url uses the GitHub repository's name. For example, if you want the website to be https://johndoe.github.io, your GitHub repository will need to be called johndoe.github.io.

You will then need to push your code to GitHub:

cd turbopelican.github.io
git add .
git commit -q -m "Initial commit."
git remote add origin [e-mail]:turbopelican/turbopelican.github.io.git # Use your own git repo reference
git push -q --set-upstream origin main

Now look at your repository on GitHub. You should be able to see the repository:

If you navigate back to the settings for GitHub Pages, you should see a message informing you that your website is already live.

ℹ️ NOTE: It may take a minute for this prompt to appear, because GitHub Actions must first deploy your website.

If you follow the link, you should be able to see your newly deployed website.

You can learn more about Pelican here.

Configuration

Pelican still targets Python 3.9, which does not bundle built-in support for reading TOML configuration. Projects using turbopelican require Python 3.11 or higher, and therefore adopt the newer convention of placing configuration in a TOML file rather than Python scripts. Generally, you should only need to modify turbopelican.toml, rather than pelicanconf.py or publishconf.py.

Development

Ensure you have uv and git installed. You will need to create a fork of the repository. Then you should navigate to GitHub Actions (https://github.com/yourusername/turbopelican/actions) and enable workflows on your repository. After that, you can clone your fork onto your computer.

git clone [e-mail]:yourusername/turbopelican.git
cd turbopelican
uv sync

When you need to check that the branch can pass CI, you can run the Makefile like so:

make ci

Once you push your branch to GitHub, the workflow "Run CI" should run. If you have not enabled workflows yet, do so, and then run the workflow manually. Pull requests should be made only for branches which pass CI. Once it has passed, you should then open a pull request. If you are contributing a new feature or breaking changes, you should set the base reference to the current feature branch. Otherwise, you should set the base reference to main.