Upgrading to Nikola v8

Chris Warrick — Sat, 05 May 2018 18:55:43 GMT

Nikola v8 is a huge release with lots of new features and fixed bugs. However, a few manual changes are required to upgrade.

Revisions to this document

2018-09-08: moved tag_cloud_data.json generation to separate plugin

2018-09-06: Removed NO_DOCUTILS_TITLE_TRANSFORM setting

2018-07-07: Beta 3: Babel and changes to i18n

2018-05-13: Beta 2: bootblog4 has featured posts, zen modernized; one new backwards incompatible change found and described (reference replaces image-reference in thumbnails)

2018-05-09: fixes to style and missing sentences

2018-05-05: initial version

How to upgrade

Upgrade to the latest v7 version: pip install Nikola==7.8.15 and make sure there are no outstanding warnings.
Upgrade to v8: pip install -U --upgrade-strategy=eager Nikola==8.0.0
Read the upgrade notes below and the full changelog
Upgrade all third-party plugins and themes. (nikola plugin --upgrade, nikola theme --upgrade)
Run nikola status and fix all warnings.
When all warnings are fixed, run nikola build.
Run nikola check -l and nikola check -f. If there are broken links or orphaned files, take care of them.

Upgrading post metadata

There are a few changes in post metadata you should make:

draft and private tags are now status metadata values (eg. .. status: draft)
mathjax tag is now a has_math metadata key (eg. .. has_math: yes)

Both changes can be applied by using the upgrade_metadata_v8 plugin.

Changes to themes and templates

The default theme for Nikola was changed to bootblog4, which has a modern, clean look, and can optionally display featured posts. There’s also bootstrap4 with the classic look. The bootstrap3 theme is not included by default, but can still be installed (nikola theme -i bootstrap3)

Moreover, there are a few changes to templates that you must take care of if you’ve customized any:

Rename crumbs.tmpl to ui_helper.tmpl and the breadcrumbs bar function to breadcrumbs (your templates may need changing as well)
Rename post.is_mathjax to post.has_math. Themes using post.is_mathjax must be updated; it is recommended that they are changed to use math_helper.tmpl.
For galeries and images, colorbox was replaced by baguetteBox.

zen modernized and uses new Font Awesome

The Zen theme was thoroughly modernized. The modernization means that:

Font Awesome v5 is used by default, you can switch to Fork Awesome v1 by installing zen-forkawesome
Your conf.py needs changing to reflect new icon names and classes (Font Awesome v5 examples: 'fa fa-tags' and 'fab fa-twitter')
the zen-ipython theme is not needed anymore, zen and zen-jinja handle Jupyter posts correctly (as do the built-in themes)
the theme internals were rewritten to more closely match built-in themes (notably, galleries Just Work™)

Backwards incompatible changes

The following changes may cause issues with blog appearance and links. Please make sure you’ve taken care of them before deploying.

