Creating a website using Nikola

Prerequisites:(What's this?)


It seems appropriate to write about the software I am using to design, build, and host this website. In brief, I am using:

In this post I will discuss my use of Nikola and give a short tutorial of how to get started with your own Nikola website.

Nikola is a Python package that allows the user to create static websites using Python metadata. It allows each webpage to be writen in a markup language such and html or RestructuredText and orchistrates them using Python. Python is a particularly good language to support because it leads the way for open source scientific programming, and is rapidly growing throughout science.

The references I used to get to grips with Nikola and would recommend are:

What is a static website?

Websites can be either static or dynamic. A static website is one whose content is static, that is, it can only be changed by the author and only by changing the underlying code. A dynamic website can also be influenced by the website users, e.g. through comments and forms. However, you can make a static website allow the use of comments (which I have) but this involves using external resources that are part of a dynamic website, e.g. using Disqus or Facebook for comments.

Advantages of a static website

  • Quick and simple to build (if you know how),
  • Quick loading times,
  • Cheap to host (free on Github),
  • Makes it look like you are a coding boss.

Disadvantages of a static website

  • A pain to update (Nikola reduces this issue),
  • Low functionality in your website (acceptable for personal website incl. blog),
  • Generally less user-friendly (Nikola reduces this issue).

More information can be found here: https://getnikola.com/handbook.html#why-static .

Software prerequisites

To get started with Nikola, I will assume you have the following programs installed:

virtualenv is a tool to create isolated Python environments. It allows you to separate some python components that are necessary for a project, but may interfere with components used for a different project. More information can be found at http://docs.python-guide.org/en/latest/dev/virtualenvs/ and https://pypi.python.org/pypi/virtualenv. Install virtualenv via pip:

$ pip install virtualenv

Install the Python packages requests and livereload which allow you to live update your webpage (one of the best features of Nikola):

$ pip install requests
$ pip install livereload

Getting started

First, create a virtualenv in the Anaconda prompt terminal

$ mkvirtualenv venv_name
Install Nikola
$ pip install nikola

To create a new site in your current directory:

$ nikola init
after which you will be required to enter some details about the website.

Next, in the new directory for the website, we can build the site using

$ nikola build
To open the website in the default browser (with automatic updates!) use
$ nikola auto -b
and use CTRL + c to cancel the current automatic building session.

This is currently a blank website, so lets add a page

$ nikola new_page
and a post
$ nikola new_post
Each new page and new post creates a new .rst (RestructuredText) file in the pages or posts folder. These files are where your markup code for the content of the webpage/post is written.

The conf.py file is where the magic happens. This is a Python script that allows you to customise your site and is very easy to use, even if you are new to Python. To make html posts/pages default we go from this conf.py

PAGES = (
    ("pages/*.rst", "", "story.tmpl"),
    ("pages/*.txt", "", "story.tmpl"),
    ("pages/*.html", "", "story.tmpl"),
)
to this
PAGES = (
    ("pages/*.html", "", "story.tmpl"),
    ("pages/*.rst", "", "story.tmpl"),
    ("pages/*.txt", "", "story.tmpl"),
)
That is, put the default file type first. To add navigation links to the new page, in the conf.py you can adjust accordingly
NAVIGATION_LINKS = {
    DEFAULT_LANG: (
		('/new_page_name.html', 'New Page Name')
        ('/archive.html', 'Archives'),
        ('/categories/index.html', 'Tags'),
        ('/rss.xml', 'RSS'),
    ),
}

Images and other files

Put any image or other file that you would like to include in your website in the files folder.

Themes

By default, Nikola uses the bootstrap-3 theme, however there are many more ready-made themes at https://themes.getnikola.com/. To use a different theme, you must first install it using

$ nikola install_theme theme_name
and then in conf.py we must set
THEME = "theme_name"

There are many additional customisations of the bootstrap theme at http://bootswatch.com/. I am currently (as of Jan 2017) using the Lumen theme which gives a simple light look. Further, it is possible to create a custom theme, for which I refer you to this helpful blog post http://shisaa.jp/postset/nikola-web.html.

Website first, blog second

This website is mainly a collection of static pages with its secondary function being this blog. By default, Nikola makes the home page of the your website into a blog-style page, however it does allow you to make a non-blog-style page your home page, which is what I preferred. First, we must set the following in the conf.py file:

INDEX_PATH = "posts"
PAGES = (
    ("pages/*.rst", "", "story.tmpl"),
    ("pages/*.txt", "", "story.tmpl"),
)
Then we must set a particular page to be the homepage by opening that page's markup document and entering
.. slug: index
in the preamble.

I like my home page to have no title, so you can turn the title off in the home page's markup document by adding

.. hidetitle: True
in the preamble.

Extra tools

Here are a few helpful bits-and-bobs I found along the way to improve this website.

Favicons

A favicon is that cool little icon that is displayed next to the name of a website in many internet browsers. To use a favicon, save the image you would like to use as a favicon in the Files folder and in the conf.py file add

FAVICONS = (
    ("icon", "/file_name.png", "16x16"),
)

Post teasers

To put a teaser of a post instead of the whole thing in the blog page we write

TEASER_END
in the content markup file for the post where you would like the teaser to end, and in the conf.py we write
INDEX_TEASERS = True

Comments

Comments powered by Disqus