Nikola (Posts by Roberto Alsina)

Nikola v8.3.3 is out!

Roberto Alsina — Sat, 17 May 2025 17:16:57 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v8.3.3. This is a bugfix release.

We’ve had to release Nikola v8.3.3 immediately after releasing Nikola v8.3.2, as it is broken on Python 3.8. We would like to thank the Python packaging ecosystem for being an incomprehensible and incompatible trainwreck.

What is Nikola?

Nikola is a static site and blog generator, written in Python. It can use Mako and Jinja2 templates, and input in many popular markup formats, such as reStructuredText and Markdown — and can even turn Jupyter Notebooks into blog posts! It also supports image galleries, and is multilingual. Nikola is flexible, and page builds are extremely fast, courtesy of doit (which is rebuilding only what has been changed).

Find out more at the website: https://getnikola.com/

Downloads

Install using pip install Nikola.

Changes from v8.3.1

Features

Trace template usage when an environment variable NIKOLA_TEMPLATES_TRACE is set to any non-empty value.
Give user control over the raw underlying template engine (either mako.lookup.TemplateLookup or jinja2.Environment) via an optional conf.py method TEMPLATE_ENGINE_FACTORY.
Switch to pyproject.toml
Add path handler slug_source linking to source of post.

Bugfixes

Ignore errors in parsing SVG files for shrinking them, copy original file to output instead (Issue #3785)
Restore annotation_helper.tmpl with dummy content - fix themes still mentioning it (Issue #3764, #3773)
Fix compatibility with watchdog 4 (Issue #3766)
nikola serve now works with non-root SITE_URL.
Stack traces meaningless for end users now more reliably suppressed (Issue #3838).

Other

Changed filter for tidy from tidy5 to tidy.

Nikola v7.8.13 is out! (maintenance release)

Roberto Alsina — Tue, 20 Mar 2018 17:50:57 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.13. This is a maintenance release for the v7 series.

Future releases in the v7 series are going to be small maintenance releases that include bugfixes only, as work on v8.0.0 is underway.

What is Nikola?

Find out more at the website: https://getnikola.com/

Downloads

Install using pip install Nikola or download tarballs on GitHub and PyPI.

Changes

Add new Thai translation by Narumol Hankrotha and Jean Jordaan (v8 backport)
Hide “Incomplete language” message for overrides of complete languages
Restore ability to override messages partially

(Note: for a while, this post said v7.8.14 was released. We apologise for the confusion.)

Nikola v7.8.5 is out!

Roberto Alsina — Fri, 12 May 2017 12:50:41 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.5. It fixes some bugs and adds new features.

What is Nikola?

Nikola is a static site and blog generator, written in Python. It can use Mako and Jinja2 templates, and input in many popular markup formats, such as reStructuredText and Markdown — and can even turn Jupyter (IPython) Notebooks into blog posts! It also supports image galleries, and is multilingual. Nikola is flexible, and page builds are extremely fast, courtesy of doit (which is rebuilding only what has been changed).

Find out more at the website: https://getnikola.com/

Downloads

Install using pip install Nikola or download tarballs on GitHub and PyPI.

Changes

Math support changes

If you edited templates related to indexes and posts (index.tmpl, post.tmpl, index_helper.tmpl, post_helper.tmpl) in your templates, you should adjust them to use math_helper.tmpl.
If you are using KaTeX, you should remove the CSS snippet from your configuration (templates), as that is now handled by Nikola.

Features

Get rid of THEME_REVEAL_CONFIG_* settings, use global context instead (Issue #2485)
New emoji shortcode
Add SECTION_PATH support to move the section indexes to a user-defined location (Issue #2738)
Add a list of template variables to documentation (Issues #2328, #2712, #2259) and update the theming reference (Issue #2259)
Add {post_title} tag for Read More links (Issue #2709)
Include MathJax config only when needed (via Issue #2715)
Include KaTeX CSS automatically when needed (Issue #2715)
Split out math code into new math_helper.tmpl template (Issue #2715)
Added jpegoptim_progressive filter to convert jpeg images to progressive jpegs.

Bugfixes

Open 127.0.0.1 when using nikola serve -b and default 0.0.0.0 hostname to avoid resolution issues — the site is still available on all interfaces (Issue #2755)
Don't break animated GIFs in postprocessing (Issue #2750)
More robust shortcodes, no need to escape URLs in reSt, work better with LaTeX, etc.
No longer creates empty subarchive pages, and no longer create broken archive navigation links on day level (Issue #2734)
Fixes post scanner plugin order (Issue #2720)
Rename POSTS_SECTION_ARE_INDEXES to POSTS_SECTIONS_ARE_INDEXES
Make date ranges work in shortcode-based post lists (Issue #2690)
Read data files only if Nikola configuration exists (Issue #2708)
Make PAGE_INDEX work with PRETTY_URLS (Issue #2705)
Fix PHP posts/pages not rendering on Windows (Issue #2706)
Improving support for PostScanner plugins by asking them which compilers are unused (Issue #2496)

Nikola Available as a Snap

Roberto Alsina — Thu, 20 Oct 2016 10:50:06 GMT

One of the larger challenges for free software developers is getting our software in the hands of the public, promptly, with the least amount of effort. Let's say that, so far, the least aount of effort has been a lot of effort.

For windows, we need to do lots of work I, personally don't want to do, so Nikola's possible windows users are left with the path of doing things like a developer, and building from source. The same for OSX users.

On Linux, thanks to the effort of a bunch of people (thanks y'all!) Nikola is available as a distro package of one sort or another for most distributions, so you can get it easily. But ... you usually will not get the latest release of Nikola, unless you are an Arch user.

I am happy to announce there is an alternative path that is a real improvement for a large number of Linux users, specifically Ubuntu users (disclaimer: I work for Canonical, I like Canonical, and I did this)

For a while I have been building Nikola as a snap after every release. But what's a snap?

A snap is a new package format that runs applications safely in a confined sandbox. That means that the packages don't need to go through as complicated a process as traditional Linux distro packages. Also, they are much, much, much easier to create.

So, if you are on a recent Ubuntu, or in one of the other distros where snaps work you can get Nikola 7.8.1 and keep it up to date, probably never more than a day behind the current release by installing it through snap:

$ snap install nikola
nikola (stable) 7.8.1 from 'ralsina' installed

Then you need to give Nikola permission to write in your home folder:

$ snap connect nikola:home core:home

And permission to use the network:

$ snap connect nikola:network core:network
$ snap connect nikola:network-bind core:network-bind

That is all. It's not, however perfect. There are a few functions of Nikola that won't currently work whe used in this way:

Some plugins that require installing 3rd party software will not work. For example, the asciidoc compiler will not be able to call asciidoc
The nikola deploy command will not work because the sandbox prevents Nikola from calling 3rd party commands. Probably the same is true about nikola github_deploy. You will have to use scripts or just run the deployment commands manually.
The -b option of nikola serve and nikola auto, which opens the site in a browser, will not work. You will have to open the site manually.
The snapped Nikola takes slightly longer to start than a regular setup (about half a second in my system)

There will also be a daily snapshot of the current code available in the snap "edge channel", as soon as I can automate it via a 3rd party build service.

Markdown can affect performance

Roberto Alsina — Tue, 18 Oct 2016 12:52:55 GMT

Markdown is a very popular input format for static site generators, that's why Nikola has supported it since very early in life, even if I prefer reSt most of the time.

One thing that has surprised me a while ago is that, considering how minimalistic markdown is, and how little it does, it can be pretty slow to process. But it turns out this is not completely markdown's fault, but that the python markdown implementation is really, really, really slow.

How slow? Let's check it out. All benchmarks in this post were done in my notebook, a nice Asus Zenbook UX305, with a fast SSD and plenty of RAM. In all cases the builds were done using no parallelization.

The test site is an empty site to which I added 1000 copies of a simple, not too large markdown file (our theming guide, converted from reSt using pandoc).

As a baseline, a site with 1000 copies of the original reSt theming.txt builds in 126 seconds.

The markdown version of that site? It gets progressively slower as files build, so I suspect it leaks something between builds, and finishes in ... 1584 seconds. That is over 12 times slower than the reSt compiler.

But you don't want to switch to reSt? No problem! We support more markdown compilers than we probably should, so you can just choose which one you prefer.

Here is a chart showing the performance of each (HTML and reSt added as reference):

There are just a few disadvantages to using any of the alternative Markdown compilers:

They are less tested, because fewer people use them (and if you use them, that changes!)
They may lack a specific feature of the "standard" markdown compiler, such as extension support (in which case, file a bug with us!)
The produced output may differ from the "standard", but that happens :-)

Really Static Comments with Staticman

Roberto Alsina — Wed, 31 Aug 2016 12:51:07 GMT

Static sites have many advantages, we always say. But they also have at least one large inherent disadvantage: they are not dynamic. Not being dynamic means that forms that alter the content of the site itself are not possible without going outside the static side of things.

That's why for comments we all end up using something like Disqus or some other alternative service, or Isso if you prefer the annoyance of self-hosting instead of the annoyance of having your data be owned by someone else.

So... how about a service that lets you do forms, but:

You keep full control of your data
The service doesn't limit what you can do with the data
You can use it for most things a form is used for?
It's free!

That service is called Staticman and it's awesome.

This is how it works:

You put your site in GitHub (or soon, Gitlab!)
You do some configuration

And Staticman will take the form's data, convert it to JSON, YAML, or whatever, and put it back in your site's GitHub repo. You can choose whether it uses "moderation", and do that via a pull request, or not, in which case it just commits directly.

Nikola can then use those data files from its templates, like in this example which displays a form to post comments, and a list of previous comments.

Then, if you combine that with an autobuild system, like using Travis or Netlify or Gitlab that means a few seconds/minutes after the form is submitted, the data appears back in the site.

So, what do we end up with? A site with comments, where you own all the data, and not even need to use Javascript to display the comments!

You can see it in action in this demo site: staticman-demo.netlify.com

TODO: submit the form via Javascript instead, so it does it in the background instead of dumping JSON results on you.

Have fun, leave a comment :-)

From Zero to Nikola in One Minute Without Installing Anything

Roberto Alsina — Tue, 30 Aug 2016 12:09:48 GMT

Maybe slightly more than one minute, but it's close to that. Thanks to netlify and GitHub (or GitLab or Bitbucket) you can create, edit and publish a Nikola-based blog without installing anything on your own computer.

This gives you about 75% of the convenience of a hosted blogging solution while keeping all the advantages of a static site, like data ownership, versioning and avoiding vendor lockin.

How to do it: you start by forking this repo and follow the steps in this video:

Keep in mind that this is not in any way a crippled version of Nikola, it has all the same features as you would get installing it on your own device, you can add themes, plugins, image galleries, etc by just adding things in your GitHub repository.

You should be able to do this with your own site, as long as it's stored in a GitHub repository and you add a requirements.txt like this one to your root directory.

So, a big round of applause for netlify for an awesome service!

Nikola v7.8.0 is out!

Roberto Alsina — Mon, 29 Aug 2016 12:50:41 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.0. It fixes some bugs and adds new features.

What is Nikola?

Nikola is a static site and blog generator, written in Python. It can use Mako and Jinja2 templates, and input in many popular markup formats, such as reStructuredText and Markdown — and can even turn Jupyter (IPython) Notebooks into blog posts! It also supports image galleries, and is multilingual. Nikola is flexible, and page builds are extremely fast, courtesy of doit (which is rebuilding only what has been changed).

Find out more at the website: https://getnikola.com/

Downloads

Install using pip install Nikola or download tarballs on GitHub and PyPI.

Changes

Features

Exposed gist as a shortcode (Issue #2459)
Always copy source files for listings (Issue #2473)
Detect dependencies in template strings (Issue #2455)
RSS feeds for sections (Issue #2068)
New data metadata that loads data from external files (Issue #2450)
Shortcode to escape to the template language (Issue #1227)
Added link to raw file in listings (Issue #1995)
New NO_DOCUTILS_TITLE_TRANSFORM (Issue #2382)
Update options of chart directive to Pygal 2.2.3
Pass global context to template shortcodes (Issue #2424)
Added new options --html2text and --transform-to-markdown to WordPress importer (Issue #2261)
Listing: guess the lexer if cannot be determined from the file name.
Read files from data/ and insert data in global context (Issue #2477)

Bugfixes

Added link to sources in the output of listing directive (Issue #2472)
Fix Windows crash with calendar locales (Issue #2332)
Remove the (useless) <base> tag by default; change conf.py to opt in (Issue #2471)
Show tag descriptions when TAG_PAGES_ARE_INDEXES is True (Issue #2444)
Record template dependencies for post-list shortcut (Issue #2451)
Default to English for docutils messages if no translations exist (Issues #2422, #2437)

Nikola v7.7.7 is out!

Roberto Alsina — Thu, 10 Mar 2016 17:16:24 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.7.7. It fixes some bugs and adds new features.

What is Nikola?

Nikola is a static site and blog generator, written in Python. It can use Mako and Jinja2 templates, and input in many popular markup formats, such as reStructuredText and Markdown — and can even turn Jupyter (IPython) Notebooks into blog posts! It also supports image galleries, and is multilingual. Nikola is flexible, and page builds are extremely fast, courtesy of doit (which is rebuilding only what has been changed).

Find out more at the website: https://getnikola.com/

Downloads

Install using pip install Nikola or download tarballs on GitHub and PyPI.

Changes

Features

New --one-file option to wordpress importer (Issue #2262)
New Pygal-based chart shortcode (Issue #2170)
Add post_type to post-list directive (Issue #2272)
Use sys.executable for launching pip in plugin (Issue #2275)

Bugfixes

Fix Indonesian translation (Issue #2291)
Fix a JSON conversion bug in the WordPress importer (Issue #2264)
Don’t create download directories when not downloading WordPress attachments (Issue #2260)
Don’t display "Good link" messages in nikola check -l by default, can be re-enabled with -v option (Issue #2268)
Fix a format string in nikola check (Issue #2267)
Don't crash wordpress importer when posts are "empty" (Issue #2263)
Don't put untranslated and nonexistent posts in sitemap (Issue #2289)

Nikola v7.7.6 is out!

Roberto Alsina — Wed, 17 Feb 2016 18:47:19 GMT

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.7.6. It fixes some bugs and adds new features.

What is Nikola?

Nikola is a static site and blog generator, written in Python. It can use Mako and Jinja2 templates, and input in many popular markup formats, such as reStructuredText and Markdown — and can even turn Jupyter (IPython) Notebooks into blog posts! It also supports image galleries, and is multilingual. Nikola is flexible, and page builds are extremely fast, courtesy of doit (which is rebuilding only what has been changed).

Find out more at the website: https://getnikola.com/

This is a bugfix release, fixing a critical error in version 7.7.5's support for IPython/Jupyter notebooks. If you had upgraded Nikola to version 7.7.5 and suddenly got errors or empty pages for your notebooks, upgrade to 7.7.6 and run nikola build -a to get everything in order.

Really sorry!

Downloads

Install using pip install Nikola or download tarballs on GitHub and PyPI.

Changes

Features

Add FRONT_INDEX_HEADER setting to allow adding greeting notices to the main index page (Issue #2249)

Bugfixes

Make Jupyter posts build (Issues #2248, #2252)