Nikola v7.8.9 is out! (maintenance release)

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

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 or download tarballs on GitHub and PyPI.

Changes

  • Restore missing unminified assets
  • Make failures to get source commit hash non-fatal in github_deploy (Issue #2847)
  • Fix a bug in HTML meta parsing that crashed on <meta> tags without name (Issue #2835)
  • Fix math not showing up in some circumstances (Issue #2841)

Nikola v7.8.8 is out!

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.8. It fixes some bugs, some related to metadata support, while also adding more internationalization 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 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

This release fixes two grave bugs in TOML metadata support (sorry!). The built-in themes have also been cleaned up and include less unused assets. In addition, taxonomies now support translations. HTML meta tags are also possible metadata sources. The default metadata format to generate can now be changed.

Features

  • Providing infrastructure for taxonomies for classification pages to link to related classifications in other languages
  • Added alternate links (visible and header) for archives and authors (Issue #993)
  • Added options to add alternative links (visible and header) for tags, sections and categories.
  • New METADATA_FORMAT option to choose preferred metadata format (Nikola/YAML/TOML/Pelican) (Part of Issue #2801)
  • Extract metadata from HTML meta and title tags like Pelican (Issue #1923)
  • Update assets in the base and base-jinja themes and clean up code (Issue #2744)
  • Show captions in the base theme gallery (Part of issue #2777)

Bugfixes

  • Fix two grave bugs in TOML metadata
  • Require just one line break after TOML/YAML metadata
  • Add alt attribute to images in galleries in base theme (Part of issue #2777)
  • Support empty lines in YAML/TOML metadata (Part of issue #2801)
  • Tests run on macOS.

Nikola v7.8.7 is out!

On behalf of the Nikola team, I am pleased to announce the immediate availability of Nikola v7.8.7. This is a part-emergency bugfix, part-world domination release.

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

In an effort to improve interoperability with other static site generators, make importing data easier, and help with world domination, Nikola v7.8.7 ships with support for the following metadata formats:

  • reST-style comments (.. name: value — default format)
  • Two-file format (reST-style comments or 7-line)
  • Jupyter Notebook metadata
  • YAML, between --- (Jekyll, Hugo)
  • TOML, between +++ (Hugo)
  • reST docinfo (Pelican)
  • Markdown metadata extension (Pelican)

In addition, Markdown is now enabled and required by default. More details: https://getnikola.com/handbook.html#metadata-formats

The release also fixes two important bugs, one that crashes when trying to detect locale in some edge cases, and another which made some themes quietly leak template files. If you’re using a Jinja2-based theme that does not have its own parent file, please force a rebuild (nikola build -a).

Features

  • Enable markdown by default (part of Issue #2809)
  • Allowing to register filters from plugins, and allowing to specify default filters as strings of the form filters.<name> (part of Issue #2475)
  • Support ignoring assets via ignore_assets theme meta field (Issue #2812)
  • Ignore unused Colorbox locales (Issue #2812)
  • Accept tag metadata as lists for YAML/TOML (Issue #2801)
  • Support for mapping metadata from other formats to Nikola names using the METADATA_MAPPING setting (Issue #2817)
  • Support for reStructured text docinfo metadata with USE_REST_DOCINFO_METADATA option, defaulting to False (Issue #1923)
  • New HIDE_REST_DOCINFO option, defaulting to False.
  • Support for Markdown Metadata for Pelican compatibility by adding 'markdown.extensions.meta' to MARKDOWN_EXTENSIONS (Issue #1923)
  • Support for YAML and TOML metadata (Issue #2801)

Bugfixes

  • Use inheritance tree when looking for theme engine (Issue #2816)
  • Fix unbound variable error in locale guessing (Issue #2806)

Nikola v7.8.6 is out!

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

Downloads

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

Or if you prefer, Snapcraft packages are now built automatically, and Nikola v7.8.6 will be available in the stable channel.

Changes

Features

  • Guess file format from file name on new_post (Issue #2798)
  • Use BaguetteBox as lightbox in base theme (Issue #2777)
  • New deduplicate_ids filter, for preventing duplication of HTML id attributes (Issue #2570)
  • Ported gallery image layout to base theme (Issue #2775)
  • Better error handling when posts can't be parsed (Issue #2771)
  • Use .theme files to store theme metadata (Issue #2758)
  • New add_header_permalinks filter, for Sphinx-style header links (Issue #2636)
  • Added alternate links for gallery translations (Issue #993)

Bugfixes

  • Use locale.getdefaultlocale() for better locale guessing (credit: @madduck)
  • Save dependencies for template hooks properly (using .__doc__ or .template_registry_identifier for callables)
  • Enable larger panorama thumbnails (Issue #2780)
  • Disable archive_rss link handler, which was useless because no such RSS was ever generated (Issue #2783)
  • Ignore files ending wih "bak" (Issue #2740)
  • Use page.tmpl by default, which is inherited from story.tmpl (Issue #1891)

Other

  • Limit Jupyter support to notebook >= 4.0.0 (it already was in requirements-extras.txt; Issue #2733)

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 &amp; 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 :-)