为什么选择 hugo ？

  • 快！世界上最快的静态网站生成工具！5秒生成6000个页面！
  • 超详细的文档，虽然是英文的
  • 活跃的社区
  • 更加自由的内容组织方式

hugo 有哪些劣势 ？

  • 死气沉沉的中文社区…中文板块平均一年一个主题…
  • 不是用前端语言编写，在主题多样性上可能存在一定的短板

那么…

安装 Hugo

macOS

brew install hugo

Windows

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

验证安装是否成功

hugo version

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

建站

hugo new site quickstart

添加一个主题

cd quickstart;
git init;
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;

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

开始写作

hugo new post/my-first-post.md

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

hugo server -D

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

基本使用

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

hugo
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 90 ms

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

使用方法:
  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命令后你会得到一个包含以下文件的目录。

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
  • archetypes: 储存.md的模板文件，类似于hexo的scaffolds，该文件夹的优先级高于主题下的/archetypes文件夹
  • config.toml: 配置文件
  • content: 储存网站的所有内容，类似于hexo的source
  • data: 储存数据文件供模板调用，类似于hexo的source/_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

+++
# 主机名 例如: http://spf13.com/
baseURL =                     ""
# 语言编码(中文: zh-CN)
languageCode =                ""
# 默认的内容语言
defaultContentLanguage =      "zh-CN"

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

# 设置使用的主题名称 (默认储存在 /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/目录下的结构反映到生成的静态网站中，如下：

.
└── 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 中的路径分解

                    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，除了必要的data与title参数外，你可以有选择性的使用其他参数。

 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指定type与layout属性）：

  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/。同理，/archetypes/、/static/、/data/的优先级也总是高于/themes/<THEME>/archetypes/、/themes/<THEME>/static/、/themes/<THEME>/data/。

所以在我们需要修改别人提供的主题时，可以将需要修改的文件复制一份到/layouts/目录下再做修改，这种方式可以避免直接对主题进行修改。

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

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

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

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

分类系统

默认情况下即tags与categories，通常来说这已经足够我们使用了，但你也可以在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 }}

扩展阅读

转载自https://blog.olowolo.com/post/hugo-quick-start/