Nikola v8 is a huge release with lots of new features and fixed bugs. However,
a few manual changes are required to upgrade.
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
- 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.
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.
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.
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™)
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
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)
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 signatured 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)
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'
on Nikola master. (If you have customized that setting, you will need
to change it to use CLDR-style date formats.)
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
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 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.
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.
-
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
-
NO_DOCUTILS_TITLE_TRANSFORM has been removed, behavior now depends on USE_REST_DOCINFO_METADATA (Issue #3124) (added 2018-09-06)
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
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.
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
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!)