Hugo in Action Note

书本结构

这本书有两个不同的部分。第一部分侧重于 Hugo 的核心功能，我们将独立于 Internet 的其余部分运行。第二部分集中在 Hugo 如何提供与各种服务通信的方法，以及 JavaScript 生态系统如何提供在 Hugo 编译步骤中不可能的功能。

第 1 章介绍了 Jamstack 并解释了其背后的想法。本章还介绍了 Jamstack 的各个部分以及它们如何协同工作。它还介绍了 Hugo 静态站点构建器，并讨论了何时使用 Hugo 是明智的，何时不适合使用 Hugo 或 Jamstack。

第 2 章简要概述了 Hugo 项目的工作目录。它还设置了网络托管并创建了一个简单的基于 Hugo 的网站，该网站位于 Internet 上，可提供出色的性能和一组可管理的依赖项。

第 3 章让我们扮演内容作者的角色。本章深入概述了 Markdown 和 YAML，这是用于创建内容和为 Hugo 网站提供元数据的两种主要语言。它还将这些语言与其他可用选项进行了比较，并概述了我们可以在 Hugo 网页的 front matter 中使用的标准元数据属性。

第 4 章让我们扮演网站编辑的角色。本章介绍如何将 Hugo 网站中的页面组织成部分、菜单和 Hugo 分类法，如何将内容捆绑到一个页面包中，以及如何有效地使用 Hugo 的内置和社区提供的短代码来启用和扩展 Markdown 功能。

第 5 章让我们第一次看到了 Go 模板语言，它提供了控制网页渲染的方法。我们将探讨如何在 Hugo 中构建自定义页面，如何使用 Go 模板语言渲染内容，如何访问 Hugo 的变量、函数、配置和前言，以及如何使用 Hugo 从文件系统中读取。

第 6 章探讨了 Hugo 主题的关键组件以及 Hugo 提供的用于构建自定义网页的工具。它教我们如何组织模板以便于维护和重用，通过在多个页面类型之间共享模板代码和代码段来提高生产力，以及使用 Hugo 管道解决资源管理问题。

第 7 章允许我们完全拥有该网站的所有权。它显示了 Hugo 内容系统的构建块（叶和分支捆绑包、分类系统、布局和类型）如何映射到模板代码。

第 8 章深入探讨了 Hugo 模块，这是 Hugo 的一个强大、被广泛误解和未充分利用的功能。Hugo 的模块允许从基于 Hugo 的网站的所有组件中创建和使用插件（从主题和模板到简码甚至内容）。

第 9 章超越了我们项目文件夹的范围，展示了 Hugo 对 Jamstack 的第二个支柱 — API 的支持。本章将我们带入 Web 2.0，它支持动态功能，如评论和联系表单。它还为历史上更具挑战性的问题提供了一些简单的解决方案，例如动态调查和 RESTful GET API。

第 10 章展示了为什么 Hugo 不遗余力地确保它与 JavaScript（Jamstack 中的“J”）完美配合。这包括自定义和集成最快的 JavaScript 捆绑器之一。Hugo 澄清了编译时和运行时环境之间的担忧，同时仍然保持紧密集成并提供统一控制。本章使用客户端脚本来实现动态功能，例如后台表单提交，并使用 npm 生态系统进行客户端搜索。它还建立了一个带有 Hugo 和 JavaScript 的混合网站，该网站拥有他们擅长的部分。

第 11 章介绍了构建低维护 API 的 Jamstack 方法，以扩展 Hugo 本身不提供的功能。我们在这样做的同时，并没有失去 Hugo 的关键性能优势。本章还探讨了 webhook（与独立 API 提供商集成的服务器到服务器 API 通信机制），使我们的网站能够充当统一的后端，运营开销很小。

第 12 章深入探讨了一个顶点项目，其中书中的所有内容都付诸实践。本章通过构建一个电子商务网站，提供从购物车到结帐再到订单履行的端到端支持，打破了 Jamstack 的一些最流行的神话。

第 13 章采用现有网站并将其向多个方向扩展。这为多种（人类）语言和具有不同主题的相同内容的多个视图提供支持。它还通过离线支持、即时页面以及 Turbo 技术和库使我们的网站更快。它还讨论了减少在浏览器中手动完成的工作的脚本，以及参与 Hugo 社区以获得支持、赞赏和贡献。

本书的章节应按顺序阅读：您从前几章中学到的东西将建立在以下章节的基础上。每一章都从上一章中留下的地方改进了示例网站。如果读者偶然想乱序理解一个主题，建议查看上一章末尾的代码检查点，以了解下一章从哪里开始。

第二章 30分中上线一个站点

Live in 30 minutes: You now have a website

新建一个站点

