使用 Hexo 在 GitHub 搭建 Blog

第 1 步：创建 GitHub 仓库

1. 登录 github.com，点击右上角 + → New repository
2. 仓库名填写 isayisee.github.io
3. 选 Public，不要勾选 Initialize README
4. 点击 Create repository，记住页面上显示的仓库地址
5. 进入仓库 → Settings → 左侧 Pages
6. 找到 Build and deployment 下的 Source
7. 选择 GitHub Actions

第 2 步：本地初始化 Hexo

npm install -g hexo-cli

hexo init my-blog
cd my-blog
npm install

# 安装插件
npm install hexo-abbrlink --save
npm install hexo-generator-searchdb --save
npm install hexo-filter-mathjax --save

第 3 步：修改配置文件

修改 _config.yml 配置

title: IsayIsee's Blog
subtitle: '欢迎你来到我的博客'
description: ''
keywords:
author: Zhan Kui
language: zh-CN
timezone: 'Asia/Shanghai'

permalink: :year/:month/:day/:abbrlink/
abbrlink:
  alg: crc32
  rep: hex
  
mathjax:
  tags: none # or 'ams' or 'all'
  single_dollars: true # enable single dollar signs as in-line math delimiters
  cjk_width: 0.9 # relative CJK char width
  normal_width: 0.6 # relative normal (monospace) width
  append_css: true # add CSS to every page
  every_page: false # if true, every page will be rendered by mathjax regardless the `mathjax` setting in Front-matter of each article

• 网站

设置	描述
title	网站标题
subtitle	网站副标题
description	网站描述
keywords	网站的关键词。 支持多个关键词。
author	您的名字
language	网站使用的语言。
timezone	网站时区， Asia/Shanghai。

• 网址

设置	描述	默认值
url	网址, 必须以 http:// 或 https:// 开头
root	网站根目录	url's pathname
permalink	文章的 永久链接 格式	:year/:month/:day/:title/
permalink_defaults	永久链接中各部分的默认值
pretty_urls	改写 permalink 的值来美化 URL
pretty_urls.trailing_index	是否在永久链接中保留尾部的 index.html，设置为 false 时去除	true
pretty_urls.trailing_html	是否在永久链接中保留尾部的 .html, 设置为 false 时去除 (对尾部的 index.html无效)	true

• 目录

设置	描述	默认值
source_dir	Source 文件夹 存储内容的位置	source
public_dir	Public 文件夹 生成静态站点的位置	public
tag_dir	标签文件夹	tags
archive_dir	归档文件夹	archives
category_dir	分类文件夹	categories
code_dir	Include code 文件夹，source_dir 下的子目录	downloads/code
i18n_dir	国际化（i18n）文件夹	:lang
skip_render	匹配到的文件将会被不做改动地复制到 public 目录中。 您可使用 glob 表达式来匹配路径。

• 文章

设置	描述	默认值
new_post_name	新文章的文件名称	:title.md
default_layout	预设布局	post
titlecase	把标题转换为 title case	false
external_link	在新标签中打开链接
external_link.enable	在新标签中打开链接	true
external_link.field	对整个网站（site）生效或仅对文章（post）生效	site
external_link.exclude	需要排除的域名。 主域名和子域名如 www 需分别配置	[]
filename_case	设置为 1 ，将文件名转换为小写形式； 设置为 2 ，将文件名转换为大写形式。	0
render_drafts	显示草稿	false
post_asset_folder	启用 资源文件夹	false
relative_link	把链接改为与根目录的相对位址	false
future	显示未来的文章	true
syntax_highlighter	代码块的设置, 请参考 代码高亮 进行设置	highlight.js
highlight	代码块的设置, 请参考 Highlight.js 进行设置
prismjs	代码块的设置, 请参考 PrismJS 进行设置

• 首页设置

设置	描述	默认值
index_generator	生成帖子归档。由 hexo-generator-index 驱动。
index_generator.path	博客索引页面的根路径	''
index_generator.per_page	每页显示帖子数	10
index_generator.order_by	帖子排列顺序。 默认情况下按日期降序(从新到旧)。	-date
index_generator.pagination_dir	URL 格式，请参阅下面的 分页 设置	page

• 分类 & 标签

设置	描述	默认值
default_category	默认分类	uncategorized
category_map	分类别名
tag_map	标签别名

• 日期 / 时间格式

设置	描述	默认值
date_format	日期格式	YYYY-MM-DD
time_format	时间格式	HH:mm:ss
updated_option	当 Front Matter 中没有指定 updated 时 updated 的取值	mtime

• 分页

设置	描述	参数
per_page	每页显示的帖子数。 0 关闭分页功能	10
pagination_dir	URL 格式	page

• 扩展

设置	描述
theme	当前主题名称。 值为false时禁用主题
theme_config	主题的配置文件。 在这里放置的配置会覆盖主题目录下的 _config.yml 中的配置
deploy	部署部分的设置
meta_generator	Meta generator 标签。 值为 false 时 Hexo 不会在头部插入该标签

