Build a personal blog with Hexo + Fluid and host it on GitHub Pages

1. Environment Setup

Install the following tools in advance:

Node.js (v16+ recommended): refer to the Runoob tutorial for installation](https://www.runoob.com/nodejs/nodejs-install-setup.html)
Git: refer to the Runoob tutorial to complete installation and configuration, and register a GitHub account](https://www.runoob.com/git/git-install-setup.html)

Verify the installation:

1
2
3

node -v
npm -v
git --version

2. Installing Hexo

Refer to the official Hexo installation documentation](https://hexo.io/zh-cn/docs/)

1	npm install -g hexo-cli

On Linux you can run the following command. You can use hexo [command] directly; otherwise you need to use npm hexo [command]

1	echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile

Create the blog project:

1
2
3

hexo init my-blog
cd my-blog
npm install

At this point the directory structure is as follows:

my-blog/
├── _config.yml          # Hexo 主配置
├── package.json
├── scaffolds/           # 模板（post, page, draft）
├── source/
│   └── _posts/          # 博客文章（Markdown）
└── themes/              # 主题目录

Start the local preview:

1	npx hexo server

Open http://localhost:4000 in your browser to see the default page.

3. Installing the Fluid Theme

More themes can be found in themes](hexo.io/themes/).

Method 1: npm installation (recommended)

1	npm install hexo-theme-fluid

Method 2: Direct download (this blog uses this method)

Download the latest version from Fluid GitHub Releases](https://github.com/fluid-dev/hexo-theme-fluid/releases) and extract it to the themes/fluid directory.

Enabling the Theme

Edit _config.yml in the root directory and modify the theme field:

1	theme: fluid

Create a theme configuration file (to override the theme's default configuration; no need to modify files inside themes/fluid):

1	cp themes/fluid/_config.yml _config.fluid.yml

If installed via npm, copy it from node_modules/hexo-theme-fluid/_config.yml.

Restart npx hexo server, and you should see the Fluid theme's pages.

4. Basic Configuration

4.1 Site Configuration (`_config.yml`)

title: My Blog            # 站点标题
subtitle: ''
description: ''
author: YourName
language: zh-CN            # 语言，en 或 zh-CN
timezone: Asia/Shanghai
url: https://yourusername.github.io   # 部署后的访问地址

4.2 Theme Configuration (`_config.fluid.yml`)

Commonly used configuration options:

# 导航栏标题
navbar:
  blog_title: "My Blog"

# 首页 Banner
index:
  banner_img: /img/banner.jpg
  slogan:
    enable: true
    text: "Welcome to My Blog"

# 文章页
post:
  banner_img: /img/default.png

# 关于页
about:
  enable: true
  avatar: /img/avatar.jpg
  name: "YourName"
  intro: "A short introduction"

For more configuration options, refer to: Fluid Configuration Guide

5. Writing Articles

Creating a New Article

1	npx hexo new "My First Post"

This will generate My-First-Post.md under source/_posts/. Edit its content:

---
title: My First Post
date: 2026-03-21 16:00:00
tags: [Tag1, Tag2]
index_img: /img/cover.jpg       # 首页封面图
banner_img: /img/banner.jpg     # 文章页顶部大图
---

正文内容，支持标准 Markdown 语法。

## 二级标题

- 列表项
- 列表项

```python
print("Hello World")
```

Common Front-matter Fields

Field	Description
`title`	Article title
`date`	Publication date
`tags`	Tag list
`index_img`	Homepage cover image
`banner_img`	Large banner image at the top of the article page
`sticky`	Pinning priority; larger numbers appear closer to the front
`hide`	Set to true to hide site-wide
`archive`	Set to false to hide only on the homepage

Creating a Draft

1	npx hexo new draft "Draft Title"

Drafts are stored in source/_drafts/ and will not be published. When you want to publish:

1	npx hexo publish "Draft Title"

6. Create tabs, about page, etc.

1 2	npx hexo new page tags npx hexo new page about

Edit the generated source/tags/index.md:

---
title: Tags
layout: tags
---

Edit source/about/index.md:

---
title: About
layout: about
---

在这里写关于页的内容。

7. Deploy to GitHub Pages

Refer to the official Hexo GitHub configuration docs

7.1 Create a GitHub Repository

Create a repository on GitHub named yourusername.github.io (replace with your GitHub username).

7.2 Initialize Git and Push

cd my-blog
git init
git remote add origin git@github.com:yourusername/yourusername.github.io.git
git add -A
git commit -m "init: hexo blog with fluid theme"
git push -u origin master

7.3 Configure GitHub Actions for Automatic Deployment

Create .github/workflows/pages.yml in the project root directory and copy the following content into it. Note that the Node version needs to be modified (in the sample code below it is 24.14.0). Use node -v to check it, and note that the output is in a format similar to v24.14.0 — do not include the "v", or the workflow will fail to run.

name: Pages

on:
  push:
    branches:
      - master # default branch

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          # If your repository depends on submodule, please see: https://github.com/actions/checkout
          submodules: recursive
      - name: Use Node.js 24.14.0
        uses: actions/setup-node@v4
        with:
          # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node
          # Ref: https://github.com/actions/setup-node#supported-version-syntax
          node-version: "24.14.0"
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7.4 Enable GitHub Pages

Go to the repository's Settings → Pages
Set Source to GitHub Actions
After pushing the code, Actions will automatically build and deploy

Once deployment is complete, visit https://yourusername.github.io to see the blog.

8. Daily Workflow

# 写新文章
npx hexo new "Article Title"

# 本地预览
npx hexo server

# 发布（推送到 GitHub 即自动部署）
git add -A
git commit -m "add: new article"
git push

Common Commands Quick Reference

Command	Description
`npx hexo new "Title"`	Create a new post
`npx hexo new page name`	Create a new page
`npx hexo server`	Local preview (port 4000)
`npx hexo generate`	Generate static files to `public/`
`npx hexo clean`	Clear cache and generated files