How to create a Hexo blog on GitHub Pages

Host your Hexo blog for free on GitHub Pages.

  1. GitHub repository
  2. Installation
  3. Writing
  4. Configuration
    1. Naming
    2. Favicon
    3. Project page
  5. Useful links:

I recommend the official guide (which I co-authored) for more updated content.

In previous post, I showed you how to create a blog using Hexo and host it on a GitLab repo then deploy using Netlify. Here’s how to host it on GitHub Pages:

GitHub repository §

  1. Register a free GitHub account or use your current one.
  2. Create a repo named username.github.io, where username is your username on GitHub.
  3. Clone this repo.
  4. Install Travis CI. It’s free for open source repo.
  5. Go to Applications settings, configure Travis CI to have access to the repo.
  6. You’ll be redirected to Travis page.
  7. On a new tab, generate a new token with repo scopes. Note down the token value.
  8. On the Travis page, go to your repo’s setting. Under Environment Variables, put GH_TOKEN as name and paste the token onto value. Click Add to save it.
  9. Add .travis.yml file to your repo with the following config:
language: node_js
node_js:
  - node # use latest version of nodejs
cache: npm
branches:
  only:
    - master # build master branch only
before_install:
  - npm install # install node packages and dependencies
script:
  - hexo generate # generate static files
deploy:
  provider: pages
  skip-cleanup: true
  github-token: $GH_TOKEN
  keep-history: true
  on:
    branch: master
  local-dir: public

  1. You can start writing a new post straightaway without installing Hexo. You still need to change the blog’s name and favicon though (how-to).

    1. To create a new post (through GitHub.com), create a new <post-title>.md file in source/_posts folder.
    2. Start with the following header/front-matter:
    ---
title: Test page
date: yyyy-mm-dd hh:mm:ss
tags:
categories:
---
    1. Write your post after the second --- using Markdown style.
    2. Save the file by clicking on “Commit changes”.

  2. After you create a new post, the website can be accessed on username.github.io. Check your repo settings, under the GitHub Pages, make sure the Source is gh-pages branch. Read on if you prefer to manage the blog from your workstation.

Installation §

  1. Having Hexo means you can debug locally, rather than waiting for Travis. You can even run a local server to preview your blog (see step 6 below).
  2. Clone your repo to your workstation.
  3. Install Node.js and Hexo using the official guide.
  4. Create a new post. Then generate static files to check for any error. You should always do this before pushing/merging commits to the master branch.
$ hexo generate
  1. (Optional) Start Hexo server on http://localhost:4000 to preview the blog. (more info)
$ hexo server
  1. Git add, commit and push the file to your GitHub repo.
$ git add 'source/_posts/your-post.md'
$ git commit -a -m 'Commit Message'
$ git push -u
  1. Check the build status by going to your project in Travis. Due to a limitation of hexo, the build will always pass even when there is error. Check the Jobs log, look for any error after $ hexo deploy.
  2. If there is no error, the generated website can be accessed on username.github.io

Writing §

  1. Create a new post (using Hexo)
$ hexo new "My New Post"
  1. My-New-Post.md is created to the source/_posts folder, with the following header/front-matter:
---
title: My New Post
date: yyyy-mm-dd hh:mm:ss
tags:
categories:
---
  1. Write your post after the second --- using Markdown style.

More info: Writing

Configuration §

Naming §

Change the website’s author and name
_config.yml:

title:
excerpt:
description:
author:

themes/typing/_config.yml:

menu:
  GitHub: <your-github-project-link>
# Customize /about page
nickname: 
description:

Favicon §

RealFaviconGenerator provides a web-based tool to generate favicons with wide compatibility.

  1. Upload your favicon (at least 260x260) and configure however you want.
  2. Install the generated package to themes/typing/source folder. Make you replace all existing files.
  3. Edit themes/typing/layout/_partial/head.ejs. Change the color values of mask-icon and msapplication-TileColor to the values you configured on the generator.
  4. Check for any error using hexo generate (you should do this before you push any commit).
  5. Commit and push.
  6. Check your favicon with the favicon checker.

Project page §

If you prefer to have a project page on GitLab:

  1. Navigate to your repo on GitHub. Go to the Settings tab. Change the Repository name so your blog is available at username.github.io/repository, repository can be any name, like blog or hexo.
  2. Edit _config.yml, change the root: value to the name.
  3. Commit and push.

Sample configuration files:

More info: