Hexo file name escape issue and solution

I’m working on reorganize posts today, and found some filename issue with Hexo.

Speical symbols are not escaped properly

Just found this issue today.

To ensure filename generate from title is legal as either file name or url path, Hexo uses hexo.util.escape.filename to escape the illegal symbols. filename does escape some symbols, but it doesn’t cover all illegal symbols, such as +, =, &, etc. If these symbols are not escaped properly, which generates illegal url link. As a result, your post will never be acessible.

I found this issue is because, I have a post with +3 trainer in its title, since + is not escaped, and + will be treated as space by http. As a consequence, my post will never be able to open, unless I escape + as %2B. To avoid this kind of problem, I wish all the symbols in post name are escaped as -.

Besides this issue, Hexo has another issue with name escaping that the escaped file name might contains continues -. For example, your post title is “A great introduction - part 1”, you will get escaped name a-great-introduction---part-1.md. I wish the continues - in the file name should be replaced with single -, name a-great-introduction-part-1.md is more readable than previous one.

To fix the 2 issues, I just created a pull request, hope it will be merged soon.

I cared about this issue so much is because I uses hexo-consle-rename plug-in, which also uses util.escape to handle file name. To keep naming consistency when between different version of Hexo, I addd a kind of evil monkey patch in the v0.1.2. So make sure the plug in can work properly even with old Hexo.

File name case issue

Besides the Hexo naming issue, I also met the case of the filename today. Although it depends on the blog hosting, but it might cause 404 if the file name case changed.

To avoid this kind of issue, I strongly recommend to set filename_case: 1 in _config.yml, which will make sure all file name are in lower case.

There is common pitfall here for Windows or Mac with case-insensitive file system. If you have deploy the website once with wrong filename casing. Regenerate after updated filename_case won’t help, because file system won’t treat case change in filename as “change”. So you cannot really commit the “change” to fix the 404 issue.

To fix this issue, there is easy and efficient trick. Go to .deploy folder, execute following commands:

$ git rm -rf *
$ git ci -m "Clean all file"
$ hexo clean
$ hexo d -g

To force clean the repo once enforce git to treat 2 files with same name but different casing as different ones. So the name casing issue can be fixed.

Use Hexo Asset Folder to manage resource used by post

Hexo asset folder is a folder that with the same name as you post file, the content in which will be copied to the folder where the rendered post html file located. It is a great way to keep the relationship between the post and its referenced resources. Personally, I prefers to put all the images or other downloadable files that referenced by the post into its asset folder.

Although asset folder is a great idea, but in practice, there are some common pitfall might disappoint you badly.

Relative Path Pitfall

The idea of asset folder is actually based on an assumption, that the asset resources will be placed under the same folder with the html. The html can reference these files with relative path.

Suppose we have following files as post file:


The compiled file structure will be like this:


The asset files are located in the same folder as the html file. So in the post file, you can reference the resource files as


Then this will be compiled as following Html:

<img src="screenshot.png">
<a href="document.pdf">Document</a>

So far it looks great. But if you open your home page of you site, you find the image isn’t displayed, and the link to document.pdf is also broken.

The problem here is that the the relative path assumption only works in /2014/08/19/awesome-post/index.html. But the content compiled from 2014-08-19-awesome-post.md might also be used by HomePage(/index.html), Archive Page(/archive/index.html), and tag pages and category pages. For these html pages, the relative path relationship doesn’t exist. So the relative link causes 404 error.

To solve the issue, someone use absolute url in the post. So they write markdown in this way:


This approach fix the link issue, but makes you lost the benefits of using relative path.

So you need hexo-tag-asset-res, which allow you to reference asset resources with relative path. It will convert them into absolute path during compilation. Easy and efficient.

Empty asset folders

For convenience, I turned on the post_asset_folder to true in my _config.yml. So the asset folder will be created along with post when I execute hexo new. It is great because create asset folder manually is boring and error-proning. If you introduced a typo carelessly, the link will be broken immediately.

