Build a blog with Hexo and GitHub Pages

Build a High-Performance Blog with GitHub Pages, Actions, Hexo, and CloudFlare.

Building a personal blog can be challenging when considering content management, hosting, and performance optimization. Many popular blogging platforms have outdated management techniques or require expensive hosting, which isn't ideal for a personal blog site. However, with the help of GitHub Pages, GitHub Actions, Hexo, and CloudFlare, you can create a high-performance blog without breaking the bank.

In this article, we'll walk through the process of setting up a blog site using the Hexo static site generator, automating the pipeline for generating and deploying the site using GitHub Actions and GitHub Pages, and enhancing site performance with CloudFlare's free CDN service.

Hexo is a fast, simple, and powerful static site generator powered by Node.js. It's an excellent choice for building a blog with minimal overhead and maximum control over your content.

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

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

$ npm install -g yarn

The hexo CLI tool streamlines the process of initializing a Hexo app, creating posts, and managing drafts.

Run the following command to install hexo-cli:

$ yarn global install hexo-cli

Check if it is installed successfully:

$ hexo --version

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

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

For information on configuring and writing posts in Hexo, please refer to the Hexo documentation.

GitHub Actions is a powerful automation tool that allows you to create custom workflows for your projects. In this case, we'll use it to automate the process of generating and deploying our Hexo blog to GitHub Pages.

Create a repository named <your GitHub username>.github.io, which stores all the generated static files. Due to this specific name, GitHub will detect it as a GitHub Pages repository, automatically linking it with the domain <your GitHub username>.github.io. For example, mine is dizys.github.io.

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

Both repositories can be either private or public. They will work the same regardless.

To allow GitHub Actions to deploy your site to GitHub Pages, you need to configure SSH keys for secure authentication.

Generate a pair of SSH keys:

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

On GitHub, go to your account settings -> SSH and GPG keys. Add an SSH public key by pasting the content of the generated file named github-actions-deploy.pub.

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

By default, your personal GitHub Pages domain is <your GitHub username>.github.io. If you want to use a custom domain instead, follow these steps:

Create a file named CNAME under the folder my-blog and fill it with your domain (with www), e.g.:

www.dizy.cc

Navigate to your domain's DNS provider and create a CNAME record pointing your subdomain www and root domain to the default GitHub Pages domain. For example, I wanted 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 file at the path .github/workflows/deploy.yml and fill in the following content:

name: Deploy

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/[email protected]
        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 '[email protected]'
      - 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 you push on the master branch, the deploy workflow will automatically run, generating blog files and deploying them to GitHub Pages.

CloudFlare is a popular CDN and security service that offers a free plan to accelerate your site with caching and distribution across their global network.

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

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

When configuring CloudFlare, ensure you use the full SSL/TLS encryption mode, or it could result in infinite redirects.

By combining the efficiency of Hexo, the automation of GitHub Actions, the simplicity of GitHub Pages, and the performance enhancements provided by CloudFlare, you can create a high-performance blog that is both easy to manage and cost-effective. Happy blogging!