为什么选择 Hugo ?

  • 快!世界上最快的静态网站生成工具!5秒生成6000个页面!
  • 超详细的文档,虽然是英文的
  • 活跃的社区
  • 更加自由的内容组织方式
  • 丰富的主题,目前主题数量已经超过 Hexo

Hugo 有哪些劣势 ?

  • 死气沉沉的中文社区…中文板块平均一年一个主题…
  • 你喜欢的某个 Jekyll 或者 Hexo 主题是无法直接用在 Hugo 上的 ┑( ̄Д  ̄)┍

那么…

翻滚吧!奈亚子!

安装 Hugo

macOS

1
brew install hugo

Windows

1
2
3
4
5
# 前往 https://github.com/gohugoio/hugo/releases
# 下载 hugo_X.XX_Windows-64bit.zip
# 解压得到 hugo.exe
# 将 hugo.exe 所在目录添加至系统环境变量
# 安装完成!

验证安装是否成功

1
hugo version

其他系统请参考官方文档——安装

建站

1
hugo new site quickstart

添加一个主题

1
2
3
4
5
6
cd quickstart;
git init;
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;

# 编辑你的 config.toml 配置文件使用该主题
echo 'theme = "ananke"' >> config.toml

开始写作

1
hugo new post/my-first-post.md

编辑你新建的markdown文件。现在,在启用drafts参数的条件下开启Hugo内置的服务器。

1
hugo server -D

你的网站已经在http://localhost:1313/开启了。

基本使用

最常用的命令一定是在你的站点目录下使用hugo命令,该命令将会生成静态文件。(可以看到生成速度真的很快ᕦ(ò_óˇ)ᕤ)

1
2
3
4
5
6
7
8
hugo
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 90 ms

这里节选出newserver这两个比较常用的命令和-D,-E,-F这三个参数的使用方法。更多的hugo命令可以参考官方文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
使用方法:
  hugo
  hugo [flags]
  hugo [command]
  hugo [command] [flags]

节选的 command:
  new         为你的站点创建新的内容
  server      一个高性能的web服务器

节选的 flags:
  -D, --buildDrafts                包括被标记为draft的文章
  -E, --buildExpired               包括已过期的文章
  -F, --buildFuture                包括将在未来发布的文章

举几个栗子:
  hugo -D                          生成静态文件并包括draft为true的文章
  hugo new post/new-content.md     新建一篇文章
  hugo new site mysite             新建一个称为mysite的站点
  hugo server --buildExpired       启动服务器并包括已过期的文章

PS: hugo server 会自动监听你的原始文稿,你在编辑原始.md文件时的变化都会实时的反映在网站上。如果你不希望启用这个功能你可以使用hugo server --watch=false命令。

目录结构

在执行完hugo new site命令后你会得到一个包含以下文件的目录。

1
2
3
4
5
6
7
8
.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
  • archetypes: 储存.md的模板文件,类似于hexoscaffolds,该文件夹的优先级高于主题下的/archetypes文件夹
  • config.toml: 配置文件
  • content: 储存网站的所有内容,类似于hexosource
  • data: 储存数据文件供模板调用,类似于hexosource/_data
  • layouts: 储存.html模板,该文件夹的优先级高于主题下的/layouts文件夹
  • static: 储存图片,css,js等静态文件,该目录下的文件会直接拷贝到/public,该文件夹的优先级高于主题下的/static文件夹
  • themes: 储存主题
  • public: 执行hugo命令后,储存生成的静态文件

配置 Hugo

编辑你的config.toml文件以配置你的站点。以下节选了部分有趣的参数,完整的配置文件可以参考官方文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
+++
# 主机名 例如: http://spf13.com/
baseURL =                     ""
# 语言编码(中文: zh-CN)
languageCode =                ""
# 默认的内容语言
defaultContentLanguage =      "zh-CN"

# 自动检测是否包含中文/日文/韩文,该参数会影响摘要和字数统计功能,建议设置为true
hasCJKLanguage =              false

# 若为 false,`Getting Started` 这样的英文标签将会被转换为 `getting-started`
preserveTaxonomyNames =       true

# 设置使用的主题名称 (默认储存在 /themes/THEMENAME/)
theme =        

# 分页
paginate =                    10
paginatePath =                "page"

# 启用 Emoji; see emoji-cheat-sheet.com
enableEmoji =                 false

# 创建robots.txt,建议设置为true
enableRobotsTXT =             false

