架设中文 Hugo 站点

基本操作

使用 hugo 架设站点其实并没有什么难度. 只是需要读一下文档.

安装 hugo 没有什么好说的, 就是一个二进制文件, 你可以选择直接下载, 然后扔到 PATH 目录. 相信如果在看这篇文档的话, 对此应该没有什么问题.

和其它类似的现代框架命令一样, 使用 hugo new site <site-name> 命令会自动生成一套脚手架代码.

下一步是选择主题, 本站选用的是 hermit 主题. 其实, 你只需要直接把主题的代码复制下来, 再丢到 themes 目录下即可. 不过, 如果你选择使用 git 来做版本管理的话, 可以尝试 git submodule.

$ hugo new site <site-name>
$ cd <site-name>
$ git init
$ git submodule add --depth 1 --name 'themes-hermit' \
    -- https://github.com/Track3/hermit.git themes/hermit
$ git add .gitmodules archetypes/ config.toml
$ git commit -m 'init commit'

接下来是配置文件 config.toml 的编辑, , 需要查看一下主题的文档. 另外, 虽然默认是 toml 格式. 不过你可以使用 yaml 或者 json, 有些主题有一些属性必须在 config.toml 中配置 menu; 另一些主题则会让你自己创建 layout 下面的一些页面.

我觉得比较重要是的 baseURL, 最好还是设为 "/", 而不要像上面那样写死. 毕竟建站换域名其实更常见, 更不要说测试预览很多部署环境都偏向于使用测试域名. 写死域名并不利用这些场景的部署.

多语言支持

有一点在官方的多语言支持文档里没有讲到. 就是主题的支持情况. 对于之前我提到的 hermit 主题来说. 比较有趣的一点就是你需要设定 languageCode 就是类似于:

[languages.en]
languageName = "English"
contentDir = "content/en"
languageCode = "en"
weight = 20

这个和主题的实现有一点关系.

实现多语言还要在多域名和多路径两种风格之间做出选择. 个人觉得没有太大必要使用两个域名来表示两个语言频道. 中日韩这种多字节文字的可能还需要再设置 hasCJKLanguage. 最后应该差不多这样:

isMultiLingual = true
defaultContentLanguage = "zh-hans"
hasCJKLanguage = true
defaultContentLanguageInSubdir = true

日期格式的话, 暂时就不要指望 二〇〇〇年 这种复杂格式了.

org mode 和 ox-hugo

如果跟我一样小众到使用 org mode 的话, 建议使用 ox-hugo 来做导出. hugo 默认的 goorg 并不是百分百兼容 org mode. ox-hugo 有一些很有意思的设计, 比如说 CLOSE 映射为 hugo 里的发表日期, TODO 作为 hugo 中草稿标志.

这里提一下 ox-hugo 的作者对于 CJK 的支持倒是很热心.

一些问题

一些不足还是需要讨论的. 任何工具都有一些局限性, 个人不能认同在小众工具的相关文字中不提及其不足之处.

比如说各种主题对于多语言的支持其实需要你去略略观察一下相关的各主题具体的实现. 比如说, hermit 代码 使用了 languageCode, 但是最初这个是为了 rss 提供的.

另一个影响使用者更多的是 hugo 的配置项中需要 Weight 参数去指定显示排序. 但说起来 yaml 里面虽然 mapping 顺序没有被保存, 但是 sequence 是有顺序的; toml 和 json 的 array 其实也类似. 所以, 理论上并不需要一个单独的 Weight 来做这件事情.

上面两个问题, 其实还涉及到一个更深层的问题. 就是 hugo 还是很依赖于 golang 的默认实现, 并没有为实现功能去加更多的代码, 当然, 这个有另一方面仍是有好处的.

结语

大致就是这些了. 部署时, 比较流行的是 github 和 netlify 相配合, 基本上可以实现代码管理和自动化发布.