前言
Hugo 是一个基于 Go 语言开发的静态网站生成器(SSG),目前由 @bep 领衔开发,Hugo 的突出特点是简洁、灵活、高效,目前有很多知名网站都在使用 Hugo:Netlify、Let’s Encrypt、IPFS、Cloudflare Developers、DigitalOcean Docs、1Password 等等。与目前国内流行的 Hexo 相比,Hugo 的速度可称为飞速🚀——在安装和使用上都是如此。
下面,我们就来看一下 Hugo 与 Hexo 的一些异同,不过需要注意的是:此文主要探讨的是用户层面上的一些异同,而非技术层面的差异。简体中文来说🐼:即一个技术小白(我)从 Hexo 迁移到 Hugo 时遇到的一些常见问题。
目录结构
|
|
在 Hugo 中,与 Hexo 的一个很大不同——也可以说是优点——是主题目录与站点目录有一样的结构,以 MemE 主题举个例子(已剔除无关文件):
|
|
其中,assets
、data
、layouts
、static
的作用都是与站点目录下的相应文件夹相同的,且站点目录下的文件可以覆盖主题目录下的相应文件——这意味着你可以在不修改主题文件的前提下方便地定制主题。在 Hugo 中,如果你想要定制主题,你只需在站点目录下新建相应的文件即可。这是非常利于主题的维护的,你只需使用 Git 的 submodule
的方式安装 Hugo 的主题,然后更新时只需直接在站点根目录下敲一条命令回车即可,非常方便!同时,这在持续集成部署时也会方便很多,这点你可以在 GitHub 中看出来,如下图。
此外,上面的 i18n
文件夹相当于 Hexo 的主题中的 languages
文件夹,如果你不喜欢主题的一些文字翻译,可以在站点目录下新建相应文件自定义。这里特别需要提醒的是,Hugo 中的 data
和 i18n
文件夹下的所有文件都是可以按「键」覆盖的,即你无需复制文件全文,只需添加你想自定义的那项即可。
配置文件
Hugo 中是不区分站点和主题的配置文件的,Hugo 中只有一个位于站点根目录下的 config.toml
配置文件1。你可能注意到 .toml
后缀,没错,Hugo 默认使用的配置文件是 TOML 格式的,它的语法是非常简单易懂的,它在语法上也没有缩进的要求2。当然,在 Hugo 中你也可使用 Hexo 默认的 YAML 格式,但我还是建议你使用 TOML,毕竟入乡随俗嘛😺。此外,如果你想将文章中的 Front Matter 也从 YAML 转换成 TOML 的话,推荐一个 Python 脚本,是我在这篇文章中发现的。但特别注意:尝试前务必先备份!
分类方式和组织方式
实话实说,这应该是从 Hexo 迁移到 Hugo 中遇到的最难的问题了,主要是概念上很难转过来。我们知道,在 Hexo 中有两种分类方式——分类和标签,它们都是在文章的 Front Matter 中设置的,其中:categories
是具有顺序性和层次性的,即你可以通过它来实现树状结构的分类;tags
则没有这种特点,它的作用只是将不同的文章联系起来。由于 Hexo 中的 categories
具有这样的特点,因此在 Hexo 中 categories
可以作为一种文章的组织方式——在 Hexo 中你可以将 categories
用在文章的 URL 结构中。
但是在 Hugo 中这是无法实现的,在 Hugo 中你是无法将文章的 Front Matter 中的 categories
用于文章的 URL 的。为什么呢?因为 Hugo 中的 categories
与 tags
在功能上其实是完全相同的,它们的作用都是将不同的文章联系起来。其实,Front Matter 中的 categories
和 tags
在 Hugo 中都属于 Taxonomies:
Hugo includes support for user-defined taxonomies to help you demonstrate logical relationships between content for the end users of your website.
简体中文来说🐼:「Hugo 支持用户定义的类别(taxonomies)来帮你为自己网站的读者展示文章之间的逻辑关系」。也就是说,在 Hugo 中其实你可以自定义自己想要的任何类别,而不仅限于部类(categories
)4和标签(tags
),比如:你可以自定义一个 series
,也就是系列╱专题╱专栏。
既然 Hugo 中基于 Front Matter 的部类和标签都属于类别,而类别的作用只是联系文章,部类自然不可能有树状结构,自然也不能用部类来组织文章。那么,在 Hugo 中你要怎么组织文章呢?分区(Sections)。所谓分区,即站点的 content
目录下的文件夹和子文件夹,一个文件夹即一个分区5。很明显,这是基于文件系统的结构的,自然也就支持树状╱网状╱嵌套结构,也就能够用来实现文章的树状分类。我觉得这是 Hugo 的又一个优点,直接利用起文件系统的结构来组织文章,合理且符合用户预期,Markdown 文档的存放也更有序。
URL
迁移博客过程中最重要的莫过于保证文章的 URL 不变,不然,这将会非常不利于 SEO。好不容易有一篇文章出现在 Google 相关搜索结果的前排,却因为 URL 的变化导致原链接 404 从而导致该文章从 Google 的索引中移除,这一定会是非常令人沮丧的😶。
当你从 Hexo 迁移到 Hugo 时,如果你在 Hexo 中的站点配置文件 _config.yml
的 permalink
中只使用了 :year
、:month
、:day
、:title
变量的话,那么文章的 URL 是能够平滑地迁移到 Hugo 的,见 URL Management。同时,提醒一点,Hexo 中的文章中的 Front Matter 中的 permalink
在 Hugo 中对应的是 slug
。
但是,对于某些用户(比如我)在迁移时则可能会有一些麻烦,比如在 Hexo 中使用了 :category
、:id
、:abbrlink
变量,以及 .html
后缀。下面就来讲讲这些情况的解决之道。
首先就是部类,即 Categories 页面,也即 Front Matter 中的 categories
,也即配置文件里的 :category
。
正如上文所说的,Hugo 中的部类是与标签无差别的,所以在 Hugo 中你是无法实现多级的部类的,即当你从 Hexo 迁移到 Hugo 时,/categories/foo/bar/
这样的链接是一定会 404 的,除非你使用 Aliases。当然,这其实也无所谓,因为重要的是文章的链接,其它页面的链接可保持也可不保持。
对于文章的链接,如果你设计了复杂的多级部类(树状分类)且将之加入了文章的 URL 结构,那么在 Hugo 中保持文章 URL 中的这种结构的合理方式就是使用分区 Sections,然后在 Hugo 的配置文件 config.toml
中的 permalinks
配置相应的分区的 :sections
变量6。
然后是 .html
后缀,博主当时年轻,想着加上这个显得 COOL 一点,于是添加了此参数并随着那篇教程带偏了很多人。现在接触了 Hugo,博主知道了这样的 URL 其实是很丑的,所以也就不在 Hugo 中保持了。毕竟,现代的服务器都有类似的自动跳转,这意味着原链接并不会 404,故在 Hugo 中也没必要再去丑化 URL。
当然,如果你还是想在 Hugo 中保持文章的 URL 的 .html
后缀,也不是没有办法,利用 Hugo 配置中的 uglyURLs
和 Output Formats 的一个配置项 noUgly
即可实现。首先在配置文件 config.toml
的顶部加上 uglyURLs = true
,然后继续添加以下代码:
|
|
这样就能实现仅文章的 URL 是有 .html
后缀的,但需要注意的是:这样是会产生一些 bugs 的——具体我就不再花时间叙述了——因此还是建议直接抛弃 .html
后缀。
迁移时另外一个比较重要的 URL 问题应该是中文部类和中文标签的英文别名问题,比如你添加了一个「树莓派」标签,但你不希望该标签的 URL 是 /tags/树莓派/
,你希望它的 URL 是英文的 /tags/raspberry-pi/
。在 Hexo 中你可以通过站点配置文件 _config.yml
中的 tag_map
来实现,但在 Hugo 中没有这样的功能,那在 Hugo 中应该怎么办呢?
首先,你需要在配置文件 config.toml
中配置下部类和标签的 URL 结构:
|
|
然后,在你的站点根目录下的 content
文件夹内新建 tags
文件夹,并在它的里面新建一个 树莓派
文件夹,最后在该文件夹内新建一个 _index.md
文件,并加入:
|
|
这样就解决了 URL 内的中文标签的别名问题。但还有一种特殊情况,就是你添加的标签如果比较复杂7,比如 Raspberry Pi(树莓派)
。那么此时,你在 tags
文件夹内新建的文件夹的名字就不能是标签的名字本身,而必须是 Hugo「链接化」后的标签名,比如 raspberry-pi树莓派
。然后,在上面添加了 slug
的基础上,再手动添加一行 title = "Raspberry Pi(树莓派)"
以修正标题。此外,如果你在配置文件 config.toml
中设置了 disablePathToLower
,那么新建的文件夹的名字就应该是 Raspberry-Pi树莓派
。
这里再来说一说 URL 中的英文字符的大小写的问题。在 Hexo 中如果你添加一个 Raspberry Pi
标签,那么它的 URL 是 Raspberry-Pi
,但在 Hugo 中它的 URL 会变成 raspberry-pi
,即将大写字母处理成了使 URL 更美观的小写字母。这也意味着当你从 Hexo 迁移到 Hugo 时,你的一些包含大写字母的原链接会 404,如果你想避免这个情况,你可以在配置文件 config.toml
的顶部加上 disablePathToLower = true
。但我还是不建议这样做,因为全小写的 URL 的确会更美观,即使这会导致原链接 404,但重要的是文章的链接,而非某一标签页面。
最后,对于以上方法,我只能保证在 MemE 主题中是正常工作的。此外,MemE 主题支持复杂的中文标签名,支持复杂的中文部类名,支持复杂的中文分区名。
对于分区,我推荐直接使用小写英文命名,然后通过新建相应的 _index.md
并添加 title
以修正标题。当然,如果你要用中文也可以,但建议用简单的中文名。然后,如果你想要使分区的 URL 却为英文,比如:你想使「系列」分区的 URL 为 /series/
而非 /系列/
,那么你需要先在「系列」文件夹下新建一个 _index.md
文件,然后加上以下内容:
|
|
最后在配置文件 config.toml
中配置下该分区下的文章的 URL 结构,比如:
|
|
对于从 Hexo 迁移到 Hugo 在 URL 上的其它情况,比如在 Hexo 中使用了 :id
和 :abbrlink
变量,那么你可以通过 url
在文章的 Front Matter 中直接手动指定文章的 URL,以保持文章链接的不变。
当然,如果在迁移时你想重构博客文章的 URL 结构,那么可以利用 Hugo 的 Aliases 或 Netlify 的 Redirects8 来保证原链接不 404。根据我的测试,这两种方式是都可以平滑地实现链接的迁移的,即不会降低文章在 Google 搜索结果中的排名。
其它方面
在迁移时还会遇到一些小问题,比如:日期格式、修改时间、阅读更多、Hexo 的标签插件等等问题,下面来一一说明。
首先是文章的 Front Matter 中的 date
日期格式的问题。在 Hugo 中,Hexo 默认的日期格式是不能工作的,比如:你必须要修改 1969-07-20 20:17:43
为 1969-07-20T20:17:43+00:00
,即添加了时区的信息。对于这点,你可以用上文提到的那个 Python 脚本批量处理一下。
然后是文章的修改时间的问题。在 Hexo 中,会自动将文件的修改时间作为文章的修改时间,但在 Hugo 中不会。不过你可以自行配置9,在配置文件 config.toml
中加入 :fileModTime
:
|
|
如此,就算你没有在文章的 Front Matter 中手动指定修改时间 lastmod
,它依然会随着你的文章的改动或修改而「自动更新」。
在 Hexo 中,你可能会在 Markdown 中使用 Hexo 标签插件来实现一些 Markdown 语法无法实现的特殊排版需求。这些特殊的语法是无法在 Hugo 中生效的,尽管在 Hugo 中有与之对应的短代码,但它们之间的语法是不同的,故我建议最好放弃这种非 Markdown 原生语法的写法。当然,如果你非要手动将之从 Hexo 迁移到 Hugo 中也不是没有可能,比如:你可以用 hugo-notice 实现 NexT 主题的 Note 标签。
此外,对于文章摘要的截取,即「阅读更多」上方的内容。在 Hexo 中你可以在文章中加入 <!-- more -->
来控制,但这在 Hugo 中是不会生效的,在 Hugo 中你必须将空格删除,即 <!--more-->
。
还有一个是 index.md
的问题,在 Hugo 中你必须在它的前面添加一个下划线,即 _index.md
。比如:你想自定义标签页面的标题为中文,那么你先在新建一个 content/tags/_index.md
文件,然后在文件中加入:
|
|
在 Hexo 中,你每对文章进行一次修改,你就必须要在浏览器中手动刷新一下页面,如此才能看到最新的渲染结果🐶。但在 Hugo 中,只要有相关变化,Hugo 就会自动为你刷新页面。也就是说,你可以即时预览😎!顺便安利一个有用的技巧,在配置文件上方添加 newContentEditor = "gedit"
(修改 gedit
为你喜欢的编辑器名),就可以在每次 hugo new
新建文章后自动打开你喜欢的文本编辑器!
在 Hugo 中,与 hexo s
命令等同的是 hugo server
,但由于默认的文章模板里面有 draft: true
,故需加上 -D
参数以渲染草稿;与 hexo g
命令等同的是 hugo
,用来生成 public
文件夹;与 hexo clean
类似的命令是 hugo --gc --cleanDestinationDir
;在 Hugo 中可以直接使用 hugo --minify
压缩 HTML、JS、CSS 等文件;在 Hugo 中,没有 hexo d
一键部署 public
文件夹到 GitHub 的操作,你需要自己新建脚本,但我建议使用 Git 管理整个站点,然后上传整个站点到 GitHub 以通过持续集成的方式部署,而非用 Git 直接部署 public
生产版代码,因为这其实是非常可笑的——Git 是用来管理源码的。此外,关于 hugo
命令的更多参数,请见 Commands。
最后,Hugo 默认是渲染到内存的,如果你有一些特殊情况要调试,比如 Service Worker,那么你可以通过使用 --renderToDisk
参数渲染到硬盘来实现调试。此外,如果你有一个厚重的 static
文件夹(比如有大量图片或视频),那么也可以使用该参数以渲染到硬盘。不然,Hugo 可能会吃光你的电脑内存🤪。
-
当然,你也可以将它拆分开来,见:https://gohugo.io/getting-started/configuration/
-
为了在中文上将 Categories 和 Taxonomies 与广义的分类区分开来,今后一例将 Categories 翻译为「部类」,将 Taxonomies 翻译为「类别」。
-
需注意的是子文件夹内必须有
_index.md
,否则 Hugo 不会认为该子文件夹为一个分区,见:https://gohugo.io/content-management/sections/#nested-sections -
Hugo 默认的分区的 URL 结构
/:sections/:slug/
就有:sections
变量,但如果你要添加其它变量,则需添加它。