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.
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.