从 Jekyll 迁移到 Hugo 是许多希望提升网站性能和简化开发流程的用户的常见选择。Hugo 以其惊人的构建速度和简洁的部署方式而闻名，这使得它成为一个极具吸引力的替代品。本指南将详细介绍迁移过程中的关键步骤和注意事项。

1. 评估您的 Jekyll 网站结构

在开始迁移之前，花时间分析您当前的 Jekyll 网站结构非常重要。这包括：

• 内容文件: 您的 .md 或 .html 文件位于何处？它们使用了哪些 Front Matter 变量？
• 布局: Jekyll 的 Liquid 模板是如何组织的？有哪些基础布局 (_layouts/)、包含文件 (_includes/) 和页面模板 (_layouts/post.html 等)？
• 静态资源: CSS、JavaScript、图片等文件存放在哪里？
• 插件: Jekyll 使用了哪些插件？Hugo 可能有内置的替代方案或需要寻找第三方解决方案。
• 配置: Jekyll 的 _config.yml 文件中有哪些设置？

2. 设置 Hugo 环境

首先，确保您已安装 Hugo。然后，创建一个新的 Hugo 站点：

hugo new site my-hugo-site
cd my-hugo-site

3. 迁移内容文件

这是迁移的核心部分。Hugo 的内容文件通常位于 content/ 目录下，并且使用 Markdown 格式。

• 复制内容: 将您 Jekyll 网站 _posts/ 目录下的 Markdown 文件复制到 Hugo 的 content/posts/ 目录下。
• 调整 Front Matter: Jekyll 使用 YAML Front Matter，而 Hugo 支持 TOML、YAML 和 JSON。如果您的 Jekyll 网站使用 YAML Front Matter，通常可以直接复制。但请注意，Hugo 有一些预定义的 Front Matter 键，例如 date、title、draft。您可能需要根据 Hugo 的惯例调整或添加这些键。
  • 日期: Jekyll 的日期格式通常是 YYYY-MM-DD HH:MM:SS +ZZZZ。Hugo 通常期望 YYYY-MM-DD。确保文件名也包含日期，例如 2023-10-27-my-post-title.md。
  • Slug: 如果您在 Jekyll 中使用了 permalink 或 slug Front Matter 变量，您可能需要在 Hugo 中手动创建对应的 slug Front Matter 变量，或者配置 Hugo 的 uglyURLs 设置。

4. 迁移布局和模板

Hugo 使用 Go Templates，而 Jekyll 使用 Liquid Templates。这两个模板引擎有相似之处，但也有关键区别。

• Hugo 的 layouts/ 目录:
  • themes/your-theme/layouts/: 您可以为您的主题创建 layouts/ 目录。
  • layouts/_default/: 存放默认的布局文件，如 baseof.html (基础模板)、single.html (单个内容模板)、list.html (列表模板)。
  • layouts/post/: 存放特定于“post”内容类型的模板。
• Liquid 到 Go Templates 的转换:
  • 变量访问: Jekyll 使用 {{ page.title }}，Hugo 使用 {{ .Title }}。
  • 循环: Jekyll 使用 {% for post in site.posts %}，Hugo 使用 {{ range .Pages }} 或 {{ range where .Data.Pages "Section" "posts" }}。
  • 条件语句: Jekyll 使用 {% if ... %}，Hugo 使用 {{ if ... }}。
  • Partials/Includes: Jekyll 的 _includes/ 对应 Hugo 的 layouts/partials/。Jekyll 的 {% include header.html %} 变成 Hugo 的 {{ partial "header.html" . }}。
  • 基础模板: Jekyll 通常有一个 _layouts/default.html，Hugo 对应 layouts/_default/baseof.html。Hugo 使用 {{ block "main" . }} 和 {{ define "main" }} ... {{ end }} 来定义和填充内容区域。
• 主题选择: 您可以选择重写所有模板，或者基于一个现有的 Hugo 主题进行修改。

5. 迁移静态资源

将 Jekyll 网站的 css/, js/, images/ 等目录下的所有静态文件复制到 Hugo 站点的 static/ 目录下。Hugo 会自动将 static/ 目录下的文件复制到输出目录的根目录下。

6. 配置 Hugo 站点 (config.toml)

创建一个 config.toml 文件（或 .yaml, .json）在 Hugo 项目的根目录。您需要将 Jekyll 的 _config.yml 中的设置迁移过来。

• baseURL: 对应 Jekyll 的 url。
• languageCode: 对应 Jekyll 的 lang。
• title: 对应 Jekyll 的 title。
• theme: 如果您选择使用 Hugo 主题，在这里指定。
• params: Jekyll 的许多配置项（如 author、description）可以放在 Hugo 的 params 部分。
• 菜单: Hugo 的菜单配置与 Jekyll 不同，需要使用 [[menu.main]] 等结构来定义。

7. 处理 Jekyll 插件

许多 Jekyll 插件在 Hugo 中有内置的替代方案或需要不同的实现方式。

• Sass/SCSS: Hugo 内置了对 Sass/SCSS 的支持，可以直接在 assets/ 目录中使用。
• 分类/标签: Hugo 内置了对分类和标签的支持。您需要在 Front Matter 中定义它们，并创建对应的列表页面。
• 生成内容: 如果您依赖 Jekyll 插件生成内容，您可能需要编写脚本来预先生成这些内容，或者寻找 Hugo 的短代码（shortcodes）或自定义的构建流程来替代。

8. 测试和部署

在迁移过程中，定期运行 hugo server 来预览您的网站。检查内容是否正确显示，链接是否有效，样式是否一致。

完成迁移后，运行 hugo 命令生成静态文件。然后，您可以将 public/ 目录的内容部署到您的托管平台。

常见迁移问题及解决方案

• 日期格式错误: 确保文件名前有日期，并且 Front Matter 中的 date 字段格式正确。
• 链接失效: 检查 Hugo 模板中的链接是否正确指向其他页面或资源。使用 relURL 或 absURL 函数可以帮助生成正确的相对或绝对 URL。
• 样式丢失: 确认 CSS 文件在 static/ 目录下，并且在模板中被正确引用。
• Liquid 特有功能: 某些 Liquid 的高级功能可能需要重新思考在 Go Templates 中的实现方式。

迁移虽然需要一些时间和精力，但通过 Hugo 获得的性能提升和开发效率的提高，通常是值得的。