从 Jekyll 迁移到 Hugo 完整实战指南:以 klogg 官网(hugo-book 主题)为例

原创2026-10-14 18:10:221,675 阅读
文章标签:桌面应用开发工具

从 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 命名参数,替代了已废弃的 expand shortcode(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 → 修复与清理。

迁移检查清单与常见坑

按仓库证据与实践整理一份迁移后的自查清单:

  1. 静态资源路径:确认所有图片、字体、CNAME 等已落入 static/,且 Markdown 中的引用路径与 static 内的实际位置一致。若开启 hugo-book 的 BookPortableLinks 实验特性,主题会在构建时对不存在的资源/页面给出 warnf 警告(见 render-link.html 与 render-image.html),可借此自动发现坏链。
  2. front matter 迁移:Jekyll 的 layout: post 等字段在 Hugo 中不再需要,改为通过 type、weight、menu 控制页面归类与排序。例如 klogg 的发布文章用 weight 控制归档顺序(见 website/content/docs/news/release_20.12.md)。
  3. 模板上下文:range 循环内外 . 的含义不同,务必用变量保存外层上下文。
  4. 构建验证:至少跑一遍 hugo 构建与 hugo server 本地预览,确认零错误后再推送到 public/gh-pages 分支。
  5. 多语言站点:如需国际化,可在配置中声明多个 [languages] 并指定各自 contentDir,参考 website/themes/hugo-book/exampleSite/config.toml 中 en/ru/zh 三语言的配置方式(对应 content、content.ru、content.zh 目录)。

只要按上述步骤走完一遍,你就能把任何一个 Jekyll 站点完整迁移到 Hugo,并借助 hugo-book 这类主题的 shortcode 生态,把原来需要用 Ruby 插件实现的功能用更轻量、更可读的方式继续表达。

登录后查看全文
klogg