Embedded Projects

Get busy Liviing

0%

How to Create a Hexo Blog on GitHub Pages in 2025- Pitfalls & Key Notes

Posted on Edited on

Introduction

A step-by-step guide to setting up a Hexo blog on GitHub Pages in 2025, highlighting common pitfalls and important notes for a smooth experience.

Prerequisites

Step 0: Install nvs and hexo-cli

  • Downlaod and install the nvs
  • You may encounter the below Policy error

Error

  • Update the policy in windows powershell terminal in Admin. mode
1
2
3
Get-ExecutionPolicy
Get-ExecutionPolicy -List
Set-ExecutionPolicy RemoteSigned

Step 1: Install Hexo

  • Install hexo-cli via npm
1
npm install -g hexo-cli

Step 2: Initialize Your Blog

1
2
3
hexo init my-blog
cd my-blog
npm install

Important:
Make sure you are in an empty directory before running hexo init.

Step 3: Create a GitHub Repository

  • Name it <username>.github.io for user/organization pages.

  • For project pages, use any repo name and set the correct branch in Hexo config.

github-page-settings

Note:
Repository name and branch matter for GitHub Pages to work.

Step 4: Configure _config.yml

  • Set your url to match your GitHub Pages URL:
    https://<username>.github.io

config-url

  • Update deploy settings for GitHub Pages.

github-deploy

Important:

  • Incorrect url or deploy config can cause broken links or failed deployments.
  • The url link is different in the url and deploy setting

Step 5: Add .nojekyll file

There are new steps for Github if you want to directly depkoy the web but not using Github internal build process.

Add a .nojekyll file in the root of the deploy files

So, you need to add a source file in Hexo

  1. Add .nojekyll file in soruce /_posts folder
add-nojekyll-in-src
  1. Add Include settgins in _config.yml file
add-nojeyll-in-config

Step 6: Deploy with Hexo

Install the deployer:

1
npm install hexo-deployer-git --save

Update _config.yml:

1
2
3
4
deploy:
  type: git
  repo: https://github.com/<username>/<repo>.git
  branch: main

Deploy:

1
2
3
4
5
hexo clean && hexo generate && hexo deploy

# On Windows, you need to split the above command
hexo clean
hexo d -g

Theme setting

Have a look at the Hexo themes here: Theme

However, most of them seem outdated and are not maintained anymore. Finally, I chose the hexo-theme-next theme.

It has a new repo for maintenance: https://github.com/theme-next/hexo-theme-next

However, it has not been updated for 5 years….

I have a little bit of regret choosing the Hexo blog framework…

Conclusion

Setting up Hexo on GitHub Pages in 2025 is straightforward but seems it is a bit outdated.

References