Hugo Future Imperfect Slim

plicx

heal the world.

创建一个新主题

Learn how to create a theme on Hugo

主题作者

13 分钟 读完

Pic 3

介绍

本教程将向您展示如何在Hugo中创建一个简单的主题。 我假设您熟悉HTML,bash命令行,并且您习惯使用Markdown格式化内容。 我将解释Hugo如何使用模板以及如何组织模板来创建主题。 我不会介绍使用CSS来设计主题的样式。

我们将从创建一个包含非常基本模板的新网站开始。 然后我们将添加几页和帖子。 只需稍加变化,您就可以创建许多不同类型的网站。

在本教程中,您输入的命令将以“$”提示符开头。 输出将随之而来。 以“#”开头的行是我为解释一点而添加的注释。 当我显示文件的更新时,最后一行的“:wq”表示保存文件。

这是一个例子:

## this is a comment
$ echo this is a command
this is a command

## edit the file
$vi foo.md
+++
date = "2014-09-28"
title = "creating a new theme"
+++

bah and humbug
:wq

## show it
$ cat foo.md
+++
date = "2014-09-28"
title = "creating a new theme"
+++

bah and humbug
$

一些定义

在创建主题之前,您需要了解一些概念。

皮肤

皮肤是负责您网站外观的文件。它是控制颜色和字体的CSS,它是决定动作和反应的Javascript。这也是Hugo用于将您的内容转换为网站将为访问者提供的HTML的规则。

您有两种方法来创建皮肤。最简单的方法是在layouts /目录中创建它。如果你这样做,那么你不必担心配置Hugo来识别它。 Hugo将寻找规则和文件的第一个地方是layouts /目录,所以它总能找到皮肤。

你的第二个选择是在themes /目录的子目录中创建它。如果你这样做,那么你必须总是告诉Hugo在哪里寻找皮肤。不过,这是额外的工作,为什么还要烦恼呢?

layouts /中创建皮肤和在themes /中创建皮肤之间的区别非常微妙。如果不更新构建它的模板和静态文件,则无法自定义layouts /中的皮肤。另一方面,在themes /中创建的皮肤可以并且这使得其他人更容易使用它。

本教程的其余部分将在themes /目录中调用一个主题创建的外观。

请注意,如果您愿意,可以使用本教程在layouts /目录中创建一个外观。主要区别在于您不需要更新站点的配置文件即可使用主题。

主页

主页或登录页面是网站的许多访问者看到的第一个页面。它是网站根目录中的index.html文件。由于Hugo将文件写入public /目录,因此我们的主页是public / index.html。

站点配置文件

当Hugo运行时,它会查找包含覆盖整个站点默认值的设置的配置文件。该文件可以使用TOML,YAML或JSON。我更喜欢使用TOML作为我的配置文件。如果您更喜欢使用JSON或YAML,则需要翻译我的示例。您还需要更改文件的名称,因为Hugo使用扩展来确定如何处理它。

