升级指南

本文同时提供以下语言的翻译： English.

从6.x升级至7.0

1. 第一次运行hexo时，Icarus会备份_config.icarus.yml并把它升级到7.0.0版本。 _config.post.yml等布局配置文件和front-matter不会被升级。 请在其中删除head.open_graph.type: blog、head.open_graph.google_plus和Gitalk的client_secret，并为没有头像的个人信息挂件设置avatar: /img/avatar.png。 另外请检查以下配置：

   • Waline的image_uploader、highlighter、tex_renderer和search选项设为true时禁用对应功能，未设置或设为false时保留。
   • 分类页面按per_page分页。 如要保持只有一页，请在_config.yml中设置category_generator.per_page: 0。

2. 请检查你使用的插件：

   • Facebook评论、Share.js、百度分享、AddThis和Google FeedBurner subscribe_email挂件已被移除，Valine、Gitment和Cusdis已弃用。 请换用其他插件。
   • Gitalk 2需要一个GitHub App和你自己的代理（在proxy中设置）。 请重新生成client secret，因为旧的已经公开在你的页面中。
   • 请将Twikoo后端升级到2.0.17，Artalk服务端升级到2.10。 如要让Artalk服务端的选项优先于配置文件中的选项，请设置prefer_remote_conf: true。
   • 自定义的Waline阅读量计数需要在data-path属性中填写页面路径。
   • 自定义的DisqusJS模板需要使用DisqusJS 3的API。
   • 自定义的图库脚本需要使用lightGallery 3和justified-gallery 4的原生API。 lightGallery 3采用GPLv3或商业许可。

3. Cyberpunk变体显示logo_dark中设置的logo，代码使用JetBrains Mono字体，代码块使用自己的配色。 /img/razor-top-black.svg和/img/razor-bottom-black.svg已被删除。

4. 自己托管MathJax 4时需要完整的mathjax和@mathjax/mathjax-newcm-font两个包。

5. 如果你保留了主题文件的自定义副本，请在7.0的文件上重新应用你的修改：

   • source/css/style.styl已改名为source/css/_style.styl。
   • layout/misc/paginator.jsx和layout/widget/profile.jsx已被删除。
   • 导航栏和PJAX的代码移到了source/js/navbar.js、source/js/appearance.js和source/js/pjax-*.js。
   • 目录、搜索、回到顶部和复制按钮都是<button>元素。
   • 页面不再加载moment.js。
   • 处理页面内容的自定义脚本需要同时在pjax:complete事件中运行。

从5.x升级至6.0

1. 将Node.js升级到14.0或者更新的版本，并将Hexo升级到7.1.1或者更新的版本。

2. 下载源代码或者从NPM安装Icarus 6.x。 你可以在Icarus快速上手中找到安装指导。 如果你打算通过修改源代码的方式自定义主题，你必须从源代码安装主题。

3. 运行hexo clean来清理缓存并让Icarus为你升级主题配置文件。

4. 阅读更新说明和最新文档来了解更多新功能的信息。

从4.x升级至5.0

1. 将Node.js升级到12.4.0或者更新的版本，并将Hexo升级到6.0或者更新的版本。

2. 下载源代码或者从NPM安装Icarus 5.x。 你可以在Icarus快速上手中找到安装指导。 如果你打算通过修改源代码的方式自定义主题，你必须从源代码安装主题。

3. 运行hexo clean来清理缓存并让Icarus为你升级主题配置文件。

4. 阅读更新说明和最新文档来了解更多新功能的信息。

从3.x升级至4.x

1. 将Node.js升级到10.13.0或者更新的版本。

2. 下载源代码或者从NPM安装Icarus 4.x。 你可以在Icarus快速上手中找到安装指导。 如果你打算通过修改源代码的方式自定义主题，你必须从源代码安装主题。

3. 运行hexo clean来清理缓存。 按照Icarus的提示安装缺失的依赖软件包：

   命令行

   $ 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. 再次运行hexo clean来让Icarus为你升级主题配置文件。 Icarus会备份并删除themes/icarus/_config.yml文件，然后创建_config.icarus.yml作为新的主题配置文件。 你可以参考_config.icarus.yml.example来了解示例配置。

   命令行

   $ 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现在将文章的缩略图和封面图区别对待。 对于有缩略图的所有文章/页面，将其front-matter中的thumbnail:更改为cover:。

   post.md

     title: Icarus快速上手
     date: 2020-04-01
   - thumbnail: /gallery/covers/vector_landscape_1.svg
   + cover: /gallery/covers/vector_landscape_1.svg
   ---

   你仍可以在front-matter中设置thumbnail来在文章归档页面以及最新文章挂件中显示小一点的缩略图。

6. 阅读更新说明和最新文档来了解更多新功能的信息。