How to use Hexo blog

🚀 Overview

1. Install Hexo
2. Initialize your blog project
3. Build static pages locally
4. Preview locally
5. Configure GitHub repository
6. Deploy to GitHub Pages

---

Install Prerequisites

Make sure you have:

node -v
npm -v
git --version

If not, install them (Ubuntu example):

sudo apt install nodejs npm git

Node.js ≥ 16 is recommended.

---

Install Hexo

npm install -g hexo-cli

---

Initialize Your Blog

hexo init my-blog
cd my-blog
npm install

Folder structure:

my-blog/
├── _config.yml      # main config
├── source/          # posts go here
├── themes/          # theme files
└── public/          # generated static site

---

Build & Preview Locally

Generate static pages

hexo generate
# or short form
hexo g

Run local preview server

hexo server
# or short form
hexo s

Then open:
http://localhost:4000

---

Deploy to GitHub Pages

Step 1: Create a new GitHub repo

Name it:

yourname.github.io

The repo name must match your GitHub username for Pages to work automatically.

---

Step 2: Install deployer plugin

npm install hexo-deployer-git --save

---

Step 3: Configure _config.yml

Add or modify at the bottom:

deploy:
  type: git
  repo: https://github.com/yourname/yourname.github.io.git
  branch: main    # or gh-pages

---

Step 4: Build & deploy

hexo clean
hexo generate
hexo deploy
# or shorthand
hexo g -d

This will:

• Clean old build
• Generate static files
• Push to your GitHub Pages repo

---

View Your Site

After a few minutes, visit:
https://yourname.github.io/

---

⚙️ Common Issues

Problem	Cause	Fix
fatal: could not read Username	GitHub auth missing	Configure SSH or use a Personal Access Token
Deployer not found: git	Plugin missing	npm install hexo-deployer-git --save
Wrong branch	Wrong config	Change branch: in _config.yml
Blank page	Didn’t generate files	Run hexo g -d

---

🧠 Optional: Separate Source and Output Repos

You can keep:

• Source code in hexo-source
• Built site in yourname.github.io

That keeps your main repo small and clean.

---

Quick Command Summary

Task	Command
Initialize blog	hexo init my-blog
Generate pages	hexo g
Preview locally	hexo s
Clean cache	hexo clean
Deploy to GitHub	hexo d

---

Would you like me to give you a ready-to-use deploy.sh shell script that automatically builds and pushes your Hexo site to GitHub in one command?