Create a blog with Anaconda, Pelican, Jupyter Notebooks (ipynb) and Github Pages (Pt. 1)

Word on the town, getting in the habit of documenting your work with Jupyter notebooks is great practise. Jupyter notebooks allow you to create and share documents containing code and rich text, to demonstrate your workflows and visualisations. On a more personal level, it gives you some freedom to be forgetful and know you'll always have an easy repository to remember how you tackled a problem in the past.

The next logical step is how can I use these files to generate content for a blog, without having to reformat and convert any visualisations in to static images? And Pelican it seems, is the answer.

This is the first post in a series documenting my process of setting up this blog from start to scratch. I know it will be useful to someone, that is myself, because I know I'll forget some if not all of these steps! So here we go..

nb: Credit to dataquest.io which this post is based on. However, I came across a ton of problems with using Anaconda, and other issues caused by subsequent updates to packages.

Setting up a Python environment and install packages¶

Setting up environments in Python is good practise when working on your own or cloned projects. It creates a seperate installation of Python, where you can install different combinations of packages, with different versions to your base installation, which can be important when ensuring each of your packages and plug-ins runs together smoothly.

• Open up Anaconda Prompt
• Navigate to the location where you want to keep your files using cd (change directory) and mkdir (make directory), for this example, we'll make a folder: 'ipynblog'
• Create a new Python environment: conda create -n ipynblog python=3.6.5
  • or conda create -n ipynblog python=3.5 anaconda to install the full compliment of Anaconda packages (~3gb)
• Activate the environment: conda activate ipynblog
• Create a file called requirements.txt containing:

Markdown
pelican
jupyter
ipython
matplotlib

• Install the required packages through conda: conda install -c conda-forge --file=requirements.txt

Some other useful commands:

• View installed environments: conda env list
• Delete environment: conda remove -n ipynblog --all
• View installed packages: conda list

Setting up Pelican, Git and the ipynb (Jupyter) plugin¶

• Start the pelican quickstart set-up: pelican-quickstart
• Choose the following options for now (use the default options with exception of Title, Author and URL prefix):

> Where do you want to create your new web site? [.]
> What will be the title of this web site? Dave's Blog
> Who will be the author of this web site? Dave Bloomer
> 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] Europe/London
> 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)
> 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)

• Install Git: conda install -c conda-forge git
• Initialise an empty Git repository, this will allow you to add the ipynb plugin: git init
• Create a '.gitignore' file containing:

output*
cache*
*.pyc
*.pid

• Create a folder 'plugins': mkdir plugins
• Download the ipynb plugin to the plugins folder: git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb
• Add the following lines to pelicanconf.py:

MARKUP = ('md', 'ipynb')
PLUGIN_PATHS = ['./plugins']
PLUGINS = ['ipynb.markup']
IGNORE_FILES = ['.ipynb_checkpoints']  # Helpful if you want to create content directly in the 'output' folder

Create some content¶

Navigate to the 'content' directory, where we will start generating, well, content. Pelican supports the creation of 'blog' and 'pages' type posts. Blog posts live in the 'content' directory, while pages are static (think about, resume, contact..) and live in the 'content\pages' directory. Now that we've installed the 'ipynb' plug-in, you can create content in either Markdown or Jupyter. Additionally, we need to create metadata which contains some basic information such as title, category, post date etc. While in-document metadata is officially supported, I found that it caused problems and decided to keep this information in a seperate file. As an example:

• Create a Jupyter notebook in the 'content' folder. An example file can be found here (credit: dataquest.io)
• Create a '.nbdata' file with the same name as the Jupyter notebook containing:

Title: Blog Post Title
Slug: address-shown-in-browser  # ie. davebloomer.github.io/address-shown-in-browser
Date: 2019-01-28 12:00
Category: blog, jupyter, python
Tags: first-post
Author: Dave Bloomer

Don't worry too much about the details for now. It's inevitable that you'll want to change the formatting when you get your blog up and running and can see how it looks in the flesh.

Use Pelican to convert ipynb to html and view¶

We'll now use Pelican to convert our Jupyter notebook in to html, which can be uploaded to GutHub pages.

• Navigate back to the 'ipynblog' folder with cd .. and run Pelican: pelican content
  • Bonus step: Start Googling the inevitable error messages
• The files generated by Pelican are stored within the 'output' folder, navigate there using: cd output
• Initalise a local server instance: python -m http.server
• Go to http://localhost:8000/ in your browser and view your blog!

That's all for part one. In the next post, we'll be looking at installing a theme, delving in to some options for customisability and uploading the site to GitHub pages.