HUGO教程-内容管理

前言

本文主要内容: 把 HUGO 官方文档的「内容管理」进行通俗总结。

为什么要写这篇文章: 按照官方文档可以快速完成安装、新建站点、配置站点、创建第一篇文章、使用主题这几件事。通过搜索发现网上大部分教程都在讲这部分，而对于大部分人来说，后续最频繁、最耗时的工作就是组织 markdown 文章了，所以内容管理尤为重要，但网上讲这部分的文章却很少。

阅读本文后可以获得: 学习本文之后, 你可以在使用主题的基础上，通过 markdown 内容熟练组织网站内容。

如果你更喜欢通过看视频教程的方式，推荐一个讲的不错的Youtube视频教程

内容组织

官方文档地址: https://gohugo.io/content-management/organization/

content 目录

所有的 markdown 文章都应该放在 content 目录下。

默认情况下，源文件的目录结构与生成后网址有紧密的联系。

下面这个例子，不需要其他额外的配置，就可以完美运行

content
  └── about
  |   └── index.md       // <- https://example.org/about/
  ├── posts
  |   ├── firstpost.md   // <- https://example.org/posts/firstpost/
  |   ├── happy          // 这个目录是个Page Bundles，将在后面讲到
  |   |   └── ness.md    // <- https://example.org/posts/happy/ness/
  |   └── secondpost.md  // <- https://example.org/posts/secondpost/
  └── quote
      ├── first.md       // <- https://example.org/quote/first/
      └── second.md      // <- https://example.org/quote/second/

content 目录的特点

在 content 中可以进行任意层级嵌套
content/第一级目录 是特殊的，可用于确定布局等，是 section 的一种(将会在后面讲到)
内容类型可以简单地分为两种类型：文章类型、列表类型
- 文章类型：页面展示的就是文章内容
- 列表类型：页面展示的是文章列表，如主页、分类文章列表页、标签文章列表页等

路径解析

HUGO 默认使用 pretty URLS形式的网址
在站点配置hugo.yaml 中，配置网站域名 baseURL = "https://example.org"
文章类型和列表类型的网址解析规则不同，官方文档给了两个例子
- 列表类型: content/posts/_index.md => https://example.org/posts/，_index.md 是一个特殊文件，将在后面讲到
- 文章类型: content/posts/my-first-hugo-post.md => https://example.org/posts/my-first-hugo-post/

Page Bundles

官方文档地址: https://gohugo.io/content-management/page-bundles/

Page Bundles，有人翻译为页面捆绑，这篇文章中我暂且翻译为页面包

HUGO 0.32 开始使用，所谓页面包，就是一个目录，目录里既放了文章内容，也放了文章所需要的资源（如图片），整个目录被称为一个页面包。

页面包又分为

leaf 叶子：包含了 index.md 以及资源的目录，没有后代页面包
branch 分支：
- 包含了 _index.md 以及资源的目录，有后代页面包, 可以是叶子，也可以是其他分支；
- content 下第一层目录即使没有_index.md, 也是一个分支，主页也是。
headless：不发布的内容，但资源可以被其他页面引用, 使用 Front matter 定义，马上要讲到

例子及对比参考官方文档

Section

官方文档地址：https://gohugo.io/content-management/sections/

section 其实就是Page Bundles 中提到的分支类型：content 目录下的第一层目录、以及任何带有_index.md 文件的目录

Front matter

官方文档地址: https://gohugo.io/content-management/front-matter/

Front matter，本文翻译为前言，是 HUGO 的一个核心功能。

前言 Front matter 是 YAML 或者 TOML 格式的，它位于文件顶部，以—开头和结束。

使用前言为页面添加额外的元数据，这些元数据可以控制页面的渲染、行为等。

比如常用的前言有

