Setting up with the Nikola Framework

Here is my down and dirty guide to what I did to create a static site and some of the many tweaks that followed. Mainly so I can remember what I did if I need to redo it again. I'm an amateur at this, so I'm not saying this is the best way to do it.


One of the key criteria for my site setup is that it is easily transferable so I'm not tied into a hosting platform and can get the best value deals, as I don't want to pay much for a personal site that is essentially a hobby. True I could use a free platform like Blogger, but I want the flexibility of being able to fully understand and customise my website. Additionally, if Blogger ever shuts down (Not an unlikely prospect as Google has shutdowna lot of services in the past) I don't want to have a problem exporting a large amount of information. For that reason an independent platform suits me and my choice is Nikola, which isn't the easiest p;atform for a non coder like me, but easy enough for to get a site working and the challenge means I've learnt a lot through this process. My site is also static, which means that it is all essential a few files and doesn't have the databases etc of most websites. The advantages are that it loads fast (except for any external iframes), it's very secure and won't get viruses. It means I can work completely off line. This is useful when I'm travelling and I want to write a post and now when I'm writing this article is a power-cut. So below is my generic setup so I remember what to change next time.
Computer desk

Installing Nikola

*I'm a linux user at home, so these commands work for that OS, for windows you'd need to setup Python, then install it via the PIP utility Sudo snap install Nikola. Then start your new site using this commandnikola init mysite. This create a folder in the home directory called my site. Two options that are useful are the demo mode which installs generic content and quiet mode, which skips the installer wizard.nikola init mysite --quiet --demo.

You can then run the site by entering the following commands that builds and starts a server, then opening the local ip address in your browser. nikola build && nikola serve --browser. To write a new blog post in the markdown format I use this command. nikola new_post -t "My Title" -f markdown

Nikola also has some advanced features, such as embedding youtube videos using the shortcodes - url adding emojis 😢, using user created template shortcodes and adding slideshows.

Installing a bootstrap theme

The bootstap3 theme in inbuilt and using bootswatch It is quite customisable as you can swap in different fonts and colour schemes. However it took me a while to figure out how to do this. The bootstrap3 theme is already installed you can swap into it by changing the file to THEME='bootstrap3', however the css and html files that allow the site to work are invisible and it's useful to download them, so you can fully customise your site. I then decided to install the Journal theme (a few of the bootswatch themes seemed broken with Nikola) using this command nikola bootswatch_theme -s journal this will download the theme, then to installl it run nikola build. To tweak the site further you can download the base html and css files by running nikola theme -c base.tmpland set THEME='custom'. We can then get to the main tweaking in the configuration file. It's now worth backing up these clean files, in case your tweaking goes wrong.

Setting in

Here are the configuration settings I've changed so far in, which is the mission control of your Nikola site.

MARKDOWN_EXTENSIONS = \['fenced_code', 'codehilite', 'extra'\]

Enables Markdown settings.

        ("/archive.html", "All Posts"),
        ("/categories/", "Tags"),
        ("/rss.xml", "RSS"),  ),}

Rearrange these how you want and add links to other pages.

THEME = "custom" - Change the theme here.

POSTS = ()
("pages/*.rst", "", "story.tmpl"),
("pages/*.txt", "", "story.tmpl"),
("pages/*.html", "", "story.tmpl"),

This block sets it as a static site. Also change INDEX_PATH = "blog"

SHOW_BLOG_TITLE = False - Removes the name from the header

IMAGE_FOLDERS = {'images': 'images'}
IMAGE_THUMBNAIL_FORMAT = '{name}.thumbnail{ext}' 

Pictures Folder settings.

CONTENT_FOOTER = '<center> Contents &copy; {date} <a href="mailto:{email}">{author}</a> {license}<br>></a></center>-->'

You can customise the links and add in some html etc in this footer.

I also activated the search box option. It inserts a great search box in your site header, you can use google, but I like DuckDuckGo. The main problem at the moment is that the site isn't indexed, so the search box doesn't find anything yet (hopefully it will in a week or two).

