Start a Hexo Blog utilizing free GitHub Pages

Build your own blog utilizing GitHub Pages & Actions with Hexo. Accelerate and protect your GitHub Pages site with free CloudFlare services.

·

5 min read

I've tried tons of blogging systems, including WordPress, Typecho, Ghost and even Blogger. It's either their content management techniques are outdated or they require decent hosting that would cost quite a lot, which wouldn't be ideal for my personal blog site. And I've long been aware of GitHub Pages being free of providing static site hosting. But it was only when GitHub released GitHub Actions that I started to be interested in setting up a pipeline of generating and deploying a static blogging site utilizing free GitHub Pages & GitHub Actions, and even accelerating the site with free CloudFlare services. So, basically, I would pay for nothing except the domain to own a pretty functioning blog site, which is quite a great deal.

In this article, I will briefly go through the steps of setting up a blog site with the static blog framework Hexo and automating the pipeline of generating & deploying the site using GitHub Actions and GitHub Pages. At the end, I will show you how to accelerate your site using the free CDN service provided by CloudFlare.

Create a Hexo app

First, you would want to create a Hexo site on your local computer so that you could modify and write posts locally and then publish them by uploading the changes.

Install Node.js

Hexo requires Node.js runtime, so it is essential to install Node.js locally first: Download and install Node.js(LTS is recommended).

Also, I use yarn as my Node.js package management tool:

$ npm install -g yarn

Install Hexo command line tool (hexo-cli)

The hexo CLI tool helps us to initialize a Hexo app and create posts and drafts.

Run the following command to install hexo-cli:

$ yarn global install hexo-cli

Check if it is installed successfully:

$ hexo --version

Initialize a new Hexo app

Run the following commands to initialize a Hexo app in folder my-blog:

$ hexo init my-blog
$ cd my-blog
$ yarn

On how to configure and write posts in Hexo, please refer to the Hexo documents

Setup deploy pipeline

Since the site is ready, we then have to configure a GitHub Actions workflow which would save us from manually generating the static files and uploading them ourselves.

Get two repositories ready

Create a repository named <your github username>.github.io, which is used to store all the generated static files. Because of this specific name, it will be detected by the GitHub and considered as a GitHub Pages repository. It will automatically be linked with the domain <your github username>.github.io. For example, mine is dizys.github.io.

Create another repository on GitHub named my-blog or whatever, push the Hexo app source files under folder my-blog to this repository.

Both repositories could be either private or public. It would work all the same.

Set up GitHub deploy credentials

We need GitHub Actions to log in with our GitHub account when deploying files to GitHub Pages. We are using SSH for that matter here.

Generate a pair of SSH keys:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/github-actions-deploy

On GitHub, in your account settings -> SSH and GPG keys. Add a SSH public key: paste the content of the generated file named github-actions-deploy.pub.

In the Settings tab of the repository my-blog, select the subtab Secrets. Add a new secret named ACTION_DEPLOY_KEY with the content of the file github-actions-deploy as its content.

Use a custom domain (Optional)

The default domain for your personal GitHub Pages is <your github username>.github.io. If you have a custom domain and want to use that instead, you can.

Create a CNAME file

If you want to use a custom domain, create a file named CNAME under folder my-blog. Fill it with your domain (with www), e.g.:

www.dizy.cc

Resolve your domain to GitHub Pages

Navigate to your DNS provider of the domain and create a CNAME record that points your subdomain www and root domain to the default GitHub Pages domain. For example, I w anted to use the subdomain www.dizy.cc and root domain dizy.cc. So I created two CNAME records for each, both pointing to dizys.github.io.

Create a GitHub Actions Workflow

Create a file at the path .github/workflows/deploy.yml, and fill in the following content:

name: Deploy

on: 
  push:
    branches: 
      - master # only triggered on master branch

jobs:
  build:

    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1.1.0
        with:
          version: 12.14.0
      - name: Setup Hexo env
        env:
          ACTION_DEPLOY_KEY: ${{ secrets.ACTION_DEPLOY_KEY }}
        run: |
          mkdir -p ~/.ssh/
          echo "$ACTION_DEPLOY_KEY" | tr -d '\r' > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          git config --global user.name 'dizys'
          git config --global user.email 'mhisf@vip.qq.com'
      - name: Install dependencies
        run: |
           npm install -g yarn
           yarn
           yarn global add hexo-cli
      - name: Generate static pages
        run: yarn hexo generate
      - name: Copy CNAME # comment this job if you don't need a custom domain
        run: cp ./CNAME ./public/
      - name: Deploy
        run: yarn hexo deploy

Now every time we push on the master branch, it will automatically run the deploy workflow, which will generate blog files and deploy them to GitHub Pages.

Accelerate your site using CloudFlare

Create an account here, set up the DNS server of your domain to the DNS server appointed by CloudFlare.

DNS records settings would remain the same for CloudFlare. With CDN and caching, your site will be delivered to your viewers much faster!

While configuring CloudFlare, make sure that you use full SSL/TLS encryption mode, or it could possibly result in infinite redirects.