Hugo将Markdown文件转换为HTML。默认情况下,Hugo希望在你的`/目录和themes /目录中的模板文件中找到Markdown文件。它将在public /目录中创建HTML文件。您可以通过在配置文件中指定备用位置来更改此设置。

内容

内容存储在包含两个部分的文本文件中。第一部分是“前面的事情”,它是关于内容的元信息。第二部分包含将转换为HTML的Markdown。

前端问题

前面的内容是有关内容的信息。与配置文件一样,它可以用TOML,YAML或JSON编写。与配置文件不同,Hugo不使用文件的扩展名来了解格式。它寻找标记来表示类型。 TOML被“+++”包围,YAML被“—”包围,而JSON被括在花括号中。我更喜欢使用TOML,因此如果您喜欢YAML或JSON,则需要翻译我的示例。

在将内容呈现为HTML之前,将前端内容中的信息传递到模板中。

Markdown

内容以Markdown编写,可以更轻松地创建内容。 Hugo通过Markdown引擎运行内容以创建将写入输出文件的HTML。

模板文件

Hugo使用模板文件将内容呈现为HTML。模板文件是内容和表示之间的桥梁。模板中的规则定义发布的内容,发布到的内容以及如何呈现给HTML文件。模板通过指定要使用的样式来指导演示。

模板有三种类型:单个,列表和部分。每种类型都将一些内容作为输入,并根据模板中的命令对其进行转换。

Hugo使用其内容知识来查找用于呈现内容的模板文件。如果找不到与内容完全匹配的模板,它将向上移动一个级别并从那里搜索。它将继续这样做,直到找到匹配的模板或用完模板进行尝试。如果找不到模板,它将使用站点的默认模板。

请注意,您可以使用前面的内容来影响Hugo选择的模板。

单一模板

单个模板用于呈现单个内容。例如,文章或帖子将是单个内容并使用单个模板。

列表模板

列表模板呈现一组相关内容。这可能是最近发布的内容或类别中所有文章的摘要。列表模板可以包含多个组。

主页模板是一种特殊类型的列表模板。 Hugo假设您网站的主页将充当网站其他内容的门户网站。

部分模板

部分模板是可以包含在其他模板中的模板。必须使用“partial”模板命令调用部分模板。它们对于卷起常见行为非常方便。例如,您的网站可能包含所有网页都使用的横幅。您可以创建一个包含横幅的部分,而不是将横幅文本复制到每个单独的列表模板中。这样,如果您决定更改横幅,则只需更改部分模板。

创建一个新站点

让我们用Hugo创建一个新的网站。我是Mac用户,因此我将在我的主目录中的Sites文件夹中创建我的用户。如果您使用的是Linux,则可能必须先创建该文件夹。

“新站点”命令将创建站点的骨架。它将为您提供基本目录结构和可用的配置文件。

$ hugo new site ~/Sites/zafta
$ cd ~/Sites/zafta
$ ls -l
total 8
drwxr-xr-x  7 quoha  staff  238 Sep 29 16:49 .
drwxr-xr-x  3 quoha  staff  102 Sep 29 16:49 ..
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$

查看content /目录以确认它是空的。

自定义主题时使用其他目录(archetypes /,layouts /和static /)。 这是一个不同教程的主题,所以请暂时忽略它们。

为新站点生成HTML

运行没有选项的hugo命令将读取所有可用内容并生成HTML文件。 它还会复制所有静态文件(这些内容都不是内容)。 由于我们有一个空站点,它不会做太多,但它会很快完成。

$ hugo --verbose
INFO: 2014/09/29 Using config file: config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html
                                            _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
$

“–verbose`”标志提供了在构建模板时有用的额外信息。 以“INFO:”或“WARN:”开头的输出的每一行都存在,因为我们使用了该标志。 以“WARN:”开头的行是警告消息。 我们稍后会讨论它们。

我们可以通过再次查看该目录来验证该命令是否有效。

$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$

看到新的公共/目录? Hugo将所有生成的内容放在那里。 当您准备发布您的网站时,就可以开始了。 但是现在,让我们确认一下我们对没有内容的网站有什么期望。

$ ls -l public
total 16
-rw-r--r--  1 quoha  staff  416 Sep 29 17:02 index.xml
-rw-r--r--  1 quoha  staff  262 Sep 29 17:02 sitemap.xml
$

Hugo创建了两个XML文件,这是标准的,但没有HTML文件。

测试的新网站

验证是你可以运行在内置的Web 服务器。如果你这样做,它将大大缩短你的开发周期。启动它通过运行在“服务器” 命令。如果它是成功的,你会看到输出类似于到了以下内容:

$ hugo server --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html
                                            _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
Serving pages from /Users/quoha/Sites/zafta/public
Web Server is available at http://localhost:1313
Press Ctrl+C to stop

连接到列出的URL(它位于以“Web Server”开头的行上)。如果一切正常,您应该得到一个显示以下内容的页面:

index.xml
sitemap.xml

这是您的公共/目录的列表。 Hugo没有创建主页,因为我们的网站没有内容。当目录中没有index.html文件时,服务器会列出目录中的文件,这是您应该在浏览器中看到的文件。

让我们回过头再看看那些警告。

WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html
                                            _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]

第二个警告更容易解释。我们还没有创建用于生成“未找到页面错误”的模板.404消息是单独教程的主题。

现在进行第一次警告。这是主页。你可以告诉它,因为它寻找的第一个布局是“index.html”。这只是主页使用的。

