记一次个人博客的安装配置(Obsidian + Hexo + Github Page)

Hexo

首先进行工具的安装 npm install -g hexo-cli

找一个文件夹，执行

hexo init <folder>
cd <folder>
npm i

输入 hexo generate 即可生成静态文件
输入 hexo server ，即可在本地访问界面

设置远端仓库托管

GitHub 上建立一个仓库
在 hexo 的 folder 打开命令行

git init
git remote add origin <url>
git add .
git commit -m "Initial commit"
git push -u origin master

Github Page

同样建立一个仓库，这里需要命名为 {username}.github.io

• 这是因为 GitHub Pages 具有两种基本的类型：用户/组织页面 (User/Organization Pages) 和项目页面 (Project Pages)
  • 用户/组织页面使用一个专门的仓库存放文件，这个仓库必须以你的用户名命名，规则如下：
    • 仓库名称必须符合 <username>.github.io 的模式。
    • 该仓库 master 分支的内容才会用来构建你的 GitHub Pages。
  • 你只能使用自己的用户名来建立用户/组织页面的仓库，形如 joe/bob.github.io 这样的仓库是不行的。
  • 当用户页面建好之后，可以使用 http(s)://<username>.github.io 来访问。

在 Token生成界面选择 “Generate New Token (Classic)”

• 选择一个过期时间
• Select Scopes 勾选 repo 中的所有选项
• Generate Token

复制生成的 Token，注意这里不要直接关闭网页，这个 Token 关闭网页后就会不可见。
在托管 hexo folder 的仓库界面打开设置，“Security-> Secret and Variables -> Actions”，新建一个 Respository Secret，将刚刚得到的 Token 粘贴进内容，给它一个名字，这里我叫 ACCESS_TOKEN

配置 Github Workflow

在 hexo folder 打开 .github 文件夹，新建一个文件夹 workflows，然后创建一个 yml 文件，粘贴如下内容

name: Generate Hexo Blog
on:
  push:
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v4
        with:
          submodules: 'true'
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Setup Hexo Environment
        run: |
          npm install -g hexo-cli
          npm ci
      - name: Generate pages
        run: |
          hexo generate
          ls -R public/
      - name: Deploy to GitHub Pages
        run: |
          cd ./public
          git init
          git config --global user.name {username}
          git config --global user.email {useremai}
          git add .
          git commit -m "${{ github.event.head_commit.message }} $(date '+%Z %Y-%m-%d %H:%M:%S') Updated By Github Actions"
          git push --force --quiet "https://${{ secrets.ACESS_TOKEN }}@github.com/{username}/{username}.github.io.git" master:main

修改 _config. yml

deploy:
	type: 'git'
	repository: https://github.com/{username}/{username}.github.io.git
		branch: main

提交修改到仓库，就可以看见一个 Action 正在运行，等待片刻后访问之前的个人主页，就可以看到博客界面了。

配置个人主题

这里选用了 Next 作为主题，首先需要 fork 上游的仓库，这是因为在我们的 workflow 中会同步子模块，因此如果想要对主题做配置，就需要对仓库的内容进行修改，所以这里 fork 了一个自己的版本便于追踪修改与版本更新

git clone <url> themes/next
git add .
git rm --cached -f themes/next
git submodule add <url> themes/next

分别对两个仓库进行提交，就可以看到主题更新了

后记：后来开摆了，转移到了 Butterfly

RSS 配置

在项目根目录下安装 hexo-generator-feed

npm install hexo-generator-feed --save

修改项目根目录的_config. Yml，插件添加 hexo-generator-feed，设置 feed 属性

Plugins: hexo-generator-feed
# Feed Atom
feed:
    type: atom
    path: atom.xml
    limit: 20
    hub:
    content:
    content_limit: 140
    content_limit_delim: " "
    order_by: -date
    icon: /images/favicon_200x200.png

修改主题根目录的_config. Yml，添加 RSS 订阅入口

• 修改social节点，添加一行启用 RSS 图标

