Hexo is The Jam!

There are dizzying number of static site generators. Excessive choice and paralysis by analysis are now part of the javascript ecosystem.

I've used the ruby-based generators (Middleman, Jekyll). I've also used content management solutions like Ghost, Wordpress, and the like. So far, Hexo is my absolute favorite static site generator. Here's why:

  • It's lightweight and fast
  • It's javascript-based, which makes tweaking things a little easier
  • Deployment is easy (deploy to Heroku, AWS, Github pages, DigitalOcean in a few steps)
  • The plugin system is robust (making plugins is easy)
  • The command line interface is robust
  • Uses markdown/yaml

But the biggest merit of Hexo is that it lacks the demerits of other blogging solutions. Let me explain.

The Problem With Ghost

Ghost is OK. But it can be a pain to configure and deploy. Updating Ghost is not as straightforward as it could be. The CMS seems bloated for simply serving up static files. There are no plugins. What if you want to spin up a new website in 10 minutes? Ghost is not so quick to deploy and customize.

The Problem With Middleman

Middleman was fun. It uses yaml, whick is a plus. But the community is relively dead. Configuration is challenging (my personal bias - I'm not a ruby guy).

The Problem With Gatsby

Gatsby is a static site generator built around React. React is sexy, no doubt. It fits with one's mental model of what a UI framework should be. But Gatsby seems like a prime example of overengineering at its finest. Why would I want to write JSX, only to have it compiled into html?

Hexo Quickstart

I'll assume that npm is intalled on your machine, but that's about it.

First, install the Hexo command line interface globally.

npm install hexo-cli -g

Now let's start a new project:

hexo init my-project
cd my-project

Your project structure will look something like:

  • scaffolds
  • source
  • _drafts
  • _posts
  • themes/landscape
  • themes/_config.yml

Generate your static site with:

hexo generate

Your static files will be generated in the folder public.

Creating Your First Post

If you poke around in source/_posts, you'll see that posts are marked files with frontmatter, e.g.:

title: deploy-a-hexo-blog.md
date: 2017-07-10 22:50:35
- javascript
- hexo


Hexo 3 dissociated the server from the main node module. Therefore you need to install hexo-server:

npm install hexo-server --save

Start the server:

hexo server

Aside: you don't need to use the node server in production. Hexo generates static files in ./public that can be served up with nginx, Apache, etc.


Deploymnet options with Hexo are unlimited.


Install the heroku deployment plugin:

npm install hexo-deployer-heroku --save

Add these settings to _config.yml

Create a new heroku project:

cd my-project
heroku create
git remote -v ## confirm that the heroku remote was added

Now that you have a heroku repository url, add it to your _config.yml:

# You can use this:
  type: heroku 
  repo: <repository url>
  message: [message]

Finally, deploy your new Hexo project:

hexo generate --deploy # or what amounts to the same thing:
heroku deploy --generate
heroku deploy # deploy without generating

Deploy To Digital Ocean

Follow the initial DigitalOcean setup here