我喜欢详细的标志导致Hugo列出它正在搜索的文件。对于主页,它们是index.html,_default / list.html和_default / single.html。我们稍后会介绍一些解释名称和路径的规则。现在,请记住,雨果找不到主页的模板,它告诉你。

此时,您已经有了一个可以构建的工作安装和站点。剩下的就是添加一些内容和主题来显示它。

##创建一个新主题

Hugo没有附带默认主题。有一些可用(当我第一次安装Hugo时我算了十几个)和Hugo带来了创建新主题的命令。

我们将创建一个名为“zafta”的新主题。由于本教程的目的是向您展示如何填写文件以提取内容,因此该主题不包含任何CSS。换句话说,丑陋但功能性。

所有主题都对内容和布局有意见。例如,Zafta使用“post”而不是“blog”。强烈的意见使得更简单的模板,但不同的意见使得使用主题变得更加困难。构建主题时,请考虑使用其他主题执行的术语。

###创建一个骨架

使用hugo“new”命令创建主题的骨架。这将创建目录结构并放置空文件供您填写。

$ hugo new theme zafta

$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
drwxr-xr-x  3 quoha  staff  102 Sep 29 17:31 themes

$ find themes -type f | xargs ls -l
-rw-r--r--  1 quoha  staff  1081 Sep 29 17:31 themes/zafta/LICENSE.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/archetypes/default.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/
                                                list.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/
                                                single.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/index.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/
                                                footer.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/
                                                header.html
-rw-r--r--  1 quoha  staff    93 Sep 29 17:31 themes/zafta/theme.toml
$

骨架包括模板(以.html结尾的文件),许可文件,主题描述(theme.toml文件)和空原型。

请花一点时间填写theme.toml和LICENSE.md文件。它们是可选的,但是如果你要分发你的主题,它会告诉世界谁赞美(或责备)。声明许可证以便人们知道他们如何使用主题也很好。

$ vi themes/zafta/theme.toml
author = "michael d henderson"
description = "a minimal working template"
license = "MIT"
name = "zafta"
source_repo = ""
tags = ["tags", "categories"]
:wq

## also edit themes/zafta/LICENSE.md and change
## the bit that says "YOUR_NAME_HERE"

请注意,骨架的模板文件为空。 别担心,我们很快就会改变它。

$ find themes/zafta -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/
                                            list.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/
                                            single.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/
                                            index.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/partials/
                                            footer.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/partials/
                                            header.html
$

更新配置文件以使用主题

现在我们已经有了一个可以使用的主题,最好将主题名称添加到配置文件中。 这是可选的,因为您始终可以在所有命令上添加“-t zafta”。 我喜欢把它配置文件,因为我喜欢更短的命令行。 如果未将其放在配置文件中或在命令行中指定它,则不会使用您期望的模板。

编辑文件以添加主题,为站点添加标题,并指定我们的所有内容都将使用TOML格式。

$ vi config.toml
theme = "zafta"
baseurl = ""
languageCode = "en-us"
title = "zafta - totally refreshing"
MetaDataFormat = "toml"
:wq

$

生成网站

现在我们有一个空主题,让我们再次生成该网站。

$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
$

您是否注意到输出不同? 主页的警告消息已消失,我们还有一条额外的信息行,说Hugo正在从主题目录中同步。

让我们检查一下public/目录,看看Hugo创建的是什么。

$ ls -l public
total 16
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 css
-rw-r--r--  1 quoha  staff    0 Sep 29 17:56 index.html
-rw-r--r--  1 quoha  staff  407 Sep 29 17:56 index.xml
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 js
-rw-r--r--  1 quoha  staff  243 Sep 29 17:56 sitemap.xml
$

请注意四件事:

雨果创建了一个主页。 这是文件public / index.html。 2.雨果创建了一个css /目录。 3.雨果创建了一个js /目录。 雨果声称它创造了0页。 它创建了一个文件并复制了静态文件,但没有创建任何页面。 那是因为它认为“页面”是直接从内容文件创建的文件。 它不会像自动创建的index.html文件那样计算。

####主页

Hugo支持许多不同类型的模板。 主页是特殊的,因为它获得了自己的模板类型和自己的模板文件。 layouts / index.html文件用于生成主页的HTML。 Hugo文档说这是唯一需要的模板,但这取决于。 Hugo的警告信息显示它会查找三个不同的模板:

WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html
                                            _default/single.html]

如果找不到任何这些,它会完全跳过创建主页。 我们注意到,当我们在没有安装主题的情况下构建网站时。

当Hugo创建我们的主题时,它创建了一个空的主页模板。 现在,当我们构建网站时,Hugo找到了模板并使用它来生成主页的HTML。 由于模板文件为空,HTML文件也是空的。 如果模板中有任何规则,那么Hugo会用它们来生成主页。

$ find . -name index.html | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 20:21 ./public/index.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 ./themes/zafta/layouts/index.html
$

静态的魔力

Hugo在生成网站时做了两件事。 它使用模板将内容转换为HTML,并将静态文件复制到站点中。 与内容不同,静态文件不会被转换。 它们完全按原样复制。

Hugo假设您的网站将同时使用CSS和JavaScript,因此它会在您的主题中创建目录来保存它们。 记得意见? 那么,Hugo的观点是你将CSS存储在一个名为css /的目录中,并将你的JavaScript存储在一个名为js /的目录中。 如果您不喜欢,可以更改主题目录中的目录名称,甚至完全删除它们。 雨果足以提供自己的观点,如果你不同意,那就表现得很好。

$ find themes/zafta -type d | xargs ls -ld
drwxr-xr-x  7 quoha  staff  238 Sep 29 17:38 themes/zafta
drwxr-xr-x  3 quoha  staff  102 Sep 29 17:31 themes/zafta/archetypes
drwxr-xr-x  5 quoha  staff  170 Sep 29 17:31 themes/zafta/layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/layouts/_default
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/layouts/partials
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/static
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:31 themes/zafta/static/css
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:31 themes/zafta/static/js
$

##主题发展周期

当您处理主题时,您将在主题目录中进行更改,重建站点并在浏览器中检查您的更改。雨果让这很容易:

1.清除public /目录。 2.在监视模式下运行内置Web服务器。 3.在浏览器中打开您的站点。 4.更新主题。 5.浏览浏览器窗口以查看更改。 6.返回第4步。

我将再提出一个观点:永远不要在现场网站上的主题上工作。始终处理您网站的副本。更改主题,测试它们,然后将它们复制到您的网站。为了增加安全性,请使用Git之类的工具来保留内容和主题的修订历史记录。相信我,当我说失去你的思想和你的变化太容易了。

有关使用Git with Hugo的信息,请查看Hugo主要网站。

###清除公共/目录

在生成网站时,Hugo将在public /目录中创建新文件并更新现有文件。它不会删除不再使用的文件。例如,将保留在错误目录中创建的文件或标题错误的文件。如果你离开他们,你可能会在以后感到困惑。我建议在生成之前清理您的网站。

注意:如果您在SSD上构建,则应忽略这一点。在SSD上搅拌可能成本很高。

Hugo的Watch Option

Hugo的“--watch”选项将监视内容/和您的主题目录以进行更改并自动重建站点。

Live Reload

Hugo内置的Web服务器支持实时重载。当页面保存在服务器上时,会告诉浏览器刷新页面。通常情况下,这种情况比你说的要快,“哇,这太棒了。”

###开发命令

使用以下命令作为工作流程的基础。

## purge old files. hugo will recreate the public directory.
##
$ rm -rf public
##
## run hugo in watch mode
##
$ hugo server --watch --verbose

这是示例输出,显示Hugo检测到主页模板的更改。 生成后,Web浏览器会自动重新加载页面。 我以前说过这个,太神奇了。

