Setup a free static blog with Pelican hosted on Github User Pagesven. 09 juin 2017 by Mick Cherry
There are several Github Pages types. The one I chose to use is names User Pages.
The main steps to setup a new blog are:
- Install the dev environnment (editor, Pelican generator, tool for easy Github Pages integration, ...)
- Create and setup the Github Pages git repository
- Create and configure the empty Pelican blog
- Setup the workflow (new post, publish)
Most of this setup has been ~~forced~~ advised to me by @MoAdiBFr :D
Install the development environnment
Check that you have
$ python --version Python 2.7.13
pip if you do not have it installed yet
$ wget https://bootstrap.pypa.io/get-pip.py $ sudo python get-pip.py $ rm get-pip.py $ pip install -U pip
Get Pelican, Markdown and ghp-import (a tool for commiting the
output folder to the proper branch, see below)
sudo pip install pelican sudo pip install markdown sudo pip install ghp-import
Here are the steps to get Sublime Text:
$ wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | sudo apt-key add - $ echo "deb https://download.sublimetext.com/ apt/stable/" | sudo tee /etc/apt/sources.list.d/sublime-text.list $ sudo apt-get update $ sudo apt-get install sublime-text $ subl
Get Sublime Text Package Control
wget -P /home/etienne/.config/sublime-text-3/Installed Packages https://packagecontrol.io/Package%20Control.sublime-package
You can now install Sublime Text packages (like MarkdownPreview or MarkdownExtended) that will prove useful for editing the blog posts.
Setup the git repository
In order for a Github User Pages website to be properly served, it needs to resides on the
master branch of a special repository that you must name username.github.io (here,
username means your Github username). This job will be done by the
We still need a way to track and save the actual blog sources. Some people create two repositories, one for the generated content, and one for the source files.
Here, we are going to use a solution that only uses one repository (the
username.github.io mandatory repo for Github User Pages) and two branches of it.
You can read Pelican tips for more details.
Start by creating a new repository on Github with the exact name
username.github.io where you replace the
username part with your own Github username. Do not add a README file or a .gitignore file when Github asks you about it.
# Make sure you already created the repository on Github $ git clone firstname.lastname@example.org:username/username.github.io.git blog Cloning into 'blog'... warning: You appear to have cloned an empty repository. $ cd blog
Create the Pelican blog
To create your blog, go to your blog folder and follow the steps from
$ cd blog $ pelican-quickstart Welcome to pelican-quickstart v3.7.1. This script will help you create a new Pelican-based website. Please answer the following questions so this script can generate the files needed by Pelican. > Where do you want to create your new web site? [.] > What will be the title of this web site? Mick Cherry\'s Serious Series > Who will be the author of this web site? Mich Cherry > What will be the default language of this web site? [en] > Do you want to specify a URL prefix? e.g., http://example.com (Y/n) n > Do you want to enable article pagination? (Y/n) > How many articles per page do you want?  > What is your time zone? [Europe/Paris] > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) > Do you want to upload your website using FTP? (y/N) n > Do you want to upload your website using SSH? (y/N) n > Do you want to upload your website using Dropbox? (y/N) n > Do you want to upload your website using S3? (y/N) n > Do you want to upload your website using Rackspace Cloud Files? (y/N) n > Do you want to upload your website using GitHub Pages? (y/N) y > Is this your personal page (username.github.io)? (y/N) y Done. Your new project is available at /home/etienne/dev/blog
Nothing to add here except for the last question: answer
yes in the case of a Github User Pages,
no if this is project/organization Pages.
Now we generate the first (default) content to initialize the master branch
$ cd blog $ make github pelican /home/etienne/dev/blog/content -o /home/etienne/dev/blog/output -s /home/etienne/dev/blog/publishconf.py WARNING: Feeds generated without SITEURL set properly may not be valid WARNING: No valid files found in content. Done: Processed 0 articles, 0 drafts, 0 pages and 0 hidden pages in 0.04 seconds. ghp-import -m "Generate Pelican site" -b master /home/etienne/dev/blog/output git push origin master Counting objects: 38, done. Delta compression using up to 4 threads. Compressing objects: 100% (36/36), done. Writing objects: 100% (38/38), 23.99 KiB | 0 bytes/s, done. Total 38 (delta 5), reused 0 (delta 0) remote: Resolving deltas: 100% (5/5), done. To github.com:ecastanie/ecastanie.github.io.git * [new branch] master -> master
make github generates the static default files to the
output folder, commit and push them to the remote
Now that the
master branch is setup, we create a new branch named
source (or anything else except
master) which will contain the whole blog sources (Markdown posts, config files)
$ cd blog $ git checkout -b source $ git status On branch source Untracked files: (use "git add <file>..." to include in what will be committed) Makefile develop_server.sh fabfile.py output/ pelicanconf.py pelicanconf.pyc publishconf.py publishconf.pyc nothing added to commit but untracked files present (use "git add" to track)
This branch will be your working branch, and
master will only be populated with the static generated content of the blog.
Now that the git repository is created, the Github Pages activated, the empty blog created, it is time to write a first article and publish it!
Again, check that you are in the
source branch (you should never have to checkout
$ cd blog $ git checkout source $ echo "Title: First post yay!" > content/First-Post.md $ echo "Date: 2020-04-09" >> content/First-Post.md $ echo "Category: Noob" >> content/First-Post.md $ echo "" >> content/First-Post.md $ echo "First!" >> content/First-Post.md
In order to save and track the source files, we need to add/commit/push these files to the
github in the following way:
$ tail Makefile github: publish git checkout source ghp-import -m "Generate Pelican site" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR) git push origin $(GITHUB_PAGES_BRANCH) git add . git commit -am "Update source files" git push origin source ...
Now just run
make github to see your blog generated, its sources commited+pushed, and the output folder pushed to the
$ cd blog $ make github
Congratulations! You now have finished the setup and first post publishing of your own Pelican blog on Github Pages!