2023-05-26    2023-11-01    5414 字  11 分钟
Hugo

在《[[一场疲惫的主题制作之旅]]》中，已经有了不少博客相关的碎碎念。这里，主要用来浅谈一下当前站点博客系统的搭建、编辑及部署相关的系列流程。

![[assets/Pasted image 20230526102219.png|400]]

当前站点，使用 Hugo 静态博客生成系统 驱动，部署在个人服务器上。事实上，你可以把生成的站点项目部署在任何可以被访问的地方（比如 Github Page），它本质上是一个包含了若干 .html 文件及相关静态资源的文件夹。

更新日志

- 2023-08-05 17:22 当下使用 Obsidian 管理博客内容
- 2023-04-05 21：31 添加新的日常编辑方式 - 使用 Typora

> 更新日志仅是为了记录每篇文章的更新过程

准备篇

……

搭建篇

……

编辑篇

这里，我们以当前文章的创建及编辑过程为例。其中：

  • ✔️ 正在使用
  • ❌ 已不使用

:: 怎么说呢？这个章节写的过于太细节了……好像…… 😅

使用 VSCode 编辑（❌）

创建文章

我们可以使用以下命令来创建文章：

1
2
3

hugo new posts/how-do-i-blog/index.md	# 推荐
# 或
hugo new posts/how-do-i-blog.md			# 不推荐

这里我们使用第一条命令，该命令会自动生成如下目录层级下 .md 文件。

content
├── posts
│   ├── how-do-i-blog
│   │   ├── imgs
│   │   │   └── 1aa09c580e674b09e82c722a3689d280012f2ae6e1700e924deeef558347d91a.png
│   │   └── index.md

为什么不直接使用 how-do-i-blog.md ，而使用 how-do-i-blog/index.md ？

正如上述目录层级中所反映的，如此方便我们把当前文件所需要的资源（如图片 imgs ）都放在当前文章的层级下，方便管理。

