Installation

This assumes that you have virtualenvwrapper.sh installed which isolates this installation from other projects you may have installed locally.

Create a virtual environment

bash$ mkvirtualenv myenv ↵
This command creates a new virtual environment named "myenv". You can choose any name you like as long as it makes sense to you. Because I use this virtual environment for Nikola, I unimaginatively call mine "nikola". Once the command has completed, virtualenvwrapper automatically puts you in that virtual environment as shown by the prefix "(myenv)".

Optionally integrating shell completion

Adding shell completion is optional, but a nice addition that Nikola provides. The following two commands enable Nikola-specific tab-completion when you activate your virtual environment, and disable it when you deactivate the virtual environment.

If you use zsh instead of bash, you can specify "--shell zsh" instead of "--shell bash".

Deactivating the virtual environment

(myenv)bash$ deactivate ↵
This exits the virtual environment you created. Alternatively, you can just quit your command shell using "exit ↵". During initial setup, you can skip this step, as you'll just need to reactivate the virtual environment to install Nikola.

Reactivating the virtual environment

bash$ workon myenv ↵
This will activate the "myenv" environment again, as well as put the environment-name indicator in your prompt. If you didn't deactivate the virtual environment using deactivate, then you won't need to reactivate your virtual environment.

Install Nikola

(myenv)bash$ pip install Nikola ↵
Inside your virtual environment (as shown by the environment-name inside parentheses before your usual prompt), this uses pip to fetch the latest version of Nikola and install it. This brings in a number of dependencies, some of which may need to be compiled. As such, if you don't have a compiler installed on your machine, you'll want to do that before this step.

Create a new blog

(myenv)bash$ cd /path/to/your/blog ↵
(myenv)bash$ nikola init myblog ↵
You can choose a name that you like for the folder instead of "myblog" (or similarly boring reasons, I named mine "blog"). This creates a folder called /path/to/your/blog/myblog in which your content, templates, cache, and output will go. It also prompts you for the name of your site, the main author's name, the main author's email address, a description of the site, the root URL for the site (which should end with a trailing slash such as "http://example.com/"), the languages you intend to use, your time zone, and which comment system you want to use (if any).

Configuration

Nikola's configuration takes place in "/path/to/your/blog/myblog/conf.py". Opening this file in your favorite text editor, you'll notice that the answers you gave during the "nikola init" process appear as the values to various settings within this file.

By default, Nikola expects markup to be reST but I prefer the straight-forward nature of HTML. So my first stop was to add HTML as a processed language. By putting it first in the list, it becomes the default for new_post which saves me from forgetting to specify the template as "-f html" every time I generate a new post. To do this, I modified the "POSTS = (…)" and "PAGES = (…)" to include the following lines:

POSTS = (
    ("posts/*.html", "posts", "post.tmpl"),
    ("posts/*.rst", "posts", "post.tmpl"),
    ("posts/*.txt", "posts", "post.tmpl"),
)
PAGES = (
    ("stories/*.html", "posts", "post.tmpl"),
    ("stories/*.rst", "stories", "story.tmpl"),
    ("stories/*.txt", "stories", "story.tmpl"),
)

I want to have my templates contain additional metadata fields for author (allowing me to easily override this for guest posts) and category. To do this, I found the comment containing ADDITIONAL_METADATA and added the following lines:

ADDITIONAL_METADATA = {
    "author": BLOG_AUTHOR, # default to me
    "category": "uncategorized",
    }

I also customized the CONTENT_FOOTER to show a minimal copyright notice:

CONTENT_FOOTER = """
    Contents © {date}
    <a href="mailto:{email}">{author}</a>
    {license}
    """
CONTENT_FOOTER = CONTENT_FOOTER.format(
    email=BLOG_EMAIL,
    author=BLOG_AUTHOR,
    date=time.gmtime().tm_year,
    license=LICENSE,
    )

To round out some personal preferences, I explored the Nikola handbook and added the following settings in their respective places:

PRETTY_URLS = True
SOCIAL_BUTTONS_CODE = "" # I don't want social buttons
COPY_SOURCES = SHOW_SOURCELINK = False # not very useful with HTML fragments
USE_BUNDLES = False # may change this later

Finally, I wanted to enable automated deployment of my blog to my web-hosting service. To deploy without needing to enter the password for my hosting service, I set up SSH keys and used ssh-copy-id to push the public key up to my server. With that in place, I adjusted the (formerly empty) list of commands DEPLOY_COMMANDS .

DEPLOY_COMMANDS = [
    "rsync -avr --delete output/ {login}@{host}:{path}".format(
        login="myusername",
        host="thechases.com",
        path="/home/myusername/public_html/",
        ),
    ]

This allows me to deploy by simply issuing "nikola deploy".

With Nikola installed and configured to my liking, it's time to go write some blog posts.