$ rm -rf public
$ hugo server --watch --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
Watching for changes in /Users/quoha/Sites/zafta/content
Serving pages from /Users/quoha/Sites/zafta/public
Web Server is available at http://localhost:1313
Press Ctrl+C to stop
INFO: 2014/09/29 File System Event: ["/Users/quoha/Sites/zafta/themes/zafta/
                                        layouts/index.html": MODIFY|ATTRIB]
Change detected, rebuilding site

WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 1 ms

##更新主页模板

主页是Hugo自动创建的几个特殊页面之一。 如前所述,它在主题的布局/目录中查找三个文件之一:

  1. index.html
  2. _default/list.html
  3. _default/single.html

我们可以更新其中一个默认模板,但一个好的设计决策是更新最具体的模板。 这不是一个硬性规则(事实上,我们将在本教程中将其分解几次),但这是一个很好的概括。

###制作一个静态主页

现在,该页面是空的,因为我们没有任何内容,我们在模板中没有任何逻辑。 让我们通过向模板添加一些文本来改变它。

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  <p>hugo says hello!</p>
</body>
</html>
:wq

$

构建网站,然后验证结果。

$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  78 Sep 29 21:26 public/index.html

$ cat public/index.html
<!DOCTYPE html>
<html>
<body>
  <p>hugo says hello!</p>
</html>

Live Reload

注意:如果您使用--watch选项运行服务器,您将在文件中看到不同的内容:

$ cat public/index.html
<!DOCTYPE html>
<html>
<body>
  <p>hugo says hello!</p>
<script>document.write('<script src="http://'
        + (location.host || 'localhost').split(':')[0]
        + ':1313/livereload.js?mindelay=10"></'
        + 'script>')</script></body>
</html>

使用--watch时,Hugo会添加Live Reload脚本。 在文档中查找实时重新加载,以查看它的作用以及如何禁用它。

###建立一个“动态”主页

“动态主页?” Hugo是一个静态的网站生成器,所以这似乎很奇怪。 我的意思是,每当Hugo构建它时,让主页自动反映网站中的内容。 我们将在模板中使用迭代来做到这一点。

####创建新帖子

现在我们有主页生成静态内容,让我们为网站添加一些内容。 我们也会在主页和自己的页面上将这些帖子显示为列表。

Hugo有一个生成骨架帖子的命令,就像它对网站和主题一样。

$ hugo --verbose new post/first.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/first.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/
                            default.md
ERROR: 2014/09/29 Unable to Cast <nil> to map[string]interface{}

$

那不是很好,是吗?

“new”命令使用原型来创建帖子文件。 Hugo创建了一个空的默认原型文件,但是当有主题时会导致错误。 对我来说,解决方法是专门为帖子类型创建一个原型文件。

$ vi themes/zafta/archetypes/post.md
+++
Description = ""
Tags = []
Categories = []
+++
:wq

$ find themes/zafta/archetypes -type f | xargs ls -l
-rw-r--r--  1 quoha  staff   0 Sep 29 21:53 themes/zafta/archetypes/default.md
-rw-r--r--  1 quoha  staff  51 Sep 29 21:54 themes/zafta/archetypes/post.md

$ hugo --verbose new post/first.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/first.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/
                            post.md
INFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/first.md
/Users/quoha/Sites/zafta/content/post/first.md created

$ hugo --verbose new post/second.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/second.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/
                            post.md
INFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/second.md
/Users/quoha/Sites/zafta/content/post/second.md created

$ ls -l content/post
total 16
-rw-r--r--  1 quoha  staff  104 Sep 29 21:54 first.md
-rw-r--r--  1 quoha  staff  105 Sep 29 21:57 second.md

$ cat content/post/first.md
+++
Categories = []
Description = ""
Tags = []
date = "2014-09-29T21:54:53-05:00"
title = "first"

+++
my first post

$ cat content/post/second.md
+++
Categories = []
Description = ""
Tags = []
date = "2014-09-29T21:57:09-05:00"
title = "second"

+++
my second post

$

构建网站,然后验证结果。

$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"category":"categories",
                                                    "tag":"tags"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
2 pages created
0 tags created
0 categories created
in 4 ms
$

输出说它创建了2页。 这些是我们的新帖子:

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  78 Sep 29 22:13 public/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/first/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/second/index.html
$

新文件为空,因为用于生成内容的模板为空。 主页也不显示新内容。 我们必须更新模板才能添加帖子。

###列表和单个模板

在雨果,我们有三种主要的模板。 我们之前更新了主页模板。 它仅由主页使用。 我们还有“单个”模板,用于为单个内容文件生成输出。 我们还有“list”模板,用于在生成输出之前对多个内容进行分组。

一般来说,列表模板名为“list.html”,单个模板名为“single.html”。

还有其他三种类型的模板:部分,内容视图和术语。 我们不会详细介绍这些内容。

###将内容添加到主页

主页将包含帖子列表。 让我们更新其模板以添加我们刚刚创建的帖子。 每次构建站点时,模板中的逻辑都会运行。

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1>{{ .Title }}</h1>
  {{ end }}
</body>
</html>
:wq

$

Hugo使用Go模板引擎。 该引擎扫描模板文件以查找“{{”和“}}”之间的命令。 在我们的模板中,命令是:

  1. range
  2. .Title
  3. end

“range”命令是一个迭代器。 我们将使用它来浏览前十页。 Hugo创建的每个HTML文件都被视为一个页面,因此循环遍历页面列表将查看将要创建的每个文件。

“.Title”命令打印“title”变量的值。 Hugo从Markdown文件中的前端内容中提取它。

“end”命令表示范围迭代器的结束。 当发现“结束”时,引擎循环回到迭代的顶部。 每次引擎进行迭代时,都会评估“范围”和“结束”之间的所有内容。 在此文件中,这将导致前十页中的标题作为标题级别1输出。

记住在任何输出文件之前创建一些变量(如.Data)是有帮助的。 Hugo将每个内容文件加载到变量中,然后在创建HTML文件之前为模板提供处理的机会。

构建网站,然后验证结果。

$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags",
                                                    "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
2 pages created
0 tags created
0 categories created
in 4 ms
$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  94 Sep 29 22:23 public/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/first/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/second/index.html
$ cat public/index.html
<!DOCTYPE html>
<html>
<body>

    <h1>second</h1>

    <h1>first</h1>

</body>
</html>
$

恭喜,主页显示了两个帖子的标题。帖子本身仍然是空的,但让我们花点时间欣赏我们所做的一切。您的模板现在动态生成输出。信不信由你,通过在这些花括号中插入range命令,你已经学会了构建主题所需要知道的一切。剩下的就是了解将使用哪个模板生成每个内容文件并熟悉模板引擎的命令。

而且,如果这完全正确,那么本教程将会更短。有一些事情需要知道,这将使创建新模板变得更加容易。不过不用担心,这一切都将到来。

###向帖子添加内容

我们正在处理内容/帖子/目录中的帖子。这意味着他们的部分是“帖子”(如果我们不做一些奇怪的事情,他们的类型也是“帖子”)。

Hugo使用section和type来查找每个内容的模板文件。 Hugo将首先查找与部分或类型名称匹配的模板文件。如果找不到,那么它将在_default /目录中查找。当我们得到类别和标签时,我们将讨论一些曲折,但是现在我们可以假设Hugo会尝试post / single.html,然后是_default / single.html。

现在我们知道了搜索规则,让我们看看我们实际可用的内容:

$ find themes/zafta -name single.html | xargs ls -l
-rw-r--r--  1 quoha  staff  132 Sep 29 17:31 themes/zafta/layouts/_default/
                                                single.html

我们可以创建一个新模板post / single.html,或更改默认值。由于我们不知道任何其他内容类型,让我们从更新默认值开始。

请记住,我们尚未创建模板的任何内容最终都将使用此模板。这可能是好事也可能是坏事。不好,因为我知道我们将添加不同类型的内容,我们最终将取消我们所做的一些更改。这很好,因为我们能够立即看到结果。从这里开始也很好,因为我们可以开始为网站构建基本布局。随着我们添加更多内容类型,我们将重构此文件并移动逻辑。雨果使这相当轻松,所以我们将接受成本并继续。

有关确定使用哪个模板的所有详细信息,请参阅有关模板呈现的Hugo文档。而且,正如文档所提到的,如果您正在构建单页面应用程序(SPA)网站,则可以删除所有其他模板,并仅使用默认单页面。那是一种令人耳目一新的快乐。

更新模板文件

$ vi themes/zafta/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
</head>
<body>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</body>
</html>
:wq

$

构建网站并验证结果。

$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags",
                                                    "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
2 pages created
0 tags created
0 categories created
in 4 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff   94 Sep 29 22:40 public/index.html
-rw-r--r--  1 quoha  staff  125 Sep 29 22:40 public/post/first/index.html
-rw-r--r--  1 quoha  staff    0 Sep 29 22:40 public/post/index.html
-rw-r--r--  1 quoha  staff  128 Sep 29 22:40 public/post/second/index.html

$ cat public/post/first/index.html
<!DOCTYPE html>
<html>
<head>
  <title>first</title>
</head>
<body>
  <h1>first</h1>
  <p>my first post</p>

</body>
</html>

$ cat public/post/second/index.html
<!DOCTYPE html>
<html>
<head>
  <title>second</title>
</head>
<body>
  <h1>second</h1>
  <p>my second post</p>

</body>
</html>
$

请注意,帖子现在有内容。 你可以去localhost:1313 / post / first来验证。

链接到内容

帖子在主页上。 让我们添加一个链接从那里到帖子。 由于这是主页,我们将更新其模板。

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
  {{ end }}
</body>
</html>

构建网站并验证结果。

$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to
    /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags",
                                                    "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
2 pages created
0 tags created
0 categories created
in 4 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  149 Sep 29 22:44 public/index.html
-rw-r--r--  1 quoha  staff  125 Sep 29 22:44 public/post/first/index.html
-rw-r--r--  1 quoha  staff    0 Sep 29 22:44 public/post/index.html
-rw-r--r--  1 quoha  staff  128 Sep 29 22:44 public/post/second/index.html

$ cat public/index.html
<!DOCTYPE html>
<html>
<body>

    <h1><a href="/post/second/">second</a></h1>

    <h1><a href="/post/first/">first</a></h1>

</body>
</html>

$

###创建一个帖子列表

我们将帖子显示在主页和他们自己的页面上。 我们还有一个空的文件public / post / index.html。 让它显示所有帖子的列表(不仅仅是前十个)。

我们需要决定更新哪个模板。 这将是一个列表,因此它应该是一个列表模板。 让我们快速浏览一下,看看哪些列表模板可用。

$ find themes/zafta -name list.html | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/
                                            list.html

与单个帖子一样,我们必须决定更新_default / list.html或创建post / list.html。 我们仍然没有多种内容类型,所以让我们保持一致并更新默认列表模板。

##创建顶级页面

让我们添加一个“关于”页面并将其显示在顶层(而不是像我们对帖子那样的子级别)。

Hugo的默认设置是使用content /目录的目录结构来指导生成的html在public /目录中的位置。 让我们通过在顶层创建一个“关于”页面来验证:

$ vi content/about.md
+++
title = "about"
description = "about this site"
date = "2014-09-27"
slug = "about time"
+++

## about us

i'm speechless
:wq

生成网站并验证结果。

$ find public -name '*.html' | xargs ls -l
-rw-rw-r--  1 mdhender  staff   334 Sep 27 15:08 public/about-time/index.html
-rw-rw-r--  1 mdhender  staff   527 Sep 27 15:08 public/index.html
-rw-rw-r--  1 mdhender  staff   358 Sep 27 15:08 public/post/first-post/
                                                    index.html
-rw-rw-r--  1 mdhender  staff     0 Sep 27 15:08 public/post/index.html
-rw-rw-r--  1 mdhender  staff   342 Sep 27 15:08 public/post/second-post/
                                                    index.html

请注意,该页面未在顶级创建。 它是在名为“about-time /”的子目录中创建的。 那个名字来自我们的slu .. Hugo将使用slug来命名生成的内容。 顺便说一句,这是一个合理的默认值,但我们可以通过与此文件作斗争来学习一些东西。

另一件事。 看一下主页。

$ cat public/index.html
<!DOCTYPE html>
<html>
<body>
    <h1><a href="http://localhost:1313/post/theme/">
        creating a new theme</a></h1>
    <h1><a href="http://localhost:1313/about-time/">about</a></h1>
    <h1><a href="http://localhost:1313/post/second-post/">second</a></h1>
    <h1><a href="http://localhost:1313/post/first-post/">first</a></h1>
<script>document.write('<script src="http://'
        + (location.host || 'localhost').split(':')[0]
    + ':1313/livereload.js?mindelay=10"></'
        + 'script>')</script></body>
</html>

Notice that the “about” link is listed with the posts? That’s not desirable, so let’s change that first.

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if eq .Type "page" }}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}
</body>
</html>
:wq

