After taking a look at a couple of more “mainstream” blogging systems, I was looking for a way to do some blogging and not deal with over-engineered systems that are bloated with unnecessary features. I didn’t want to spend time in understanding the details required to actually tweak those systems and customize them to my liking.
And then I found static website generators like Jekyll and Hexo. After choosing Hexo because it used a more familiar toolset, I found out that I actually understood how it worked without investing too much time. And with my (VERY!) limited knowledge of web programming I could tweak it and make my blog to look and feel the way I wanted it.
“Great…” I hear you say “… now how do I do that?”

Setting up

The idea behind is simple. The Hexo system compiles with Node.js a static website from a template and it’s pages from markdown files.
Setting up a minimal blog is easy. After installing Node.js on your system, we simply need to execute

$ npm install hexo-cli -g
$ hexo init blog

That’s it! The last command will create a folder named ‘blog’ with necessary files to generate your website (blog?)
The next step is to actually check that it works. Simply, execute the following.

$ hexo generate
$ hexo server

Now you have a local webserver running that will host your blog and you can test it. (by default it would be http://localhost:4000)

Customizing it

Setting up is nice, but nobody really wants a website with default look and feel. So, now what?

First step would be to design the look and feel of the website, which can be done in two ways.

  • If you have some knowledge in web development, you can have a go at creating your own theme for Hexo. This would probably require some web design skills with CSS and knowledge of one of the supported Javascript template engines (such as EJS, Haml, Jade, or Pug. A good starting place would be in this article and Hexo’s documentation article can be useful as well.
  • If you are like me and don’t know that much about web development, you can simply get one of existing themes and tweak it to your liking. At the very minimum, it would involve fiddling with _config.yml file inside the theme’s folder, but tweaking around page templates and CSS is also possible, of course.

For example, in case of this blog, I took an existing theme - “Butterfly” and tweaked it a little.

Creating content

Finally, when the tweaking is complete it is time to actually write something, this is why why wanted a blog in the first place, no?

Running the following console command will create an empty post with specified title - which is simply a markdown file at [Hexo root]/source/_posts/[post title].md

Console command to create a new post:

$ hexo new post <title>

You can read more about writing in Hexo in relevant documentation article.

Publishing it

After finishing writing a post or two, it is time to publish the website.
We would start by executing the following command in the console:

$ hexo generate

This would “compile” markdown and theme’s templates into a static website, which then can be deployed to a hosting service.

Note: the destination of such “compilation” would be [Hexo root]/public folder

Now, after we generated our static website, it is time to deploy it. Before doing that, we would need to configure Hexo’s deploy command in the _config.yml file, a command that can be used to deploy compiled website to one or more destinations.
For example, the following will enable deployment to a git repository

type: git
repo: [repository url]
branch: [branch name]

You can read more about the deploy command in it’s documentation article.

So, that’s it. Have fun blogging!

Actually, I think this blog post is a bit longer than it could (or should!) be, but I wanted to be thorough, especially since this is my first blog post :)