雨果vs杰基尔：静态网站生成器主题的史诗般的战斗

In this article, we'll compare the nuances of creating themes for the top two static site generators.

在本文中，我们将比较为前两个静态网站生成器创建主题的细微差别。

I recently took on the task of creating a documentation site theme for two projects. Both projects needed the same basic features, but one uses Jekyll while the other uses Hugo.

我最近承担了为两个项目创建文档站点主题的任务。两个项目都需要相同的基本功能，但是一个使用Jekyll，另一个使用Hugo。

In typical developer rationality, there was clearly only one option. I decided to create the same theme in both frameworks, and to give you, dear reader, a side-by-side comparison.

按照典型的开发人员理性，显然只有一种选择。我决定在两个框架中创建相同的主题，并为您提供亲爱的读者并排比较。

This post isn’t a comprehensive theme-building guide, but is rather intended to familiarize you with the process of building a theme in either generator. Here's what we'll cover:

这篇文章不是全面的主题构建指南，而是旨在使您熟悉在任一生成器中构建主题的过程。这是我们要介绍的内容：

How theme files are organized主题文件的组织方式
Where to put content在哪里放置内容
How templating works模板的工作原理
Creating a top-level menu with the pages object

使用pages对象创建顶层菜单
Creating a menu with nested links from a data list使用数据列表中的嵌套链接创建菜单
Putting the template together将模板放在一起
Creating styles创建样式
How to configure and deploy to GitHub Pages如何配置和部署到GitHub Pages

Here’s a crappy wireframe of the theme I’m going to create.

这是我要创建的主题的wire脚线框。

If you’re planning to build-along, it may be helpful to serve the theme locally as you build it – and both generators offer this functionality. For Jekyll, run jekyll serve, and for Hugo, hugo serve.

如果您打算同时构建，则在构建主题时在本地提供主题可能会有所帮助–并且两个生成器都提供此功能。对于Jekyll，请运行jekyll serve ；对于Hugo，请使用雨果hugo serve 。

There are two main elements: the main content area, and the all-important sidebar menu. To create them, you’ll need template files that tell the site generator how to generate the HTML page. To organize theme template files in a sensible way, you first need to know what directory structure the site generator expects.

有两个主要元素：主要内容区域和非常重要的侧边栏菜单。要创建它们，您将需要模板文件，这些文件告诉网站生成器如何生成HTML页面。要以一种明智的方式组织主题模板文件，您首先需要知道站点生成器期望的目录结构。

主题文件的组织方式 (How theme files are organized)

Jekyll supports gem-based themes, which users can install like any other Ruby gems. This method hides theme files in the gem, so for the purposes of this comparison, we aren’t using gem-based themes.

Jekyll支持基于gem的主题，用户可以像安装其他任何Ruby gem一样进行安装。此方法将主题文件隐藏在gem中，因此出于比较目的，我们未使用基于gem的主题。

When you run jekyll new-theme <name>, Jekyll will scaffold a new theme for you. Here’s what those files look like:

当您运行jekyll new-theme <name> ，Jekyll将为您架设一个新主题。这些文件如下所示：

.
├── assets
├── Gemfile
├── _includes
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
└── <name>.gemspec

The directory names are appropriately descriptive. The _includes directory is for small bits of code that you reuse in different places, in much the same way you’d put butter on everything. (Just me?)

目录名称具有适当的描述性。 _includes目录用于在不同地方重复使用的少量代码，几乎就像在所有内容上加黄油一样。 (只有我？)

The _layouts directory contains templates for different types of pages on your site. The _sass folder is for Sass files used to build your site’s stylesheet.

_layouts目录包含网站上不同类型页面的模板。 _sass文件夹用于用于构建网站样式表的Sass文件。

You can scaffold a new Hugo theme by running hugo new theme <name>. It has these files:

您可以通过运行hugo new theme <name>来搭建一个新的Hugo主题。它具有以下文件：