hugo new site acme-corporation --format yaml

提示说

Congratulations! Your new Hugo site was created in /home/tong/hugo/acme-corporation.

Just a few more steps...

1. Change the current directory to /home/tong/hugo/acme-corporation.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.yaml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

先来看下目录结构

archetypes assets content data hugo.yaml i18n layouts static themes

archetypes
- 包含内容文件的模板。Hugo 尝试最大限度地减少创建内容所需的复制和粘贴工作。我们可以为这个文件夹中的 Markdown 文件或文件夹创建模板，Hugo 使用它们来创建基本内容文件。 -assets
- 将图像、JavaScript 和 CSS 文件作为未处理的源代码放置，以便从网站全局使用。此文件夹允许我们在编译期间处理这些文件。Hugo 可以调整图像大小、捆绑和缩小 JavaScript 文件，并通过其资源管道（Hugo Pipes）将 SCSS 转换为 CSS。我们将在第 6 章中学习图像处理和资源捆绑，并在第 10 章中学习 JavaScript 资源。
content — 包含传统上进入数据库的所有内容。我们可以根据需要将内容组织到文件和文件夹中。默认情况下，Hugo 根据此文件夹的结构直接生成网站输出，我们可以使用每个文件中的元数据来覆盖默认配置。
data — 以 YAML、TOML、CSV 或 JSON 文件的形式存储结构化内容，这些文件在整个网站中作为全局变量提供。传统数据库不仅仅包含网页内容。可以有与结构化数据关联的表，这些表在 content 文件夹中没有位置，因此当我们从 Hugo 外部生成内容并将该信息作为 JSON 或 CSV 文件传递给 Hugo 以供使用时，这个文件夹会派上用场。
layouts
- 覆盖主题的某些部分。Hugo 为我们提供了混合和匹配主题页面的灵活性，并编写我们自己的自定义页面。在此文件夹中，将进行主题的所有自定义。我们可以使用此目录来存储这些被覆盖的主题布局。主题和布局之间的界限是模糊的，Hugo 为我们提供了完全的灵活性，通过一个接一个地覆盖页面来慢慢创建主题。在本章中，我们将使用 layouts 文件夹来更新主页，并在第 6 章和第 7 章中详细介绍 layouts。
themes
- 包含我们用来使 content 文件夹中的内容可显示的代码。我们可以使用 Go 模板语言来编写主题。我们将在本章中添加主题，并在第 7 章中创建自己的主题。
config — 包含网站的配置。此目录包含网站中共享的元数据，包括主题的名称以及需要传递给 Hugo 或主题以呈现内容的任何参数。默认情况下，Hugo 会创建一个 config.yaml 文件。Hugo 支持将此配置文件拆分为多个文件，并使用不同的环境和生产环境。这会将配置转换为文件夹。我们将在第 4 章中详细介绍配置。
static
- 存储字体或 PDF 文件等静态内容。Hugo 将此内容按原样复制到输出目录。此文件夹在某种程度上等同于 Apache/Nginx Web 服务器根文件夹，您可以在其中放置任何 HTML 文件以进行渲染。建议在 content、data、themes 和 layouts 文件夹中放置尽可能多的内容，以便以编程方式访问它并从 Hugo 的渲染管道中受益。在 static 文件夹中，我们可以存储 .pdf、.woff（用于 Web 字体）等二进制文件，以及不属于其他任何地方的可下载内容的 .zip 文件。在本章中，我们将在 static 文件夹中放置一些文件。

构建完后后，可能会产生的文件

public — Hugo 的默认输出目录，hugo 命令在其中生成要在 CDN 上部署和缓存的 HTML 输出。
resources — 处理数据时，Hugo 会将繁重作的结果缓存在此文件夹中。我们应该将此文件夹放入我们的版本控制中，并在 build 中重用其数据。这个文件夹是使用 Hugo 获得出色性能的关键因素之一。处理图像是一项 CPU 密集型作，并且需要时间。大多数资源在构建过程中不会更改，只要处理后的图像不更改，就可以缓存它们，从而为 Hugo 提供显著的性能提升。

添加主题

Eclectic，可以直接下载到themes文件夹中。

echo "theme: Eclectic" >> config.yaml

运行开发服务器

hugo server

指定端口 hugo server --port 8000 或者 hugo server -p 8000

如果想监视更新 hugo server --noHTTPCache --disableFastRender

添加网站配置

修改 hugo.yaml

baseURL: https://example.org/
languageCode: en-us
title: My New Hugo Site
theme: Eclectic

author: 
  facebook: "https://facebook.com/example" 
  twitter: "https://twitter.com/example" 
  email: "contact@example.org" 
  name: "Acme Corporation" 
  location: New York 
  phone: (999) 999-9999 
  hours: "**Mon-Fri:** 9:00AM - 6:00PM, ET" 
