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:

1
2
3
4

/2014-08-19-awesome-post.md
/2014-08-19-awesome-post/
  screenshot.png
  document.pdf

The compiled file structure will be like this:

1
2
3
4

/2014/08/19/awesome-post/
  index.html
  screenshot.png
  document.pdf

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

1
2
3

![ScreenShot](screenshot.png)
[Document](document.pdf)

Then this will be compiled as following Html:

1
2
3
4
5
6

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

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:

1
2
3

![ScreenShot](/2014/08/19/awesome-post/screenshot.png)
[Document](/2014/08/19/awesome-post/document.pdf)

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.

When writing blog with [Hexo], I uses hexo new command to create new post file. If the title of the post is provided, then the file is named according to the tile. This is super convinient, and I’m really loving it.

But there is problem! If I changed my mind when during the writing, so I changed the title of the post. As a consequence, the post file name doesn’t match to the post title any longer.

In the past, I have to rename the post file manually. If there is asset folder, I also have to remember rename it accordingly. And I have to becareful to avoid introduce typo, or it either break the reference or cause other problems.

Besides, if you have special name pattern for your post, such as have time-stamp in your post name. The problem is more complicated. You have to reserve the time-stamp carefully, and replace all the space or any other improper characters with -.

At least for me, it is a complicated, error-proning and unpleasant work to do.

I’m a lazy guy, I don’t want to repeat this pain time and time again. To save myself from such pain, I create the plug-in hexo-console-rename.

The plug-in reads the front-matter of the post, then figure out the proper name. It is smart enough to know what is the proper name for the post, when you changed your configuration, it changes its behavior also.

To use the plug-in is super easy. I usually use it in this way:

1

$ hexo r source/**/*.md

Then it scans all the posts for me, and fix the filename when necessary. Easy and efficient.

Advanced Usages

Actually after I created the plugin, I figured out sevearl advance usages of this plug-in. Sometimes, it could become your life savor!

new_post_name updated

If you change the new_post_name in your _config.yml. You new post will follow a different name pattern than old ones. At this time, you might really want to rename all the old posts to keep consistency! But do it manually is a painful job to do!

Then hexo-console-rename is your live-savor! You just run

1

$ hexo r -p ':title.md' source/**/*.md

Then all the old files will be renamed under your new naming rule! Aesome!

date in your post changed

It isn’t a common case, but if you have changed the date field in the front-matter of your post. And you have time-stamp in your file name. You can also use hexo-console-rename to rename the file for you.

For more detail, check out the hexo-console-rename home page.

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:

1

{% 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.

JSONView is a very popular JSON formatter for Chrome, which automatically prettifies the JSON content.

JSONView provide a very sweety feature that allow user to customize the css used to format the JSON. And I love dark theme and the Consolas font so much, so I customized my dark own dark theme for JSONView.

Here is my theme css, and you can copy it to your JSONView theme editor to apply.
Also you can find code on gist: https://gist.github.com/timnew/5167241

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

body {
  white-space: pre;
  font-family: consolas;
  color: white;
  background: black;
}
.property {
  color: orange;
  font-weight: bold;
}
.type-null {
  color: gray;
}
.type-boolean {
  color: orangered;
}
.type-number {
  color: lightblue;
}
.type-string {
  color: lightgreen;
}
a {
  color: dodgerBlue;
}
.callback-function {
  color: gray;
}
.collapser:after {
  content: "-";
}
.collapsed > .collapser:after {
  content: "+";
}
.ellipsis:after {
  content: "...";
}
.collapsible {
  margin-left: 2em;
}
.hoverable {
  padding: 1px 2px 1px 2px;
  border-radius: 3px;
}
.hovered {
  background-color: rgba(255, 255, 255, .3);  
}
.collapser {
  padding-right: 6px;
  padding-left: 6px;
}