• 包括或不包括目录和文件

设置	描述
include	包含隐藏文件（包括名称以下划线开头的文件/文件夹，* 除外）
exclude	排除文件或文件夹
ignore	忽略文件/文件夹

第 4 步：开启 Discussions 并安装 Giscus App

1. 仓库页面 → Settings → General → 往下找 Features → 勾选 Discussions
2. 访问 github.com/apps/giscus，点击 Install，选择你的博客仓库

第 5 步：在 giscus.app 获取配置参数

访问 giscus.app/zh-CN：

1. 仓库填写 IsayIsee/isayisee.github.io
2. Discussion 分类选 Announcements
3. 页面映射选 pathname
4. 网站会自动生成一段代码，从中复制 data-repo-id 和 data-category-id 的值

第 6 步：写入主题配置

使用 Redefine 主题：

# 安装 Redefine 主题
npm install hexo-theme-redefine --save

在 _config.yml 中修改主题：

theme: redefine

然后把主题配置文件复制一份到根目录：

bash

cp node_modules/hexo-theme-redefine/_config.yml _config.butterfly.yml

编辑 _config.butterfly.yml，找到 comments 相关部分修改：

info:
  title: IsayIsee's Blog
  subtitle: 欢迎来到我的博客
  author: Zhan Kui
  url: https://isayisee.github.io

home_banner:
  enable: true
  style: fixed
  title: IsayIsee's Blog
  subtitle:
    text: ["This is the first message", "This is the second message", "etc"] # subtitle text, array
    hitokoto:  # 一言配置
      enable: true
      show_author: true
      api: https://v1.hitokoto.cn?c=k
    loop: false
    smart_backspace: true
    
navbar:
  auto_hide: true

  # Navbar links
  links:
    Home: 
      path: / 
      icon: fa-regular fa-house # can be empty
    About:
      icon: fa-regular fa-user
      submenus:
        Github: https://github.com/IsayIsee
        Blog: https://isayisee.github.io
    Tags:
      icon: fa-solid fa-tags
      path: /tags/
    Categories: #取名随意
      icon: fa-solid fa-folder #图标
      path: /categories/ #链接
  search:
    # 需要安装 hexo-generator-searchdb 插件
    # npm install hexo-generator-searchdb --save
    enable: true
    
footer:
  runtime: true # show website running time or not
  icon: '<i class="fa-solid fa-heart fa-beat" style="--fa-animation-duration: 0.5s; color: #f54545"></i>'
  start: 2026/3/31 00:00:00
  statistics: true # show site statistics or not (total articles, total words)

comments:
  enable: true
  system: giscus
  
config:
  giscus:
    repo: IsayIsee/isayisee.github.io
    repo_id: 填入第 5 步获取的 repo_id
    category: Announcements
    category_id: 填入第 5 步获取的 category_id
    lang: zh-CN
    
page_templates:
  friends_column: 2
  tags_style: cloud # blur, cloud

第 7 步：创建 Actions 工作流文件

在本地项目中创建文件 .github/workflows/pages.yml，内容如下：

name: Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          submodules: recursive

      - name: Use Node.js 24.12.0
        uses: actions/setup-node@v4
        with:
          node-version: "24.12.0"

      - name: Install Dependencies
        run: npm install

      - name: Build
        run: npx hexo generate

      - 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

第 8 步：把源码推送到 GitHub

# 在 my-blog 父目录下
git clone https://github.com/IsayIsee/isayisee.github.io.git

cp -r my-blog/* isayisee.github.io
cd isayisee.github.io

git add *
git commit -m "init hexo blog"
git push -u origin main

第 9 步：提交内容

• 安装 Typora Redefine 主题

  • 从 https://github.com/EvanNotFound/typora-theme-redefine 下载 Redefine Typora Theme 源码

  • 打开 Typora，转到 Preferences -> Appearance

    点击 Open Theme Folder 打开主题存放文件夹

  • 将下载下来的所有 .css 后缀的文件和 redefine 文件夹一起复制到主题文件夹

  • 重启Typora并在 Themes 菜单中启用 Redefine Theme

  • 最后把亮色模式设置为 Redefine Light ，暗色设置为 Redefine Dark

• 将 Markdown 文件提交到 source/_posts 目录中，Action 会自动生成静态页面

  • front-matter

    ---
    title: 主题样式 Demo
    date: 2022-10-02 19:07:05
    tags:
        - "Demo"
        - "Hexo"
        - "Hexo Theme"
        - "Hexo Theme Redefine"
    thumbnail: https://evan.beee.top/img/redefine-1-final.webp
    sticky: 999			# 顶置的文章，sticky 值越大，顶置的文章越靠前
    comment: true		# 启用评论
    categories: Web		# 分类
    mathjax: false		# 使用 mathjax 编写公式
    excerpt: "文章摘要"   # 可自定义文章摘要
    permalink: /post/build-blog-with-hexo/	# 默认使用了 abbrlink 生成，也可以自定义
    ---