跳到主要内容

Hugo 速查表

本文档提供 Hugo 常用命令、配置和模板语法的快速参考。

命令行​

站点命令​

命令说明
hugo new site <name>创建新站点
hugo new content <path>创建新内容
hugo new theme <name>创建新主题

构建命令​

命令说明
hugo构建站点
hugo -D包含草稿构建
hugo -F包含未来日期内容
hugo --minify压缩输出
hugo -d <dir>指定输出目录
hugo -b <url>指定基础 URL
hugo --gc清理未使用资源

开发命令​

命令说明
hugo server启动开发服务器
hugo server -D包含草稿
hugo server --navigateToChanged自动跳转到修改的页面
hugo server --liveReloadPort 443指定热重载端口
hugo server --bind 0.0.0.0允许外部访问

其他命令​

命令说明
hugo version显示版本
hugo env显示环境信息
hugo list drafts列出草稿
hugo list future列出未来内容
hugo list expired列出过期内容
hugo config显示配置
hugo convert toYAML转换配置格式

目录结构​

my-site/
├── archetypes/          # 内容模板
│   └── default.md
├── assets/              # 需要处理的资源
│   ├── css/
│   └── js/
├── content/             # 内容文件
│   ├── posts/
│   └── _index.md
├── data/                # 数据文件
├── layouts/             # 模板文件
│   ├── _default/
│   ├── partials/
│   └── shortcodes/
├── static/              # 静态文件
├── themes/              # 主题
├── public/              # 构建输出
└── hugo.toml            # 配置文件

Front Matter​

常用变量​

---
title: "文章标题"
date: 2024-01-15
lastmod: 2024-01-20
draft: false
weight: 10
description: "文章描述"
summary: "自定义摘要"
slug: "custom-url"
url: "/custom/path/"
aliases:
  - /old-url/
tags: ["Hugo", "Web"]
categories: ["技术"]
image: "/images/cover.jpg"
toc: true
---

TOML 格式​

+++
title = "文章标题"
date = 2024-01-15
draft = false
tags = ["Hugo", "Web"]
+++

JSON 格式​

{
  "title": "文章标题",
  "date": "2024-01-15",
  "draft": false
}

模板语法​

变量​

{{ .Title }}                    <!-- 页面标题 -->
{{ .Content }}                  <!-- 页面内容 -->
{{ .Summary }}                  <!-- 摘要 -->
{{ .Date }}                     <!-- 日期 -->
{{ .RelPermalink }}             <!-- 相对 URL -->
{{ .Permalink }}                <!-- 绝对 URL -->
{{ .Site.Title }}               <!-- 站点标题 -->
{{ .Site.BaseURL }}             <!-- 站点基础 URL -->
{{ .Params.custom }}            <!-- 自定义参数 -->

条件判断​

{{ if .Title }}{{ end }}
{{ if eq .Type "posts" }}{{ end }}
{{ if ne .Draft true }}{{ end }}
{{ if and .Title .Content }}{{ end }}
{{ if or .Params.featured .Params.pinned }}{{ end }}
{{ if not .Draft }}{{ end }}

{{ if eq .Section "posts" }}
    <!-- posts section -->
{{ else if eq .Section "tutorials" }}
    <!-- tutorials section -->
{{ else }}
    <!-- other -->
{{ end }}

{{ with .Params.author }}
    <p>作者：{{ . }}</p>
{{ end }}

循环​

{{ range .Site.RegularPages }}
    <h2>{{ .Title }}</h2>
{{ end }}

{{ range first 5 .Site.RegularPages }}
    <h2>{{ .Title }}</h2>
{{ end }}

{{ range .Site.RegularPages.ByDate.Reverse }}
    <h2>{{ .Title }}</h2>
{{ end }}

{{ range $index, $page := .Site.RegularPages }}
    <div class="post-{{ $index }}">{{ $page.Title }}</div>
{{ end }}

函数​

<!-- 字符串 -->
{{ .Title | upper }}                    <!-- 大写 -->
{{ .Title | lower }}                    <!-- 小写 -->
{{ .Title | title }}                    <!-- 标题格式 -->
{{ .Summary | truncate 100 }}           <!-- 截断 -->
{{ .Title | replace "old" "new" }}      <!-- 替换 -->

<!-- 日期 -->
{{ .Date.Format "2006-01-02" }}
{{ .Date.Format "2006年01月02日" }}

<!-- 数学 -->
{{ add 1 2 }}    <!-- 3 -->
{{ sub 5 2 }}    <!-- 3 -->
{{ mul 3 4 }}    <!-- 12 -->
{{ div 10 2 }}   <!-- 5 -->

