由于本地使用obsidian对笔记进行编辑和分类时，多端同步繁琐，无法在线查看。因此选用Hexo博客框架+Github建站，搭建一个自己的个人博客页面，同时通过配置Obsidian,使得在本地也可以使用Obsidian进行管理和笔记的编辑。

(其实是羡慕别人炫酷的个人博客×)😄😄

效果

博客链接：LegGasai’s CSLearning

一.新建Github仓库

1.创建同名仓库

注意图中Repository name必须为Owner.github.io，这样github才能正确识别为github pages

二.创建Hexo项目

Hexo是一个快速、简洁且高效的博客框架，且开源社区提供了大量的第三方主题样式，可一键生成华丽的个人博客网页。官网链接Hexo

1.安装Hexo

确保已经安装了如下工具

  • Node.js (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本)
  • Git

然后通过npm安装Hexo脚手架

1
$ npm install -g hexo-cli

安装完成后，建站（创建Hexo项目）,将<folder>替换成你的文件夹名

1
2
3
$ hexo init <folder>
$ cd <folder>
$ npm install

新建完成后，指定文件夹的目录如下：

1
2
3
4
5
6
7
8
.  
├── _config.yml  
├── package.json  
├── scaffolds  
├── source  
|   ├── _drafts  
|   └── _posts  
└── themes

之后主要会用到_config.yml文件和source文件夹

2.修改配置

修改_config.yml中的配置

1
2
3
4
5
6
7
8
# Site  
title: <your blog name>  
subtitle: ''  
description: ''  
keywords:  
author: <your name> 
language: zh-CN #改成中文  
timezone: 'Asia/Shanghai'

各参数说明如下

参数 描述
title 网站标题
subtitle 网站副标题
description 网站描述
keywords 网站的关键词。支持多个关键词。
author 您的名字
language 网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 zh-Hans和 zh-CN。
timezone 网站时区。Hexo 默认使用您电脑的时区。请参考 时区列表 进行设置，如 America/New_York, Japan, 和 UTC 。一般的，对于中国大陆地区可以使用 Asia/Shanghai。 
1
2
3
# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://leggasai.github.io/

其他配置可以先不用改，后续配置Hexo主题的时候再对应修改

三.配置Hexo主题(Butterfly为例)

由于默认的主题比较简陋，好在社区提供了大量的现成的Hexo主题框架供我们选择，网页链接：Themes | Hexo

1.选择主题

我们可以根据自己的需要和审美，选择一款自己喜爱的主题，这边笔者选择的是比较热门的一款Butterfly主题。

2.安装和配置

选择主题后，我们需要找到该主题的官方文档，来进行配置。例如Butterfly的参考文档如下：

首先安装主题,在你的Hexo根目录下

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

然后应用主题，修改Hexo根目录下的/_config.yml

1
2
3
4
# Extensions  
## Plugins: https://hexo.io/plugins/  
## Themes: https://hexo.io/themes/  
theme: butterfly

接着安装必要的渲染器插件

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

为了减少升级主题后带来的不便，请使用以下方法（建议，可以不做）。

在 hexo 的根目录创建一个文件 _config.butterfly.yml，并把主题目录的 _config.yml 内容复制到 _config.butterfly.yml 去。( 注意: 复制的是主题的 _config.yml ，而不是 hexo 的 _config.yml)

Hexo会自动合并主题中的_config.yml 和_config.butterfly.yml 里的配置，如果存在同名配置，会使用 _config.butterfly.yml 的配置，其优先度较高。

然后根据官方文档和自己需求，进行页面的定制即可，参考文档如下：

四.配置Obsidian

为了获得在本地管理和组织所有笔记的良好体验，推荐本地使用Obsidian进行编辑。但Obsidian和Hexo需要一些额外的配置。

首先用Obsidian打开Hexo的根目录

修改.gitignore文件，忽略产生的.obsidian配置信息。修改如下，主要是添加了最后一行.obsidian/workspace

1
2
3
4
5
6
7
8
9
.DS_Store  
Thumbs.db  
db.json  
*.log  
node_modules/  
public/  
.deploy*/  
_multiconfig.yml  
.obsidian/workspace

修改obsidian配置

  • 修改新建笔记存放的位置，因为Hexo默认是放在source/_posts文件夹下的，所以需要修改与之保持一致。
  • 关闭Wiki链接，Hexo不支持，如果不关闭在本地obsidian是有效果的，部署至网站后，图片和文件会加载不出。
  • 修改附件默认存放位置，在source文件夹下可以新建一个img或其他名字的文件夹，用于存放笔记中的图片，文件，视频等
  • 添加忽略文件，将Hexo项目除source文件夹外其他文件夹排除。

添加模板

obsidian可以自定义模板信息，通过模板快速创建Hexo的front-matter信息