.
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── header.html
│       └── head.html
├── LICENSE
├── static
│   ├── css
│   └── js
└── theme.toml

You can see some similarities. Hugo’s page template files are tucked into layouts/. Note that the _default page type has files for a list.html and a single.html.

您会看到一些相似之处。 Hugo的页面模板文件被塞入layouts/ 。请注意， _default页面类型具有list.html和single.html 。

Unlike Jekyll, Hugo uses these specific file names to distinguish between list pages (like a page with links to all your blog posts on it) and single pages (like one of your blog posts). The layouts/partials/ directory contains the buttery reusable bits, and stylesheet files have a spot picked out in static/css/.

与Jekyll不同，Hugo使用这些特定的文件名来区分列表页面 (例如带有指向您所有博客文章链接的页面)和单个页面 (例如您的博客文章之一)。 layouts/partials/目录包含可重复使用的黄油，样式表文件的位置在static/css/ 。

These directory structures aren’t set in stone, as both site generators allow some measure of customization. For example, Jekyll lets you define collections, and Hugo makes use of page bundles. These features let you organize your content multiple ways, but for now, let's look at where to put some simple pages.

这些目录结构并不是一成不变的，因为两个站点生成器都允许某种程度的自定义。例如，Jekyll允许您定义集合，而Hugo利用页面捆绑包。这些功能使您可以通过多种方式组织内容，但现在，让我们看一下放置一些简单页面的位置。

在哪里放置内容 (Where to put content)

To create a site menu that looks like this:

要创建一个如下所示的站点菜单：

IntroductionGetting StartedConfigurationDeploying
Advanced UsageAll Configuration SettingsCustomizingHelp and Support

You’ll need two sections (“Introduction” and “Advanced Usage”) containing their respective subsections.

您将需要两个部分(“简介”和“高级用法”)，分别包含各自的小节。

Jekyll isn’t strict with its content location. It expects pages in the root of your site, and will build whatever’s there. Here’s how you might organize these pages in your Jekyll site root:

Jekyll对其内容位置并不严格。它期望页面位于您网站的根目录中，并将构建任何内容。您可以按照以下方式在Jekyll网站根目录中组织这些页面：

.
├── 404.html
├── assets
├── Gemfile
├── _includes
├── index.markdown
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── index.md
│   └── quickstart.md
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
├── <name>.gemspec
└── usage├── customizing.md├── index.md├── settings.md└── support.md

You can change the location of the site source in your Jekyll configuration.

您可以在Jekyll配置中更改站点源的位置。

In Hugo, all rendered content is expected in the content/ folder. This prevents Hugo from trying to render pages you don’t want, such as 404.html, as site content. Here’s how you might organize your content/ directory in Hugo:

