Intro Comments
 
on nikola, web, python

Nikola, one kickass Site and Blog generator

main-image

Nikola is a static Blog & Site generator, it's built in Python and it's to my opinion a very interesting Python project and one of the best site generator out there. I want to take the opportunity to thanks Roberto Alsina, who authored and who support the project, as well as Chris "Kwpolska" Warrick who is a major contributor to Nikola.

Nikola website: http://getnikola.com/
Python Package : https://pypi.python.org/pypi/Nikola/
On Github: https://github.com/getnikola/nikola

Nikola take his name from Nikola Tesla, which is considered as one of the greatest geek of all times, he invented fluorescent lighting, the Tesla induction motor, the Tesla coil, and developed the alternating current (AC) and many other things.

Nikola Tesla

Features

Nikola has many features, the most remarkable ones are:

  • Blogs, with tags, feeds, archives, comments, etc.
  • RSS Feeds
  • A lot of themes: https://github.com/getnikola/nikola-themes and easily themable
  • Flexible, extensible via plugins (https://github.com/getnikola/plugins)
  • Small codebase
  • reStructuredText or Markdown as input language (also Wiki, BBCode, Textile, and HTML)
  • Easy image galleries (just drop files in a folder!)
  • Syntax highlighting for almost any programming language or markup
  • Preview web server examples
  • Live re-rendering while you edit

I personally designed few website with Nikola and from my experience it has been a breeze even to create multi-languages website (English, Spanish & Catalan). To show an example, here 2 websites I built & deployed using Nikola/Bootstrap3:

Why a Static website?

There is many reasons that are well explained by Roberto Aslina (http://getnikola.com/handbook.html#why-static). There is countless advantages, but the most notable ones is that is crazy fast as you remove all the logic of dynamic website and just deliver your content, plus you can take advantage for free hosting provided by Github (http://pages.github.com/), I will definitely trust more Github than my own hosted webserver. By experience, I had many sites using Wordpress and they ended up into a costly maintenance effort, many security updates, down-time and so many problems you really want to be taken off your shoulders. So static is the answer in many cases, I really try to ask myself why do I need a dynamic website and if I don't find a very good reasons then it means that static fit perfectly.

The recommended formats are reStructuredText and Markdown, but there is also support for textile and WikiCreole and even for just writing HTML. I use Nikola with reStructuredText so if you don't have a preference, here a quick tutorial http://getnikola.com/quickstart.html and there is a handy Online reStructuredText editor that may help you to learn some rst quickly: http://rst.ninjs.org/

Enough, it's time to get started, no? Let's show you how to create a simple website with Nikola.

Install Nikola in 3 steps

1) create a virtualenv :

$ mkvirtualenv kickass-website

2) install nikola:

$ pip install Nikola

3) install python-requests & livereload:

$ pip install requests==2.2.1
$ pip install livereload==2.1.0

Now type nikola and you should be good to get started!

Let's type nikola help, this will give us an idea of all the command available by Nikola.

$ nikola help
Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com


Available commands:
  nikola auto                 automatically detect site changes, rebuild and optionally refresh a browser
  nikola bootswatch_theme     given a swatch name from bootswatch.com and a parent theme, creates a custom theme
  nikola build                run tasks
  nikola check                check links and files in the generated site
  nikola clean                clean action / remove targets
  nikola console              start an interactive Python console with access to your site
  nikola deploy               deploy the site
  nikola doit_auto            automatically execute tasks when a dependency changes
  nikola dumpdb               dump dependency DB
  nikola forget               clear successful run status from internal DB
  nikola help                 show help
  nikola ignore               ignore task (skip) on subsequent runs
  nikola import_blogger       import a blogger dump
  nikola import_feed          import a RSS/Atom dump
  nikola import_wordpress     import a WordPress dump
  nikola init                 create a Nikola site in the specified folder
  nikola install_plugin       install plugin into current site
  nikola install_theme        install theme into current site
  nikola list                 list tasks from dodo file
  nikola mincss               apply mincss to the generated site
  nikola new_post             create a new blog post or site page
  nikola orphans              list all orphans
  nikola run                  run tasks
  nikola serve                start the test webserver
  nikola strace               use strace to list file_deps and targets
  nikola tabcompletion        generate script for tab-complention
  nikola version              print the Nikola version number

  nikola help                 show help / reference
  nikola help <command>       show command usage
  nikola help <task-name>     show task usage