menu:
  main: 
    - identifier: about 
      name: About 
      url: /about 
      weight: 100 
    - identifier: contact 
      name: Contact 
      url: /contact 
      weight: 200 
params: 
  color: "#4f46e5"
  copyright: "Copyright &copy; 2022 Acme Corporation.
    All Rights Reserved."
  footer:
  - title: About
    content: >
      Acme Corporation is the world's leading
      manufacturer of digital shapes. From squares and
      circles to triangles and hexagons, we have it
      all. Browse through our collection of various
      forms with different thicknesses and line styles.
      We shape the world. You live in it.


  - title: Recent Blog Posts
    recents: blog
    recentCount: 7
  - title: Contact Us
    contact: true

可以把网站徽标放到 assets/image 文件夹（而不是 themes/Eclectic/ assets/image 文件夹中）来控制网站背景图像。我们将 logo.svg 和 background.svg 放在此文件夹中以个性化网站。

使用自定义的主页，在 layouts 中添加 index.html

在 assets 中的文件会由 Hugo Pipes 处理。对于无需处理的文件，可以直接放到 static 文件夹。比如： static/index.css, static/image/background.svg, static/image/logo.svg, 和 static/favicon.ico

注：如果发现你新应用的样式没有生效，可以试试清空浏览器缓存重新加载页面。

持续交付

部署到 netlify

使用命令行参数 hugo --minify --baseURL $DEPLOY_PRIME_URL 来构建生产版本的网站。或者在netlify.toml 文件中指定构建参数。

注意要指定 Hugo 的确切版本，我们可以在指定构建命令时单击“显示高级”按钮，然后添加具有正确值的环境变量 HUGO_VERSION，这是我们要使用的 Hugo 版本（例如，0.91.2）。如果未指定版本号，Netlify 不保证设置最新版本的 Hugo。最好通过手动提供构建版本来控制构建版本。

我使用的版本是：

hugo version 
# hugo v0.147.9

GitHub Pages

将本地的修改推送到 GitHub 仓库，GitHub Actions 会自动构建并部署网站。

首先需要打开github pages 功能，在仓库页面选择 Settings -> Pages -> Source -> Deploy from a branch 切换为 GitHub Actions。

在 actions 配置中，搜索 hugo，使用对应的配置模板。

具体配置可参考：Hugo setup

可能要修改的配置是版本号 echo "HUGO_VERSION=0.119.0" >> .env

更换主题

如果我们想把主题切换成 Universal，我们可以在 themes 文件夹中下载 Universal 主题。

并修改 config.yaml 中的 theme 字段为 Universal。为了更好的兼容，配置上还要做些其他的改动。

第三章使用标记语言生成内容

markdown 基础语法

链接