在Hugo中，所有呈现的内容都应在content/文件夹中。这样可以防止Hugo尝试将不需要的页面(例如404.html呈现为网站内容。这是您在Hugo中组织content/目录的方式：

.
├── _index.md
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── _index.md
│   └── quickstart.md
└── usage├── customizing.md├── _index.md├── settings.md└── support.md

To Hugo, _index.md and index.md mean different things. It can be helpful to know what kind of Page Bundle you want for each section: Leaf, which has no children, or Branch.

对于Hugo来说， _index.md和index.md含义不同。了解每个部分需要哪种页面捆绑可能会有所帮助：无子级的Leaf或Branch。

Now that you have some idea of where to put things, let’s look at how to build a page template.

现在您已经知道了将内容放置在哪里，让我们看看如何构建页面模板。

模板的工作原理 (How templating works)

Jekyll page templates are built with the Liquid templating language. It uses braces to output variable content to a page, such as the page’s title: {{ page.title }}.

Jekyll页面模板是使用Liquid模板语言构建的。它使用花括号将可变内容输出到页面，例如页面的标题： {{ page.title }} 。

Hugo’s templates also use braces, but they’re built with Go Templates. The syntax is similar, but different: {{ .Title }}.

Hugo的模板也使用花括号，但它们是使用Go Templates构建的。语法相似，但不同： {{ .Title }} 。

Both Liquid and Go Templates can handle logic. Liquid uses tags syntax to denote logic operations:

Liquid和Go模板都可以处理逻辑。 Liquid使用标签语法来表示逻辑运算：

{% if user %}Hello {{ user.name }}!
{% endif %}

And Go Templates places its functions and arguments in its braces syntax:

Go Templates将其功能和参数放在其大括号语法中：

{{ if .User }}Hello {{ .User }}!
{{ end }}

Templating languages allow you to build one skeleton HTML page, then tell the site generator to put variable content in areas you define. Let’s compare two possible default page templates for Jekyll and Hugo.

模板语言允许您构建一个框架HTML页面，然后告诉网站生成器将可变内容放入您定义的区域。让我们比较一下Jekyll和Hugo的两个可能的default页面模板。

Jekyll’s scaffold default theme is bare, so we’ll look at their starter theme Minima. Here’s _layouts/default.html in Jekyll (Liquid):

Jekyll的脚手架default主题为裸色，因此我们将看看他们的入门主题Minima 。这是Jekyll(液体)中的_layouts/default.html ：

<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">{%- include head.html -%}<body>{%- include header.html -%}<main class="page-content" aria-label="Content"><div class="wrapper">{{ content }}</div></main>{%- include footer.html -%}</body></html>

Here’s Hugo’s scaffold theme layouts/_default/baseof.html (Go Templates):

这是Hugo的脚手架主题layouts/_default/baseof.html (转到模板)：

<!DOCTYPE html>
<html>{{- partial "head.html" . -}}<body>{{- partial "header.html" . -}}<div id="content">{{- block "main" . }}{{- end }}</div>{{- partial "footer.html" . -}}</body>
</html>

Different syntax, same idea. Both templates pull in reusable bits for head.html, header.html, and footer.html. These show up on a lot of pages, so it makes sense not to have to repeat yourself.

不同的语法，相同的想法。这两个模板都为head.html ， header.html和footer.html head.html了可重用的位。这些内容显示在很多页面上，因此不必重复自己就很有意义。

Both templates also have a spot for the main content, though the Jekyll template uses a variable ({{ content }}) while Hugo uses a block ({{- block "main" . }}{{- end }}). Blocks are just another way Hugo lets you define reusable bits.

尽管Jekyll模板使用变量( {{ content }} )，而Hugo使用块( {{- block "main" . }}{{- end }} )，但这两个模板也都具有主要内容。块只是Hugo允许您定义可重用位的另一种方式。

Now that you know how templating works, you can build the sidebar menu for the theme.

现在您知道模板的工作原理，您可以为主题构建侧边栏菜单。

使用`pages`对象创建顶层菜单 (Creating a top-level menu with the `pages` object)

You can programmatically create a top-level menu from your pages. It will look like this:

您可以以编程方式从页面创建顶层菜单。它看起来像这样：

Introduction
Advanced Usage

Let’s start with Jekyll. You can display links to site pages in your Liquid template by iterating through the site.pages object that Jekyll provides and building a list:

让我们从杰基尔开始。您可以通过遍历Jekyll提供的site.pages对象并构建一个列表，在Liquid模板中显示指向网站页面的链接：

<ul>{% for page in site.pages %}<li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>{% endfor %}
</ul>

This returns all of the site’s pages, including all the ones that you might not want, like 404.html. You can filter for the pages you actually want with a couple more tags, such as conditionally including pages if they have a section: true parameter set:

这将返回网站的所有页面，包括您可能不需要的所有页面，例如404.html 。您可以使用更多标签过滤实际所需的页面，例如，如果页面具有section: true ，则有条件地包括这些页面section: true参数集：

<ul>{% for page in site.pages %}{%- if page.section -%}<li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>{%- endif -%}{% endfor %}
</ul>

You can achieve the same effect with slightly less code in Hugo. Loop through Hugo’s .Pages object using Go Template’s range action:

您可以在Hugo中使用更少的代码来达到相同的效果。使用Go Template的range动作遍历Hugo的.Pages对象：

<ul>
{{ range .Pages }}<li><a href="{{.Permalink}}">{{.Title}}</a></li>
{{ end }}
</ul>

This template uses the .Pages object to return all the top-level pages in content/ of your Hugo site. Since Hugo uses a specific folder for the site content you want rendered, there’s no additional filtering necessary to build a simple menu of site pages.

此模板使用.Pages对象返回Hugo网站content/的所有顶级页面。由于Hugo为您要呈现的网站内容使用特定的文件夹，因此无需额外的筛选即可构建简单的网站页面菜单。

使用数据列表中的嵌套链接创建菜单 (Creating a menu with nested links from a data list)

Both site generators can use a separately defined data list of links to render a menu in your template. This is more suitable for creating nested links, like this:

两个站点生成器都可以使用单独定义的链接数据列表来在模板中呈现菜单。这更适合创建嵌套链接，如下所示：

IntroductionGetting StartedConfigurationDeploying
Advanced UsageAll Configuration SettingsCustomizingHelp and Support

Jekyll supports data files in a few formats, including YAML. Here’s the definition for the menu above in _data/menu.yml:

Jekyll支持几种格式的数据文件，包括YAML。这是_data/menu.yml上面菜单的定义：

section:- page: Introductionurl: /introsubsection:- page: Getting Startedurl: /intro/quickstart- page: Configurationurl: /intro/config- page: Deployingurl: /intro/deploy- page: Advanced Usageurl: /usagesubsection:- page: Customizingurl: /usage/customizing- page: All Configuration Settingsurl: /usage/settings- page: Help and Supporturl: /usage/support

Here’s how to render the data in the sidebar template:

以下是在侧边栏模板中呈现数据的方法：

{% for a in site.data.menu.section %}
<a href="{{ a.url }}">{{ a.page }}</a>
<ul>{% for b in a.subsection %}<li><a href="{{ b.url }}">{{ b.page }}</a></li>{% endfor %}
</ul>
{% endfor %}

This method allows you to build a custom menu, two nesting levels deep. The nesting levels are limited by the for loops in the template. For a recursive version that handles further levels of nesting, see Nested tree navigation with recursion.

此方法使您可以构建一个自定义菜单，深两个嵌套级别。嵌套级别受模板中的for循环限制。有关可处理更多嵌套级别的递归版本，请参阅带有递归的嵌套树导航。

Hugo does something similar with its menu templates. You can define menu links in your Hugo site config, and even add useful properties that Hugo understands, like weighting. Here’s a definition of the menu above in config.yaml:

雨果(Hugo)的菜单模板做类似的事情。您可以在Hugo网站配置中定义菜单链接，甚至可以添加Hugo可以理解的有用属性，例如权重。这是上面config.yaml菜单的定义：

sectionPagesMenu: mainmenu:  main:- identifier: introname: Introductionurl: /intro/weight: 1- name: Getting Startedparent: introurl: /intro/quickstart/weight: 1- name: Configurationparent: introurl: /intro/config/weight: 2- name: Deployingparent: introurl: /intro/deploy/weight: 3- identifier: usagename: Advanced Usageurl: /usage/- name: Customizingparent: usageurl: /usage/customizing/weight: 2- name: All Configuration Settingsparent: usageurl: /usage/settings/weight: 1- name: Help and Supportparent: usageurl: /usage/support/weight: 3

Hugo uses the identifier, which must match the section name, along with the parent variable to handle nesting. Here’s how to render the menu in the sidebar template:

Hugo使用identifier (必须与节名称匹配)以及parent变量来处理嵌套。以下是在侧边栏模板中呈现菜单的方法：

<ul>{{ range .Site.Menus.main }}{{ if .HasChildren }}<li><a href="{{ .URL }}">{{ .Name }}</a></li><ul class="sub-menu">{{ range .Children }}<li><a href="{{ .URL }}">{{ .Name }}</a></li>{{ end }}</ul>{{ else }}<li><a href="{{ .URL }}">{{ .Name }}</a></li>{{ end }}{{ end }}
</ul>

The range function iterates over the menu data, and Hugo’s .Children variable handles nested pages for you.

range函数遍历菜单数据，Hugo的.Children变量为您处理嵌套页面。

将模板放在一起 (Putting the template together)

With your menu in your reusable sidebar bit (_includes/sidebar.html for Jekyll and partials/sidebar.html for Hugo), you can add it to the default.html template.

将菜单放在可重复使用的侧边栏位中(对于Jekyll为_includes/sidebar.html ，对于Hugo为partials/sidebar.html )，可以将其添加到default.html模板中。

In Jekyll:

在杰基尔：

<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">{%- include head.html -%}<body>{%- include sidebar.html -%}{%- include header.html -%}<div id="content" class="page-content" aria-label="Content">{{ content }}</div>{%- include footer.html -%}</body></html>

In Hugo:

在雨果：

<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}<body>{{- partial "sidebar.html" . -}}{{- partial "header.html" . -}}<div id="content" class="page-content" aria-label="Content">{{- block "main" . }}{{- end }}</div>{{- partial "footer.html" . -}}
</body></html>

