Blogging with Hexo note

Let’s talk about static site generators. More specifically, lets talk about Hexo - a static site generator built on node.js. A good friend of mine had suggested I check it out after expressing some interest in other similar technology. My initial exposure to static site generators up until this point has been non-existent. After doing a bit of reading on the advantages of static vs dynamically generated content, the solution seemed to fit my modest needs quite well. I dont have time to manage back-ends and latest security updates for a wordpress/drupal/sharepoint driven site and I am most definitely not going back to the days of managing each individual page manually. With a static site generator, I have the freedom to change and refine layouts and introduce widgets and other iterations in a manageable way. All I simply need to do is regenerate the content based on my updated template files and upload the new source files.

Being sold on the premise that this technology is precisely what I need, I was quickly brought down to earth with the realization that my experience with CLI’s has been practically nil. Fortunately, once node.js and npm are installed, setting up hexo is a breeze.

Setting up

Installing hexo using npm turned out to be quite simple. Hexo’s website does have at least some thorough instruction on the topic of installation and project setup. If you have node and npm installed, setting up a new hexo project directory is a matter of executing a few simple commands.

  • npm install hexo-cli -g
  • cd <project directory>
  • hexo init <new folder>
  • cd <new folder>
  • npm install

Doing so creates a default project structure under <new folder> including a scaffolds, source and themes directory, a _config.yml and package.json file. Using hexo’s generate command will create a public directory, housing all of your site’s static files.

Basic commands

Using hexo requires only a few basic commands to generate, test and even push your content to a repository. Hexo allows you to also lazy-type these commands for extreme brevity, for those who are averse to typing out full commands. Admittedly after using them rather frequently, this is a pretty convenient feature to have.

To begin viewing your blog locally, simply type the following into your console:

  • hexo server

Hexo then creates a build of your source material and launches a local server at port 4000. Any updates to your content can be viewed quickly with a simple refresh of the browser (sans-caching). Any changes that require a database refresh or a global configuration update will require a manual command to clean things up. Close any current sessions you have running (via Ctrl +C) first, then enter:

  • hexo clean

To generate the static files that your site will comprise of, use the aptly named command:

  • hexo generate

A public directory is created to serve as the root directory for your generated files. All files that hexo recognizes as a renderable format will be generated, while other resource files such as javascript, css, media, etc., will be copied directly over. Files preceded by an underscore will be ignored when copying resource files to the public folder.

For a larger run-down of commands and alternative flag support, you can view hexo’s documentation on commands

Creating content

Content created with hexo is a simple process. A content file is created from the command-line, which hexo then sorts into a source directory in the root folder. You can specify a ‘layout’ for your content, which looks for a corresponding ‘scaffold’ (located in the scaffold directory in the root folder) file to derive the structure of the new content file. Hexo then populates some very basic properties in the new file’s front-matter, including the title and date. The file generated is a markdown file and can then be opened and edited to add specific content to your entry. The command for creating a new entry looks like this:

  • hexo new [layout] <title>

Where [layout] is the type of layout (or scaffold) you wish to base your entry’s structure from, and <title> is the name of your entry. A title that includes space should be encapsulated by parenthesis.

By default, hexo will use the post layout for your new entry. Other natively supported layouts include page and draft. New posts and drafts have their own subdirectory, while a new page will create a custom subdirectory based on the new page’s name. Custom layouts can be referenced by creating a new scaffold markdown file placed in the scaffold directory under root, then using the scaffold name as the layout name for your new entry.

An unfortunate limitation of the current implementation of layout customization is that all custom layouts are treated identically as posts. Custom layouts are generated in the /posts subdirectory and are stored within the posts variable within hexo. This seems to limit the usefulness of creating custom layout types as there is no proper way to group them as separate collections from posts. The main drawback to this is how deeply certain modules are tied to the posts collection such as pagination. Thankfully hexo supports some rather handy sorting and filtering methods to quickly grab collections from your main posts collection for your convenience.


Within the themes directory are subdirectories containing your custom theme files. By default, hexo ships with a rather non-aesthetically-pleasing ‘landascape’ theme. There are a number of existing themes to download and utilize for an out-of-box experience, which can be found on hexo’s theme page and likely searchable on github. Your applied theme is set in the root _config.yml file. A clean-up command and server reset is required to reflect theme changes.

the layout subdirectory contains your theme’s template files. Hexo routes all page generation through a generic ‘layout’ template file. This is a common structure that all of your pages will inherit (if any). your layout template will have a body which routes to other template files conditionally. Template files can load other segments of template files to stitch together more elaborately structured pages.

Hexo natively supports Swig templating engine, and other template engine plugins for EJS, Haml and Jade can be found on github or downloaded via hexo’s plugin command. Switching templating engines is as simple as using the proper file extension in your file naming convention.Additionally, hexo can compile Sass, Less and Stylus with the proper plugins installed.


Hexo seems to be a very solid static blog generator. It has a healthy catalogue of plugins which provide a range of options for template engines and preprocessors, as well as other modules to assist in theming your site. There are a range of free themes to select from featuring clean layouts for a variety of uses. Hexo’s page generation is fast and as a novice in the realm of CLIs its commands are simple to navigate.

One of the largest drawbacks to the platform is a lack of documentation on many of the more in-depth topics of interest that anyone looking to create their own theme will be yearning to know. Be prepared to be scraping google searches and stack-overflow threads for the specific answers that you may be looking for as they are the best and only source to find the answers to certain questions.

As I discover more specific details on certain theme development information I intend to write about them in greater depth. Otherwise I have been rather pleased to have finally found a rather manageable solution to assist in site creation with the balance of flexibility and stability that I have been so desperately searching for. I anticipate support for the platform to grow and for certain elements of flexibility to be ironed out in the future.