[visible text](http://example.org/path/to/file)

拓展html

<strong>bold with <em>emphasis</em></strong>

bold with emphasis

这个功能是默认禁用的，需要通过设置 markup/goldmark/renderer/unsafe 为 true 来启用。

markup:
  goldmark:
    renderer:
      unsafe: true

Floating image via HTML: Follow up text after the image. This honors the floats and wraps around the image, automatically going into the next line.

表情

Smile please :smile:

Smile please 😄

这个功能是默认禁用的，需要通过设置

enableEmoji: true

来启用。

元数据 yaml

主要在写配置文件时使用。

Front matter

在文章内容的开头，由三个短划线分隔的 YAML 格式的元数据块。也称为页面元数据。常用的配置有

Name	Dafault	Use
title	文件名	文章标题
description	空	给搜索引擎的描述
date		文章发布日期
keywords		关键字
draft	false	是否为草稿
aliases	[]	备用url，可指向相同内容，用于旧系统迁移
layout		页面布局
cascade
outputs
tags

第四章内容管理

自定义配置-按环境设置

将 hugo.yaml中的配置文件拆分到config/_default目录中的各个子文件中。

config/
├── _default
│   ├── author.yaml
│   ├── config.yaml
│   ├── markup.yaml
│   ├── menu.yaml
│   └── params.yaml
├── development
│   └── config.yaml
└── production
    └── config.yaml

各个文件内容

config/_default/config.yaml

baseURL: http://example.org/
languageCode: en-us
title: Acme Corporation
theme: Eclectic
enableEmoji: true
enableGitInfo: true # 自动设置作者和日期

config/_default/markup.yaml

goldmark:
  renderer:
    unsafe: true
highlight:
  lineNos: true

config/_default/menu.yaml

main:
  - identifier: about
    name: About
    url: /about
    weight: 100
  - identifier: contact
    name: Contact
    url: /contact
    weight: 200

同时，添加开发环境和生产环境的配置文件。

开发环境： config/development/config.yaml

buildDrafts: true
minify: false
params:
  DebugMenu: true

当通过 hugo server 启动开发服务器时，Hugo 会加载 config/development/config.yaml 中的配置。

生产环境：config/production/config.yaml

enableRobotsTXT: true
minify: true

我们可以通过在环境变量 HUGO_ENV 中指定配置或在 Hugo 命令行中使用 –environment 标志来将配置覆盖为我们想要的任何名称。

更多的环境变量可以参考这个链接

section

当网站包含大量内容时，将所有这些内容放在顶级页面中会使管理内容变得具有挑战性。因此，我们可以将内容分为博客、新闻或产品等部分。

在content中创建了子文件夹，就相当于创建了一个section, 在文件夹中添加_index.md 相当于添加了索引页。

网站内容的组织结构可能是这样

content/
├── about.md
├── blog
│   ├── _index.md
│   ├── building-squares.md
│   ├── community
│   │   ├── _index.md
│   │   ├── circle.md
│   │   └── curve.md
│   ├── process-1.md
│   ├── process-2.md
│   ├── process-3.md
│   ├── process-4.md
│   └── tropical triangles.md
├── contact.md
├── credits.md
├── data-driven.md
├── markdown.md
├── news
│   ├── _index.md
│   ├── shaper.md
│   └── square-license.md
├── posts
│   └── a.md
├── privacy.md
└── terms.md

通用的显示菜单的方法

main:
  - identifier: about
    name: About
    url: /about
    weight: 100
  - identifier: contact
    name: Contact
    url: /contact
    weight: 200

也可以在 content/blog/_index.md 中动态添加

---
menu:
  main:
    name: Posts
    weight: 110
  footer:
    name: Posts
    weight: 10
---

可以通过 Netlify CMS 实现用图形界面管理内容。

多页面文件夹

index.md代表一个单独的页面，_index.md 代表一个文件夹的索引页。

比如/about页面，是个单独的页面，没有子页面，可以用content/about/index.md代表其内容。也可以直接用content/about.md代表其内容。

而/blog有子页面，可以用content/blog/_index.md代表其内容。

分类法

给页面设置标签

---
title: Tropical triangles
tags: [triangle, shape, product]
categories: [shape, design]
---

config 中添加配置 taxonomies

category: categories
tag: tags
series: series

shortcodes

hugo 内置的短代码有：ref, relref, figure, highlight, param

字符转义

{ 表示{
} 表示 }
小于号 < 转义为 <
大于号 > 转义为 >

&#45;  <!-- 连字符 -->
&#43;  <!-- 加号 -->
&#46;  <!-- 点号 -->

代码转义1

<!-- 你的 HTML 代码 -->

代码转义2


<!-- 你的 HTML 代码 -->

代码转义3

自定义快捷代码，可以向layouts/shortcodes文件夹中添加html文件，文件名就是shortcode的名称。

比如添加 divider.html 文件

<div style="background-image: linear-gradient(to right, transparent, #4f46e5, transparent);margin:15px 0;height:2px;position:relative">
  <!-- Additional trick: We can add Unicode characters as-is in HTML to render them.-->
  <span style="position:absolute; left:calc(50% - 10px); line-height:2px; font-size:30px; padding: 0 5px;background: white; color:#4f46e5">☺</span>
</div>

代码中使用 {{<divider>}} 来引入这段代码

也可以使用 {{% productInfo %}} 的方式直接替换 productInfo.md 的文件内容。

内联短代码

启用需修改配置： enableInlineShortcodes: true

第五章使用Go模板语言自定义页面

分离数据和设计

要将文件夹标记成分支（该目录下还有子页面），就在里面添加_index.md文件；

如果要将文件夹标记成叶子（该目录下没有子页面），就在里面添加index.md文件，且这样就不会使用 layouts 中提供的模板了。

go 模板语言和go语言不同，用双花括号标记。

hugo new blog/line –kind blog

第六章结构化网页

使用不同的布局

type: modern

Hugo 中的基本模板名为 baseof.html

书本结构#

第二章 30分中上线一个站点#

新建一个站点#

先来看下目录结构#

添加主题#

运行开发服务器#

添加网站配置#

持续交付#

部署到 netlify#

GitHub Pages#

更换主题#

第三章 使用标记语言生成内容#

markdown 基础语法#

元数据 yaml#

Front matter#

第四章 内容管理#

自定义配置-按环境设置#

section#

menu#

多页面文件夹#

分类法#

shortcodes#

代码转义1#

代码转义2#

代码转义3#

内联短代码#

第五章 使用Go模板语言自定义页面#

分离数据和设计#

第六章 结构化网页#

使用不同的布局#