social:
# 其他社交按钮
RSS: /atom.xml || fa fa-rss

• 修改follow_me节点，开启 RSS 订阅入口

follow_me:
# 其他社交按钮
RSS: /atom.xml || fa fa-rss

Obsidian

综合调研了网上的各种 Obsidian 方案，始终没有找到满意的，于是决定自己搞

既然已经通过 Github 托管了博客，我们也希望一起将 Obsidian 中的文档托管

Obsidian Git

可以下载 Obsidian 中的插件 Git，很多博客中都叫 Obsidian Git，因为 Obisidian 的规则原因，现在已经改名叫 Git，配置过程大同小异这里就不多讲了。

配置备份

这里可以配置一个工作流来进行自动备份，防止出现一些误操作导致文件丢失

name: Scheduled Backup to bkp branch

on:
  schedule:
    # 每天凌晨 2 点运行（UTC 时间，需根据时区调整）
    - cron: '0 2 * * *'
  workflow_dispatch:  # 支持手动触发

jobs:
  backup:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.ACCESS_TOKEN }}

      - name: Set up Git
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "github-actions@users.noreply.github.com"

      - name: Check and create bkp branch if not exists
        run: |
          # 拉取所有分支
          git fetch origin
          
          # 检查远程是否存在 bkp 分支
          if ! git ls-remote --heads origin bkp; then
            echo "bkp branch does not exist, creating it..."
            git checkout --orphan bkp  # 创建孤立分支
            git rm -rf .              # 清空内容
            git commit --allow-empty -m "Initialize bkp branch"
            git push origin bkp       # 推送到远程
          else
            echo "bkp branch exists, fetching it..."
            git checkout bkp          # 切换到 bkp 分支
          fi

      - name: Backup changes to bkp branch
        run: |
          # 确保当前在 bkp 分支
          git checkout bkp
          git reset --hard origin/main  # 用 main 分支内容覆盖
          
          # 提交更改
          git add .
          git commit -m "Scheduled Backup from main ($(date '+%Z %Y-%m-%d %H:%M:%S'))" || echo "No changes to commit."
          
          # 推送到远程 bkp 分支
          git push --force "https://${{ secrets.ACCESS_TOKEN }}@github.com/${{ github.repository }}.git" bkp

在配置好 Obisidian 文档的 Git 仓库后，我们将其添加为 Hexo 仓库的子模块:

git submodule addd <url> source

再通过修改 Hexo 的配置来排除一些你不希望渲染的文件，这里可以参考 Hexo 的配置规则，如下所示

Hexo 配置规则

包括或不包括目录和文件

使用以下选项可明确处理或忽略某些文件/文件夹。 可以使用 glob 表达式 进行路径匹配。

include 和 exclude 选项只会应用到 source/ ，而 ignore 选项会应用到所有文件夹.

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

例如：

# 处理或不处理目录或文件  
include:  
  - ".nojekyll"  
  # 处理 'source/css/_typing.css'  
  - "css/_typing.css"  
  # 处理 'source/_css/' 中的任何文件，但不包括子目录及其其中的文件。  
  - "_css/*"  
  # 处理 'source/_css/' 中的任何文件和子目录下的任何文件。  
  - "_css/**/*"  
  
exclude:  
  # 不处理 'source/js/test.js'。  
  - "js/test.js"  
  # 不处理 'source/js/' 中的文件、但包括子目录下的所有目录和文件。  
  - "js/*"  
  # 不处理 'source/js/' 中的文件和子目录下的任何文件。  
  - "js/**/*"  
  # 不处理 'source/js/' 目录下的所有文件名以 'test' 开头的文件，但包括其它文件和子目录下的单文件。  
  - "js/test*"  
  # 不处理 'source/js/' 及其子目录中任何以 'test' 开头的文件。  
  - "js/**/test*"  
  # 不要用 exclude 来忽略 'source/_posts/' 中的文件。  
  # 你应该使用 'skip_render'。 或者在要忽略的文件的文件名之前加一个下划线 '_'。  
  # - "_posts/hello-world.md" # 在这里配置是没有用的。  
  
