写在前面

在分别了使用了Hexo、Gridea、Github page等方式部署blog后，我最终选择了Hugo+静态托管

那为什么会选择这种方式，有以下几个原因：

  • 对golang有着特殊的偏爱，使我开始关注Hugo
  • Hugo快！世界上最快的静态网站生成工具！5秒生成6000个页面！
  • 拥有丰富的主题，目前主题数量已经超过 Hexo
  • Github page还是会抽风，免费还是会付出代价（而且静态网站托管一点也不贵）

除此之外，想分享下我目前的写作方式：

  1. 通过Typora编写本地markdown，非常友好
  2. 将文件夹设置为iCloud同步盘
  3. 将文件夹软链到Hugo的content目录

通过这种方式可以很好地管理个人的知识储备（谁用谁知道），那废话不多说，本篇文章主要记录Hogo的搭建方式

搭建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 blog

添加一个主题

info

本文使用主题为even，各个主题的步骤不一样，请以主题的步骤为准

1
2
3
4

cd blog 
git clone https://github.com/olOwOlo/hugo-theme-even themes/even
# 复制主题自带的配置文件到blog目录下
将blog/themes/even/exampleSite/config.toml复制并覆盖blog/config.toml

开始写作

1

hugo new post/helloworld.md

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

1

hugo server -D

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

基本使用

这里节选出new与server这两个比较常用的命令和-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的模板文件，类似于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
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，除了必要的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//layouts/UNSPECIFIED/UNSPECIFIED.html
  7. /themes//layouts/posts/UNSPECIFIED.html
  8. /themes//layouts/UNSPECIFIED/single.html
  9. /themes//layouts/posts/single.html
  10. /themes//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//layouts/review/reviewarticle.html
  7. /themes//layouts/posts/reviewarticle.html
  8. /themes//layouts/review/single.html
  9. /themes//layouts/posts/single.html
  10. /themes//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才能发挥更好的效果。）

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

1
2

<%--more-->
# 将上面的%换成!即可

分类系统

默认情况下即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 }}

扩展阅读