博客系统迁移：Hexo 到 Hugo

虽然旧博客的源文件不会删除，但是其主题、布局等还是具有怀念意义的，因此采用之前自己写的工具对其备份，然后利用 PdfMerger 将所有文章打成一个文件。

1
2

blog-backup -w ljc -o /tmp/blog -v
java -jar target/pdfmerger-1.2.2-jar-with-dependencies.jar  /tmp/blog/*pdf ljc-backup.pdf

对于个人博客的迁移而言，保证文章链接不变是最重要的。在 hexo 中，文件名与链接的对应关系如下：

1

permalink: blog/:year/:month/:day/:title/

对应的 markdown 文件是

1

source/_posts/:year-:month-:day-:title.markdown

这样的好处是文件按照时间排列，管理方便。

Hugo 则不同，它默认会用文件中 frontmatter 的 date，而非文件名中的。我已经习惯了 hexo 的组织方式，不想去改变，经过一番探索，最终在 hugo 添加下面的配置完美解决：

1
2
3
4
5

[frontmatter]
  date = [":filename", ":default", ":fileModTime"]

[permalinks]
  post = "/blog/:year/:month/:day/:slug/"

这样 Hugo 就会首先从文件名中解析日期，同时也会解析 slug；失败时再从 frontmatter 中解析，更多用法可参考官方文档 Configure Dates。

同时，为了避免 hugo new post/year-month-day-slug.org 时标题中带日期，修改默认模板如下：

1

title: {{ replace  .Name "-" " " | replaceRE "^\\d{4} \\d{2} \\d{2} (.*)" "$1" | title }}

默认 Hugo 生成的 RSS 链接为 /index.xml ，而我之前用的是 /atom.xml，可以通过如下配置修改：

1
2
3
4

[outputFormats]
[outputFormats.RSS]
mediatype = "application/rss"
baseName = "atom"

Hugo 中默认会把链接中的字母变成小写，比如标签 Go ，在之前对应地址 /tags/Go ，换成 Hugo 后则是 /tags/go ，可以通过下面的配置关闭这个转化。

1

disablePathToLower = true

如果想保留这个功能，可以进行下面的操作：

1
2
3
4
5
6
7
8

# 让 git 区分文件名大小写
git config --global core.ignorecase true
# 删掉仓库中已有的大写目录
git rm -rf 'tags/Go'
# 重新生成网站
hugo
# 重新添加
git add .

这时 git status 会显示

1

renamed:    tags/Go/index.html -> tags/go/index.html

然后提交就可以了。

Frontmatter 定义了每篇文章的属性，比如标题、分类等。这也是在 hexo 迁移到 hugo 时问题最多的地方，根本原因在于 hexo 对 frontmatter 格式较宽松，而 hugo 则比较严格。

下面一个 hugo 中标准的 frontmatter（除 yaml 外，还可以是 toml/json）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

categories:
- Development
- VIM
date: "2012-04-06"
description: spf13-vim is a cross platform distribution of vim plugins and resources
  for Vim.
slug: spf13-vim-3-0-release-and-new-website
tags:
- .vimrc
- plugins
- spf13-vim
- vim
title: spf13-vim 3.0 release and new website

主要有两点需要注意：

1. categories/tags 这两个属性必须是数组

2. frontmatter 前后需要用 --- 包起来，与正文区分

而在 hexo 中，

1. categories/tags 可以是数组，也可以是字符串，表示一个元素的数组

2. 只需要 frontmatter 末尾强制用 --- 与正文区分，前面的不做要求

由于我文章较多（72篇需要迁移），且格式也都不一样（可能是 hexo 2/3 的区别），因此写了两个脚本来辅助，最终生成符合 hugo 要求的 frontmatter。如果 frontmatter 格式不对，可能会遇到下面的错误：

1
2
3
4
5
6

Start building sites …
ERROR 2020/12/04 20:33:38 render of "home" failed:
execute of template failed: template: index.html:6:9:
executing "content" at <.Render>: error calling Render: "~/quickstart/content/post/2016-04-23-sicp-chapter4-summary.markdown:8:19":
failed to execute template ["summary"] v: "~/quickstart/themes/even/layouts/post/summary.html:8:19": execute of template failed:
template: post/summary.html:8:19: executing "post/summary.html" at <.>: range can't iterate over 研习经典

说明 categories 或 tags 有不是数组的，需要改成数组

1

EOF looking for end YAML front matter delimiter

说明缺少了 frontmatter 结尾的分隔符，如果缺少开头的分隔符，编译文章没有错误，但是最终生成的文章页面会没有标题。

在 hexo 中分类（category） 和标签（tags） 用法是不一样的，分类可以有层次，比如：

1
2
3
4
5

categories:
- [Sports, Baseball]
- [MLB, American League, Boston Red Sox]
- [MLB, American League, New York Yankees]
- Rivalries

标签则没有；在 hugo 中分类与标签用法一样，都只有一层。由于我之前博客就没有用到多层分类的情况，所以也就不需要额外处理了。

其次，在 hexo 可以通过 category_map/tag_map 来定义 category/tags 的固定链接地址（即 slug），虽然我之前也了这个特性，但是这次并没有去适配，采用 hugo 默认的即可。有修改需求的读者可参考：

• Is it possible to customize the categories/tages url?

markdown 中引用图片的标准做法是

1

![Alt text here](/images/image.jpg "Title here")

但是我一般只写 alt，title 基本没写过，之前使用的主题 maupassant 默认会把图片的 alt 显式在图片下面，而 hugo 只认 title，搜索发现可以通过 hugo 提供的 markdown render hook 来实现。方式如下：

1. 创建 layouts/_default/_markup/render-image.html 文件

2. 添加内容

   1 2 3 4 5 6 7 8

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

对于 org-mode 而言，直接采用下面的方式即可：

1
2

#+CAPTION: some-title
[[<img-src>]]

本次迁移的所有修改可以在 Github 中查看，供有相同迁移需求的读者参考。

由于目前我又两个博客（中文和英文），因此需要做些配置让 easy hugo 识别这两个。

1
2
3
4
5
6
7

(use-package easy-hugo
  :custom ((easy-hugo-basedir  "~/gh/jiacai2050.github.io/")
		   (easy-hugo-url  "https://liujiacai.net")
           (easy-hugo-default-ext ".org")
           (easy-hugo-bloglist '(((easy-hugo-basedir . "~/gh/en-blog/")
                                  (easy-hugo-default-ext ".org")
		                          (easy-hugo-url . "https://en.liujiacai.net"))))))

虽然可以用 hugo new post/xxx.org 的方式来创建新文件，但是由于文件名中需要有固定格式的日期，每次手动输入很繁琐，因此基于 easy hugo 的多博客管理，自己实现了 hugo-newpost 函数，实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

(defun my/hugo-newpost (slug title tags categories)
  (interactive "sSlug:
sTitle:
sTags:
sCategories: ")
  (easy-hugo-with-env
   (let* ((now (current-time))
		  (basename (concat (format-time-string "%Y-%m-%d-" now)
							slug easy-hugo-default-ext))
		  (postdir (expand-file-name easy-hugo-postdir easy-hugo-basedir))
		  (filename (expand-file-name basename postdir)))
	 (when (file-exists-p filename)
       (error "%s already exists!" filename))
	 (find-file filename)
	 (insert
	  (format "#+TITLE: %s
#+DATE: %s
#+TAGS[]: %s
#+CATEGORIES[]: %s

" title (my/iso-8601-date-string) tags categories))
	 (goto-char (point-max))
	 (save-buffer))))

这样就可以通过调用 my/hugo-newpost 自动生成带日期的文件名，并且根据输入生成指定的 slug/title/tag/category。

由于目前我全局开启了 evil mode，需要把 easy-hugo-mode 添加到 evil-emacs-state-modes 里面去才能使用 easy-hugo 的快捷键，顺道解决了 easy hugo 的一个 bug。完整配置可参考这次的 Git 提交。

easy-hugo 还提供了预览、发布（默认调用 deploy.sh）等命令，比较简单，这里不再赘述。