<!-- DuckDuckGo custom search -->
<form method="get" id="search" action=""
class="navbar-form pull-left">
<input type="hidden" name="sites" value="%s">
<input type="hidden" name="k8" value="#444444">
<input type="hidden" name="k9" value="#D51920">
<input type="hidden" name="kt" value="h">
<input type="text" name="q" maxlength="255"
placeholder="Search&hellip;" class="span2" style="margin-top: 4px;">
<input type="submit" value="DuckDuckGo Search" style="visibility: hidden;">
<!-- End of custom search -->
""" % SITE_URL

INDEX_TEASERS = True I set the index teaser to true, so I can have teasers in the RSS feed.

Lastly I turned off the meta-data for photos.


Removing the source box

I didn't want the show source code box present in the theme. I think it may be possible to turn this off in, SHOW_SOURCELINK = False but I couldn't find it/didn't do it. I ended up deleting the relevant lines (through trial and error) in base.tmpl in the custom themes folder.

Set up domain and hosting email

I have my domain registered with GoDaddy and they gave me the hosting (I think) free for the first year. Once the site is setup, it's simply a case of copying the files from the Nikola output folder on my computer, to the PublicHTML folder on the GoDaddy Server. This can be automated using the following process.

After adding the website to my hosting platform, the next step was to setup an SSH key, so that I could quickly update my website. I did this by adding the relevant public key to the C panels SSH section. I then set up a .bashrc command so that I have a quick command to update the site. The site updates via rsync using the following command.

rsync -rvz /home/route/to/output/ user@ipaddress:/home/user/public_html

As a backup I can transfer the files using the excellent FileZilla program. My email had an outlook login as part of the package, so I used that as the easiest option. You can set this up inside Nikola , but I found this too tricky to set up. This is my workaround that essentially does the same thing.

The 404 Error Page.

To make my site even better I decided to add my own custom 404 page to my site. I couldn't find a way to do this via Nikola, so I simply customised the existing html in the 404.shtml file and uploaded it to the server and that seemed to work. I tried being clever, but basically just added a link to my homepage.

Changing to a site

It was fairly straight forward to tweak my site and change it from the default blog option using the Nikola Instructions . What threw me was setting the homepage, so it wasn't in Restructured Text, which I'm not sure about. Markdown isn't available in site mode, so I had to use html. I created a new page and eventually I worked out that you set .. slug: index at the top of this html page. I then decided to take the hard option for coding my homepage in my rather scrappy html, using some table to organise photos etc (I can't code css). Luckily the very good in built code in the theming does most of the hard-work for me. It took a lot of trial and error to get the site looking how I want. The next steps would be to create some template to do most of the hard-work for me, so you don't have to recode the next page. I decided no to do this, but to turn off the default page title showing on your site, you need to add .. hidetitle: True at the top of your file.

Site maps and traffic

It's worth registering your site with Google Analytics , so you can see if anyone looks at your site (It will also track if you open the site). This involves copying a script and adding it to the base.tmpl that we downloaded earlier.

An optional extra:

In order for your site to be properly indexed by search engines you can register it with each service and upload your sitemap, so it's quicker for them to discover it.

Google Webmaster,Yandex Webmaster - Worth doing if you want it to appear in DuckDuckGO and Bing Webmaster.

Add Some Social Media Buttons

I found it quite tricky to get some social media buttons that work with Nikola . It has a Sharethis widget installed that you can activate from the files, but this looks awful if you are viewing the site on a phone. You can add buttons directly from each platform, but I found that Pinterest and others didn't work as Javascript doesn't work by default in Nikola. Facebook had the best button as it was easily customisable and also had an iframe option, but it's tricky to get a uniform look for your site using these buttons anyway. The best soloution I found was using as it was free and I could customise the buttons and download them as a html link, I then could tweak the default colour. This was good, the only problem is that you have to go back to the site to generate new buttons for each page or just have a generic button for your homepage.


Setting this site up has taken a lot of time, effort and experimentation, but I've learnt a lot, improved my 'script kiddy' coding and if I had to do it again I think it would take me a fraction of the time. It's tricky working out the correct setting as Nikola isn't a widely used platform, so there isn't loads of documentation around. The main site is great, but takes some figuring out to tweak your setting for a beginner like me.

So this is where I've got to so far with my static site (not this site, also built on Nikola and I'm happy with the basic functionality. There is plenty more tweaking to come including adding a site logo and some flavicons, so I will have to do a mark two post soon.


Comments powered by Disqus