When the site is generated, each page will contain all the code from your sidebar.html.

生成网站后，每个页面都将包含sidebar.html所有sidebar.html 。

创建样式表 (Create a stylesheet)

Both site generators accept Sass for creating CSS stylesheets. Jekyll has Sass processing built in, and Hugo uses Hugo Pipes. Both options have some quirks.

两个站点生成器都接受Sass创建CSS样式表。 Jekyll 内置了Sass处理，Hugo使用Hugo Pipes 。两种选择都有一些怪癖。

Jekyll中的Sass和CSS (Sass and CSS in Jekyll)

To process a Sass file in Jekyll, create your style definitions in the _sass directory. For example, in a file at _sass/style-definitions.scss:

要在Jekyll中处理Sass文件，请在_sass目录中创建样式定义。例如，在_sass/style-definitions.scss的文件中：

$background-color: #eef !default;
$text-color: #111 !default;body {background-color: $background-color;color: $text-color;
}

Jekyll won’t generate this file directly, as it only processes files with front matter. To create the end-result filepath for your site’s stylesheet, use a placeholder with empty front matter where you want the .css file to appear. For example, assets/css/style.scss. In this file, simply import your styles:

Jekyll不会直接生成此文件，因为它仅处理前端文件。要为您网站的样式表创建最终结果文件路径，请在您希望显示.css文件的位置使用带空的占位符的占位符。例如， assets/css/style.scss 。在此文件中，只需导入样式：