But by ask Hexo to create asset folder automatically causes another problem. I don’t really have asset resources for each post, then there must be a number of empty asset folders. So I wish these folders can be removed if it is empty.

For this purpose, you might need hexo-console-clean-asset-folder. This plugin helps you to remove all the empty asset folders automatically.

Rename the post

Well, renaming a post already published is that common. But it is very likely to rename a draft. When renaming the post file, you have to remember also rename the asset folder too, or the link will broken.

To help you on this issue, you might need hexo-console-rename. The plugin helps you to rename the asset folder along with post. And it also helps you on migration once you updated your new_post_name pattern.

So this is the common pitfalls in using asset folder in Hexo, and the plug-ins that help you to mitigate the pain.

New Favicon design for my blog

To ㊗️ my wife passed driver license theory course, I created a new log for my blog 😝

Here is what I got:

Logo for ThoughtWorkshop


Gear is the hint of workshop. Because this blog is named as TimNew's ThoughtWorkshop

In the beginning, I was intend to create the gear in Steampunk style. I like such old-fashioned style, but later I found such style is not distinguishable in small icon, so I simplified it to the dark-metel gear.


Letter D is from the pronunciation of my Chinese name, which might not be well-known. It is a personal logo, so I wish to have something personal in it.

The font is Gear Box from Gaut Fonts.

It is an awesome font to create some mechanical feel design.

Gear Box Logo

The rainbow color is the hint of unrestrained idea and inspiration. In Chinese, it reads 天 🌌 马 🐎 行 ✈️ 空 🚀 不 🚫 靠 🎵 谱.

Well, this is it.

Embed CodePen snippet in Hexo

CodePen is a service that provide Html, JavaScript and Css live show-case. It is another clone of Js Fiddle, but with cooler UI and support.

Both CodePen and Js Fiddle provides embedded widget that allow user to embedded their code into blog or articles.

Here is the example, code from CodePen:

This is from Js Fiddle:

Hexo has built-in the Js Fiddle Plug-in to allow writer to embed code from Js Fiddle, which is probably ported from Octopress.
But for CodePen, there is not such thing.

So I created hexo-tag-codepen, its provides similar syntax as built-in ‘Js Fiddle’ plug in:

{% codepen userId|anonymous|anon slugHash theme [defaultTab [height [width]]] %}

Now you can embedded Pens from CodePen in your Hexo blog. Enjoy.

For detail, check out hexo-tag-codepen document.

Migrate Blog to Hexo

This post is a celebration for the migration from Octopress to Hexo

Octopress has done an excellent job on filling the gap between jekyll and full function repo based blog engine. But because of the tech stack it is based on. It isn’t really a awesome framework to use.

The first time I got pissed off by Octopress was by the end of 2012. Then I come up the idea to rewrite it in Node.js. But I wasn’t able to make it happen, because I was held by the new project assignment, and didn’t have too many spare time on the blog engine.

To save effort, I began to customize Octopress by rewriting some code in Octopress and Jekyll, which started the long march of Octopress customization.

I did a number of customization on Octopress, from erb template to Jekyll generators, from Rake script to TextMate bundles.

Before I switch to Sublime, I uses TextMate for quite long time. So I customized the Rake script and TextMate bundle, which enables me to invoke almost every rake command in TextMate with hotkey. I can even rename the blog post file name according to the title in front-matter without leaving TextMate. Besides the functionality, I also customized the templates and the widgets a lot to get better visual effects and reading experience.

I’ve benefited from these customization a lot. On the other hand, these deep customization blocks me from migrating to Hexo, a better alternative. Even I have found Hexo in the early 2013, and believe it is a better blog platform. But it is really costy for me to migrate the blogs away from the Octopress.

Luckily, after years development, a bunch of tools and libraries came up, which has minimized the gap between Octopress and Hexo.
After several days effort, finally retired the Octoress engine, and completed the journey of moving from Octopress to Hexo.