生成网站并验证结果。 主页有两个部分,帖子和页面,每个部分都有正确的标题和链接集。

但是,关于页面仍然呈现为about-time /index.html。

$ find public -name '*.html' | xargs ls -l
-rw-rw-r--  1 mdhender  staff    334 Sep 27 15:33 public/about-time/index.html
-rw-rw-r--  1 mdhender  staff    645 Sep 27 15:33 public/index.html
-rw-rw-r--  1 mdhender  staff    358 Sep 27 15:33 public/post/first-post/
                                                    index.html
-rw-rw-r--  1 mdhender  staff      0 Sep 27 15:33 public/post/index.html
-rw-rw-r--  1 mdhender  staff    342 Sep 27 15:33 public/post/second-post/
                                                    index.html

知道hugo正在使用slug生成文件名,最简单的解决方案是更改slug。 让我们以艰难的方式去做,并更改配置文件中的永久链接。

$ vi config.toml
[permalinks]
  page = "/:title/"
  about = "/:filename/"

生成网站并验证这不起作用。 Hugo让“slug”或“URL”覆盖配置文件中的永久链接设置。 继续注释content / about.md中的slug,然后生成网站以在正确的位置创建它。

##共享模板

如果您一直关注,您可能会注意到帖子在浏览器中有标题而主页没有。 那是因为我们没有将标题放在主页的模板中(layouts / index.html)。 这是一件容易的事,但让我们看一个不同的选择。

