Blogging with Jupyter and Pelican

Posted on Thu 30 March 2017 in Computer

This articles tells how to build this blog site.

Installation and Setup

  • Jupyter, and an article telling what is jupyter notebook
  • Pelican, pythonic blog system supports markdown, rst, asciidoc, ipynb etc.
  • ipynb2pelican, a plugin enables ipynb support by metacell
  • ghp-import is needed for github page import. It can be installed by pip
  • Flex Theme, the best pelican theme I have found

Setup pelican

$ 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? Peijun's Thoughts
> Who will be the author of this web site? Peijun Zhu
> 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? [10] 
> What is your time zone? [Europe/Paris] US/Eastern
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y
> 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) 
> Do you want to upload your website using SSH? (y/N) 
> Do you want to upload your website using Dropbox? (y/N) 
> Do you want to upload your website using S3? (y/N) 
> Do you want to upload your website using Rackspace Cloud Files? (y/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/zpj/code/test

Setup Git and Github Pages

  • Set up your Github Pages

    Head over to GitHub and create a new repository named username.github.io, where username is your username (or organization name) on GitHub.

  • Change directory to the blog folder containing Makefile, pelicanconf.py etc.
  • Init git repo by git init
  • Create a branch src by git checkout -b src. This will be your working folder
  • Add a remote repo related to your github page and push the src to github
  • Now you can push webpage to master branch by make github, which includes ghp-import commands.

Write your post in jupyter notebook!

There is a official tutorial on how to write a MarkDown/reStructuredText article with metadata

ipynb2pelican defined a metadata format here: https://github.com/peijunz/ipynb2pelican#metacell

Generate Site

make html

Test site at localhost

make serve

Then, go to address localhost:8000 in your browser.

Generate + test

make devserver

It will automatically regenerate html instantly after your change of the src.

Deploy to github page

make github

Tweaks

Extra \n in indented code block

For indent style code block

Some text before

    This is a indented code block
    This is another line

Some text after the block with an empty line between them

It will produce

This is a indented code block
This is another line

Some text after the block with an empty line between them

So you should stick to ``` style code block or remove empty lines after indented code block. This is a bug of nbconvert

extra directory

extra directory can be used to place static files unrelated to pelican for your sites.

In html and publish of Makefile, add:

if test -d $(BASEDIR)/extra; then cp -r $(BASEDIR)/extra/* $(OUTPUTDIR)/; fi
  • CNAME file for github page
  • local mathjax
    • Link local mathjax to the extra directory
      ln -s MATHJAX_PATH extra/static
      

Cache

In pelicanconf.py

CACHE_CONTENT = True
LOAD_CONTENT_CACHE = True

In publishconf.py

CACHE_CONTENT = False
LOAD_CONTENT_CACHE = False