How to Publish a Pelican Blog via GitHub¶

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
4. Install and activate a virtual environment, Anaconda recommended. See this post for basic conda tutorial
5. Create a file called requirements.txt in the blog directory with the following content:

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

6. Run pip install -r requirements.txt in the blog directory to install all of the required packages. Refer to the notes in this post

Create blog¶

Run pelican-quickstart in the blog directory and follow the interactive setup sequence.
Feel free to hit return to accept the default values besides the following lines:

• the title of the website
• the author of the website
• n for the URL prefix
• timezone

Install Jupyter plugin for Pelican¶

Since Pelican doesn't support writing blog posts using Jupyter by default, we must install a plugin which is available from Github. If you don't have git installed, check here for installation instructions.

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...'

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: 2018-07-16 20:00
   Category: posts
   Tags: python, tutorial, pelican
   author: Shayne Mei
   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. 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

Pick a theme¶

1. Choose a theme here
2. Go to where you want to store the themes and run 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>'

Publish posts¶

1. Go to blog directory: cd <blogdir>
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.

reference