I messed with Nikola a while back, but ended up going with Hugo. Nikola has evolved in the last couple years, though. Let’s check it out!
Nikola is a static site generator written in Python. Its features support a flexible workflow while still providing a solid blogging experience “out of the box.” You can extend that flexibility further via plugins.
That focused flexibility intrigues me. Cleaning my site after Hugo deprecated the mmark format was a chore. My site has too many moving parts for me to casually port it, but I can still play a little.
Setup
It’s generally a good idea to have a dedicated Python environment for each of your projects. So I’ll set something up with pyenv and pyenv-virtualenv.
Next is Nikola itself. I’ll follow the suggestion to install Nikola[Extras], which includes all sorts of niftiness.
Initialize the site
Let’s initialize an empty site.
Okay, no need to paste the entire exchange. Suffice to say that many questions are asked. And as Nikola itself mentions, we can skip those questions questions with nikola init -q
.
We get a configuration file written in Python and a handful of empty directories. I see nothing for themes, but that’s okay. Nikola starts us off with the bootblog4 theme. We can pick or make new themes later.
My answers to Nikola’s setup questions sit up there near the top of conf.py
.
The rest of the file lists and explains default configuration. You could learn almost everything you need about Nikola from the configuration file. Nevertheless, I plan to keep the documentation handy.
Local Development
Nikola includes a built-in server to check your site locally. We have no content yet, but let’s take a look anyways.
The auto
command instructs Nikola to serve your site, refreshing whenever you save a change. With the --browser
flag, it also opens a new browser tab to your development site.
NOTE
Unless you’re in tmux, in which case it depends on how your desktop and tmux are configured. I had to run
nikola auto --browser
from a separate terminal tab in Linux Cinnamon to get the browser action. I’ll look up how to fix that eventually.
http://127.0.0.1:8000
shows a basically empty front page. Nikola filled in the templates for the default theme with values from conf.py
.
Each of the “Archive,” “Tags,” and “RSS Feed” links lead to summary pages with nothing listed. Since I have no content for Nikola to summarize yet, that makes sense.
Following the “Random Geekery” link at the top takes me to the live site. I consider this incorrect behavior. We want to see how the development site works, not the live site.
We can probably fix that in theme templates or with an option, but for the moment let’s just update config.py
.
And now the site title header links to the front page. Perfect for today.
Let’s start blogging!
Blogging with Nikola
Nikola supports an overwhelming number of options, especially when you start looking at plugins. That works great for someone like me. I constantly get new ideas not quite covered by the expected workflow, regardless of what that flow is.
Of course, “an overwhelming number of options’ is not the same as “unopinionated.” Unopinionated tools expect you to create your own workflow — or copy someone else’s. Despite its many options, Nikola includes a default workflow.
Writing a blog post
The new_post
command asks you for a title and uses that to create a file from your settings.
Fire up an editor — or do it automatically with nikola new_post -e
— and add something!
Unless you configure it differently, Nikola uses reStructuredText for new posts. RestructuredText, or ReST, is a formatting language similar in spirit to Markdown. The syntax looks different, but they share a purpose: simplified writing compared to HTML for everything. And of course Markdown is supported for those who prefer it.
Nikola reads our post’s metadata from ReST comments at the front of the file. I know I will miss something important if I tried summarizing it. Let’s just link to Nikola’s own metadata documentation.
What does the site look like now that it has a post?
This theme shows post content. I prefer showing a quick summary of posts on the front page.
And a comment in the post to show where the cutoff point is:
Now the index has a summary and the main content is on the post page. The tag rests at the bottom, and a source link sits with the headline.
What about that “Source” link? Nikola lets you download the ReST source of a post. Neat, but not a feature I care about.
Okay I need to stop. I intended to focus on the default Nikola flow. But here I am poking at config.py
. Oh well. I gotta be me.
But still let’s move on.
The Archive, Tags, and RSS Feed links work, listing posts as expected. The lists aren’t very interesting with only one post though. I’ll see what I can come up with for next time. Oh and I’m not sure I can properly describe how excited I am that Archive automatically generates pages for years. I didn’t have to make a special-purpose taxonomy or anything!
Adding Pages
Anyways. Blogging is good, but a site needs more than blog posts. Let’s use nikola new_post -p
to create a page instead of a post.
Everybody could use a now page. Excuse me a moment while I edit pages/now.rst
. Oh! Since it’s not a post, it won’t show up unless we link to it. The /now
page is significant enough that it should go on the site menu.
Back over to config.py
:
What’s left?
If this was a really real site, we would build and deploy.
Nikola has a deploy
command? Well sure! You can configure multiple deployment options. rsync — my favorite — even gets highlighted in the commented example.
But I’m leaving that section of config.py
alone for now.
This was fun! Will I replace Hugo with Nikola? I don’t know yet. I’d have to try importing and building the current site.
That sounds like a project for another day.
Backlinks
Added to vault 2024-01-15. Updated on 2024-02-01