How to set up hexo on github.io

In my first post on this blog I am going to explain how I set it up in the first place.

I chose to use hexo.io on Github Pages.
This allows me to write my posts in markdown language and deploy them using git.

resources

For the most part I followed Jamie Paton’s guide. Since it is a couple of years old by now, a few things have to be done differently.
I am going to assume you are running ubuntu or a similar distribution of Linux. All the following commands are to be issued in your terminal.

installation of prerequisites

As already outlined in the hexo docs, you need Node.js and Git.
You might already have git, otherwise install it with

sudo apt-get install git

For the installation of Node.js, hexo (and I) recommend nvm. Get it via:

wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.29.0/install.sh | bash

then install Node.js via

nvm install 5.2

5.2.0 is the latest (stable) version as of the time of this post. You can also choose the LTS version instead (4.2.3)

install hexo

Now you can install hexo!

npm install -g hexo-cli

Go to the directory where you want to store your project in, and initialise hexo via

hexo init username.github.io
cd username.github.io

As suggested by Jamie, now is a good time to set up a few general things like title and author:

vim _config.yml

Feel free to use gedit, sublime or the text editor of your choise instead of vim. You can find the documentation of the settings here.
Add the entries for the github deployment:

deploy:
  type: git
  repository: https://github.com/username/username.github.com.git
  branch: master

If you set up ssh authentication for github, you can also use the ssh URL here.
You also need to install the plugin that allows hexo to deploy to git:

npm install hexo-deployer-git --save

If you are using multiple accounts on github with ssh, and you need some additional configuration to identify the correct one for deployment, the git repository is set up in .deploy_git in your hexo directory.

set up github

For Github Pages, set up a new repository on your github account named username.github.io - it is important that the username matches your github username.

deploy

You are almost finished! To deploy hexo on your github page, use

hexo generate
hexo deploy

or just hexo generate -d. You can now find your blog at https://username.github.io
You will notice that hexo automatically added a “hello world” first blog. You might want to get rid of that one before you announce your blog.
Delete ./source/_posts/hello_world.md, and then run hexo clean followed by hexo generate -d

themes

There are already quite a lot of themes for hexo, and if you don’t like any of them you can also create your own.
When I set up my blog, it came with the default theme landscape which I didn’t like much, so I switched to “light”.

write a post

To create a new blog post, use

hexo new post <title>

then edit the file in ./source/_posts/<title>.md
After finishing your article, run hexo generate -d again to deploy the new article on your blog!

Thanks a lot to Jamie again for the excellent initial guide!