我们可以将公共位放入存储在themes / zafta / layouts / partials /目录中的共享模板中。

###创建页眉和页脚部分

在雨果中,部分是糖衣模板。 通常,模板引用具有指定的路径。 部分是不同的。 Hugo沿着TODO定义的搜索路径搜索它们。 这使最终用户更容易覆盖主题的演示文稿。

$ vi themes/zafta/layouts/partials/header.html
<!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
</head>
<body>
:wq

$ vi themes/zafta/layouts/partials/footer.html
</body>
</html>
:wq

更新主页模板以使用部分

模板调用和局部调用之间最显着的区别是缺少路径:

{{ template "theme/partials/header.html" . }}

{{ partial "header.html" . }}

两者都在上下文中传递。

让我们更改主页模板以使用这些新的部分。

$ vi themes/zafta/layouts/index.html
{{ partial "header.html" . }}

  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if or (eq .Type "page") (eq .Type "about") }}
      <h2><a href="{{ .Permalink }}">{{ .Type }} -
        {{ .Title }} - {{ .RelPermalink }}</a></h2>
    {{ end }}
  {{ end }}

{{ partial "footer.html" . }}
:wq

生成网站并验证结果。 主页上的标题现在是“你的标题”,它来自config.toml文件中的“title”变量。

更新默认单一模板以使用部分

