/ how-to-guide  

How to deploy Hexo blog to Github pages

Hexo provides fast and easy one-click deployment, supporting Github Pages, Netlify, OpenShift etc. In this post, I will walk through the process of deploying Hexo blog site to Github Pages.

Folder structure of Hexo

Before discussing the process, I think it is important to understand the folder structure of Hexo. Basically, a Hexo blog site contains the following folders:

  • scaffolds: Template folder. When you create a new post, Hexo will create a “.md” file under source based on scaffold.
  • source: The Resource folder. It is where the user resources are stored. It stores all “.md” files which would be rendered to html pages.
  • themes: Stores all theme files.
  • public This is where all rendered files comes in. When deploying, we need this folder to get to the Github repository so that Github pages can host it.

Now let’s look at how to deploy the blog site to Github Pages.

Install hexo-deployer-git

1
npm install hexo-deployer-git --save

Setup Github repository

Login GitHub account and create a new repository named username.github.io, where username is the username on GitHub.

  • Note that the first part of the repository must exactly match the username, otherwise it won’t work.

Refer to https://pages.github.com for more details.

Change config file

Add the following lines to _config.yml:

1
2
3
4
5
deploy:
  type:    git
  repo:    <repository url> #e.g. https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch:  [branch]         #branch name, default is 'master'
  message: [message]        #commit message, default is 'Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}'

Generate site files and push to remote repository

1
2
hexo clean
hexo deploy

Wait for a couple of minutes, then visit username.github.io, the blog site should be visiable!

How does it works

When hexo deploy is executed, Hexo pushes the files and directories in the public folder to the remote repositories and branches specified in _config.yml and completely overwrites the existing content under that branch.