这样做还有额外的好处，我们将在后面 [[#插入图片]] 的部分进一步说明。

插入图片

在文章中插入图片是一个相对高频的操作。在第三方的博客平台中，一般来说直接复制图片并粘贴到要插入的位置就可以了，很方便。而编辑 .md 文件，插入图片就稍微麻烦一些。

我们通过 ![图片名称](地址链接) 在文章中插入图片，默认情况下，你需要经过：

1. 搜索图片
2. 另存图片到本地
3. 编辑 `![图片名称](地址链接)` 引用
……

很繁琐！

而且还不能控制图片的‘显示’尺寸，需要插入图片数量过多的时候，简直就是一种折磨了。

有没有一种更好的方式来插入图片呢？

很幸运，有！

我平时是使用 VSCode 来管理站点内容和编辑 .md 文件的，其中有一款插件很好地解决了这个问题。

![[assets/Pasted image 20230526102347.png]]

它提供了丰富的自定义设置选项，这里主要用到以下几种：

  • Markdown-image › Base: File Name Format ，设置为 ${hash} ，当然有其它各种格式可选组合；
  • Markdown-image › Base: Image Width ，设置为 400 ，默认宽度设为 400px ；
  • Markdown-image › Local: Path ，设置为 ./imgs ，生成的图片放在当前文章同级目录下的 imgs 文件夹中。

这也是上文中我们推荐使用 hugo new posts/how-do-i-blog/index.md 命令来生成文章的原因之一。

使用该插件，你只需要复制所需要图片（本地或网络图片），并通过其提供的粘贴方式（右键选择）插入到位置即可。如此，你的 .md 文件中，就会插如下内容：

<img alt="picture 3" src="imgs/30737f6467ed6269eed8911b8a915f47b9fed706b8f892efd3271d9b6a76181c.png" width="400" />

它会被渲染成下面这张图片，是不是很方便！

![[assets/Pasted image 20230526102356.png]]

它的原理是什么？

它会读取你剪切板中刚刚复制的图片数据，在你粘贴的时候，重新生成一份拷贝，并在 .md 文件中，插入对应的图片格式，并引用。真的很方便！🎉

其他插件

cyberbiont/vscode-open-in-typora: open Markdown files from VSCode in Typora

![[assets/Pasted image 20230815170141.png]]

在 VSCode 中使用 Typora 打开当前 Markdown 文件。

使用 Typora 编辑（❌）

创建文章不是 Typora 的强项，光是手写 Front Matter 都让人受不了，就老老实实地用 [[#创建文章]] 章节中的命令创建好文章，再用 Typora 编辑就好。（这也是不支持第三方插件的坏处了，什么问题你只能等着作者去解决。相对来说，Obsidian 就不存在这个问题，它支持类似于 Snippet 的插件扩展。）

:: 现在的编辑操作就是使用 Typora 完成的。 😄

之前的 VSCode 使用的不是很爽吗？为什么切换为 Typora 了呢？

VSCode 确实很爽，到目前为止，我也经常使用它。切换到 Typora 的原因也很简单，家里的电脑性能不行，新的主机配置还在纠结中……

更多原因可以查看 [[一款 Typora 主题]] 中的描述。

PS： VSCode 真的是一款非常优秀的编辑器，插件丰富且优质，可扩展性强，可轻可重。

使用 Typora 的感觉怎么样？

很好！如 [[一款 Typora 主题]] 中所描述的那样，配合自己制作的主题（由站点样式适配），基本上实现了所见即所得的编辑。另外，Typora 本身集成了许多 Markdown 相关的快捷键，很直观也很好用，尤其是当你专注于编写内容的时候。

它还有‘专注模式’和‘打字机模式’，很舒心。

其内置的图片插入功能也不错，基本上和 [[#插入图片]] 章节中的实现是相同的，原理没有探究。怎么说呢，Typora 上的相对来说，更加符合日常的编辑逻辑，还贴心地增加了可以缩放图片的选项，最最重要的还是‘所见即所得’，你可以实时看到你的图片。

使用 Obsidian 编辑（✔️）

支持扩展的编辑器是可以不断进化的，比如 Emacs、Vi/Vim 等。

上面说了，Typora 是不容易扩展的（不支持），这就限制了使用，要么牵就，要么离开…… 尝试了几个软件之后，Obsidian 可以说是相当不错的管理软件了，稍微‘调教’之后，就相当顺手了。

Obsidian 也是所见即所得的编辑模式，有非常丰富的三方插件，如键位映射、图片缩放/清理、表格插入/编辑等功能都可以很方便的得到实现。

……

为了更方便地显示图片及适应 [[如何使用 hugo-theme-virgo 主题]] 中关于 [[#Wiki 链接及图片语法渲染]] 的兼容，重新组织了博客层级，如下：

C:\USERS\JACK\APPDATA\ROAMING\SITE\CONTENT
│  A Simple Bookmark Copying.md
│  Ajax.md
│  C.md
│  Canvas.md
│  CPU 是如何制造出来的.md
│  CPU 缓存是什么.md
│  CSS 中的动效.md
│  Emacs Lisp.md
│  Emojings.md
│  Git.md
│  GTD 管理系统.md
│  Java 那些事儿.md
│
├─assets
│      3b5d12f26d9d00dc2b021d097ff8c34.jpg
│      4.gif
│      Pasted image 20230525155800.png
│      Pasted image 20230817094853.png
│      vim.gif
│
└─snippets
        frontmatter.md
        longitudinal.md
        more.md
        timestamp.md

并且，使用 tags 标签来分类博文，而不是之前的 categories 分类。

创建文章

如上面的博客层级所示，我用 content 目录作为 Obsidian 的根目录，如此，Obsidian 相关的所有配置（如插件、主题、设置等） .obsidian 文件夹都使用 Git 统一管理。

💡 .obsidian 默认位于 Obsidian 仓库的根目录。

创建文章很简单，直接使用 Obsidian 提供的相关创建逻辑就行了。需要注意的是，如果你的博文也想用 Hugo 进行管理的话，就需要在博文头部添加相应的信息。如：

---
title: 我是怎么写博客的
aliases: []
tags:
  - Hugo
date: 2023-05-26 
time: 10:21
---

其中， title 和 date 是必须的，Hugo 需要使用其提供的信息进行渲染。

如果你使用 hugo new 命令去生成 .md 文件的话，那么你只需要设置 Hugo 相关的 archetypes/default.md ，如：

---
title: "{{ replace .Name "-" " " | title }}"
aliases: 
tags: [_Misc]
date: {{ .Date | time.Format "2006-01-02" }}
time: {{ .Date | time.Format "15:04" }}
---

然后，运行如 hugo new my-post-name.md 之类的命令就可以了。

当然，Obsidan 本身也是支持插入模板的，如 Templater 模板插件，你写好模板，放在相应文件夹下（如 snippets/frontmatter） ，运行插入命令即可，如：

---
title:  <% tp.file.title %>
aliases: 
tags:
  - _Misc
date:  <% tp.date.now() %>
time:  <% tp.date.now("HH:mm") %>
---

插入图片

Obsidian 的插入图片很方便，你只需要像文本一样粘贴进来就好了。图片会自动上传到设置好的目录，可以是相对于当前文件的相对位置，也可以相对于仓库根目录的绝对位置。

图片插入后，默认是 WIKI 语法的，如 ![[path/to/img]] ，可以在设置中修改为常用 Markdown 语法的。当然，如果你使用  hugo-theme-virgo 主题的话，就不用担心，它支持 WIKI 语法的图片和链接的渲染。

![[assets/Pasted image 20231026173226.png]]

这个插件，可以让你方便的调整图片尺寸，如按着 ALT 键滚动缩放。

插入表格

这方面，目前没有遇到比 Typora 做的更好的了。当然，借助下面这个插件，可以实现类似 Typora 表格插入和编辑的体验：

![[assets/Pasted image 20231026173536.png]]

另外，这个插件是没有上传到官方插件仓库的，但可以借助 Obsidian42-Bart 这个插件去引入，也很方便。

![[assets/Pasted image 20231026173648.png]]

不得不说，支持第三方扩展的软件，才会更有生命力！

渲染篇

语法增强

我们在 hugo-theme-virgo 主题中，对 Markdown 的语法提供了一些增强功能 - 下划线、文字高亮、批注、折叠板 。

新增语法 效果
*_下划线* _下划线
*=高亮* =高亮

当然，如果你使用其它主题，这些增强的样式是无法生效的，幸运的是，它在其他主题中依然得到渲染 - 使用斜体显示，你并不会丢失你想表达的内容。

我们使用 >:: 吐槽系 或 > :: 吐槽系 来表示，如此在不支持的情况下，可以解析为引用样式，便于区分。在 hugo-theme-virgo 主题中，批注样式渲染如下：

![[assets/Pasted image 20230805191220.png|375]]

Wiki 链接及图片语法渲染

最近使用 Obsidian ，其使用的链接及图片格式为 Wiki 语法，如下：

名称 描述
链接 ![[assets/Pasted image 20231005135434.png|60]]
链接（带描述） ![[assets/Pasted image 20231005135451.png|116]]
图片 ![[assets/Pasted image 20231005135507.png|120]]
图片（带尺寸） ![[assets/Pasted image 20231005135528.png|166]]

Hugo 默认的 Markdown 引擎是不支持渲染这种语法的，我们这里做了一下增强，现在你可以畅快地使用 Obsidian 来编辑你的博客了。

部署篇

当你想部署你的站点内容到托管平台时，你可能会经过以下步骤：

1. 执行 `hugo` 命令，生成站点内容，默认放在站点根目录的 `public` 文件夹中；
2. 复制内容包，上传到托管平台；
……

如果，只操作一次的话，不是很复杂，但如果，你的内容更新比较频繁，那就有些烦扰了。内容包的部署方式有很多，各有优缺。

脚本部署

我们这里，使用脚本部署，一次性配置之后，每次部署只需要执行一条简单的命令即可。分享出来，供大家参考使用。

我们的站点目录如下所示：

.
├── config.toml
├── content
│   ├── about
│   ├── archive.md
│   ├── _index.md
│   ├── nav
│   ├── posts
│   └── search.md
├── package.json
├── README.md
├── resources
│   └── _gen
├── scripts
│   ├── deploy.sh
│   └── update.sh

> 2023-09-05 22:41 最新 - 完全可以做为唯一的部署脚本 ！它对站点内容的跟踪是完备的，当前环境下，只会在首次部署的时候进行全量更新，后续会自动基于 Git 的更新记录进行增量式更新，体验相当不错。

其中， scripts/deploy.sh 便是我们定义的部署脚本，其内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

#!/bin/sh
# 最新的 deploy.sh 
# -------------------
# Deploy posts to `loveminimal.github.io`
# -------------------
# rm -rf "public/CNAME" && cp -r "CNAME" "public/" # Fix potential error - Recovery `CNAME` before deploy.

# 判断是否存在 public
if [ -d "public" ]
then
    # 判断是否已经存在与 site 同级的 .temp 文件夹
    if [ ! -d "../.temp" ]
    then
        # ^ 若不存在，直接复制 public 为 ../.temp ，进入该目录，初始化，强制推送至指定的远程仓库
        echo -e "\e[32m >>> .temp not exited. \e[0m"
        cp -r "public" "../.temp"
        echo -e "\e[32m >>>[DONE] copy public to .temp. \e[0m"

        cd "../.temp"

        git init
        git add .
        git commit -m "Posts update."
        git remote add origin jack@walkssi.com:/home/jack/.repo/site.git
        # git remote add origin https://github.com/loveminimal/loveminimal.github.io.git
        # git push -f origin master:main
        git push -f origin master

    else 
        # ^ 若存在，则进入 ../.temp 目录，判断该仓库是否已初始化（包含 .git ）
        echo -e "\e[32m >>> .temp exited. \e[0m"
        cd "../.temp"
        if [ -d ".git" ]
        then
            # ^^ 若存在 .git ，则备份 .git ，并在处理 .temp 后，恢复它
            echo -e "\e[42m >>> copying.... \e[0m"
            echo -e "\e[42m >>> copying.... \e[0m"
            
            mv ".git" "../.git.bak"
            # 此处，对于 .temp 处理的目的是为了绝对保持其与 site/public 文件的一致性（无论增删）
            cd ..
            rm -rf .temp
            cp -r "site/public" ".temp"
            mv ".git.bak" ".temp/.git"
            
            cd .temp
            git add .
            git commit -m "Posts update."
            git push -f origin master
        else
            # ^^ 若不存在 .git ，初始化，强制推送至指定的远程仓库
            git init
            git add .
            git commit -m "Posts update."
            git remote add origin jack@walkssi.com:/home/jack/.repo/site.git
            # git remote add origin https://github.com/loveminimal/loveminimal.github.io.git
            # git push -f origin master:main
            git push -f origin master
        fi

    fi
    echo -e "\e[42m >>>[DONE] Update. \e[0m"
    cd "../site"
fi

在站点根目录下，运行 source scripts/deploy.sh 就可以静待站点部署完成了。

命令简化

使用 source scripts/deploy.sh 还是有点太复杂了？有如下限制：

  • 需要进行到站点根目录才可以运行它；
  • 部署后，站点内的内容包并没得到清理。

哈，你只需要多加几条命令即可，如下：

cd ~/AppData/Roaming/site && rm -rf public && hugo && source scripts/deploy.sh && rm -rf public

如此，无论当前你在那一种路径，都会：

  1. 自动进入站点根目录（此处是 site）；
  2. 删除站点下旧的 public （如果有的话）；
  3. 根据当前内容生成新的 public 内容包；
  4. 执行部署脚本，发布到对应托管平台；
  5. 清理掉生成的 public 内容包。

Emm… 还是长啊，每次都要键入这么长，太麻烦了，怎么办？

那么你就需要了解一些关于 bash alias 方面的知识了，如下所示，在当前用户家目录下，创建 .bash_aliases 文件（若无），并添加如下内容：

alias ssd="cd ~/AppData/Roaming/site && rm -rf public && hugo && source scripts/deploy.sh && rm -rf public"

保存后，在用户家目录下，运行 source .bashrc 命令使 .bash_aliases 中的别名生效。

OK，现在，当你想部署站点的时候，你只需要运行键入 ssd ，回车即可完成部署。

‘用户家目录’是什么？

在 Windows 下，有两个家目录：

  • 用户家目录，如 C:\Users\jack ，一些软件的默认配置会放在该目录下；
  • 用户漫游家目录，如 C:\Users\jack\AppData\Roaming ，另一些软件的配置又会放在这个目录下。

😅 微软的东西真的有点混乱哈。

如果，你使用的是 GNU/Linux 系统，那么家目录就只有一个喽，如 /home/jack 。

附录

废弃的部署脚本

最初版本的 scripts/deploy.sh 脚本，其内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

#!/bin/sh
# -------------------
# deploy.sh
# Deploy posts to `loveminimal.github.io`
# -------------------

# 检测是否存在 .temp 文件夹，若存在，先移除 
if [ -d "../.temp" ]
then
    echo -e "\e[31m >>> .temp exited. \e[0m"
    rm -rf "../.temp"
    echo -e "\e[32m >>> ... \e[0m"
    echo -e "\e[32m >>> .temp has been removed. \e[0m"
else
    echo -e "\e[32m >>> .temp not exited. \e[0m"
fi

if [ -d "public" ]
then
	# 如果你是部署到 GitHub ，并绑定了域名，那你可能需要启用该行，以
	# 保证其正确的指向
    # rm -rf "public/CNAME" && cp -r "CNAME" "public/"

	# 拷贝内容包 public 到一个临时文件夹 .temp ，并
	# 用 git 初始化管理该它
    cp -r "public" "../.temp"
    cd "../.temp"
    pwd
    git init
    git add .
    git commit -m "Posts update."

	# 添加远程库，引得我们使用的是个人服务器的仓库地址，如果
	# 你是托管在 GitHub 上，那么连接的对应的远程库即可 - <YOUR_USERNAME>.github.io
	# 如果你是在 GitHub ‘政治正确’后创建的库，其默认分支为 main, 那你
	# 需要 master:main 而不是 master
    git remote add origin jack@ovirgo.com:/home/jack/.repo/site.git
    git push -f origin master
    # git remote add origin https://github.com/loveminimal/loveminimal.github.io.git
    # git push -f origin master:main

	# 清除临时文件夹
    cd ..
    rm -rf ".temp"

	# 返回站点目录
    cd "site"
fi

初看，上述脚本初看可能有些混乱，但其实，理论上你只需要：

  • 更改远程仓库地址；
  • 更改站点目录，即可。

> 2023-09-05 11:53 更新 - 添加增量更新脚本

随着博文数量的增加，我们使用 deploy.sh 全量更新的话，时间也会随之变长。单纯的文字还好，但站点难免会引入外部的静态资源（图片、音频等），如此‘等待’就成了一个问题。所以，就有了 update.sh ，如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

#!/bin/sh
# -------------------
# update.sh
# Deploy posts to `loveminimal.github.io`
# -------------------
if [ ! -d "../.temp" ]
then
    echo -e "\e[32m >>> .temp not exited. \e[0m"
    mkdir "../.temp"
    echo -e "\e[32m >>> ... \e[0m"
    echo -e "\e[32m >>> .temp has been created. \e[0m"
else 
    echo -e "\e[32m >>> .temp exited. \e[0m"
fi

if [ -d "public" ]
then
    # rm -rf "public/CNAME" && cp -r "CNAME" "public/" # Fix potential error - Recovery `CNAME` before deploy.

    cp -r "public/." "../.temp"
    cd "../.temp"
    pwd
    # 该仓库没有初始化，初始化该仓库，并推送
    # 仓库已初始化，仅推送增量更新
    if [ -d ".git" ]
    then
        git add .
        git commit -m "Posts update."
        git push -f origin master
    else
        git init
        git add .
        git commit -m "Posts update."
        git remote add origin jack@walkssi.com:/home/jack/.repo/site.git
        # git remote add origin https://github.com/loveminimal/loveminimal.github.io.git
        # git push -f origin master:main
        git push -f origin master
    fi
    cd ..
    # rm -rf ".temp"
    cd "site"
fi

它保留了临时文件夹的仓库跟踪，使得我们只需要提交增量更新即可，极大的缩小了仓库更新的时间。

当然，这样也会存在一个问题，就是当你删除了某些静态文件，如图片等，仓库是无法追踪到的，它只能知道你增加了什么。幸运的是，这个场景本身很少出现，你并需要关注它。当然，如果你实在介意，你可以执行以下操作中的一个就可以实现全量更新了：

  • 手动删除 .temp 文件夹；
  • 或者，你可以直接执行前面的 deploy.sh 脚本；
  • 或者，你可以使用下面这个最新的 update.sh 脚本，它会严格保持修改前后文件的一致性，性能介于 deploy.sh 和旧的 update.sh 之间，比后者稍慢一点点（配置中等主机下几乎相同），但比前者快出非常非常多。

💡 事实上，你完全可以用下面这个最新（2023-09-05 22:41）的 deploy.sh 做为唯一的部署脚本（推荐）！