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:

1. Use a private repository to store Hexo source files (Markdown articles, configuration files, etc.)
2. Use a public repository to host the generated static website files
3. 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:

1
2
3
4
5
6

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)

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

3.2 Create a Public Repository (for Hosting the Site)

1. Click + again → New repository
2. 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
3. Select Public
4. 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

1. Click your profile picture in the top right corner of GitHub → Settings
2. Scroll to the bottom of the left sidebar, click Developer settings
3. Expand Personal access tokens → Click Tokens (classic)
4. 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)

5. Scroll to the bottom and click Generate token
6. 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

1. Open your private repository (the one storing source files)
2. Go to Settings → Secrets and variables → Actions
3. Click New repository secret
4. 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
5. 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

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

5.5 Configure GitHub Pages

1. Open your public repository (username.github.io)
2. By now, files should already be there (pushed automatically by Actions)
3. Go to Settings → Pages
4. Under Build and deployment:
   • Source: Select Deploy from a branch
   • Branch: Select main, leave the directory as / (root)
5. 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:

1
2
3
4
5
6
7
8
9
10
11

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

1. Detect the new push and run the build process
2. Generate static files
3. 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:

1. Check if PUBLISH_REPOSITORY in deploy.yml is correct
2. Confirm that the token has repo and workflow permissions enabled
3. 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:

1. Check if Actions ran successfully (a green checkmark ✅ on the left indicates success)
2. Clear your browser cache and refresh
3. 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:

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

1

blog.yourdomain.com

3. Add a CNAME record at your domain registrar pointing to username.github.io
4. 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:

1. Periodically push to other Git platforms, such as a self-hosted Gitea instance
2. Keep a few copies on another device or NAS
3. 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

• Hexo Official Documentation
• GitHub Pages Documentation
• GitHub Actions Documentation
• Markdown Guide