---
---@import "style-definitions";

This rather hackish configuration has an upside: you can use Liquid template tags and variables in your placeholder file. This is a nice way to allow users to set variables from the site _config.yml, for example.

这种颇为骇人听闻的配置有一个好处：您可以在占位符文件中使用Liquid模板标签和变量。例如，这是允许用户从站点_config.yml设置变量的好方法。

The resulting CSS stylesheet in your generated site has the path /assets/css/style.css. You can link to it in your site’s head.html using:

生成的网站中生成CSS样式表的路径为/assets/css/style.css 。您可以使用以下方法在您网站的head.html链接到该网站：

<link rel="stylesheet" href="{{ "/assets/css/style.css" | relative_url }}" media="screen">

雨果的萨斯和雨果烟斗 (Sass and Hugo Pipes in Hugo)

Hugo uses Hugo Pipes to process Sass to CSS. You can achieve this by using Hugo’s asset processing function, resources.ToCSS, which expects a source in the assets/ directory. It takes the SCSS file as an argument.

Hugo使用Hugo Pipes将Sass转换为CSS。您可以通过使用Hugo的资产处理功能resources.ToCSS来实现这一目标，该功能需要有一个assets/目录。它使用SCSS文件作为参数。

With your style definitions in a Sass file at assets/sass/style.scss, here’s how to get, process, and link your Sass in your theme’s head.html:

