Setting up a website with Nikola

Traditionally, the initial blog post on a custom made site desribes how to setup and build the site. However, there are already a plethora of such descriptions available. Therefore, I here rather share my motivation for the why, the outcome of my research about the how, followed by some points about practicalities.

Why to setup your own website

Given the large amount of available personalizable profile sites for academics (ResearchGate, Academica, ScienceOpen but also institutes webpages like my one here) one might ask why to build an own one.

For me, it is about taking back control: Control about what is presented on a profile, control about how it is presented, and, not at last, control to what other resources I want to link my content.

Don’t get me wrong. I very much welcomed the final arrival of web 2.0 to the research community. The social web for researchers were an important stepping stone for me personally - and I believe also for the broader scientific community - for disseminating research results and connecting to other research(ers). However, I think it is time to move on.

We scientists gather and handle increasing amount of data, often develop our own analysis software and publish research outcomes on a daily basis. I think, we should also take the collecting and presenting of our research efforts in our own hands.

How to build a website

Having decided on building my own website, I had to find a way to do that.

From the beginning I had a pretty good idea what I wanted to accomplish with the website. I wanted a framework for building the website which

  • is open source

  • is reasonable fast (ergo a static website generator)

  • is well documented

  • works well with Gitlab or Github

  • allows to include Jupyter notebooks

There are plenty of open static website generators available (see for example here).

After some research, the choice come down to either Hugo or Nikola. Hugo provides some blazing fast website generation (the actual program is a single executable written in Go). In addition, the Hugo community developed tons of beautiful themes (see the Hugo theme gallery), including one theme specifically developed for academics. The latter almost tipped the scale towards Hugo. What Hugo is lacking, however, is a native support for Jupyter notebooks.

This is in contrast to Nikola, which allows to write posts in several markdown languages (among others my preferred reStructuredText format) as well as in Jupyter notebooks. Nikola also provides multiple themes and it is quite easy to adopt any bootwatch based theme (see Custom theme below). Thus, I finally decided to give Nikola a try.

Setting up Nikola

First, install Nikola.

It is good practice, to install it in a virtual environment (either virtualenv or conda). See the Nikola getting started guide for further information.

If you want to use an Anaconda environment, Tejaa Chintaluri has some good tips.

After activating the virtual or anaconda environment, install Nikola with

pip install --upgrade Nikola
pip install --upgrade "Nikola[extras]"

After that, follow the Nikola getting started guide guide to build you first test site.

Hosting your website

Gitlab and Github provide a space for hosting your website.

I did not test with Github, but I think you would need to push the content of the build directory ("output" or "public", depending on your setting for OUTPUT_FOLDER) to your remote repository. See the Github pages documentation for further information.

Gitlab will build your website for you on a virtual machine in a Docker container. To set this up, you need to set the OUTPUT_FOLDER in to "public" and include a .gitlab.yml file in your webpage repo.

Below the example .gitlab.yml of this website:


  - Nikola build
  - master

    - pip3 install jupyter
    - Nikola build
    - public
  - master

To get started, Gitlab also provides an example webpage build with Nikola on Gitlab pages.

Note, that you have to include the line pip3 install jupyter in the .gitlab.yml file if you want to use Juypter notebooks.

From there on you just need to push the source code of your website to your Gitlab remote repo and it will build automatically. Depending on the availability of the virtual machines you might have to wait a couple of minutes before the build process starts. You can track the process in the section CI/CD category (on the sidebar).

For more information check the Gitlab pages documentation.

Further tips and tricks

Building your website

nikola build
nikola serve -b

However, if you work on your site, you might want to immediately see the consequences of your changes. You can continously build a Nikola site by:

nikola auto -b

Custom theme

Nikola already provides some themes (see Nikola themes). However, not all of theme are compatible with Jupyter notebooks and/or look good on mobile devices.

Generally, the Mako - Jinja2 seems ok.

You can also easily build your own bootstrap based theme by:

nikola bootswatch_theme -n YOUR_CUSTOM_THEME_NAME -s BOOTSWATCH_THEME_NAME -p bootstrap3-jinja

You can find the free bootswatch themes here.