title：页面标题
date：页面创建时间
draft：是否草稿，草稿不会被渲染，默认为 false
tags：页面标签数组
categories：页面分类数组
keywords：页面关键字数组
weight：页面权重，用于排序，默认为 0
description：页面描述
build：build options
headless：将一个叶子页面包作为一个 headless，不渲染
isCJKLanguage: 是否中日韩文
layout：使用特定的模板
slug：覆盖 URL 的最后一段
url：覆盖整个 URL

Archetypes

官方文档地址: https://gohugo.io/content-management/archetypes/

Archetypes是新文章的模板

hugo new site 命令生成了 archetypes/default.md, 这个文件就是默认的新文章的模板，文件内容为

+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true
+++

hugo new content 命令会以这个archetypes/default.md 为模板，生成新的文件。

所以你可以修改这个文件的内容，加上更多的前言数据。也可以建立新的模板文件。hugo new content命令会按照规则寻找合适的模板，如果找不到，就会使用默认的模板。

archetypes/posts.md
archetypes/default.md
themes/my-theme/archetypes/posts.md
themes/my-theme/archetypes/default.md

模板文件中可以使用函数，就像默认模板中的.Date、.File 那样，具体请看官方文档

模板文件一般是为前言服务的，但也可以包含内容。

还可以为叶子类型的页面包创建模板文件，比如

archetypes/
├── galleries/
│   ├── images/       <-- 将会自动生成 images 目录
│   │   └── .gitkeep
│   └── index.md      <-- 和default.md格式相同
└── default.md

使用 --kind 参数可以指定特定的模板文件

Taxonomies

官方文档地址: https://gohugo.io/content-management/taxonomies/

Taxonomies是用来分类文章的机制。

Taxonomies需要在站点配置文件中进行配置，但如果不配置，HUGO 会默认使用标签tags、分类categories作为 Taxonomies。

在文章的前言中，我们可以指定文章的分类和标签，就像这样

categories: [HUGO]
tags: [HUGO内容管理]

HUGO 会自动处理分类和标签的链接，点击链接可以进入对应的分类和标签的页面。

https://example.org/categories/hugo/
https://example.org/tags/hugo内容管理/

当然，你可以在站点配置中配置自定义的分类法。

taxonomies:
  category: categories
  series: series
  tag: tags

URL 管理

官方文档地址: https://gohugo.io/content-management/urls/

通过文章前言的 slug、url 可以影响页面的 URL 通过站点配置的 permalinks 可以配置页面的 URL规则

菜单管理

官方文档地址: https://gohugo.io/content-management/menus/

定义菜单的步骤

定义菜单实体
设定每一个实体的国际化配置
使用模板来展示菜单

但往往使用第三方主题已经完成了菜单的定义，只需要按照主题的文档网菜单中添加条目即可。

定义菜单项的三种方法

自动为顶级 section定义，使用站点配置的 sectionPagesMenu: main
使用文章的前言 menus: main或者是 menu: main
使用站点配置的 menus

在前言的方式中，还可以添加其他的属性，如 name、post、pre 等

站点配置的例子

menus:
  main:
  - name: Home
    pageRef: /
    weight: 10
  - name: Products
    pageRef: /products
    weight: 20
  - name: Services
    pageRef: /services
    weight: 30

评论系统

官方文档地址: https://gohugo.io/content-management/comments/

播客的文章大部分情况是给别人阅读的，评论系统非常重要。

由于 HUGO 生成的是静态页面，由于没有数据库，所以没办法将别人的评论记录下来，所以需要使用第三方评论系统，比如 Disqus、Gitment 等。

HUGO 默认支持 Disqus，在站点配置中加入

services:
  disqus:
    shortname: your-disqus-shortname

然后使用 {{ template "_internal/disqus.html" . }} 来呈现评论。

如果使用第三方模板，那么设置方式有可能不同，需要根据模板的文档来设置。

下一步建议

这篇文章只讲了常用的部分，还有一部分需要你去翻阅一下官方文档
如果你使用别人提供的主题，可以进一步参考对应主题的文档，了解如何使用特定的主题
如果你不使用别人的主题，需要完全控制网页，或者是创建主题给别人使用，需要进一步学习主题、模板等知识