起因

最近我把布尔费墨公众号文章都离线到了本地obsidian，在折腾obsidian的过程中，无意间看到一个博客：山茶花舍 (irithys.com)，从字里行间感受到博主磅礴的生命力，虫洞中看到十年之约 和更多独立博客，深受感染，于是也萌生了好好摆弄独立博客的念想，就把原先部署在github pages上的日记博客做了迁移。

本文记录迁移过程:
github pages + jekyll -> vercel + github + hugo + freenom + waline

vercel、hugo、freenom、waline都是第一次用，会有踩坑记录。obsidian相对熟手，更多是教程。

效果

  • 顺滑的文章读写同步体验
  • 只需要折腾第一次
  • 博客源码不公开
  • 多客户端支持
  • 主题易更换
  • 顶级域名
  • 全免费

配置

git & github

git是基础，内容较多，自行搜索，不多赘述。

hugo

hugo是用go编写的跨平台静态博客框架，换hugo用纯粹是为了新鲜感。安装和初始化配置后，使用hugo server开启本地调试，访问localhost就能实时查看博客效果。

官方主题库Hugo Themes查看主题demo、风格、特性、配置，看中某主题后，其介绍页面 Download 一般会跳转到主题的github源码页面。也可以同时安装很多个主题。在config.toml中设置启用哪一个。

hugo工程的目录简介参考这篇博客Hugo 不完美教程 - II: Hugo 目录组织

踩坑：修改主题后无法推送到github

解决方法一：直接下载ZIP格式源码解压到themes目录，而非git clone / git submodule add

解决方法二：正常用git clone / git submodule add 下载主题，将该主题的layouts目录复制到hugo工程根目录，修改主题时仅修改该目录，不改themes目录的文件内容

配置：自动给图片加上说明文字

在博客根目录下新建 layouts/_default/_markup/render-image.html，内容如下：

1
2
3
4
5
6

<figure>
<center>
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}">
<figcaption>{{ .Text }}</figcaption>
</center>
</figure>

这时，插入图片时输入 ![说明文字](图片链接) 就能像这样显示了

参考：Hug给图片加上说明文字-叶寻的博客

配置：部分目录仅同步到git，不同步到博客

如果有一些敏感目录放着自己的隐私文章，不想公开到博客，同时又想同步到git备份，那么可以在hugo的配置文件中加入ignoreFiles属性：(以yaml为例)

1
2
3

ignoreFiles:
  - secret/
  - posts/legecy/

配置：自动更新文件中的修改时间

暂时删除了这个显示，因为不太对，以后需要再拿出来修改。
一些文章是持续更新的，所以需要这个功能。实现效果：自动增加文章更新时间，获取顺序为文章的frontmatter、git提交时间、文件修改时间。config.yaml加入

1
2
3
4
5
6
7

enableGitInfo: true
frontmatter:
  lastmod:
  - lastmod
  - :git
  - :fileModTime
  - ':default'

layouts/partials/post_meta.html 中加入

1

{{- $scratch.Add "meta" (slice (printf "%s&nbsp;更新" (.Lastmod.Format (.Site.Params.dateFormat | default "2006-01-02")))) }}

参考这两篇：
自动更新文件中的修改时间 – EmacsTalk
Hugo博客修改post_meta头部信息 | Sulv’s Blog (sulvblog.cn)

vercel

vercel 提供静态网站托管服务，类似于github pages，有以下优点：

  1. 部署简单。可以和 github 账号及仓库关联，只要源码提交到 github，vercel 会在几秒钟内部署好
  2. 操作简单。其使用全在官网操作台，不需要本地环境。只要前几次设置好，后面就不用管了。
  3. 可以关联私密github仓库，保护源码。
  4. 默认配置https，不需要费劲弄证书
  5. 默认提供vercel.app二级域名

踩坑：vercel端和本地的表现不一致

vercel自带的hugo版本比较低，可能导致本地没问题，推送到vercel就报错。把vercel自带hugo换成高版本就好了。

解决办法： 在hugo项目根目录添加 vercel.json 文件，内容如下：（版本号最好和本地hugo一致）

1
2
3
4
5
6
7

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.105.0"
    }
  }
}

踩坑：草稿文章会在vercel上显示，本地不会

vercel默认的build参数带了-D，即--buildDrafts，该参数优先级最高，只要设置了，那么所有草稿都会输出。

解决办法： vercel project settings -> Build & Development Settings -> Build Commond: 原先是 hugo -D --gc ，勾选右侧override，把-D删掉。同理修改 Development Command。然后提交新的commit触发部署，或者在deployments中找到最新那一条redeploy

waline !

Waline 实现评论区、访问统计功能。快速上手 页面非常人性化，一步步照做即可，数据库依托于 LeanCloud国际版，可以一键部署在vercel，操作配置都非常简单。域名配置和博客本体类似，直接在vercel上用freenom的二级域名就可。

hugo 我用了paperMod主题，只需要把 waline 的HTML代码插入到 partial/comments.html 就好了。经测试，访问统计的数据加载比较慢，暂时没放出来（毕竟也没多少访问量）

踩坑：暗黑模式下评论文本输入框是白的

waline支持自动暗黑模式：init 增加参数 dark: 'auto'

踩坑：评论区不在文章末尾

本章节标题为什么是 waline! 而不是 waline 呢？因为不加不行

obsidian

