Update Hexo 3.0

Spend a whole night working on updating Hexo. It is much more complicated than I expected. For anyone’s convenience, I record some key points when migrate from Hexo 2.x to 3.0 besides the official documentation.

First things first: uninstall Hexo

Yes. Though the official wiki says that we can directly migrate from 2.x to 3.0, this doesn’t work (to me). Besides, instead of wasting time figuring out what’s wrong when updating, re-installating and configurating Hexo 3.0 seems acceptable to me. You can try to update directly but I didn’t do that successfully.
Before your uninstallation, backup your posts and any other custom setting files (eg. _config.yml, your own theme file, etc).
To uninstall Hexo, use the node package manager(npm):

npm uninstall hexo 

Now, install Hexo 3.0

Run

$ sudo npm install -g hexo-cli

Hexo wiki doesn’t mention the administration permission, but in my experience we have to add sudo here.

Then we need to setup hexo folder in your desired place(folder).

$ hexo init <folder>
$ cd <folder>
$ sudo npm install

Still, try sudo when you fail to run any command.

For your future convenience, we install all necessary services here:

npm install hexo-generator-index --save
npm install hexo-generator-archive --save
npm install hexo-generator-category --save
npm install hexo-generator-tag --save
npm install hexo-server --save
npm install hexo-deployer-git --save
npm install hexo-deployer-heroku --save
npm install hexo-deployer-rsync --save
npm install hexo-deployer-openshift --save

and any plugins you probably need:

npm install hexo-renderer-marked@0.2 --save
npm install hexo-renderer-stylus@0.2 --save
npm install hexo-generator-feed@1 --save
npm install hexo-generator-sitemap@1 --save

All in sudo mode (or you can directly do all of these in sudo -i mode).
Now, we finished installation.

Next, configuration

As before, most of the configurations are the same (in _config.yml), but some tricky changes are:

1. deploy to github
   Instead of set it as github, set it to git. Otherwise you will be fail when deploy to github.
   In case you didn’t know how to deploy, go to this page and follow the instruction.

2. content in each page
   You will probably find that in archive or category, lots of posts are lost. This is because all pages show the number of posts as the per_page: 10. (see this issue(chinese) in github) If you want to modify each page’s content, try add the following in _config.yml:

   archive_generator:
     yearly: true
     monthly: true
     per_page: 0
   
   category_generator:
     per_page: 0
   
   tag_generator:
      per_page: 0

   About the theme, I prefer to add any feature or change anything by modifying the default theme(landscape) since it is a perfect suit for current Hexo version. If you use any third party theme you will probably find that it costs you long time generating all your posts when you have plenty of (200+) them.

According to the issues appear on github, there are many other problems in version 3.0. The killed problem is that some of the expressions (eg "-") can’t appear appropriately. Since Octopress also released its 3.0 early this year, I am wondering should I try to use Octopress. But the news is actually not that exciting on its website. So, question mark here.