Deploy Hexo Blog to GitHub Pages with GitHub Actions

Word count: 1.8kReading time: 11 min

 2026/03/05 

Preface

What is GitHub Pages?

GitHub Pages is a free static website hosting service provided by GitHub
You just need to push your website files to a GitHub repository, and your site will be accessible via a domain like username.github.io
It supports custom domains and doesn’t require purchasing a server, making it ideal for personal blogs, project documentation, and other static websites

What is Hexo?

Hexo is a fast, simple, and powerful blogging framework
It is built on Node.js, parses articles using Markdown, and can generate static web pages in seconds
Hexo also boasts a rich ecosystem of themes and plugins, allowing you to easily create a personalized blog

How It Works

The approach used in this tutorial is:

Use a private repository to store Hexo source files (Markdown articles, configuration files, etc.)
Use a public repository to host the generated static website files
Use GitHub Actions to automate building and deployment

When you push updates to your private repository, GitHub Actions will automatically:

Set up the Hexo environment
Generate static web pages based on your configuration
Push the generated files to the public repository
GitHub Pages detects the file changes and automatically updates your blog

Can I Use a Custom Domain?

Sure, once configured, you can bind your own domain in GitHub Pages settings

Prerequisites

Before you begin, make sure you have:

✅ A GitHub account
✅ Node.js environment (recommended: the latest v22 LTS version)
✅ A code editor (VS Code recommended)
✅ Git installed (for committing code to GitHub repositories)

Notes

All references to “GitHub username” in this article refer to the username you use to log in to GitHub, not your display name

It is recommended to keep English comments in configuration files, as they help you understand the meaning of each option

Step 1: Local Installation and Initialization

1.1 Install Node.js

Visit the Node.js official website to download and install the latest LTS version (I am using v22.14.0)

After installation, verify in your terminal:

1 2	node -v # Should display v22.14.0 or similar npm -v # Should display the npm version

1.2 Create a Project Folder

Create a folder (it’s best to avoid Chinese characters in the path to prevent mysterious bugs) in your preferred location, for example Blog
Then open it with VS Code

1.3 Install Hexo CLI

Run the following in the VS Code terminal:

1	npm install -g hexo-cli

Verify the installation:

1	hexo version

1.4 Initialize the Hexo Project

1 2	hexo init npm install

After initialization, your project directory structure should look like this:

Blog/
├── _config.yml       # Site configuration file
├── source/           # Source folder
│   └── _posts/       # Markdown articles go here
├── themes/           # Themes folder
└── xxxx             # Other folders/files, not listed here

1.5 Configure Site URL

Edit the _config.yml file in the root directory, find the # URL section:

If using the default GitHub Pages domain:

1
2
3

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://<YourGitHubUsername>.github.io/

Replace <YourGitHubUsername> with your actual username, e.g., https://gebilaowang.github.io/

If using a custom domain:

1
2
3

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://your-domain.com/

1.6 Local Preview

1	hexo s # "s" is short for "server"

The terminal should display:

1
2
3

INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

Open http://localhost:4000/ in your browser, and you should see the Hexo page

Step 2: Theme Configuration (Optional)

The default Hexo theme is quite minimal. If you want a more polished look, you can install a third-party theme.

Popular Theme Recommendations

NexT - Minimalist style
Butterfly - Beautiful interface, responsive design
Fluid - Material Design style
Matery - Card-based design

Each theme comes with detailed configuration documentation. Please refer to the README.md of the corresponding GitHub repository for setup instructions

Step 3: Create GitHub Repositories

3.1 Create a Private Repository (for Source Files)

Log in to GitHub, click the + in the top right corner → New repository
Choose any repository name, e.g., hexo-blog or blog-source
Important: Select Private
Do not initialize with a README, .gitignore, or license
Click Create repository

3.2 Create a Public Repository (for Hosting the Site)

Click + again → New repository
Important: The repository name must strictly follow the format <YourGitHubUsername>.github.io
- For example, if your username is gebilaowang, the repository name should be gebilaowang.github.io
- The name must match your username exactly, including capitalization
Select Public
Click Create repository

Why create two repositories?

The private repository protects your source files (configurations, drafts, etc.) from public exposure

The public repository only contains the generated static files, meeting GitHub Pages requirements

Separating source code from build artifacts makes maintenance easier

Step 4: Configure GitHub Actions for Automated Deployment

4.1 Create a Workflow File

Navigate to the .github/workflows/ folder in your project root (create it if it doesn’t exist):

1	mkdir -p .github/workflows

Create a deploy.yml file inside .github/workflows/ with the following content:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # Triggers when pushing to the main branch

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@master

      - name: Build and Deploy
        uses: theme-keep/hexo-deploy-github-pages-action@master
        env:
          BRANCH: main
          PUBLISH_DIR: ./public
          PERSONAL_TOKEN: ${{ secrets.HEXO_GHPAGE_SECRET }}
          PUBLISH_REPOSITORY: <YourGitHubUsername>/<YourGitHubUsername>.github.io

Things you must change:

Replace <YourGitHubUsername> in the last line with your actual username
For example: PUBLISH_REPOSITORY: gebilaowang/gebilaowang.github.io

4.2 Generate a GitHub Personal Access Token

Click your profile picture in the top right corner of GitHub → Settings
Scroll to the bottom of the left sidebar, click Developer settings
Expand Personal access tokens → Click Tokens (classic)
Click Generate new token in the top right → Select Generate new token (classic)

Configure the Token:

Note: Add a description, e.g., Hexo Deployment Token
Expiration: Select No expiration
Permissions:
- ✅ repo (Full control of private repositories)
- ✅ workflow (Update GitHub Action workflows)