obsidan当前文章截图
obsidan当前文章截图
最好的本地 markdown 知识管理软件，可定制化强。可以通过设置与hugo工程目录联动，实现这些效果：文件统一、内链统一、图片统一。

文件统一

即所有文章markdown文件只有一份，既可以本地ob上管理和编写，又能直接发布到博客。

直接在hugo工程的content目录建立obsidian仓库，这样会在content目录下新建.obsidian文件夹，其中存放了本仓库的设置、插件本体及设置，这些设置和插件还会跟随整个hugo工程由git备份到github。

你需要在hugo根目录的.gitignore 中加入以下内容，因为每次在ob中打开关闭文件都会变动workspace.json的内容。

1

content/.obsidian/workspace.json

内链统一

即同一个内链（对本地其他文章的引用），本地ob和博客都能访问。ob中需要如下设置：

1
2

文件与链接 -> 内部链接类型 -> 基于仓库根目录的绝对路径
文件与链接 -> 使用wiki链接 -> 关闭

这样一来，在编写md新增内链时，输入 [[ 选取引用文章后，就会自动变成[hello-world](/posts/2022-11-15-hello-world)，只要删掉链接里最后的.md，加上/，改成[hello-world](/posts/2022-11-15-hello-world)就能达成ob和网页同时正常访问，还可以在后面加#定位到具体小节，像这样：内链统一

一旦被引用的文件名或所在目录名在 ob 内发生改动，ob 会自动更新内链

踩坑：自动更新后的内链会恢复成[xxx](/posts/xxx)的形式

已用 py 解决，每次运行会把所有文章的内链都修复。

踩坑：博客文章的 URL 中的中文标点会被去除

导致博客链接和ob链接不一致，暂未系统解决，目前是手动把文件名中的标点删掉

图片统一且本地化

即图片存储于本地，本地ob与博客用同一个链接，都能正常查看。在完成以上两个统一之后，再做图片统一相当简单。

在content下新建目录 img，用于集中存放所有文章的图片。ob中设置以下一条即可：

1

文件与链接 -> 附件默认存放路径 -> 指定的附件文件夹 -> img

插入图片时有两种情况：

  1. 图片在剪贴板。在ob中直接CTRL-V就行，这时图片文件会自动存放到 img 目录下，md中会插入内链为![ ](img/xxxxx.png)，需要在最前面加/ 变成 ![](/img/xxxx.png)
  2. 图片在本地。挪到img目录下，用内链方式引用，最前面加 /

优点：

  1. 设置简单，不用折腾图床
  2. 目录结构简单清爽。尽管图片集中存放，ob自动更新内链的特性可以让你无需管理图片文件
  3. 插入图片相当方便
  4. 如果你对本地化有执念，这也是好处之一

缺点：图片直接保存在github，速度不会快，大图最好压缩使用

tag统一

即文章内对TAG的引用在ob和博客都可以正常跳转。如果在文章中加#tag，ob中可以点击列出所有该TAG文章，但是博客不会解析。只需要这么处理就可以了：[#技术](/tags/技术) -> #技术

缺点：引用这个tag的文章在ob中也会加入该tag，关系图谱中也会出现/tags/技术的引用。

metadata 处理

即front matter，md文件最开头的元数据。这方面的核心需求是新建md时自动添加元数据，省去重复输入，可以通过ob的模板功能实现。

与git的联动

需要安装第三方插件：obsidian git。最主要的配置把custom git path设置为..\，在obsidian中只是把content目录设成了ob仓库，而git的仓库是在content的上一级目录。

之后如果只有内容上的更新需要git同步，只需ob中CTRL+P呼出命令面板，分别输入git commit 以及 git push即可同步到git，继而同步到vercel

域名与CDN

免费域名 freenom

freenom，目前唯一的免费域名提供商，有 tk、ml、ga、cf、gq 这几类后缀的免费域名。域名主要分为注册、申请、解析三步。参考freenom免费域名申请及设置域名解析_DLchs666的博客，缺点是默认免费一年，需要自己手动续。

注册账号时推荐用google账号关联，补充一些个人信息就注册好了。首页输入选好想要的免费域名，加入购物车确定即可。

申请好域名后，在freenom中配置该域名DNS为vercel：manage domain -> management tools -> nameserver -> Use custom nameservers (enter below)，

1
2

NS1.VERCEL-DNS.COM
NS2.VERCEL-DNS.COM

然后在vercel中Project Settings -> domains，将申请到的域名添加上就可以了。成功后，vercel域名配置界面会显示 Valid Configuration。

踩坑：官网很难访问，即使挂了代理

freenom官网访问起来比较神奇，有些页面需要直连，挂代理不通，有些页面又需要挂代理，需要切换着访问。

阿里云买域名

freenom域名到期后，我想着买个长期域名算了。

阿里云的部分域名10年很便宜，fun域名初始10年188元，续费也没贵多少，相比国外域名商唯一缺点是要实名买，倒是不用ICP备案。类似freenom做好配置后，稍等等就ok了。

CDN

换完域名后，我又试着搞了CDN，国内免费CDN就挺好，可以有效解决vercel站点无法访问和慢的问题，缺点是网站要ICP备案。我不想搞，只能找国外的了，试着用了cloudflare，很易用，不错，控制台有详细配置说明，照做就行了。缺点是做完CDN后，国内部分省份运营商还是访问不了的。