Nikola v7.8.5 is out!

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 v7.8.4 is out!

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.4. 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

  • Refactor RSS feed generation to allow better plugin access
  • Add Jupyter config as dependency for jupyter posts (by @knowsuchagency)
  • Make nikola plugin --list-installed more readable (Issue #2692)
  • Accept now in post-list date conditions
  • Add RSS_COPYRIGHT, RSS_COPYRIGHT_PLAIN, and RSS_COPYRIGHT_FORMATS options in conf.py which can be disabled by specifying copyright_=False to generic_rss_renderer, or overriden by specifying an explicit value.
  • Write PID of detached nikola serve process to a file called nikolaserve.pid
  • Append file name (generated from title) if nikola new_post receives directory name as path (Issue #2651)
  • Add a require_all_tags parameter to the post-list directive to show only posts that have all specified tags. (Issue #2665)
  • Add META_GENERATOR_TAG option in conf.py allowing the meta generator tag to be disabled (Issue #2628)
  • Add YUI_COMPRESSOR_EXECUTABLE, CLOSURE_COMPILER_EXECUTABLE, OPTIPNG_EXECUTABLE, JPEGOPTIM_EXECUTABLE and HTML_TIDY_EXECUTABLE to configure executables for built-in filters. (Issue #2615)
  • Allow setting custom GUID in feeds (Issue #2378)

Bugfixes

  • Remove misplaced and duplicated meta description tags (Issue #2694)
  • Fix crash if PAGE_INDEX is enabled and make them actually work (Issues #2646, #2702)
  • Ignore NEW_POST_DATE_PATH when creating pages (Issue #2699)
  • Ensure post.updated is timezone-aware (Issue #2698)
  • Pass previously missing post object and language to reST compiler and language to Markdown compiler (for shortcodes)
  • Fix crashes when rendering subcategories (Issue #2681)
  • Prevent writing cache files outside of the cache folder (Issue #2684)
  • Fix mimetype guessing in auto mode (Issue #2645)
  • Fix filters.html5lib_xmllike for laters html5lib (Issue #2648)
  • Skip the current post in post lists (Issue #2666)
  • Fix poor performance when compiling multiple markdown documents with the markdown compiler. (Issue #2660)
  • Fix crash if SHOW_INDEX_PAGE_NAVIGATION is True while INDEXES_STATIC is False. (Issue #2654)
  • Make NEW_POST_DATE_PATH follow rrule if it exists (Issue #2653)

Nikola v7.8.3 is out (emergency bugfix release)

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.3. This is an emergency bugfix release, which fixes a bug that prevented nikola new_page from working. There has also been a minor change to post sorting order (won’t affect most sites). The wheel packages have also been fixed (they now exist for Python 2 and 3, with correct doit versioning).

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

  • Sort posts chronologically with one unified function (easier to change). (Issue #2627)
  • Sort posts in the following order (most important last): source path (A-Z), title (A-Z), date (reverse chronological order), priority meta number (descending). (Issue #2627)

Bugfixes

  • Fix a bug that prevents nikola new_page from working (Issue #2631)

Nikola v7.8.2 is out!

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.2. It adds a ton of new features, while also fixing some bugs.

Key Changes

  • A rewrite of all taxonomies (tags, categories, sections, etc.) in a generic fashion, allowing for much greater flexibility (by Felix Fontein) — adds new settings, enables new features (CREATE_ARCHIVE_NAVIGATION) and customizability
  • Automatic cration of year/month/day directory structures (NEW_POST_DATE_PATH)
  • Ability to sort posts from within templates (sort_posts)
  • API changes for post compilers (new compile, compile_string functions)
  • Addition of a generator meta tag to default themes — we hope you do not mind a bit of promotion for Nikola?

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

Minor API change: The compile_string compiler method (partially internal) now takes a post argument and returns between two and four values, adding shortcode_deps and shortcode support. See issues #2623 and #2624.

Features

  • Add meta generator tag to default templates to promote Nikola (Issue #2619)
  • Add nikola new_post -d and NEW_POST_DATE_PATH to allow automatic creation of year/month/day (date-based) directory structures (Issue #2513)
  • Allow enabling pretty URLs with per-post setting (Issue #2613)
  • Add a sort_posts function (available as Jinja filter in global context), which allows general-purpose timeline sorting (Issue #2602)
  • Allow creating archive navigation (Issue #1639)
  • Accept a page argument for taxonomy paths (Issue #2585)
  • Query strings in magic links are passed as keyword arguments to path handlers (via Issue #2580)
  • Accept arbitrary arguments to path handlers (via Issue #2580)
  • Added new typogrify_oldschool filter (Issue #2574)
  • Improving handling of .dep files, and allowing compilers to specify additional targets for the render_posts task (Issue #2536)
  • render_template and generic_renderer can now create HTML fragments.
  • Allow posts to set custom URL_TYPE by using the url_type meta tag (useful for HTML fragments inserted using JavaScript)
  • Plugins can depend on other plugins being installed (Issue #2533)
  • The destination folder in POSTS and PAGES can now be translated (Issue #2116)
  • Pass post object and lang to post compilers (Issue #2531)
  • Pass url_type into template's context.
  • Make thumbnail naming configurable with IMAGE_THUMBNAIL_FORMAT.
  • There is a new plugin category Taxonomy which allows to easily create new taxonomies. All of the existing taxonomies (authors, archives, indexes, page index, sections, tags, and categories) have been converted to the new system. (Issue #2107)
  • Added CATEGORIES_INDEX_PATH, similar to TAGS_INDEX_PATH. (Issue #2567)
  • Made INDEX_PATH, RSS_PATH and AUTHOR_PATH translatable. (Issue #1914)
  • Added setting SHOW_INDEX_PAGE_NAVIGATION which enables a basic page navigation for indexes. (Issue #2299)
  • Added settings DISABLE_INDEXES_PLUGIN_INDEX_AND_ATOM_FEED and DISABLE_INDEXES_PLUGIN_RSS_FEED to disable specific parts of the classify_indexes taxonomy plugin. (Issue #2591)

Bugfixes

  • Work around conflicts between posts and sections trying to render index.html files (via Issue #2613)
  • Make AUTHOR_PAGES_ARE_INDEXES really work (Issue #2600)
  • WordPress importer now correctly handles & etc. in tags. (Issue #2557)
  • If CODE_COLOR_SCHEME is empty, don’t generate code.css (Issue #2597)
  • Don’t warn about nikolademo DISQUS account when comments are disabled (Issue #2588)
  • Make data from global context available to templated shortcodes as global_data (Issue #2488)
  • Don't crash if plugins is a file (Issue #2539)
  • Don't mangle bare # links (Issue #2553)
  • generic_index_renderer now always produces output. It previously did not when the post list was empty and INDEXES_STATIC == False. (via Issue #2579)

Nikola Available as a Snap

Note

This is all slightly experimental

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

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):

Seconds to build (bigger is worse) 00100100200200300300400400500500600600700700800800900900100010001100110012001200130013001400140015001500158472.67350427350428267.00000000000006194127.80512820512821492.28773310023314126182.93675213675215503.3090034965035110238.06837606837607505.9022435897436564293.20000000000005513.357808857808934348.331623931624518.220134032634132403.46324786324783518.544289044289125458.5948717948718519.678831585081614513.7264957264957521.4616841491842Seconds to build (bigger is worse)markdownkramdownrestpandoccommonmarkmistunemistune+cythonmisakahtml

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 :-)

Nikola v7.8.1 is out!

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.1. 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

Bugfixes

  • Rename stories to pages in most of the codebase (Issue #1891)
  • Report missing/unknown dates in posts with filenames (Issues #2505, #2506)
  • Report filename of post that raised exception when scanning (Issue #2505)
  • Accept page and pages for the type field in post lists
  • Don’t crash if a post list has no posts (Issue #2489)

Features

  • Add Hebrew translation by Yitzhak Bar Geva
  • Add Chinese (Traditional) zh_TW translation by Po-Wen Chi
  • Add nikola theme --list-installed (Issue #2504)
  • Add KATEX_AUTO_RENDER setting to configure math delimiters
  • Update KaTeX version to 0.6.0: support aligned math display
  • Better support for a tree of files in data/

Really Static Comments with Staticman

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:

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

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!

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)