I’ve been working on creating a static website using Pelican and everything works fine when I run it locally on my computer. However, I’m having trouble figuring out how to properly deploy it to GitHub Pages for hosting.
I’ve tried following various tutorials online but most of them seem to assume I already know certain basics about GitHub deployment. They often skip over important details that would be obvious to experienced developers but confusing for someone just starting out.
Can someone walk me through the complete process of taking a Pelican-generated static site and getting it live on GitHub Pages? I need a detailed explanation that covers all the necessary steps from start to finish.
Had the same issues when I first deployed my Pelican site. What helped was understanding the output directory structure before messing with GitHub. I created a simple bash script for the build and push process. After running pelican content, copy the HTML files from output to a temp folder, switch to gh-pages branch, replace everything with new content, then commit and push. The base URL config tripped me up initially. Your SITEURL in pelicanconf.py needs to match your GitHub Pages URL exactly or your CSS and internal links break. Also check that your theme’s static files copy correctly to output. One gotcha: mixed content issues with custom themes. GitHub Pages uses HTTPS, so hardcoded HTTP links in your theme cause problems. Test your deployed site thoroughly before calling it done.
These solutions work, but you’ll still memorize commands every time you publish. And when your build breaks, you’re stuck debugging git branches or plugin problems.
I built a workflow where I just update content files - everything else runs automatically. No more pelican commands or remembering which branch to push.
My setup watches the content folder. I add a blog post or edit something, and it automatically builds with pelican, fixes SITEURL for GitHub Pages, and pushes to gh-pages.
It checks for broken links before deploying, so bad internal links get caught early. Sends me a notification when it’s done too.
Runs completely in the background. I write, hit save, done. No git or command line needed.
Latenode makes this ridiculously easy. Connect your GitHub repo and set up the workflow without touching Actions YAML or complex CI/CD stuff.
Most GitHub Pages and Pelican tutorials skip a crucial part: you need two separate branches. One for your source files and another for the generated site. To do this, create a repo called username.github.io (for your main site) or a custom name for project sites. Place your Pelican source files, such as pelicanconf.py and your content folder, in the main branch.
The key is to set up the OUTPUT_PATH in your config to point to a different folder. After running pelican content to generate everything, push just the contents of that output folder to your gh-pages branch (or the main branch if you’re using username.github.io).
Many face issues by cramming source files and generated HTML into the same branch. GitHub Pages only requires the final HTML, CSS, and assets, disregarding your Markdown files or Pelican configuration. Once you separate the source from the output, the deployment process becomes straightforward.
Been there with manual Pelican deployments. Everyone suggests GitHub Actions or manually pushing to gh-pages branches. It works but gets old fast.
I automated the whole thing now. Push content changes to my repo and everything builds and deploys automatically.
It watches my Pelican source files. Detects changes, builds the static files, pushes to the right GitHub Pages branch. No more manual pelican commands or branch switching.
I threw in image optimization and cache busting too. Takes about 2 minutes from push to live site.
This kills all the usual deployment headaches. Can’t forget to build before pushing. Can’t accidentally push source files to the wrong branch. No manual steps breaking your flow.
You can set this up easily with Latenode. Handles GitHub integration and build triggers without writing custom Actions or dealing with complex CI/CD stuff.
honestly, just use pelican-plugins/ghp-import. install it with pip, generate your site, then run ghp-import output -p. it handles all the branch switching automatically - no more copying files around or dealing with git checkout headaches.
Config files are way more important than most people think. You need different settings for local dev vs production - don’t use the same pelicanconf.py for both. I run two configs: pelicanconf.py for local testing and publishconf.py for GitHub Pages. The publish config imports base settings but swaps SITEURL for your actual GitHub Pages domain and flips RELATIVE_URLS to False. When you deploy, run pelican content -s publishconf.py instead of default. This fixes the super common problem where everything works locally but CSS and images break on GitHub Pages due to wrong URL paths. One more thing - check your theme works with your Pelican version before deploying. Version mismatches cause silent failures that’ll drive you crazy trying to debug.