将您的样式定义保存在assets/sass/style.scss中的Sass文件中，以下是在主题的head.html获取，处理和链接Sass的head.html ：

{{ $style := resources.Get "/sass/style.scss" | resources.ToCSS }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" media="screen">

Hugo asset processing requires extended Hugo, which you may not have by default. You can get extended Hugo from the releases page.

Hugo资产处理需要扩展的Hugo ，默认情况下您可能没有。您可以从发布页面获取扩展的Hugo。

配置并部署到GitHub Pages (Configure and deploy to GitHub Pages)

Before your site generator can build your site, it needs a configuration file to set some necessary parameters. Configuration files live in the site root directory. Among other settings, you can declare the name of the theme to use when building the site.

在站点生成器可以构建站点之前，它需要一个配置文件来设置一些必要的参数。配置文件位于站点根目录中。在其他设置中，您可以声明在构建网站时使用的主题名称。

配置Jekyll (Configure Jekyll)

Here’s a minimal _config.yml for Jekyll:

这是Jekyll的最小_config.yml ：

title: Your awesome title
description: >- # this means to ignore newlines until "baseurl:"Write an awesome description for your new site here. You can edit thisline in _config.yml. It will appear in your document head meta (forGoogle search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
theme: # for gem-based themes
remote_theme: # for themes hosted on GitHub, when used with GitHub Pages

With remote_theme, any Jekyll theme hosted on GitHub can be used with sites hosted on GitHub Pages.

使用remote_theme ，可以将托管在GitHub上的任何Jekyll主题与托管在GitHub Pages上的站点一起使用。

Jekyll has a default configuration, so any parameters added to your configuration file will override the defaults. Here are additional configuration settings.

Jekyll具有默认配置，因此添加到配置文件中的任何参数都将覆盖默认设置。这是其他配置设置。

配置雨果 (Configure Hugo)

Here’s a minimal example of Hugo’s config.yml:

这是Hugo的config.yml的一个最小示例：

baseURL: https://example.com/ # The full domain your site will live at
languageCode: en-us
title: Hugo Docs Site
theme: # theme name

Hugo makes no assumptions, so if a necessary parameter is missing, you’ll see a warning when building or serving your site. Here are all configuration settings for Hugo.

Hugo不做任何假设，因此，如果缺少必要的参数，则在构建或服务您的网站时会看到警告。这是Hugo的所有配置设置。

部署到GitHub Pages (Deploy to GitHub Pages)

Both generators build your site with a command.

两个生成器都使用命令来构建您的站点。

For Jekyll, use jekyll build. See further build options here.

对于Jekyll，请使用jekyll build 。在此处查看更多构建选项。

For Hugo, use hugo. You can run hugo help or see further build options here.

对于雨果，用hugo 。您可以运行hugo help或在此处查看其他构建选项。

You’ll have to choose the source for your GitHub Pages site. Once done, your site will update each time you push a new build. Of course, you can also automate your GitHub Pages build using GitHub Actions. Here’s one for building and deploying with Hugo, and one for building and deploying Jekyll.

您必须选择GitHub Pages网站的来源。完成后，您每次推送新版本时，您的网站都会更新。当然，您也可以使用GitHub Actions自动执行GitHub Pages构建。这是一个与Hugo一起构建和部署的工具，另一个是与Jekyll一起构建和部署的工具。

开演时间！ (Showtime!)

All the substantial differences between these two generators are under the hood. All the same, let’s take a look at the finished themes, in two color variations.

这两个发电机之间的所有实质性差异都在引擎盖下。都是一样，让我们看一下完成的主题，有两种颜色。

Here’s Hugo:

这是雨果：

Here's Jekyll:

这是杰基尔：

等谁赢了？ (Wait who won?)