# 定义文章访问路径,详细见下文"URL管理" See "content-management/urls/"
permalinks =                  ""
+++

除了预设的参数外,你也可以通过下面的方式自定义自己的参数。你可以在模板中获取到自定义的参数,通常情况下你使用的主题都会要求你这么做,具体信息可以阅读相关主题的文档。

1
2
3
[params]
  author = "olOwOlo"
  github = "olOwOlo"

至此,你已经掌握了足够的知识,你只需要从主题列表中挑选一个你喜欢的主题,阅读主题的文档并提供主题所需的信息,便可以开始使用hugo来写作了。

阅读下面的内容可以帮你更好的了解到hugo如何管理你的内容,而你又该如何更好的与hugo协作。

以上是对Getting Started的总结,下面是对Content Management的总结


千反田同学很好奇!

组织content/文件夹

hugo会将content/目录下的结构反映到生成的静态网站中,如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about/
    ├── post
    |   ├── _index.md   // <- https://example.com/post/
    |   ├── firstpost.md   // <- https://example.com/post/firstpost/
    |   ├── happy
    |   |   └── ness.md  // <- https://example.com/post/happy/ness/
    |   └── secondpost.md  // <- https://example.com/post/secondpost/
    └── quote
        ├── first.md       // <- https://example.com/quote/first/
        └── second.md      // <- https://example.com/quote/second/

需要注意的是_index.md是一个比较特殊的文件,如果你只是需要一个about页面,你只需要hugo new about.md即可。关于_index.md的相关信息可以参阅官方文档

Hugo 中的路径分解

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
                    section
                    ⊢--^--⊣
                               url
                    ⊢-------------^------------⊣

      baseURL             path        slug
⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣
                  permalink
⊢----------------------^-----------------------⊣
https://example.com/events/chicago/lollapalooza/

Hugo 中的类型

content/下的内容可能不仅仅只有文章,还可能有照片甚至其他不同形式的内容。hugo通过type属性来标记不同形式的内容,根据不同的type值,hugo会选择合适的模板来渲染内容。

默认情况下type被赋值为section。例如:使用hugo new posts/new-post.md命令得到的新文件会被默认为posts类型。当然你也可以在下文提到的front matter中显式的将文章的type指定为其他值。

Front Matter

Hugo 支持TOML、YAML、JSON格式的Front Matter。

以下列出一份完整的YAML格式的Front Matter,除了必要的datatitle参数外,你可以有选择性的使用其他参数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
---
title: "文章标题"
description: "文章的描述信息"
tags: [ "标签1", "标签2", "标签3" ]
categories: [ "分类1", "分类2" ]
keywords: [ "Hugo", "keyword" ]
date: 2012-04-06
lastmod: 2015-12-23
# CJKLanguage: Chinese, Japanese, Korean
isCJKLanguage: true

# 如果draft为true,除非使用 --buildDrafts 参数,否则不会发布文章
draft: false

# 设置文章的过期时间,如果是已过期的文章则不会发布,除非使用 --buildExpired 参数
expiryDate: 2020-01-01

# 设置文章的发布时间,如果是未来的时间则不会发布,除非使用 --buildFuture 参数
publishDate: 2020-01-01

# 排序你的文章
weight: 40

# 使用这两个参数将会重置permalink,默认使用文件名
url: 
slug: 

# 别名将通过重定向实现
aliases:
  - 别名1
  - /posts/my-original-url/
  - /2010/01/01/another-url.html

# type 与 layout 参数将会改变 Hugo 寻找该文章模板的顺序,将在下一节细述
type: review
layout: reviewarticle

# 三个比较复杂的参数
taxonomies:
linkTitle: 
outputs:
# 实验性的参数
markup: "md"

# 你还可以自定义任何参数,这些参数可以在模板中使用
include_toc: true
show_comments: false
---

模板选择顺序

这是一篇content/posts/下的文章寻找模板的顺序(此时我们未在文章的Front Matter指定typelayout属性):

  1. /layouts/UNSPECIFIED/UNSPECIFIED.html
  2. /layouts/posts/UNSPECIFIED.html
  3. /layouts/UNSPECIFIED/single.html
  4. /layouts/posts/single.html
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html
  7. /themes/<THEME>/layouts/posts/UNSPECIFIED.html
  8. /themes/<THEME>/layouts/UNSPECIFIED/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

如果我们在Front Matter中添加以下代码

1
2
type: review
layout: reviewarticle