ignore:  
  # 忽略任何一个名叫 'foo' 的文件夹。  
  - "**/foo"  
  # 只忽略 'themes/' 下的 'foo' 文件夹。  
  - "**/themes/*/foo"  
  # 对 'themes/' 目录下的每个文件夹中忽略名叫 'foo' 的子文件夹。  
  - "**/themes/**/foo"

列表中的每一项都必须用单引号或双引号包裹起来。

include 和 exclude 并不适用于 themes/ 目录下的文件。 如果需要忽略 themes/ 目录下的部分文件或文件夹，可以使用 ignore 或在文件名之前添加下划线 _。

source/_posts 文件夹是一个例外，但该文件夹下任何名称以 _ 开头的文件或文件夹仍会被忽略。不建议在该文件夹中使用 include 规则。

配置自动更新工作流

这里我们期望的流程是这样的：“在 Obisidian 中写文章” -> “文章自动同步到 Git” -> “Git Workflow 根据标志查询是否更新发布到网页" -> “通知 hexo 仓库进行编译发布” -> “hexo 将编译结果发布到网页所在的静态仓库”

我们之前已经配好了 Obisidian 的 Git 同步模块，那么接下来要做的就是 “Git Workflow 根据标志查询是否更新发布到网页" -> "通知 hexo 仓库进行编译发布" 这一步了，可以使用以下工作流来解决：

name: Noitfy by push
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    if: "contains(github.event.head_commit.message, 'sync')"
    steps:
      - name: Notify repository
        run: |
          curl -XPOST -u {your_name}:${{ secrets.ACCESS_TOKEN }} -H "Content-Type: application/json" https://api.github.com/repos/{your_name}/{your_hexo_repo}/dispatches --data '{"event_type": "deploy"}'

这里我设置的比较简单，会自动检测提交的 commit message 中是否含有设置的关键词进行发布，同时，设置一个周期的自动更新工作流:

name: Check Commit Interval and Trigger Workflow

on:
  schedule:
    - cron: '0 0 * * *' # 每天运行一次
  workflow_dispatch: # 支持手动触发

jobs:
  check-commit-interval:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Get Latest Commit Date
        run: |
          # 获取最新 commit 的时间
          LATEST_COMMIT_DATE=$(git log -1 --format=%ci)
          echo "Latest Commit Date: $LATEST_COMMIT_DATE"

          # 获取当前时间
          CURRENT_DATE=$(date -u +"%Y-%m-%d %H:%M:%S")
          echo "Current Date: $CURRENT_DATE"

          # 计算时间差（天数）
          DIFF_DAYS=$(( ($(date -d "$CURRENT_DATE" +%s) - $(date -d "$LATEST_COMMIT_DATE" +%s)) / 86400 ))
          echo "Time Difference: $DIFF_DAYS days"

          # 设置 DIFF_DAYS 变量
          echo "DIFF_DAYS=$DIFF_DAYS" >> $GITHUB_ENV

      - name: Trigger Workflow
        if: env.DIFF_DAYS > 3
        run: |
          curl -XPOST -u {your_name}:${{ secrets.ACCESS_TOKEN }} -H "Content-Type: application/json" https://api.github.com/repos/{your_name}/{your_hexo_repo}/dispatches --data '{"event_type": "deploy"}'

这样设置之后，原先的发布工作流其实会出现一些问题，为此，将其修改：

name: Generate Hexo Blog
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, 'Updated By Github Actions')"
    steps:
      - name: Checkout source
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          submodules: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Setup Hexo Environment
        run: |
          npm install -g hexo-cli
          npm ci

      - name: Update submodule
        run: |
          git config --global user.name "Github Actions"
          git config --global user.email "github-actions@users.noreply.github.com"
          git submodule update --remote
          git add source/
          git commit -m "Update submodule ($(date '+%Z %Y-%m-%d %H:%M:%S') Updated By Github Actions)" || exit 0
          git push "https://${{ secrets.ACCESS_TOKEN }}@github.com/{your_name}/{hexo_repo}" main || exit 0
          

      - name: Generate pages
        run: |
          git clone https://github.com/{your_name}/{pages_repo} public
          ls -R public/
          hexo generate

      - name: Deploy to GitHub Pages
        run: |
          cd ./public
          git add .
          git commit -m "${{ github.event.head_commit.message }} ($(date '+%Z %Y-%m-%d %H:%M:%S') Updated By Github Actions)"
          git push --force "https://${{ secrets.ACCESS_TOKEN }}@github.com/{your_name}/{pages_repo}" main

