Get started with Hexo on Github

"My weblog is getting pretty old" was the first thing I thought when I tried to update it to the latest technology. And it's true, I've started my weblog on community server, moved it to wordpress, tried to run it on Ghost and finally made the move to static HTML with Octopress.

The final move to a static HTML website has provided me with the best experience so far. If you can afford to mess with HTML, Markdown and CSS than generating a weblog based on markdown and some templates is by far the most flexible and most performant way to run a weblog.

The downside for me is that octopress right now is very outdated on my machine. The buildscripts that I use are a few years old and lack the necessary bugfixes to run them on Windows. Which I still use at work.

After some searching however I found a good alternative to Octopress called Hexo. In this post I will take you through the basics steps to set up a Hexo blog with a theme and a few plugins to host the website on Github pages.

<!-- more -->

Step 1: Download Hexo and configure your website

The first step is to install Hexo on your machine. For this you need to install the hexo-cli module using NPM:

1
npm -g install hexo-cli

The Hexo CLI module is designed to give you the necessary commandline tools to create a new static website in a folder and generate the static HTML for that website among other utility functions that you normally need to maintain a website.

To create a new website, execute the following set of commands:

1
2
3
hexo init [website]
cd [website]
npm install

The first command genrates a new folder with some basic configuration and templates. Since hexo is essentially a set of node modules you need to run npm install to get everything setup correctly.

After initializing the website you need to do some basic configuration for it. You can find the site configuration settings in the _config.yml file which is located in the root of the website.

In this file you need to specify the name and URL of the website and some basic information about you as the author of the website.

You can check the website by running the following set of commands

1
2
hexo generate
hexo server

Open your browser and go to http://localhost:4000/ to see the results.

Step 2: Select a theme for your website

Hexo uses a set of templates to render the pages of your website. Templates for the website are normally located inside a theme that you configure in the _config.yml file.

The default theme is okay, but if you like to use something else, you can find quite a few good themes on hexo.io.

To switch themes you need to find a new theme, go to its github repository and clone it into the themes folder of your website. Once that is done you configure the new theme in \_config.yml and run hexo generate to generate the website with the new theme.

Hexo themes have some configuration that comes along with them, so check out the \_config.yml file inside the theme for additional settings. Some themes come with sample configuration files that you may have to rename to configure the theme correclty.

Here's a tip for working with themes if you use GIT to store your website sources. Make sure you either fork the theme or remove the .git folder from the theme folder so that you manage the theme through the repository that holds the sources of your website. Otherwise you will lose configuration settings that are required to properly generate the website.

Step 3: Install additional plugins

When you initialize a basic Hexo website it comes with very few plugins. Just a few basic ones that you need in order to make things look right in combination with the landscape theme.

I had to add a few plugins to make the website look right for my weblog. Here's a short list of my favorites:

hexo-renderer-marked

All of my blogposts contain weird line breaks to make the thing look right on screen without me having to enable line wrapping in my favorite text editor. Hexo has the weird habit of rendering those linebreaks.

The hexo marked renderer is a markdown rendering engine that enables you to configure how your markdown should be processed. The module follows commonmark specs as much as possible.

My configuration for this module looks like this:

1
2
3
4
5
6
7
8
9
# Marked renderer
marked:
gfm: true
pedantic: false
sanitize: false
tables: true
breaks: false
smartLists: true
smartypants: true

You can download this module by running npm install hexo-renderer-marked --save

hexo-generator-category

If you like, you can include a page for every category you use on your weblog. Add a property to your markdown files that specify in which category the post belongs and install this module to generate a page for that category.

You can install the module by running npm install hexo-generator-category --save

hexo-generator-tag

I don't have a tag page in my navigation, but you can select a tag and go to a page listing all the posts that are tagged with that particular tag. The hexo-generator-tag module is required for this functionality, so I suggest you install this if you like to enable people to browse your site by tag.

To install the module, you guessed it, use npm install hexo-generator-tag --save

hexo-generator-cname

One of the interesting features of github pages is the fact that you can use a custom domain name for your github pages website. All you need to do is add a CNAME file with your custom domainname in it and link the Github IP-Address in your DNS registration to your domainname.

Hexo however, doesn't generate a CNAME file by default. So to get one, you need to add the hexo-generator-cname module to your website.

The module uses the URL setting from your website configuration to generate the CNAME file, so make sure that the URL corresponds to the custom domainname you have linked to the github pages IP-address.

Step 4: Setup deployment to github

With everything set up it's time to deploy your new website. For this you need to add one final plugin to Hexo. Install the hexo-deployer-git module using NPM and add the following bits of configuration to your _config.yml file to set it up:

1
2
3
4
deploy:
type: git
repository: https://github.com/[username]]/[username].github.io
branch: master

Replace the [username] bits with your username and save the configuration. Now you can run the following set of commands to generate and deploy your website:

1
2
hexo generate
hexo deploy

This will generate the HTML files and deploy them to the master branch of your personal github pages website. Notice that the deployer will use a force push to update the branch on github. If you plan on relying on the history of your master branch than I suggest you don't use this plugin but deploy everything manually. In most cases however I wouldn't worry about it, because the generated stuff matches what you've seen locally.

Final step: Moving over old stuff

Now that you've seen what you need to do to set up a hexo based static website it's time to move over your old stuff. Since I was using octopress I had a relatively easy job. Copy over my markdown files to the \_posts folder and generate the website.

If you are coming from wordpress or some other blog platform you may want to take a look at the migrator plugins that are available. There's a plugin for blogger, wordpress, joomla and if that doesn't work you can always try to use the RSS migrator plugin which works well for the more obscure blog platforms.

If you haven't tried this stuff yet for yourself, please take 30 minutes and give it a shot! It may surprise you how easy it actually is.

avatar

Willem Meints

AI Fanatic, Technical Evangelist, Microsoft MVP