Hugo

1、结构

命令：hugo new site blog

blog
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
├── themes
└── public

archetypes

在通过hugo new xxx 创建内容页面的时候，默认情况下hugo会创建date、title等front matter，可以通过在archetypes目录下创建文件，设置自定义的front matter。

config.toml

所有的hugo站点都有一个全局配置文件，用来配置整个站点的信息，hugo默认提供了跟多配置指令。

content

站点下所有的内容页面，也就是我们创建的md文件都在这个content目录下面。

data

data目录用来存储网站用到一些配置、数据文件。文件类型可以是yaml|toml|json等格式。

layouts

存放用来渲染content目录下面内容的模版文件，模版.html格式结尾，layouts可以同时存储在项目目录和themes//layouts目录下。layouts目录格式如下：

layouts
├── _default
├── partials
├── shortcodes
├── taxonomy
└── section

section指的是content目录下面的section，如果在layouts目录下设置了section，会优先选择section下面的模版。

static

用来存储图片、css、js等静态资源文件。

themes

用来存储主题，主题可以方便的帮助我们快速建立站点，也可以方便的切换网站的风格样式。

public

hugo编译后生成网站的所有文件都存储在这里面，把这个目录放到任意web服务器就可以发布网站成功。

2、内容

Page Bundles

hugo中的内容组织是依赖Page Bundles来管理的。Page Bundles包括Leaf Bundle（没有子节点）和Branch Bundle（home page, section, taxonomy terms, taxonomy list）两类。

官方文档：https://gohugo.io/content-management/page-bundles/#branch-bundles

Section

section是基于content/目录下的组织结构定义的页面集合。content/ 下的第一级子目录都是一个section。如果想让一个子目录成为section，需要在目录下面定义_index.md文件。 所有的section构成一个section tree。

content
└── blog        <-- Section, because first-level dir under content/
    ├── funny-cats
    │   ├── mypost.md
    │   └── kittens         <-- Section, because contains _index.md
    │       └── _index.md
    └── tech                <-- Section, because contains _index.md
        └── _index.md

如果section tree 需要可导航，至少最底层的部分需要定义一个_index.md文件。

3、模版

1. Single Template

single template 用于渲染页面内容。

2. List Template

list template 用于渲染一组相关内容，例如一个站点下所有内容，一个目录下的内容；

homepage 也就是_index.md，是一个特殊类型的list template，homepage实际上就是一个站点所有内容的入口。

3. partial Template

partial template 可以被其他模版引用，实际上可以理解为模版级别的组件，例如页面头部、页面底部等。

3.1 模版查找规则

基础模版查询规则

1. /layouts/section/<TYPE>-baseof.html
2. /themes/<THEME>/layouts/section/<TYPE>-baseof.html
3. /layouts/<TYPE>/baseof.html
4. /themes/<THEME>/layouts/<TYPE>/baseof.html
5. /layouts/section/baseof.html
6. /themes/<THEME>/layouts/section/baseof.html
7. /layouts/_default/<TYPE>-baseof.html
8. /themes/<THEME>/layouts/_default/<TYPE>-baseof.html
9. /layouts/_default/baseof.html
10. /themes/<THEME>/layouts/_default/baseof.html

页面模版查询规则

下面按照优先级顺序排列：

1、kind

判断页面是single page 还是 list page？

如果是single page，会选择模版_default/single.html

如果是list page（section listings, home page, taxonomy lists, taxonomy terms），会选择模版_default/list.html

2、Output Format

根据输出格式的名称和后缀，选择匹配的模版。例如输出格式是rss，后缀是.html,首先看有没有匹配的index.rss.html格式的模版。

3、Language

根据站点设置的语言选择匹配的模版，比如，站点的语言为fr，模版匹配的优先级是：index.fr.amp.html > index.amp.html > index.fr.html

4、Layout

