Hacker's blog - Hexo in Heroku

A step-by-step guide how the awesome Hexo blog can be setup to work with in Windows with one-line deployments into Heroku account. When I did this, it took me some time to find all this information, so I decided to gather all relevant setup steps in one place.

Before following this guide, please make sure that

  • You already know how to use Git in a basic way - how to commit and push to remote repo
  • Git is installed and available in the command line prompt
  • You have registered for Heroku account

WTF is Hexo?

Hexo Framework is Jekyll inspired static website generator, written in Node.js. What I liked about it, that it is very customizeable and still simple to use. Essentially, it takes a bunch of markdown files and compiles them into static html/javascript website.


This is probably not the only way to do it, but I think it is the easiest, so:

Environment Setup

  • Install Node.js environment. I did it with their installer from their website.
  • Install Heroku Toolbelt, and follow the instructions on the page to login into Heroku and create your app.

Notice the Git url that you get when you execute heroku create - Heroku website is essentially a Git repository, and in order to deploy a website you simply need to do a git push.

Hexo Setup

Installation

The next step is to open Node.js command-line and follow the instructions found on Hexo’s page - but without the hexo server command - it is not needed yet. This will install command line utility to work with the blog - thats “hexo-cli” npm package, and git clone Hexo into the folder you provide.

Configuration

Themes

Hexo supports “themes” - a layout and templates with all the relevant CSS/javascript. Installing a theme is easy, you need to copy theme folder into /themes folder (and usually it is nicer to do a git clone of the theme into the /themes folder). Nice collection of themes can be found here

After setting up theme folder, changing themes is simply a matter of editing _config.yml in hexo root -> changing theme to relevant [theme folder name].

Plugins

Hexo support for plugins. (Hexo plugin page) They are written in Node.js and are installed through npm package manager. The plugins I recommend to use for starters are

  • hexo-deployer-heroku -> command line deployment to Heroku
  • hexo-generator-seo-friendly-sitemap -> generate a sitemap for…well, seo
    Deployment
    Deployment to heroku: once you installed hexo-deployer-heroku, add to _config.yml the following
    1
    2
    3
    deploy:
    type: heroku
    repo: https://git.heroku.com/[Heroku App Name].git

    Now, you can deploy by simply executing hexo generate –deploy

    Facepalm warning: make sure you do not have multiple deploy: sections in the config - since the last one overwrites all those before
    Comments
    Register at Disqus and configure “Disqus Engage”. Website shortname that you get, insert into _config.yml -> disqus_shortname: “[your Disqus shortname]”

    If a comments section doesn’t appear, check in theme’s template that the Disqus javascript is there (it should be there, since Hexo kind-of assumes using Disqus as comments engine)

    If Disqus scripts are not in the theme template, you can use the following to add comments (assuming EJS templating engine)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<% if (post.comments && config.disqus_shortname && !is_page()){ %>
<section id="comments">
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = '<%=config.disqus_shortname%>'; // required: replace example with your forum shortname

/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</section>
<% } %>

And now?

Steps so far is enough to setup a basic blog and deploy it. There are a couple of more steps I would do next

  • Setup Google Analytics - in most Hexo themes I’ve looked on, it is a simple as specifying tracking Id in theme’s _config.yml (themes have their own _config.yml, in addition to sitewide Hexo’s _config.yml)
  • Setup (if needed asset) folders (more on this in Hexo’s assets documentation page)
  • Customize the theme to fit your needs (rather obvious I think, but I mention this anyway :))