Upgrade Guide

This article is also available in 简体中文.

Upgrading from 5.x to 6.0

1. Upgrade Node.js to 14.0 or a newer version.

2. Install Icarus 6.x either via source code dowload or NPM install. You can find instructions in Getting Started with Icarus. If you plan to customize the theme by altering its source code, you are required to install the theme from source code.

3. Run hexo clean to clear cache files and let Icarus upgrade your theme configuration file for you.

4. Check out the release notes and the latest documentation for more information of the new features.

Upgrading from 4.x to 5.0

1. Upgrade Node.js to 12.4.0 or a newer version.

2. Install Icarus 5.x either via source code dowload or NPM install. You can find instructions in Getting Started with Icarus. If you plan to customize the theme by altering its source code, you are required to install the theme from source code.

3. Run hexo clean to clear cache files and let Icarus upgrade your theme configuration file for you.

4. Check out the release notes and the latest documentation for more information of the new features.

Upgrading from 3.x to 4.x

1. Upgrade Node.js to 10.13.0 or a newer version.

2. Install Icarus 4.x either via source code dowload or NPM install. You can find instructions in Getting Started with Icarus. If you plan to customize the theme by altering its source code, you are required to install the theme from source code.

3. Run hexo clean to clear cache files. Install any missing packages as prompted by Icarus:

   Shell

   $ hexo clean
   ...
   ERROR Please install the missing dependencies your Hexo site root directory:
   ERROR npm install --save hexo@^5.0.2 hexo-component-inferno@^0.8.2 hexo-log@^2.0.0 hexo-util@^2.2.0
   ERROR or:
   ERROR yarn add hexo@^5.0.2 hexo-component-inferno@^0.8.2 hexo-log@^2.0.0 hexo-util@^2.2.0

4. Run hexo clean again to let Icarus upgrade your theme configuration file for you. Icarus will back up and remove themes/icarus/_config.yml, and then create _config.icarus.yml as the new theme configuration file. You can refer to _config.icarus.yml.example for example configurations.

   Shell

   $ hexo clean
   ...
   WARN  Your theme configuration is outdated (3.0.0 < 4.0.0).
   INFO  To skip the configuration upgrade, use "--icarus-dont-upgrade-config".
   INFO  Backing up theme configuration files...
   INFO  themes/icarus/_config.yml => themes/icarus/_config.yml.dc00f8b8f8bc03ede351d711e958dc4b
   INFO  Upgrading theme configurations...
   INFO  Theme configurations are written to /tmp/_config.icarus.yml.
   INFO  Example configurations is at /tmp/_config.icarus.yml.example.

5. Icarus now treats post thumbnails and cover images separately. For any posts/pages with an thumbnail image, change thumbnail: to cover: in the front-matter:

   post.md

     title: Getting Started with Icarus
     date: 2020-04-01
   - thumbnail: /gallery/covers/vector_landscape_1.svg
   + cover: /gallery/covers/vector_landscape_1.svg
   ---

   You can still set thumbnail in the front-matter to show a smaller thumbnail image for your posts in the archive page and in the recent post widget.

6. Check out the release notes and the latest documentation for more information of the new features.