<!-- 数组 -->
{{ first 3 .Pages }}
{{ last 3 .Pages }}
{{ range split "a,b,c" "," }}{{ . }}{{ end }}
{{ delimit .Params.tags ", " }}

Partials​

{{ partial "header.html" . }}
{{ partial "nav.html" .Site }}

定义和继承​

<!-- baseof.html -->
{{ block "main" . }}{{ end }}

<!-- single.html -->
{{ define "main" }}
    <article>{{ .Content }}</article>
{{ end }}

配置​

基本配置​

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'ananke'

buildDrafts = false
enableEmoji = true
summaryLength = 70

[pagination]
  pagerSize = 10

URL 配置​

[permalinks]
  posts = '/:year/:month/:title/'

# 占位符: :year :month :day :title :slug :section :filename

多语言配置​

defaultContentLanguage = 'zh'

[languages]
  [languages.zh]
    title = '我的博客'
    weight = 1
  [languages.en]
    title = 'My Blog'
    weight = 2

菜单配置​

[menu]
  [[menu.main]]
    name = '首页'
    url = '/'
    weight = 1
  [[menu.main]]
    name = '博客'
    url = '/posts/'
    weight = 2

标记配置​

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
    codeFences = true
    lineNos = true
    style = 'monokai'
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4

分类法配置​

[taxonomies]
  tag = 'tags'
  category = 'categories'
  author = 'authors'

短代码​

内置短代码​

<!-- 图片 -->
{{< figure src="/img/photo.jpg" title="标题" >}}

<!-- YouTube -->
{{< youtube VIDEO_ID >}}

<!-- Gist -->
{{< gist username gist_id >}}

<!-- 代码高亮 -->
{{< highlight python "linenos=table" >}}
print("Hello")
{{< /highlight >}}

<!-- 页面引用 -->
{{< ref "about.md" >}}
{{< relref "posts/my-post.md" >}}

自定义短代码​

<!-- layouts/shortcodes/alert.html -->
{{ $type := .Get "type" | default "info" }}
<div class="alert alert-{{ $type }}">
    {{ .Inner | markdownify }}
</div>

使用：

{{< alert type="warning" >}}
警告信息
{{< /alert >}}

页面变量​

页面属性​

变量说明
.Title页面标题
.Content页面内容
.Summary摘要
.Date发布日期
.Lastmod最后修改日期
.Draft是否草稿
.WordCount字数
.ReadingTime阅读时间
.RelPermalink相对 URL
.Permalink绝对 URL
.Section所属分区
.Type内容类型
.Kind页面类型
.Weight权重
.Params自定义参数

站点属性​

变量说明
.Site.Title站点标题
.Site.BaseURL基础 URL
.Site.LanguageCode语言代码
.Site.Params站点参数
.Site.Menus菜单
.Site.RegularPages所有常规页面
.Site.Pages所有页面
.Site.Taxonomies分类法

排序方法​

{{ range .Pages.ByTitle }}
{{ range .Pages.ByDate }}
{{ range .Pages.ByDate.Reverse }}
{{ range .Pages.ByPublishDate }}
{{ range .Pages.ByLastmod }}
{{ range .Pages.ByWeight }}
{{ range .Pages.ByLength }}

分页​

{{ $paginator := .Paginate .Pages }}
{{ range $paginator.Pages }}
    <h2>{{ .Title }}</h2>
{{ end }}

{{ if $paginator.HasPrev }}
    <a href="{{ $paginator.Prev.URL }}">上一页</a>
{{ end }}

<span>{{ $paginator.PageNumber }} / {{ $paginator.TotalPages }}</span>

{{ if $paginator.HasNext }}
    <a href="{{ $paginator.Next.URL }}">下一页</a>
{{ end }}

资源处理​

<!-- 获取资源 -->
{{ $css := resources.Get "css/main.css" }}

<!-- 处理资源 -->
{{ $css | minify }}
{{ $css | fingerprint }}
{{ $css | resources.Concat "css/bundle.css" }}

<!-- 图片处理 -->
{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x" }}
{{ $webp := $image.Resize "800x webp" }}

部署配置​

GitHub Actions​

- name: Build with Hugo
  run: hugo --gc --minify

Netlify​

[build]
  publish = "public"
  command = "hugo --gc --minify"

[context.production.environment]
  HUGO_VERSION = "0.121.1"

Vercel​

Framework preset: Hugo

常见问题​

中文 URL 问题​

# hugo.toml
disablePathToLower = true

代码高亮不显示​

[markup]
  [markup.highlight]
    noClasses = false

草稿不显示​

hugo server -D
# 或
hugo --buildDrafts

热重载不工作​

hugo server --disableFastRender

内存不足​

hugo --gc

有用的链接​