在source/_obsidian文件夹下新建template.md文件，内容如下：

1
2
3
4
5
---  
title: {{title}}  
date: {{date}}  
tags: []  
---

之后使用obsidian添加新笔记时，只需要引入该模版即可。

添加插件

自动生成categories

在本地使用Obsidian时，我们常常会用笔记的路径(如前端/Vue)来代表其categories(分类)，但在Hexo中需要在front-matter中手动定义categories,如果我们不想每次都手动配置，而是让Hexo自动以笔记的路径来定义其categories。

添加hexo-auto-category依赖，根据文件目录自动生成 categories 信息

1
npm install hexo-auto-category --save

在根目录下的_config.yml添加配置

1
2
3
4
5
6
# Generate categories from directory-tree  
# Dependencies: https://github.com/xu-song/hexo-auto-category  
# depth: the max_depth of directory-tree you want to generate, should > 0  
auto_category:  
  enable: true  
  depth:

生成唯一静态链接

默认的笔记链接是根据笔记的时间+标题生成的，但如果我们修改了笔记的时间，那么如果别的文章中引用了这篇笔记，就会失效。

添加hexo-abbrlink依赖

1
npm install hexo-abbrlink --save

在根目录下的_config.yml添加配置

1
2
3
4
5
6
permalink: posts/:abbrlink/
# abbrlink config  
# https://github.com/rozbo/hexo-abbrlink  
abbrlink:  
  alg: crc32      #support crc16(default) and crc32  
  rep: hex

Obsidian文件树插件

由于直接用Obsidian打开Hexo项目，目录树会显示很多无关紧要的目录，在Obsidian中我们只需要关注source/_post这个文件夹即可。

在Obsidian第三方插件中安装File Tree Alternative Plugin插件

文件夹聚焦效果：

五.配置一键部署

配置一键部署功能，可以实现本地博客编写完毕后，一键同步到github上，并同步响应的个人主页。参考文档如下：部署 | Hexo

安装hexo-deployer-git插件

1
$ npm install hexo-deployer-git --save

然后修改根目录下的_config.yml文件（注意不是主题配置文件）

1
2
3
4
5
6
7
8
9
10
11
12
13
# Deployment  
## Docs: https://hexo.io/docs/one-command-deployment  
deploy:  
  type: git  
  repo: <your repo url>
  branch: <branch name>


# Example
deploy:  
  type: git  
  repo: git@github.com:xxxx/xxxx.github.io.git  
  branch: main
参数 描述 默认
repo 库（Repository）地址 建议使用git@github.com形式的
branch 分支名称 gh-pages (GitHub)
coding-pages (Coding.net)
master (others)
message 自定义提交信息 Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }})
token 可选的令牌值，用于认证 repo。用 $ 作为前缀从而从环境变量中读取令牌

然后执行指令,如果提示需要验证github帐号和密码，则可以配置SSH密钥认证，方式在这就不赘述了，自行百度即可。

1
2
hexo clean;
hexo deploy;

踩坑记录

总得来说，按照Hexo和Butterfly文档进行配置，笔者自己遇到的问题并不多，如果读者在配置中，遇到问题的欢迎留言评论~

1.配置评论功能

网上大多都是使用Valine管理评论的，因为其无需后端，但是自从2022年起，其不支持国内用户使用了。因此换用了Waline+Vercel构建评论功能。

参考文档如下：快速上手 | Waline

但Vercel的节点，国内无法访问，因此要使用评论功能，只能通过特殊手段，除非自己购买了域名。

2.配置一键部署

笔者自己通过hexo d部署到github时，经常出现timeout out的情况（也有部分是网络原因），后来发现是因为仓库链接写的是https的形式，改成git@github.com形式的情况就好很多。

1
2
3
4
5
6
# Deployment  
## Docs: https://hexo.io/docs/one-command-deployment  
deploy:  
  type: git  
  repo: git@github.com:<username>/<username>.github.io.git  
  branch: main

3.标签页/分类页/关于我页面缺失

也就是图中的这些，其中archives是创建Hexo框架时已经有的，不需要自己手动配置，而标签，分类，友链，关于界面是需要手动配置的。

其配置的具体方式如下：Butterfly 安裝文檔(二) 主題頁面 | Butterfly

进入项目根目录，输入如下命令：

1
hexo new page tags

然后在source/tags文件夹下会新建一个index.md文件，进入该文件，进行如下修改：

1
2
3
4
5
6
7
---
title: 标签
date: 2023-01-05 00:00:00
type: "tags"
orderby: random
order: 1
---

然后重新执行指令：

1
2
3
hexo clean;
hexo g;
hexo s;

其余页面的配置也类似。

友链页的配置请参考：Butterfly 安裝文檔(二) 主題頁面 | Butterfly