My Book!

This Website

Share this article: TwitterFacebookGoogle+Diaspora*Email

I felt it was fitting to write the first "Project" article on this website, since it's the most recent little project I've been working on.

Choosing a framework

I was looking for a few things in a website: Something easily customizable, easily publishable, capable of blog feeds, and that could easily incorporate Jupyter Notebooks directly into it.

Looking around, it seemed the best fit for the job were static site generators. Static site generators are just programs that take a bunch of content, your settings and templates/stylesheets, and create static HTML files. Static site generators are simple to use, easy to customize, don't require some awkward web UI, and publishing is extremely fast and doesn't even require me to visit a website. They also have the advantage of being fast compared to any dynamic websites since the server just has to serve a plain HTML page. There are a few other advantages to them - I found this a helpful read.

With a static site generator, I can easily write an article in Markdown. Then with a couple simple terminal commands I can have it publish to the site.

Choosing a static site generator

It turns out Jekyll is the most popular static site generator. That means it has the advantage of the biggest community of support. However, there were two major disadvantages for me.

First, Jekyll is written in Ruby. I'm not very familiar with Ruby, and don't currently have any reason to learn it (besides for Jekyll). This means if I wanted to dig into the code to customize things, it would be a big pain.

Second, Jekyll doesn't have easy support for Jupyter Notebooks. I want to be able to do some data exploration in a Jupyter Notebook, and then just upload the notebook as an article easily. While it is possible to post Jupyter Notebooks with Jekyll, it isn't supported natively and takes extra steps.

After doing some research, I ended up deciding on Pelican. Pelican is written in Python, my preferred language. With a simple plugin, publishing Jupyter Notebooks becomes almost as easy as publishing Markdown - a separate file needs to be created for the metadata. Making changes to notebooks and then republishing becomes trivial, and life is easy.

Website host

After I had figured out how I was going to create my website, I had to choose a place to put it. This was a no-brainer. Because I'm using a static website, I don't need any fancy server support. Github Pages is free and allows me to change my site just by pushing to a Github repo. It also allows custom URLs (though not with HTTPS currently). So the whole process for publishing an article is: write Markdown or Jupyter Notebook, run pelican to generate the site pages, commit and push to Github. Super easy and quick!

If you're looking for a tutorial on how to set up your own Github hosted Pelican website, this tutorial is super helpful.

Comments !