$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

生成网站并验证结果。 帖子和about页面上的标题都应反映markdown文件中的值。

##将“发布日期”添加到帖子

让帖子显示它们被编写或发布的日期是很常见的,所以让我们添加它。 我们帖子的前面有一个名为“date”的变量。 它通常是内容创建的日期,但让我们假装是我们想要显示的值。

###将“Date Published”添加到模板中

我们将首先更新用于呈现帖子的模板。 模板代码如下所示:

{{ .Date.Format "Mon, Jan 2, 2006" }}

帖子使用默认的单一模板,因此我们将更改该文件。

$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

生成网站并验证结果。 帖子现在显示日期。 但是有一个问题。 “约”页面也显示日期。

像往常一样,有几种方法可以仅在帖子上显示日期。 我们可以像在主页上那样做一个“if”语句。 另一种方法是为帖子创建单独的模板。

“if”解决方案适用于只有几种内容类型的网站。 它也符合“今天的代码”的原则。

但是,让我们假设我们使网站变得如此复杂,我们觉得我们必须创建一个新的模板类型。 在Hugo-speak中,我们将创建一个剖面模板。

让我们在忘记之前恢复默认的单一模板。

$ mkdir themes/zafta/layouts/post
$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

现在我们将更新单个模板的帖子版本。 如果您还记得Hugo的规则,模板引擎将使用此版本超过默认值。

$ vi themes/zafta/layouts/post/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

请注意,我们从默认模板中删除了日期逻辑,并将其放在帖子模板中。 生成网站并验证结果。 帖子有日期,而关于页面没有。

不要重复自己

DRY是一个很好的设计目标,Hugo在支持它方面做得很好。 好模板的部分技术是知道何时添加新模板以及何时更新现有模板。 当你想到这一点时,接受你将进行一些重构。 Hugo简单快速,所以延迟分割模板是可以的。

最新文章

Posts

查看更多

标签