Sections are replaced by categories (Issue #2833) — see below
Reading reST docinfo metadata, including first heading as title, requires USE_REST_DOCINFO_METADATA now (Issue #2987)
NO_DOCUTILS_TITLE_TRANSFORM setting removed, behavior now depends on USE_REST_DOCINFO_METADATA (Issue #3124) (added 2018-09-06)
RSS feeds might have changed their places due to RSS_PATH behavior changes (you may need to change RSS_PATH, RSS_FILENAME_BASE)
Atom feeds for archives and Atom pagination are no longer supported (Issue #3016)
(added 2018-05-10) You need <a class="reference"> (instead of image-reference) to activate the lightbox now
(added 2018-09-08) tag_cloud_data.json now requires a separate plugin: nikola theme -i tagcloud

Babel and i18n changes (added 2018-08-07)

For a long time, Nikola’s i18n features depended on the system locale support. That led to a bunch of issues and strange bugs. We’ve replaced this with the Babel library. New features include:

more flexible date formatting
no more strange bugs related to system locale configuration
translated dates even if system support was not there (eg. on Alpine Linux, cf. discussion on issue #2606)
proper forms for some Slavic languages (eg. marzec vs marca)

DATE_FORMAT changed

DATE_FORMAT uses different tokens. If you customized DATE_FORMAT, you need to change it to use CLDR formats. (Hint: the new default value is YYYY-MM-dd HH:mm)

babeldates plugin obsoleted, LocaleBorg internal API changed

The babeldates plugin is obsoleted by the changes. If you were using it, rename BABEL_DATE_FORMAT to DATE_FORMAT and remove the plugin.

In addition, the LocaleBorg extension API was simplified. The new API expects extension authors to create functions matching the signatures and assign them to the following names:

LocaleBorg.datetime_formatter(date, date_format, lang, locale)
LocaleBorg.in_string_formatter(date, mode, custom_format, lang, locale)

Translation help wanted

However, this means that we needed to reorganize translations. In order to have things in a working state, I used some guessworks and tried to produce a working form. However, not all languages will have grammatically correct output at this point. This is why we need help from our community around the world.

So, if you have the time, please help us check if our translations (on Transifex or GitHub) are correct. Specifically, we need to know if the date tags (in “Posts for XX” messages) are correctly placed. We also need to know if the translation for those fits the required form. To find out, you can run the test script and check how all the forms look for your locale. If they don't fit, they can be overridden: for example, Polish uses “Posty z {month_year:MMMM yyyy}” and takes advantage of the last bullet point.

As a bonus, the use of Babel means that it's even easier to use "human-friendly" dates on your blog — try setting DATE_FORMAT = 'long'.

Removed and renamed settings

The following settings have been removed. Nikola will now always behave as if the value was what is displayed afer the setting name.

FEED_PREVIEWIMAGE = True
SITEMAP_INCLUDE_FILELESS_DIRS = True
USE_OPEN_GRAPH = True
USE_BASE_TAG = False
NO_DOCUTILS_TITLE_TRANSFORM — behavior now depends on USE_REST_DOCINFO_METADATA (Issue #3124) (added 2018-09-06)

The following settings were renamed:

UNSLUGIFY_TITLES → FILE_METADATA_UNSLUGIFY_TITLES
TAG_PAGES_TITLES → TAG_TITLES
TAG_PAGES_DESCRIPTIONS → TAG_DESCRIPTIONS
CATEGORY_PAGES_TITLES → CATEGORY_TITLES
CATEGORY_PAGES_DESCRIPTIONS → CATEGORY_DESCRIPTIONS
DISABLE_INDEXES_PLUGIN_INDEX_AND_ATOM_FEED → DISABLE_INDEXES and DISABLE_MAIN_ATOM_FEED
DISABLE_INDEXES_PLUGIN_RSS_FEED → DISABLE_MAIN_RSS_FEED

Sections were replaced by categories

Sections were an unfinished feature. Having both sections and categories at the same time made no sense. The sections feature was removed and replaced by categories. Categories now support using the destination path, with the possibility to ignore common prefixes, and to use subdirectories. Categories can do everything sections used to.

The way to migrate depends on what your blog setup was:

if you were only using categories, you don’t need to do anything (except for the two renamed settings mentioned above)
if you were only using sections, read on or details of required changes
if you were using both, you’ll need to pick one of the two (beware: might break links)

PS. the section_prevnext plugin has been renamed category_prevnext for v8.

Changes to posts

If your posts are using the section metadata field, you should rename it to category. Nikola will do this conversion automatically if no category is specified, while also issuing a warning.

Changes to configuration

POSTS_SECTION_TITLE has been merged into CATEGORY_TITLES (whose name has changed from CATEGORY_PAGES_TITLES)
POSTS_SECTION_DESCRIPTIONS has been merged into CATEGORY_DESCRIPTIONS (whose name has changed from CATEGORY_PAGES_DESCRPTIONS)
In order to activate the path-based behavior, enable CATEGORY_DESTPATH_AS_DEFAULT
To control what is used to generate paths, you can set CATEGORY_DESTPATH_TRIM_PREFIX and CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY (old sections behavior/default values are False and True respectively, but flipping them makes the feature much more flexible)
POSTS_SECTION_NAME is now CATEGORY_DESTPATH_NAMES
POSTS_SECTION_COLORS is not supported by default, but you can replace it with some manual tinkering
CATEGORY_ALLOW_HIERARCHIES, CATEGORY_OUTPUT_FLAT_HIERARCHY are heavily recommended if you use CATEGORY_DESTPATH_AS_DEFAULT, and required if you use CATEGORY_PAGES_FOLLOW_DESTPATH

Recreating the old behavior of sections

CATEGORY_ALLOW_HIERARCHIES = True
CATEGORY_OUTPUT_FLAT_HIERARCHY = True
CATEGORY_DESTPATH_AS_DEFAULT = True
CATEGORY_DESTPATH_TRIM_PREFIX = False
CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY = True
CATEGORY_PAGES_FOLLOW_DESTPATH = True

Colorizing categories (or anything, really)

The colorization feature is now available for anything, not only sections. Templates can use the colorize_str(string, base_color, presets) function, like so:

${colorize_str(post.meta('category'), theme_color, category_colors)}

You need to add category_colors to the global context manually — this expects a regular (untranslated) dict mapping category names to hex colors.

Plugins

If you are using section_prevnext, remove it and install category_prevnext instead.

If you are using the projectpages plugin, you can migrate your metadata like this:

sed 's/.. status:/.. devstatus:/g' *.rst -i
sed '/.. featured: False/d' *.rst -i
sed 's/.. featured: True/.. status: featured/g' *.rst -i
sed '/.. hidden: False/d' *.rst -i
sed 's/.. hidden: True/.. status: private/g' *.rst -i

On YAML configuration

One of the features we’ve promised for Nikola v8 was YAML config. We’re afraid we won’t offer this in the v8.0.0 release just yet. Doing this right will require substantial amounts of time, and the v8 project has been going for over a year.

Rest assured: we haven’t scrapped this idea. YAML config will appear in a future v8.x.0 release. Before that happens, we need to build a configuration management framework, with support for migrations among other things — its main focus will be Nikola config, but we hope to make it flexible enough to work anywhere. (If you’re aware of a good project that does this, do tell us!)

Nikola (Posts about documentation)

Upgrading to Nikola v8