该文章现在的寻找模板顺序为:

  1. /layouts/review/reviewarticle.html
  2. /layouts/posts/reviewarticle.html
  3. /layouts/review/single.html
  4. /layouts/posts/single.html
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/review/reviewarticle.html
  7. /themes/<THEME>/layouts/posts/reviewarticle.html
  8. /themes/<THEME>/layouts/review/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

值得注意的是,/layouts/ 目录下模板优先级总是高于 /themes/<THEME>/layouts/ 。同理,若根目录下存在与 /themes/ 文件夹下同名的文件夹,根目录下的文件优先级总是高于 /themes/ 文件夹

因此,在我们只是需要别人提供的主题做一些小修改时,尤其是对于一些静态资源需要进行覆盖时,将新的文件置于根目录的文件夹下而不是直接对主题进行修改,日后需要更新主题时就无需解决 git 冲突的问题了。

当然,如果是需要直接对 /layouts/ 目录下的模板进行修改,还是建议新建一个 git 分支进行更改。

URL管理

正如前文所言,hugo会将content/目录下的结构反映到生成的静态网站中,但config.toml中的permalinks参数允许你自由更改内容的URL。例如:你想从hexo迁移到hugo,你可以将permalinks定义为下面这种形式以适应之前的URL。

1
2
[permalinks]
  post = "/:year/:month/:title/"

上面的配置将改变content/post/文件夹下所有文章的URL。

举个栗子,content/post/sample-entry.md的URL将从默认的https://example.com/post/sample-entry/改变为https://example.com/2013/11/sample-entry/

所有可用的属性如下:

1
/:monthname/:day/:weekday/:weekdayname/:yearday/:section/:title/:slug/:filename/

内容摘要

Hugo会自动提取文章的前70个字符作为摘要。(注意:该功能在中文环境下需要在config.toml中添加hasCJKLanguage = true才能发挥更好的效果。)

当然你也可以在文章内使用<!--more-->针对文章手动进行摘要提取,在<!--more-->之前出现的内容都会作为摘要使用,且能够保持渲染后的结构而不是纯文字版本。

Shortcodes

Shortcodes帮助你在编写markdown时快捷的插入HTML代码,功能上类似于Hexo的标签插件

1
2
3
4
5
6
{{< ref "blog/post.md" >}} => https://example.com/blog/post/
{{< ref "post.md#tldr" >}} => https://example.com/blog/post/#tldr:caffebad
{{< relref "post.md" >}} => /blog/post/
{{< relref "blog/post.md#tldr" >}} => /blog/post/#tldr:caffebad
{{< ref "#tldr" >}} => #tldr:badcaffe
{{< relref "#tldr" >}} => #tldr:badcaffe

上述代码通过内置的relrelref帮助你快速引用站点内的其他文章。

注意: 如果你的 content/ 目录下有多个同名的文件,引用该文章必须使用 blog/post.md 这样的相对路径而不是只提供 post.md 这样的文件名。

hugo还内置了instagramtweetyoutube等Shortcodes,可以阅读官方文档了解更多信息,你使用的主题可能也会提供Shortcodes,当然你也可以定制你自己的Shortcodes

分类系统

默认情况下即tagscategories,通常来说这已经足够我们使用了,但你也可以在config.toml文件中添加下面的代码来添加更多的分类。

1
2
3
4
[taxonomies]
  tag = "tags"
  category = "categories"
  series = "series"

维包子什么都知道!

Custom Output Formats

hugo能够输出多种不同格式的内容,这里简单的举个如何同时输出markdown文件的栗子:

在你的config.toml文件下添加:

1
2
3
4
5
6
7
8
[mediaTypes]
  [mediaTypes."text/plain"]
    suffix = "md"

[outputFormats.MarkDown]
  mediaType = "text/plain"
  isPlainText = true
  isHTML = false

为 MarkDown 新建一个 single.md 模板,写入以下代码,并放置在 /layouts/_default/ 文件夹下

1
{{ .RawContent }}

针对所有内容,在config.toml文件下添加:

1
2
3
4
5
6
[outputs]
  home = ["HTML", "RSS"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]

针对某篇文章,在该文章的Front Matter中添加:

1
2
3
outputs:
  - html
  - markdown

在模板中的合适位置添加代码链接到你的.md文件:

1
2
3
{{ with .OutputFormats.Get "markdown" -}}
<a href="{{ .Permalink }}">查看本文 Markdown 版本 »</a>
{{- end }}

扩展阅读