- 1. Upgrade Hexo
- 2. Upgrade Theme
- 3. References
Recently I decided to update my Hexo blog to the latest version and start to writing posts again. The process was not that smooth. So I wrote this post in case anyone needs any help.
The breaking changes in 3.1.1, to me, are that many modules within hexo before are divided further into independent ones. It is hard to update because the structure is so different, not as simple as just update the hexo CLI. We need to do way more than that.
The first thing is to follow the document provided by the developer. It is said to be of help when migrating from 2.x to 3.0.
Add hexo data to package.json.
If you use rss in your blog, you should also install the feed generator.
The theme I have been using is derived from Jacman. I did lots of tuning on the details and disconnected it from its original git repo. So it is hard for me to upgrade it just by git pull.
The problem I first had was the page just didn’t show. It showed a bunch of unprocessed ejs code instead like below.
I found the solution in the common hexo problems post. It is very simple. Just run
npm install under your blog post directory again to install and enable the ejs renderer.
Alright, now the page shows and everything looks good. After I scrolled to the bottom, I found that the author img is not showing. The log in browser debugging tool simply said that the img is not found on server.
But the image is in its directory, not changed at all. That leads me to the answer that the path is wrong. The root path should be “/“. But it is “/css” in the log.
The problem was noticed by the Jacman theme developer. You can find his post on how to support Jacman with hexo 3.0. The reason is the code in
This line reads root path from config. In hexo 3.0 if root path is set to “/“ or not left blank, it would fail to get the correct path.
The fix is to change
The result line should be like below.
This is another problem introduced by previous version of Jacman theme. It failed to leave out the zero-post categories and tags, which is very annoying if you have lots of new categories or tags in your draft folder.
To solve this problem, you can update to the latest version or just add a if block to check post length.
The same goes for
When I tried to use other themes for a change, I found that the links for posts were wrong. This seems to be a bug for hexo 3.1.1.
The temporary fix is to set relative_link to false in _config.yml for now. Hope that it would be fixed soon.
Then I opened some posts to double check everything was good. It turned out that all code blocks are not working anymore. The line number is always 1 not matter how many rows in it. And the syntax was not highlighted either. This is also caused by hexo 3.1.1. The reason is that highlight.js interpret the code as plain text.
We can manually set language for each code block. But that would be too much work. Instead, we can set auto language detection of highlight.js. Add the config below to manually enable detection in _config.yml.