Let's create a demo website

1) We will create now a demo site with demo files to explore nikola

$ nikola init --demo mykickasswebsite

This create the directory mykickasswebsite, if you don't want the demo files, then you can simply remove --demo
I will recommend to explore the files that has been created by nikola, those will help generating your static website.

2) From here, you should be able to build the website, this will create all the static files needed by your webserver to deliver a kickass website:

$ cd mykickasswebsite
$ nikola build

... some magic is happening here!

All the static files are stored in the folder output, you can open the output/index.html in your web browser, but there is nicer way we will show after how to see the result on your browser.

When you enter in the new site directory you will notice the following structure:

files
galleries
listings
posts
stories
  • files directory contains static assets that you want to have available regardless of the theme you use.
  • galleries reveal the photo gallery feature of Nikola. Inside this directory you can create as many directories as you like, each being a separate gallery.
  • listings, is for source code listings, please refer here for further information http://getnikola.com/handbook.html#id41
  • posts get more to the heart of Nikola. This directory will keep all your post files in a chosen markup language.
  • stories, it contains all the "static" pages (non-post pages) you wish to serve. Things like an about or contact page would fit nicely there.

The main page is stored in stories/index.rst, so you can update this file and then run nikola build again.

3) Now let's type nikola serve to serve locally all the static files built:

$ nikola serve

Point your browser to the ip/port indicated, normally it should be http://127.0.0.1:8000/

'CRTL-C' on terminal to stop it!

4) If you remember we installed livereload earlier this will help us to reload automatically our website every time we edit our code.

$ nikola auto

So this is a much nicer way than nikola serve

5) Let's keep nikola auto and let's try create a new post by running nikola new_post

$ nikola new_post

Creating New Post
-----------------

Enter title: my new post
Scanning posts....done!
[2014-02-13T16:17:46Z] NOTICE: new_post: Your post's text is at: posts/my-new-post.rst

Now edit posts/my-new-post.rst and write some text to finalize your first blog post on Nikola.

If you kept nikola auto running you will notice that your home page changed automatically and displayed the new post.

All of this also produced new static files, saved in the output/ folder which you can host on a webserver (or github) and power your awesome kickass website freely hosted.

6) Let's change the theme to bootstrap3.

$ nikola bootswatch_theme bootstrap3

This command download and install bootstrap3 on your Nikola website.
You will notice a new directory themes which contains a directory custom,
you can explore this directory to customize the bootstrap3 theme .

bootswatch_theme allow you to download and install theme from http://bootswatch.com/

7) Let's explore conf.py, let's start by configuring properly few settings:

# Data about this site
BLOG_AUTHOR = "Your Name"
BLOG_TITLE = "Demo Site"
# This is the main URL for your site. It will be used
# in a prominent link
SITE_URL = "http://getnikola.com/"
# This is the URL where nikola's output will be deployed.
# If not set, defaults to SITE_URL
# BASE_URL = "http://getnikola.com/"
BLOG_EMAIL = "[email protected]"
BLOG_DESCRIPTION = "This is a demo site for Nikola."

Other important settings you will want to configure are the menu:

# Links for the sidebar / navigation bar.
# You should provide a key-value pair for each used language.
NAVIGATION_LINKS = {
    DEFAULT_LANG: (
        ('/archive.html', 'Archives'),
        ('/categories/index.html', 'Tags'),
        ('/rss.xml', 'RSS'),
    ),
}

I think that will be enough for today, if you feel Nikola is the right tool for you, I can recommend those extra references:

 
comments powered by Disqus