.. title: Upgrading to Nikola v8 .. slug: upgrading-to-nikola-v8 .. date: 2018-05-05 18:55:43 UTC .. tags: nikola, documentation .. category: .. link: .. description: How to upgrade to Nikola v8? This is a list of all things you need to take care of first. .. type: text .. author: Chris Warrick .. updated: 2018-09-10 19:00:00 UTC .. class:: lead Nikola v8 is a huge release with lots of new features and fixed bugs. However, a few manual changes are required to upgrade. .. class:: alert alert-primary .. contents:: 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 ============== 1. Upgrade to the latest v7 version: ``pip install Nikola==7.8.15`` and make sure there are no outstanding warnings. 2. Upgrade to v8: ``pip install -U --upgrade-strategy=eager Nikola==8.0.0`` 3. Read the upgrade notes below and `the full changelog`__ 4. Upgrade all third-party plugins and themes. (``nikola plugin --upgrade``, ``nikola theme --upgrade``) 5. Run ``nikola status`` and fix all warnings. 6. When all warnings are fixed, run ``nikola build``. 7. Run ``nikola check -l`` and ``nikola check -f``. If there are broken links or orphaned files, take care of them. __ https://getnikola.com/changes.html 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. __ https://plugins.getnikola.com/v8/upgrade_metadata_v8/ 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``) __ https://getnikola.com/handbook.html#featured-posts 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 ```` (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. __ https://github.com/getnikola/nikola/issues/2833 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 --------------------------------------- .. code:: python 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: .. code:: mako ${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: .. code:: text 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!)