Make your own blog with Github Pages and Nikola

  |   Source

Today, we're going to start by taking a look at how to make a blog using the static website generation framework called Nikola.

Secondly, we're going to see how we can easily host our blog on the interwebs using github pages.

Last, we'll look at how we can create our content using Jupyter notebooks.

Technologies

First things, first. We're going to need to install some software on our machine. It will help you have a very basic understanding of git and Python, but if you don't, it's ok. We're going to start with the basics.

These instructions are based on OS X, but the instructions will be similar for Linux, or even windows. The only real differences should be in how you install software.

First, let's ensure we have git installed. Open a terminal and type in:

which git

If that returns a path to git, we're good. Otherwise type:

xcode-select -install

This will open an alert box prompting you to install xcode's command line tools, which includes git.

Next, we're going to install Homebrew. Homebrew is a package manager for OS X. It's basically a utility that makes it easy to install and maintain software on to your computer. In a terminal, run:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Next, we're going to install an extension of homebrew called Cask. Cask allows us to install even more software to include things like Google Chrome using the homebrew package manager. Type in:

brew install caskroom/cask/brew-cask

Now we can install atom, an open-source text editor maintained by github.

brew cask install atom

Additionally, we want to make sure we're using the latest version of Python on our machine, which is 3.5.0 at the time of this article. Downloads can be found here

Now that we have the latest Python installed, we just need to install the Nikola and IPython libraries

pip install "Nikola[extras]"
pip install "ipython[all]"

Lastly, we can install the livereload plugin for chrome so that we can see how our website changes as we edit the content without having to re-create the website and refresh our browser each time a change is made.

Next, we're going to want to create a new project on github. If you don't yet have an account and don't know how to make a project, doing so is really straightforward. Just go to github.com, create an account, log in, and click on the green create repository or just navigate to https://github.com/new . Let's call it nikola-demo

A git repo is sort of like a series of snapshots of all the files and folders in a project. Github hosts repositories, meaning that you can download repositories onto your local machine from github (pull) and upload repositories to github from you machine (push).

So now, that I have created my new project in github, I'm ready to clone it onto my local machine. The clone command will create a new folder in the directory you're in named after the project you're cloning. Then it will pull all of the files from github into that folder, essentially creating a copy of that project.

git clone git@github.com:<your-username>/nikola-demo.git

Next, we change directory into that folder.

cd nikola-demo

To create our project, we run

nikola init

The command will ask us a few questions. This first question isn't very clear, but it's asking what folder we want to create our project in. We don't want to create a new folder, so to use the one we're currently in, we just type in '.' (no single-quotes)

For every other question, you can type in what you like or leave it blank. For the purpose of this demo, it's all the same.

Nikola has now created some folders for us as well as a configuration file, conf.py

Let's now open our project in atom. Type:

atom .

Now, because we want to write content using Jupyter notbooks, we need to make a couple of slight changes to the conf.py file.

In the left pane in atom, double-click on conf.py to open it and navigate to the POSTS and PAGES variables. We need to add .ipynb files as a format that nikola can use. We do that by adding a tuple to each of these variables like so:

POSTS = (
    ("posts/*.rst", "posts", "post.tmpl"),
    ("posts/*.txt", "posts", "post.tmpl"),
    ("posts/*.ipynb", "posts", "post.tmpl"),
)
PAGES = (
    ("stories/*.rst", "stories", "story.tmpl"),
    ("stories/*.txt", "stories", "story.tmpl"),
    ("stories/*.ipynb", "stories", "story.tmpl"),
)

Make sure to save the file once you've made the edits.

Now we can create a new post and specify Ipython Notebook as the format we want to use

nikola new_post -f ipynb

This will ask you what you want to call your post. Let's call it My First Post. This will create a file:

posts/my-first-post.ipynb

Next open a new terminal and navigate to the posts/ directory in your project and run:

ipython notebook

You'll see a list of the ipython notebooks in that folder. There should only be the one we just created. Click on it, and it will open a new tab in your browser where we can edit that notebook.

In the other terminal window type in:

nikola auto -b

nikola is now running a server with your website on your machine that will be accessible in your browser window at localhost:8000 by default.

Now, as we make edits to our ipython notebook and save them, we can see how our site will change simultaneously without having to rebuid the website or even reload the webpage that our website is in!

Once we're done editing our notebook, let's save our changes to github. We should tell git to ignore some files first:

_site/
*.pyc
.DS_Store
cache/
output/
**/.ipynb_checkpoints/

Save those lines to a file .gitignore in your project's root directory. You can do this by typing in atom .gitignore from the project root or if you prefer, you can copy those lines and type:

pbpaste > .gitignore

Next, let's commit our changes on our local machine. Type in:

git add .
git commit -m "Initial commit."

Now, to push those changes to github, type:

git push

Before publishing to github pages, let's install a theme for out blog. We can see the available themes by typing in nikola install_theme -l from our project root.

Let's install the ipython-xkcd theme:

nikola install_theme ipython-xkcd

Now in conf.py, edit the THEME variable

THEME = "ipython-xkcd"

We can now see what our site looks like by typing in nikola auto -b again.

Now let's update our git repo with our changes.

git add .
git commit -m "Installed a new theme and edited conf.py"
git push

We're ready to deploy to github! Nikola includes a handy github_deploy command to allow us to quickly publish to github pages.

nikola github_deploy

So what just happened?

  1. Nikola checked out a new branch in git (gh-pages)
  2. It built the website in that branch
  3. It pushed that branch to github
  4. Master branch was checked out again

Ta da! Your blog is now available at

<your-username>.github.io/nikola-demo

Basically, any project you have in github that has a gh-pages branch can be accessed via <your-username>.github.io/<your-project>.

Nikola is just one framework that allows you to create static websites and host them on github pages. Jekyll is a common one that is written in Ruby and the default framework used by github. It is probably the most popular framework and thus probably has the most themes.

Another popular framework for Python is Pelican. Pelican is more popular than Nikola and has more themes, but I chose Nikola because it has better support for Jupyter notebooks and it is easier to write content in multiple different formats and have them render correctly on your site. In my experience when using Pelican. If I wrote one article in IPython notebook format and another in reStructuredText, one of the articles would end up looking strange because of the way Pelican uses CSS.

Comments powered by Disqus