Setting up a website with Nikola

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 conf.py 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 conf.py to "public" and include a .gitlab.yml file in your webpage repo.

Below the example .gitlab.yml of this website:

image: registry.gitlab.com/paddy-hack/Nikola

test:
  script:
  - Nikola build
  except:
  - master

pages:
  script:
    - pip3 install jupyter
    - Nikola build
  artifacts:
    paths:
    - public
  only:
  - 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

nikola build
nikola serve -b

nikola auto -b

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