Scroll to the bottom and click Generate token
Important: Copy the generated token immediately (format: ghp_xxxxxxxxxxxx)

⚠️ Warning:
The token is only shown once! Save it immediately in a secure location; if lost, you will need to regenerate it
Do not share this token, as a leaked token could lead to your GitHub account being compromised!

4.3 Configure Repository Secret

Open your private repository (the one storing source files)
Go to Settings → Secrets and variables → Actions
Click New repository secret
Fill in:
- Name: HEXO_GHPAGE_SECRET (if you changed the variable name in deploy.yml, make sure they match)
- Secret: Paste the token you just copied
Click Add secret

Step 5: Push Code and Deploy

5.1 Initialize a Git Repository

If your VS Code terminal is still running hexo server, press Ctrl+C to stop it first

1
2
3

git init
git add .
git commit -m "Initial commit: Hexo blog setup"

5.2 Link the Remote Repository

Link your local repository to your private repository:

1	git remote add origin https://github.com/<YourGitHubUsername>/<YourPrivateRepositoryName>.git

For example:

1	git remote add origin https://github.com/gebilaowang/hexo-blog.git

5.3 Push to GitHub

1 2	git branch -M main git push -u origin main

5.4 Check Deployment Progress

After pushing, open your private repository
Click the Actions tab at the top
You should see a running workflow named Deploy to GitHub Pages
Click into it to view detailed build logs
Wait for the green ✅ icon, which indicates a successful deployment

5.5 Configure GitHub Pages

Open your public repository (username.github.io)
By now, files should already be there (pushed automatically by Actions)
Go to Settings → Pages
Under Build and deployment:
- Source: Select Deploy from a branch
- Branch: Select main, leave the directory as / (root)
Click Save

5.6 Visit Your Blog

Wait 1-2 minutes, then open your browser and navigate to:

1	https://<YourGitHubUsername>.github.io/

If you see the Hexo interface, congratulations

Your Hexo blog has been successfully deployed to GitHub Pages

Step 6: Daily Writing Workflow

6.1 Create a New Article

Open the VS Code terminal and run:

1	hexo new "Article Title"

This will generate a new Markdown file in the source/_posts/ directory

6.2 Edit the Article

Open the newly generated Markdown file and start writing

Example:

---
title: My first blog
date: 2025-03-06 12:00:00
tags:
  - Essay
categories:
  - Daily
description: This is my first blog.
---

This is where the content goes...

6.3 Local Preview

1
2
3

hexo clean  # Clear cache
hexo generate  # or hexo g, generate static files
hexo server  # or hexo s, start local server

Open http://localhost:4000/ in your browser to preview

6.4 Publish Updates

Once everything looks good, commit and push to GitHub:

1
2
3

git add .
git commit -m "docs: <New Article Title>" # It's recommended to note what was added in the commit message for easier management later
git push

After pushing, GitHub Actions will:

Detect the new push and run the build process
Generate static files
Deploy to GitHub Pages

Wait a moment, refresh your blog, and the new article will appear

FAQ

Q1: What if the Actions build fails?

Solution:

Check if PUBLISH_REPOSITORY in deploy.yml is correct
Confirm that the token has repo and workflow permissions enabled
Check the Actions logs, search for the error details on Google, or use an AI coding assistant to help identify the issue

Q2: Blog not updating after push?

Solution:

Check if Actions ran successfully (a green checkmark ✅ on the left indicates success)
Clear your browser cache and refresh
Sometimes it takes a few minutes for the compiled static pages to be fully deployed to the server; wait a few minutes and try again

Q3: How do I bind a custom domain?

If you plan to use a custom domain, you need to configure it in advance:

Create a CNAME file (no extension) in the source/ directory of your private repository
The file content should be your domain, for example:

1	blog.yourdomain.com

Add a CNAME record at your domain registrar pointing to username.github.io
Wait for DNS to propagate (may take a few hours)

This way, every time you commit, the CNAME file will be copied to the public/ directory and pushed to the public repository along with the build output

Note: The CNAME file should contain only one line with your domain name; no extra blank lines or content

Q4: Theme configuration changes not taking effect?

Solution:

1
2
3

hexo clean # Clear cache
hexo generate # Regenerate
hexo server # Start the server and check in your browser

Q5: How do I back up my blog?

A few suggestions:

Periodically push to other Git platforms, such as a self-hosted Gitea instance
Keep a few copies on another device or NAS
Back up important configuration files separately

Conclusion

Congratulations, you now have a Hexo blog powered by GitHub Pages

Now, it’s time to start your writing journey!

References

Author: MarchSnow

Link: https://blog.88889000.xyz/2026/tech/hexo-github-actions-github-pages/

Publish date: March 5th 2026, 20:34:20 UTC

Update date: May 26th 2026, 08:44:02 UTC

Page Views: --

License: Licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

Next Post

Using GitHub No-Reply Email for an Extra Layer of Privacy Protection
Previous Post

Hello World

CATALOG

1. Preface
2. Step 1: Local Installation and Initialization
3. Step 2: Theme Configuration (Optional)
1. 3.1. Popular Theme Recommendations
4. Step 3: Create GitHub Repositories
1. 4.1. 3.1 Create a Private Repository (for Source Files)
2. 4.2. 3.2 Create a Public Repository (for Hosting the Site)
5. Step 4: Configure GitHub Actions for Automated Deployment
6. Step 5: Push Code and Deploy
7. Step 6: Daily Writing Workflow
8. FAQ
9. Conclusion
10. References