从 Jekyll 迁移到 Hugo 完整实战指南:以 klogg 官网(hugo-book 主题)为例
从 Jekyll 迁移到 Hugo 完整实战指南:以 klogg 官网(hugo-book 主题)为例
本文是一份面向静态博客/文档站维护者的迁移实操指南,核心主题是如何将基于 Jekyll 的站点平滑迁移到 Hugo:包括静态资源目录的搬迁、Hugo 配置文件与发布目录的设定、模板与插件(shortcodes)的等价改写,以及迁移后的内容修复与清理。文中将以开源项目 klogg 的官网为贯穿案例——该官网正是使用 Hugo 与 hugo-book 主题构建的(见 website/config.toml),读者学完本文即可掌握一套可复制的 Jekyll → Hugo 迁移方法论,并能读懂 Hugo 站点的目录结构与主题扩展机制。
迁移前:理解 Jekyll 与 Hugo 的根本差异
迁移的第一步不是动手改文件,而是先弄清两个静态站生成器在"约定"上的差异。Hugo 的理念是"零依赖、一个二进制、毫秒级构建",而 Jekyll 依赖 Ruby 生态。两者最大的结构性差异体现在静态资源与输出目录上:
| 维度 | Jekyll | Hugo |
|---|---|---|
| 静态资源目录 | 根目录下所有不以 _ 开头的目录都会被原样拷贝到输出目录 |
统一放在 static/ 目录下 |
| 默认输出目录 | _site |
public |
| 模板引擎 | Liquid | Go 原生模板(html/template) |
| 可执行扩展机制 | Ruby plugins | shortcodes(可内嵌于 Markdown) |
klogg 官网的实践正体现了 Hugo 的目录约定:静态资源(Logo、图片、字体、图标)位于 website/static,内容包括 Markdown 源文件位于 website/content,主题代码位于 website/themes/hugo-book。理解这些目录划分是迁移的基础。
第一步:把静态内容移入 static
Jekyll 有一条规则:任何不以 _ 开头的目录,都会被原样拷贝到 _site 输出目录中。Hugo 则把所有静态内容统一收纳在 static 目录下,因此迁移的第一步就是把它们全部搬过去。
假设原 Jekyll 项目结构是这样的:
▾ <root>/
▾ images/
logo.png
迁移后应变成:
▾ <root>/
▾ static/
▾ images/
logo.png
此外,任何希望最终落在站点根路径的文件(例如自定义域名所需的 CNAME 文件)也要一并移入 static,Hugo 会原样发布 static 下的所有内容。对照仓库看:website/static 下既有 favicon.png、klogg.png 这样的根级文件,也有 css/、js/、images/、webfonts/ 等子目录,全部会被 Hugo 直接拷贝到输出站点的对应路径。
第二步:创建 Hugo 配置文件
Hugo 支持从 JSON、YAML 或 TOML 三种格式读取配置,也支持自定义参数。迁移时需要把你原来的 Jekyll _config.yml 中的站点级配置(标题、URL、语言、菜单、自定义参数等)翻译成 Hugo 配置。
以仓库中 klogg 官网的真实配置为例(website/config.toml),一个可运行的最小配置是这样:
baseURL = "https://klogg.filimonov.dev/"
languageCode = "en-us"
title = "KLOGG"
theme = 'hugo-book'
disableKinds = ['taxonomy', 'taxonomyTerm']
[markup]
[markup.goldmark.renderer]
unsafe = true
[params]
BookToC = 2
BookLogo = 'klogg.png'
BookSection = 'docs'
BookRepo = 'https://github.com/variar/klogg'
BookDateFormat = 'Jan 2, 2006'
BookSearch = false
关键参数说明:
baseURL:站点的绝对根地址,生成 sitemap、RSS 与绝对链接时使用;languageCode:站点主语言,会影响 HTML 的lang属性与 i18n 行为;theme:声明使用的主题目录名,这里指定了hugo-book,对应 website/themes/hugo-book;disableKinds:禁用不需要的页面类型(klogg 官网关掉了 taxonomy 与 taxonomyTerm,即标签/分类归档页);markup.goldmark.renderer.unsafe = true:允许 Markdown 中直接书写原始 HTML,hugo-book 的 mermaid/katex 等特性依赖此开关(可对照 website/themes/hugo-book/exampleSite/config.toml 中的注释确认);<a href="https://link.gitcode.com/i/44999ef304c1f2baed393eaccf615ce7" target="_blank">params]:主题自定义参数区。BookSection = 'docs'决定左侧菜单渲染哪个内容分区(在 [website/themes/hugo-book/layouts/partials/docs/menu-filetree.html 中通过.Site.Params.BookSection读取,默认值为docs);BookToC = 2控制右侧目录层级数;BookLogo指定站点 Logo;BookSearch控制是否开启站内搜索。
第三步:把发布目录指向 _site(或调整 submodule)
Jekyll 默认把站点发布到 _site,而 Hugo 默认发布到 public。如果你此前习惯把 _site 作为 git submodule 挂载到 GitHub Pages 的 gh-pages 分支,迁移时有两条路可选:
方案一(推荐):把 submodule 从 _site 改挂到 public
git submodule deinit _site
git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
方案二:让 Hugo 继续使用 _site 作为发布目录
Hugo 的配置项原名 publishdir(对应 --destination 命令行参数),配置如下:
{
..
"publishdir": "_site",
..
}
实际部署时两者皆可,但推荐方案一:让 Hugo 使用其惯用的 public 目录,减少后续认知偏差与配置文件里残留 Jekyll 痕迹的可能。
第四步:把 Jekyll 模板转换为 Hugo 模板
这是整个迁移工作中工作量最大的部分。Jekyll 模板基于 Liquid(Ruby),Hugo 模板基于 Go 的 html/template 模板引擎——一个逻辑极简、"只提供恰到好处的逻辑量"的引擎。Go 模板的独特之处在于上下文感知:变量与内容会根据其输出位置(HTML、属性、URL 等)被自动转义/净化。
Go 模板的语法要点,直接决定了你改写模板的方式:
- 变量与函数调用写在大括号内:
{{ foo }}、{{ add 1 2 }} - 参数以空格分隔
- 字段与方法通过点号访问:
{{ .Params.bar }} - 支持管道(pipes)串联:前一个动作的输出成为下一个动作的最后一个参数,例如
{{ index .Params "disqus_url" | html }}先取出页面参数再执行 HTML 转义 - 迭代用
range,条件用if/else/with/or/and,每个语句块以end收尾 {{ . }}永远指代"当前上下文"(context):顶层是页面数据,进入range循环后则变成当前迭代项
一个典型陷阱是循环内的上下文切换——进入 range 后 . 不再指向整页数据,需要在循环外先把要用到的值存入变量。hugo-book 主题的源码可以印证这一点,例如 website/themes/hugo-book/layouts/partials/docs/menu-filetree.html 中 book-section-children 递归模板通过 (dict "Section" . "CurrentPage" $) 显式传递上下文;website/themes/hugo-book/layouts/_default/baseof.html 则展示了 {{ template "menu" . }} 这类带尾随点号的模板 include 写法——把当前上下文传给被引用的模板。
第五步:把 Jekyll 插件转换为 Hugo shortcodes
Jekyll 有插件机制(Ruby),Hugo 则有 shortcodes。两者功能对等,移植成本通常很低:插件用于"在内容中插入一段定制 HTML 逻辑",shortcode 也是。
一个真实的移植案例:image 插件 → figure shortcode
原作者在 Jekyll 中写了一个自定义 image_tag 插件,用于生成带标题(caption)的 figure 图片。Jekyll 插件(Ruby/Liquid)的实现如下:
module Jekyll
class ImageTag < Liquid::Tag
@url = nil
@caption = nil
@class = nil
@link = nil
# Patterns
IMAGE_URL_WITH_CLASS_AND_CAPTION =
IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens)
super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1
@url = $3
@caption = $7
@link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1
@url = $3
@caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1
@caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1
@url = $3
elsif markup =~ IMAGE_URL
@url = $1
end
end
def render(context)
if @class
source = "<figure class='#{@class}'>"
else
source = "<figure>"
end
if @link
source += "<a href=\"#{@link}\">"
end
source += "<img src=\"#{@url}\">"
if @link
source += "</a>"
end
source += "<figcaption>#{@caption}</figcaption>" if @caption
source += "</figure>"
source
end
end
end
Liquid::Template.register_tag('image', Jekyll::ImageTag)
移植到 Hugo 后,等价的 image shortcode 写作如下(注意 Hugo shortcode 使用 Go 模板语法,参数通过 .Get / .Inner 访问):
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }}
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
{{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
使用方式的改写
插件时代的调用写法:
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
shortcode 时代的调用写法(此例使用了一个略微扩展、名为 fig 的版本,与内置的 figure 略有不同):
{{% fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" %}}
顺带一提,shortcode 的命名参数在可读性上明显优于 Jekyll 插件靠空格与正则解析的位置参数——这正是 Hugo shortcode 机制的附带收益。
hugo-book 主题自带的 shortcode 全家桶
从 klogg 官网使用的 hugo-book 主题仓库中,可以看到大量现成 shortcode,迁移 Jekyll 插件时可以直接复用而非重写:
hint(hint.html):{{< hint info >}}…{{< /hint >}},渲染带样式的提示块,第一参数指定样式类(info/warning/danger 等),正文经markdownify渲染;details(details.html):折叠面板,支持open与title命名参数,替代了已废弃的expandshortcode(expand.html 会打印 deprecation 警告);tabs/tab(tabs.html、tab.html):标签页切换;tab通过.Parent.Scratch把内容收集到父级tabs再统一渲染,且当tab脱离tabs使用时会在构建期直接报错(errorf);button(button.html):链接按钮,支持href与relref两种寻址方式(后者会调用 Hugo 的relref函数解析页面引用);columns(columns.html):用<--->分隔符做多栏布局;mermaid(mermaid.html):按需加载 mermaid.min.js,且只加载一次(通过.Page.Scratch标记),内部用<p class="mermaid">包裹图表代码;katex(katex.html):同样"首用加载"KaTeX 资源,display参数控制行间/行内公式的包裹符号;section(section.html):遍历.Page.Pages输出子页面列表,适用于章节索引页。
klogg 官网自身就在实际内容中使用了这些机制——例如 website/content/_index.md 用 {{< columns >}} 做分栏、用 {{< button href="…" >}}Windows/Linux/Mac{{< /button >}} 输出下载按钮。这印证了"插件 → shortcode"这条路在真实项目中是主流的扩展方式。
第六步:收尾工作
修复内容
迁移后内容的修复工作量取决于原 Jekyll 站点的自定义程度,没有放之四海皆准的规则,但有一条经验法则:hugo server --watch 是你的好朋友。启动本地开发服务器,边改边看渲染结果,逐个页面修复 Markdown 语法、front matter 与 shortcode 调用中的错误,直到构建无错、页面显示正常。
补充说明:Hugo 使用 hugo server 提供本地预览(--watch 在较新版本中已是默认行为),并可用 hugo --minify 做生产构建。仓库示例配置顶部还给出了一个带 --minify --themesDir … --baseURL=… 的启动命令范例(见 website/themes/hugo-book/exampleSite/config.toml 首行注释)。
清理
此时应删除 Jekyll 相关配置与不再使用的文件:_config.yml、_layouts/、_includes/、_plugins/、Gemfile 等。凡是迁移后不再被 Hugo 引用的东西,一律清理干净,保持仓库整洁。
实战案例:一次真实迁移的 diff
原作者曾在不到一个"带娃爸爸的一天"内将个人站点从 Jekyll 迁移到 Hugo,并保留了完整的迁移 diff 记录(包含所有改动与踩坑过程),可作为迁移节奏的参考样本。迁移的核心步骤正是本文上述六步:搬静态资源 → 建 Hugo 配置 → 调发布目录 → 重写模板 → 改写插件为 shortcode → 修复与清理。
迁移检查清单与常见坑
按仓库证据与实践整理一份迁移后的自查清单:
- 静态资源路径:确认所有图片、字体、
CNAME等已落入static/,且 Markdown 中的引用路径与static内的实际位置一致。若开启 hugo-book 的BookPortableLinks实验特性,主题会在构建时对不存在的资源/页面给出warnf警告(见 render-link.html 与 render-image.html),可借此自动发现坏链。 - front matter 迁移:Jekyll 的
layout: post等字段在 Hugo 中不再需要,改为通过type、weight、menu控制页面归类与排序。例如 klogg 的发布文章用weight控制归档顺序(见 website/content/docs/news/release_20.12.md)。 - 模板上下文:
range循环内外.的含义不同,务必用变量保存外层上下文。 - 构建验证:至少跑一遍
hugo构建与hugo server本地预览,确认零错误后再推送到public/gh-pages分支。 - 多语言站点:如需国际化,可在配置中声明多个
[languages]并指定各自contentDir,参考 website/themes/hugo-book/exampleSite/config.toml 中en/ru/zh三语言的配置方式(对应content、content.ru、content.zh目录)。
只要按上述步骤走完一遍,你就能把任何一个 Jekyll 站点完整迁移到 Hugo,并借助 hugo-book 这类主题的 shortcode 生态,把原来需要用 Ruby 插件实现的功能用更轻量、更可读的方式继续表达。