Github, worlds leading hosting service for Git repositories offers a simple, elegant website solution. It allows its users to store page content in a git repository along with their code.
In this blog post ill walk you through the process of setting up a website by combining Pelican with Github Pages. Pelican is a simple python utility that lets you create beautiful weblogs using just text files. In other words its a static-site generator. I have chosen Pelican over other static-site generators as Pelican unlike its counter parts is based on python hence initial setup takes literally no time.
Setting up a github.io page¶
To create your Github user page, log in to Github and create a new repositorie username.github.io, as explained on Github pages. (Use your Github username for these repositories.) The username.github.io repository will contain the output HTML files Pelican generates. To add the output directory as a submodule, initialize it with a README file.
Installing Pelican¶
We will first create a virtual environment for Pelican via virtualenv before installing Pelican. cd into the directory where you want to install the Pelican website and then run the following command:
python -m venv .
source bin/activate
This essentially creates a virtual python environment where Pelican can be installed and any python package installed here wont affect the global python packages. Once the virtual environment has been created and activated, Pelican can be installed via prefixing with sudo if permissions warrant:
pip install pelican markdown typogrify ghp-import shovel cssmin webassets
Now clone the source repository you created:
git clone https://github.com/YOUR_USERNAME/YOUR_USERNAME.github.io.git web-sources
Then change directory to the source folder:
cd web-sources
Because of how Github Pages prefers to work, serving the files from the master branch, you have to put your source code in a new branch, preserving the “master” for the output of the static files generated by Pelican. To do that, you must create a new branch called “source”:
git checkout -b source
Pelican quickstart¶
Pelican provides an excellent quickstart command. Run it:
pelican-quickstart
The quickstart will ask you various questions, which you can answer in turn. Before answering them, take a look at my answers below:
> Where do you want to create your new web site? [.] ./
> What will be the title of this web site? Ashwin's Chronicles
> Who will be the author of this web site? Ashwin Kumar Karnad
> What will be the default language of this web site? [pt] 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) y
> How many articles per page do you want? [10] 10
> What is your time zone? [Europe/Paris] Asia/Calcutta
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y **# PAY ATTENTION TO THIS!**
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) 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 YOUR_USERNAME.github.io
Now, go ahead and create your first blog post! You might want to open the project folder on your favorite code editor and find the “content” folder inside it. Then, create a new file, which can be called my-first-post.md (Just for testing). The contents should begin with the metadata which identifies the Title, Date, Category and more from the post before you start with the content, like this:
Title: My first post
Date: 2018-1-2
Modified: 2018-1-3
Category: misc
Tags: first, misc
Slug: My-first-post
Authors: Your name
Summary: What does your post talk about? Write here.
This is the *first post* from my Pelican blog. **YAY!**
Let’s see how it looks?
Go to the terminal, generate the static files and start the server. To do that, use the following command:
(venv)$ make html && make serve
While this command is running, you should be able to visit it on your favorite web browser by typing localhost:8000 on the address bar.
A little touch up¶
Now, if you want to put an image in a post, a neat way is to first create a ‘images’ directory inside your content directory, where your posts are. Now, you have to tell Pelican to use it. Find the pelicanconf.py, the file where you configure the system, and add a variable that contains the directory with your images:
STATIC_PATHS = ['images']
Save it. Go to your post and add the image this way:
You can interrupt the server at anytime pressing CTRL+C on the terminal. But you should start it again and check if the image is correct. Can you remember how?
(venv)$ make html && make serve
One last step before your coding is “done”: you should make sure anyone can read your posts using ATOM or RSS feeds. Find the pelicanconf.py, the file where you configure the system, and edit the part about feed generation:
FEED_ALL_ATOM = 'feeds/all.atom.xml'
FEED_ALL_RSS = 'feeds/all.rss.xml'
AUTHOR_FEED_RSS = 'feeds/%s.rss.xml'
RSS_FEED_SUMMARY_ONLY = False
Save everything so you can send the code to Github. You can do that by adding all files, committing it with a message (‘first commit’) and using git push. You will be asked for your Github login and password.
git add -A && git commit -a -m 'first commit' && git push --all
As I had said before you would be preserving the master branch for the output of the static files generated by Pelican. Now it’s time to generate the mater:
$ make github
You will be asked for your Github login and password again. And… voilà! Your new blog should be live on https://YOUR_USERNAME.github.io.
What’s next?¶
You generated your first Pelican static website using Markdown and Jinja2. Additional modifications can be made to the Jinja2 templates and the content contained in the Markdown files.
Adding .gitignore¶
.gitignore file contains a list of files and folder that git will ignore while syncing with the remote repository. Utilizing .gitignore wisely can reduce the amount of data you need to upload.
make a file .gitignore in the web-sources file with the following contents
#Custom
output
pelicanconf_local.py
#Python
*.py[cod]
# C extensions
*.so
# Packages
*.egg
*.egg-info
dist
build
eggs
parts
bin
var
sdist
develop-eggs
.installed.cfg
lib
lib64
# Installer logs
pip-log.txt
# Unit test / coverage reports
.coverage
.tox
nosetests.xml
# Translations
*.mo
# Mr Developer
.mr.developer.cfg
.project
.pydevproject
Automate GitHub upload process¶
Create a file up.sh in the web-sources
git add -A && git commit -a -m ""$1" && git push --all
Now whenever you want to upload sync the repo just do bash up.sh "Comment" Note that the argument “Comment” should not contain spaces.
Download Themes¶
Clone pelican-themes repository
git clone --recursive https://github.com/getpelican/pelican-themes themes
In pelicanconf.py add the following variables:
THEME = 'themes/bootstrap2'
OUTPUT_PATH = 'output'
PATH = 'content
Custom Home page¶
Add this variables to pelicanconf.py
# Custom Home page
DIRECT_TEMPLATES = (('index', 'blog', 'tags', 'categories', 'archives'))
PAGINATED_DIRECT_TEMPLATES = (('blog',))
TEMPLATE_PAGES = {'home.html': 'index.html',}
Duplicated the index.html to blog.html in your template folder and add this lines:
{% set active_page = "blog" %}
{% block title %}{{ SITENAME }} - Blog{% endblock %}
Create home.html or use page override feature to use a Markdown page as your home page.
nano home.html
{% extends "base.html" %}
{% block content %}
<div class='page'>
<div class="page-header"><h1>Home</h1></div>
<div class="page-content">Content</div>
</div>
{% endblock %}
Process for new articles.¶
Ones the setup is done, the contents of the folder web-sources need not be generated again using the above procedure. All one has to do is place the article in the content folder then (after testing the website locally using make devserver) then execute bash up.sh "Comment" to sync the source branch and then do make github
Process for moving to a different machine¶
If you are on a different machine or you have lost access to the web-sources folder, you just have to make the virtual environment and then do git clone again. i.e
virtualenv website
cd website
source bin/activate
pip install pelican markdown typogrify ghp-import shovel
git clone https://github.com/YOUR_USERNAME/YOUR_USERNAME.github.io.git web-sources
cd web-sources
git checkout -b source
This article just touches upon getting a basic website up and running. More features that Pelican offers (like custom plugins)can be explored here.
Upgrading Pelican¶
Pelican is under constant development so it might happen that after sometime you will need to upgrade to a newer version. For instance when I wrote the tutorial initially pelican was on version 3.7 and the current version is 4.7 is it seemed like a good idea to upgrade.
To upgrade and regenerate the content you need these twoo commands
pip install --upgrade pelican
pelican content
Then we need to update the local copies of the plugins and themes. If you have just cloned from the original git repos the nall you need to do is
git pull origin
FAQs and Tips¶
- Separate slug (URL) words with a hyphen, or an underscore? you should use a hyphen for your SEO URLs. Google treats a hyphen as a word separator, but does not treat an underscore that way. Google treats and underscore as a word joiner — so github_pages is the same as githubpages to Google.