How to setup Github Blog via Pelican

There are many ways to setup a Github blog, but since I love Python I think it makes sense to use Pelican, which is a Static Site Generator, Powered by Python.

Set up environment

1. Create a blog directory for all blog content and styles: mkdir <blogname>
2. Go into the blog directory: cd <blogname>
3. Create a file called .gitignore, and add in the content from this file. The .gitignore file is used to omitted certain dynamic compiled file when commit your changes.
4. Install and activate a virtual environment. You could use Anaconda, pipenv, or virtualenv. You can see my tutorials for Anaconda, pipenv, or virtualenv.

5. Create a file called requirements.txt in the blog directory with the following content:

   Markdown==3.2.1
   pelican==3.7.1
   jupyter>=1.0
   ipython>=4.0
   nbconvert>=4.0
   beautifulsoup4
   ghp-import==0.4.1
   matplotlib==1.5.1
   

6. Make sure your virtual environment is activated and run pip install -r requirements.txt in the blog directory to install all of the required packages.

Create blog

• Run pelican-quickstart in the blog directory and follow the interactive setup sequence.
• Feel free to hit the Enter key to accept the default values except for the following lines:
  • the title of the website
  • the author of the website
  • n for the URL prefix
  • timezone

Install Jupyter plugin for Pelican

There are a lot of plugins that are super handy for Pelican, and jupyter plugin is definitely one among them. Follow the steps below to install the plugin:

1. Run git init in the blog folder
2. mkdir plugins
3. git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb

4. Open pelicanconf.py and add the following lines:

   MARKUP = ('md', 'ipynb')
   PLUGIN_PATHS = ['./plugins']
   PLUGINS = ['ipynb.markup']
   IGNORE_FILES = ['.ipynb_checkpoints']
   

   • The first 3 lines of code tell Pelican to activate the plugin when generating HTML and the last line fixes a common error 'Could not find metadata...'

There is also a github repo that has all the available plugins for Pelican and you can find it here

Create posts from Jupyter Notebook

1. Write anything (code or markdown cells) in a jupyter notebook
2. Copy the file into the content directory in the blog directory
3. Create a txt file with the same name of your notebook file and an .ipynb-meta extension.
   • For example: first-post.ipynb-meta
4. Its content should be formatted as follows:

   Title: First Post
   Slug: first-post 
   Date: 2020-04-12 12:12
   Category: posts 
   Tags: python, tutorial, pelican 
   Author: Carson Z.
   Summary: This is my first post!
   

Create a GitHub Page

1. Log in/Sign up for GitHub
2. Create a repo in your account and name it <username>.github.io.
   • Substitute <username> with your GitHub username.
   • For example, mine is zmcddn
   • Refer to this official guide for repo creation
3. cd to the blog directory and run git remote add origin git@github.com:<username>/<username>.github.io.git
4. Set SITEURL in publishconf.py to http://<username>.github.io
   • For example, mine is https://zmcddn.github.io (remember to remove the trailing slash if there is one)

Pick a theme

1. Choose a theme here
2. Go to the blog root folder (i.e. <blogname> folder) and create a theme folder through mkdir theme
3. cd theme and git clone --recursive https://github.com/getpelican/pelican-themes pelican-themes
4. Open the pelicanconf.py and add this line: THEME = '<path_to_chosen_theme>'
   • For example, theme/pelican-themes/tuxlite_tbs

Note that once you've chosen your theme, you have to click into the theme page to see how the theme is setup, coz it might need some special configuration and cannot be used directly out of box

Run the blog locally to see what it looks like

1. Go to blog output directory: cd <blogname>\output
2. Run python -m pelican.server to spin up the server
3. Open up you browser (i.e. Chrome) and type in http://localhost:8000/, then you should see you blog

If you would like to see theme change or how your new article looks like, each time you've changed anything you could run the following steps to see it locally:

1. Go to blog directory: cd <blogname>
2. Run pelican content -s publishconf.py to create html files
3. Go to the output directory cd output
4. Run python -m pelican.server to spin up the server and you can see it in your browser at http://localhost:8000/

Publish posts

1. Go to blog directory: cd <blogname>
2. Create html from notebook files: pelican content
3. Use correct settings for deployment: pelican content -s publishconf.py
4. Import everything in the output folder to the master branch: ghp-import output -b master
5. Push content to GitHub Pages: git push origin master

In the future, make sure

• pelican virtual environment is activated
• notebook file containing new post is moved into content directory
• corresponding ipynb-meta file has been created

and then repeat the 5 steps above to publish new posts.

A bit more in-depth about the overall setup

• This tutorial provides a ste-by-step guide to setup a Github blog via Pelican
• The package ghp-import and command ghp-import output -b master is used to push static blog pages to the github.io site so its super easy to setup
  • However, if you run git status in your blog directory, you'll see many uncommitted files since ghp-import doesn't work exactly the same as git commit
    • Thus you should be very careful with your blog directory and don't use any reset command (I learned it the hard way ...)
    • A better way is to setup your blog project in another private github repo and use the normal git commit workflow to catch any changes
• Pelican uses Jinja templates so all Jinja tags can be used in the templates
• How Pelican works is that all your blog articles are stored in the content folder and once you run pelican content it will generate static pages and store them in the output directory, which is used (and pushed) to github.io for display

Summary

Reference

• How to Publish a Pelican Blog via GitHub
• Building a Data Science Blog for Your Portfolio