Create Hexo Blog for Free Part 1: Hexo Intro and Using GitHub Page


Hexo is a framework used to generate static website. GitHub is used as web server.

I’ve been using this for years and is the very website you are browsing right now. By the end of this tutorial, you will be able to create something similar to this: or the current website you are in:

Here is the most comprehensive guide out there, enjoy!

finished (Finished product)


There’s a lot I can say of website building, from the early days in college when I first started learning HTML, CSS and JS, finding myself designing layout in Adobe Dreamweaver for hours. Later I found Adobe Muse, a fluid, adaptive website builder with no coding requirement until it was discontinued in 2018. I also tried the old fashion website builder such as Wix, Squarespace or WordPress, which in my opinion is too expensive for charging over $100/yr.

Today, I will show you how to use a combination of Hexo framework and Github Page to build and host your own blog website (almost for free, you only need to pay for custom domain name which is optional).

Create Hexo Scaffolding

Install npm

npm is a JavaScript package manager, a must-have to install various packages to build our blog including the Hexo framework.

Download instruction:

Install Hexo

Once npm has finished installing, go to commandline and install Hexo

$ npm install hexo-cli -g

Initialize Hexo Blog

Now we can create the Hexo Blog scafolding:


Choose a root directory where the hexo blog folder will be located and execute the following command.

Important: all command listed below should be launched from the blog folder root path.

$ hexo init blog
$ cd blog
$ npm install

We don’t need to create a new root folder, as Hexo commandline will create one called “blog” for us, we can just rename it afterward.

Afterward, we should see the same thing being generated like the image above.

Add Your Blog Post (optional)

All Hexo post should be written in Markdown (.md) format, if you have existing post, you can move it to the <blog_name>/source/_posts/ directory.

If not, there’s a default in there already, and it is serving as an example.

Generate Static Website

You can generate the website using those scafold and host it using your local machine as the server, thus allowing you to preview it

$ hexo generate
$ hexo server

Once you get a confirmation from the commandline, at this point open a browser and go to the following url: http://localhost:4000/

And there you have it.

local server

GitHub and Git Deployer Configuration

The next thing to do is getting the website on to the GitHub server which offers free hosting, nice isn’t it?

Install Deployer

Install hexo-deployer-git plugin for Hexo

$ npm install hexo-deployer-git -save

Create GitHub Repo

Second thing is to create a brand new and blank repository with any name, this repo is used to store all the files related to your blog.

The name of the repo doesn’t have to be, it can be anything

  • I see many misconception about forcing you to use this repo name, how would one host multiple websites using GitHub if this was required.


Next thing is to specify the newly created repo in your blog configuration file so that the “Git deployer” knows where to upload the file to:

In your _config.yml, create the following fields (or modify if you have it already) like so:

type: git

You would replace the repo url with the one in your repo’s SSH.


Finally, you are good to deploy

$ hexo deploy

Go to your repo to see if it’s updated, you should see something like so:


Common Command

I like to bundle the hexo deploy command with the hexo clean command which will prompt a re-population of the whole directory, this gives a cleaner result.

$ hexo clean && hexo deploy

What’s Next

Please follow my next blog post and learn about blog customization using theme and custom domain name:


Xiaoliang’s Blog - Tutorial for Hexo+Github=Blog