Index ¦ Archives ¦ RSS > Tag: nikola

On Nikola

Eight months ago I switched this site to using Nikola. It is a static site generator which takes a bunch of files on disk and spits out your site in HTML, ensuring there are links everywhere as appropriate, applying templates etc. You then serve up those HTML files via any regular web server. (The opposite approach is a CMS.)

Sadly there is one design pattern that has severely affected my use of it. Nikola attempts to only do the work necessary each time you do a build. For example if you create a new post, it wants to only generate the HTML for that post and update the indexes that list posts. This should be a lot faster than generating everything from scratch.

Sadly it is nowhere near that simple. For example a setting in the configuration file could change how posts are output (eg point to a different template) which requires everything to be rebuilt. Or something could have been deleted or renamed, actions that Nikola doesn't know about. It would have to scan the output directory for files and deduce they should be deleted/renamed too. Once you add in templates, processors, configuration settings this gets very complicated.

When I first started using Nikola I quickly discovered that it would frequently get the incremental builds wrong. I did report them to the author who was surprised that any existed, and was sceptical. I have no doubt it always worked for him though!

Through the bug tracker I discovered others seeing even more cases of the incremental builds being wrong. I quickly resorted to doing full clean builds since there is no evidence Nikola would ever get incremental builds right in all circumstances. The result was me being happy.

My long experience has left me with several principles when using software to build outputs:

  • A build then clean then build should give the same results between the two builds
  • Doing the build on different machines should give the same result
  • If incremental building is possible then it must give the same results as a full clean build

If these principles are not met then the output is non-deterministic. That means you can't depend on it, and testing it is problematic.

An example of this is Nikola generated sitemaps. It uses the date of the generated file in the output directory as the date of change in the sitemap. That breaks all 3 principles above. An approach that would work correctly is to give the output file the same timestamp as the input file. Sadly the author refuses to fix the problem.

This is the straw that breaks the camel's back for me. I don't want the content of my site to vary based on what type of build I did, to differ between machines, or when I do the build. So I have to figure out what to migrate to, or write my own.

Writing general purpose software is harder than just writing something for internal use. I applaud the author for making that effort and doing a good job. But there are times where principles matter, and we don't share these particular ones.

Category: misc – Tags: nikola


All Change

Things look different here. The hand written HTML and styles were from a decade ago, and didn't really support my resume's claim of long time proficiency in the web arts. (It was of course "cobbler's children have no shoes" syndrome.)

I also originally supported Google Plus, and posted occasional content there. However over the last 6 months or so Google has made maximum efforts to make reading it as difficult as possible. I missed having somewhere to post the periodic rants and finds.

Now you can see my fix. This site is built using Nikola which ticks the boxes for simplicity, using Python, and not requiring yet more usernames and passwords, complicated servers and databases, worrying about various attacks, maintenance etc. Under the hood there is jquery and bootstrap, but ironically I write this content even further removed from the web arts than before.

There is even an rss feed which pleases me a lot compared to the Reader shutdown, and walled garden of Google Plus. Anyone can read (and respond thanks to disqus) in virtually any way that works for them.

Doing the conversion was relatively easy but somewhat tedious. Nikola let me keep existing files and do incremental conversions. My resume took a while as the structure wasn't that good. pandoc does a good first pass on other docs.

I also redid all my Google Plus posts here in this blog. Data Takeout let me get the underlying data, but it took many hours of Python coding to munge the data into a reasonably good looking and compatible format.

Category: misc – Tags: nikola

Contact me