配置模板以适用于 Front Matter

Hexo 在进行渲染时会自动对文章的 Front Matter 进行解析以实现各种功能

https://hexo.io/zh-cn/docs/front-matter

在 Obsidian 中下载插件 Templater ，并自定义一个 Template 文件用于控制 Hexo 的渲染
我的文件是这么写的：

---

title: <% tp.file.title %>

date: <% tp.file.creation_date() %>

updated: <% tp.file.last_modified_date() %>

tags:

categories:

description:

from:

aliases:

published: false

comments: false

---

渲染引擎

为了支持更多的语法和数学公式，需要对渲染引擎进行替换：

npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it-plus --save

Obsidian双链语法支持

插件地址

配置图床

根据文档 我们使用指令下载 CLI

npm install picgo -g

picgo set uploader

在 git 创建一个公有仓库，并像前面一样，设置密钥，按照提示填入
这里要注意不要填入域名，否则生成的图片会指向域名

Obisidian 自动上传

下载插件 Image Auto Upload，选择 picgo-core 模式即可

外链禁止跳转

npm install hexo-external-link --save

在 _config.yml 中启用即可

添加搜索

npm install hexo-generator-search --save

然后在 _config.yml 中设置

search:
  path: search.xml
  content: true
  field: post

并在 _config.butterfly.yml 中设置

search:
  use: local_search
  placeholder: 搜索
  # Local Search
  local_search:
    enable: true
    # Preload the search data when the page loads.
    preload: true
    # Show top n results per article, show all results by setting to -1
    top_n_per_article: 1
    # Unescape html strings to the readable one.
    unescape: false
    CDN:

代码高亮

笔记发布后，发现代码高亮失效，切换到 next 主题后，发现代码又正常染色了
因此很快将问题定位到 Butterfly 主题
在 Github 上寻找(相关问题)[https://github.com/jerryc127/hexo-theme-butterfly/issues/245]
照做，将 _config.yml 中的 hljs 改成 false，问题解决。

公式渲染

这里根据主题文档的描述，从 @upupming/hexo-renderer-markdown-it-plus 处获取了最新版的渲染引擎，并且切换到 katex 上，问题得以解决

配置评论

使用 https://giscus.app , 无需部署，还是一样白嫖 github 的服务器
按照 app 里的提示创建好 discussion, 然后将输出的值填入 _config.butterfly.yml 中

<script src="https://giscus.app/client.js"
        data-repo="Sentixxx/Sentixxx.github.io"
        data-repo-id="repo-id"
        data-category="Announcements"
        data-category-id="category-id"
        data-mapping="url"
        data-strict="1"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

giscus:
	repo: Sentixxx/Sentixxx.github.io
	repo_id: 
	category_id: 
	light_theme: light
	dark_theme: dark
	js:
	option:

虽然但是，这里并没有给额外的，应该填在哪里呢？根据回答，其实其他属性直接填进 options 就好了，也就是这样

giscus:
	repo: Sentixxx/Sentixxx.github.io
	repo_id: R_kgDONuW2Fw
	category_id: DIC_kwDONuW2F84C2aTW
	light_theme: light
	dark_theme: dark
	js:
	option:
		data-mapping: url
		data-strict: 1
		data-reactions-enabled: 1
		data-loading: lazy

这样配完再启动，就会发现……还是没有评论
——其实是要在 comments 下面设置：

comments:	
	use: Giscus

然后就可以评论了

To Be Continued