可以在页面头部设置layout，设置页面用指定的模版进行渲染，例如，页面在目录posts（默认section）下面，layout=custom，查找规则如下：

• layouts/posts/custom.html
• layouts/posts/single.html
• layouts/_default/custom.html
• layouts/_default/single.html

5. type

如果在页面的头部设置了属性type属性，如果type=event，查找规则如下：

• layouts/event/custom.html
• layouts/event/single.html
• layouts/events/single.html
• layouts/_default/single.html

官方文档：https://gohugo.io/templates/lookup-order/

4、语法

go-template 基础语法

在父模版中通过{{ block "xxx"}} 定义一个块，在子模块中可以通过{{define "xxx"}} 定义的内容进行替换。

{{ define "chrome/header.html" }}
  <div>{{ .Site.Params.author}}</div>
{{ end }}

方法一 ：partial（推荐使用）

用于引入定义的局部模版，局部模版位置必须在themes/layouts/partials 或者layouts/partials目录下。

{{ partial "chrome/header.html" . }}

方法二 ：template

template 在一些比较老的版本中用于引入定义的局部模版，现在在内部模版中仍然使用。

{{ template "chrome/header.html" . }}

-用于去除空格，例如：

1. {{- xxx}用于去除{{- 前边的空格
2. {{ xxx -}用于去除-}}后边的空格
3. {{- xxx -}}用于去除两边的空格

.Paginator主要用来构建菜单，只能在homePage、listPage中使用。

{{ range .Paginator.Pages }}
   {{ .Title }}
{{ end }}

5、短代码

短代码（shortcodes）相当于一些自定义模版，通过在md文档中引用，生成代码片段，类似于一些js框架中的组件。

短代码必须在themes/layouts/partials 或者layouts/partials目录下定义。

短代码在模版文件中引用是无效的，只能在content目录下的*.md文件中引用。

引用方式

{{% msshortcodes params1="xxx" %}}**this** is a text{{% /msshortcodes %}}
{{< msshortcodes params1="xxx"  >}} **Yeahhh !** is a text {{< /msshortcodes >}}

1. % 代表短代码中的内容需要进一步渲染
2. < 代表短代码中间的内容项不需要进一步渲染

官方文档：https://gohugo.io/content-management/shortcodes

6、taxonomy

hugo中通过taxonomy来实现用户对内容的分组。taxonomy需要在站点配置文件中定义：

[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

默认情况下，hugo提供了category、tag两个分类，不需要用户在配置文件中定义，但如果还有其他的taxonomy定义，则默认的tag、category也需要定义；

使用方式

1. 在站点配置文件中添加taxonomy,例如：series
2. 定义taxonomy list template；例如，在layouts/taxonomy/series.html
3. 在内容文件的front matter中设置term；例如，series = [“s1”,“s2”]
4. 访问taxonomy列表，例如，localhost:1313/series/s1

7、变量

.Site

大部分站点变量定义在站点配置文件中（config.[yaml|toml|json] ）

.Site.Menus:站点下的所有菜单

.Site.Pages:站点下的所有页面

.Site.Params: 站点下的参数

.Page

页面级参数都定义在页面头部的front matter中，例如：

+++
title = "Hugo"
date = 2018-08-13T18:29:20+08:00
description = ""
draft = false
weight = 10
+++

使用方式

{{ .Params.xxx }} 或者是 {{ .Site.Params.xxx }}

1. .Page.Content:当前页面的内容
2. .Page.Daga:特定于此页面的数据
3. .Page.Dir:相对于content目录的文件路径

8、格式

hugo的配置文件以及页面的front matter支持三种格式配置：toml、yaml、json，使用任意一种都可以;

toml

+++
title = "QuickStart"
date = "2017-04-24T18:36:24+02:00"
+++

yaml

---
title : "QuickStart"
date : "2017-04-24T18:36:24+02:00"
---

json

{
  title : "QuickStart"
  date : "2017-04-24T18:36:24+02:00"
}