Deploy Hexo Blog to Git

Posted on

This article is about how to create a Hexo project and deploy it to your Github Page as your personal blog. I figured it out tonight following the instruction in this article HERE.

Create Your Hexo Project

Installation

You can simply follow the instruction on their official web page at https://hexo.io/docs/index.html. To install Hexo, you need NodeJS and Git installed as preferences. If you already have those installed, use the command line below to install Hexo. Then you are good to go. 

1
$ npm install -g hexo-cli

Create A Project

First, make a directory in your local where you want to put your blog project, then go to that folder in your terminal. Then you can initialize a Hexo project using the command line at:

1
$ hexo init

This command will init the project for you. The file structure in the folder should look like: 

1
2
3
4
5
6
7
+-- _config.yml //the configuration file
+-- package.json //contains the dependencies of the project
+-- scaffolds //contains some basis for posts, drafts, photos, etc.
+-- source //where the posts in your blog come from
|   +-- _drafts //drafts
|   +-- _posts //posts
+-- themes //contains the themes you'd like to use

Then you need to do the command below in the folder to install the dependencies. After that you will have a node_modules folder contains the libraries.

1
$ npm install

More details at https://hexo.io/docs/setup.html.

Run Server

To run the server, simply do hexo server or hexo d in short. Then you can go to localhost:4000 to check the blog project. When you do init, it created a default fundemental blog layout for you with the Hexo study information. 

1
$ hexo server

Write Post

You can directly modify files in the _posts folder as mentioned using Markdown language.

Create GitHub Page

GitHub Page is somewhere you can deploy your web project onto. Every GitHub account get one page.

Create A Repository

It is required that you follow the naming pattern for your GitHub Page as [username]/[username].github.io. For example mine repository is at yutonghuangorange/yutonghuangorange.github.io, and my GitHub Page is at the url https://yutonghuangorange.github.io.

Create One Commit

It requires one commit to initialize the project. Basically it will render the index.html file in the repository as the index page. For example you can simly create a index.html file and write “Test” into it, when you go to the link you can see the text “Test” rendered in the page.

If you are using command line to play with Git, you can follow the instruction here.

1
2
3
4
5
$ git clone https://github.com/[username]/[username].github.io.git 
$ echo "Test" > index.html
$ git add .
$ git commit -m "The first commit for the index page"
$ git push

Then your GitHub Page repository should be good to go.

Deploy Hexo to GitHub

This is the key part of the whole process. There are basically two ways to do this. First is to use the Deploy function that Hexo has originally, Second is to use Git to do that.

The Principle of Deployment

When you deploy your hexo project to your github page, what it does is to first generate the required static files from whatever your Hexo project contains, then put those static files in a structure that Git can understand and render into a folder called .deploy_git, and upload those files to your repository. In this case, every time you want to update your repository, you need to first regenerate the static files then commit them.

Using Hexo Deploy

Configuration

First thing first, is to change the configuration file for your Hexo project in _config.yml file in the root of your project. Add the lines below to it.

1
2
3
4
5
deploy:
  type: git
  repo: [your repo] // for example: git@github.com:yutonghuangorange/yutonghuangorange.github.io.git
  branch: [branch] // for example: master
  message: [message]

Then you need to install the package used for this functionality.

1
$ npm install hexo-deployer-git --save

Then you need to generate the static files to be uploaded.

Procedures

1
$ hexo generate # or hexo g in short

Finally, deploy it to your git repo.

1
$ hexo deploy # or hexo d in short

Errors

You might get errors when you try the hexo d the first time. 

1
2
3
4
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

If you see this, it means that you didn’t have a SSH key set up in your Git Hub account. You can follow the instructions HERE for a reference. After you set up the key, you should be able to deploy it to your repo properly.