Hugo教程

开始

快速开始

安装Hugo

在Hugo项目release页面下载对应平台的Hugo二进制程序，并添加对应环境变量。

通过如下命令确认安装正确

hugo version

创建新站点

hugo new site quickstart

以上命令会在当前目录下quickstart文件夹中创建新的Hugo站点。

添加主题

在themes.gohugo.io浏览并选择喜欢的主题：

使用Tranquilpeak主题

1
2
3
4
5


cd quickstart
git init
# git config core.autocrlf false
git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/tranquilpeak
echo 'theme = "tranquilpeak"' >> config.toml

使用Academic主题

使用Academic主题需摒弃之前创建的新站点

使用Git

1
2
3


git clone https://github.com/sourcethemes/academic-kickstart.git quickstart
cd quickstart
git submodule update --init --recursive

使用Zip

下载并解压到当前文件夹，可改名为喜欢的名字。下载并解压为上一步骤文件夹下themes/academic/目录。

使用Beautiful Hugo主题

1

git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautiful

使用Cayman主题

1
2


git submodule add https://github.com/zwbetz-gh/cayman-hugo-theme.git themes/cayman
git submodule update --remote --merge # updating theme

添加内容

hugo new posts/my-first-post.md

如果需要，可以编辑生成的文件。

启动Hugo服务器

hugo server -D

启动Hugo Server并启用drafts

在http://localhost:1313/查看你的新站点。

生成静态页面

1

hugo -D

输出默认在./public/，可使用-d/–destination选项修改，或者在config文件中设置publishdir。

部署到Github Pages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 1. 确保站点在本地工作
hugo server
#Or
hugo server -t <YOURTHEME>
# 2. Ctrl+C终止服务器并删除public目录
rm -rf public
# 3. 添加子模块
git submodule add -b master git@github.com:username/username.github.io.git public
cd public && git config user.name UserName && git config user.email YourEmail && cd ..
# 4. 部署
hugo -t tranquilpeak
./deploy.sh "Your optional commit message"

deploy.sh脚本如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


#!/usr/bin/env bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public
# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back up to the Project Root
cd ..

添加Staticman

为仓库添加Staticman

在项目设置页Collaborators中添加staticmanapp，此时打开邀请链接https://api.staticman.net/v2/connect/{your GitHub username}/{your repository name}

创建配置文件

基本用法

Hugo的CLI功能齐全，但使用简单，即使是那些在命令行工作经验非常有限的人也是如此。

以下是您在开发Hugo项目时将使用的最常用命令的说明。有关Hugo CLI的全面叙述，请参阅命令行参考。

测试安装

安装Hugo成功后使用如下命令测试

hugo help

hugo命令

hugo命令最常见的用法是在当前目录运行，这将默认在public/目录生成你的网站，但是可以在站点配置中修改publishDir字段来自定义输出目录。

草稿，将来和过期内容

Hugo允许您在内容的前言设置draft, publishdate，甚至是expirydate。默认情况下，Hugo不会发布：

具有未来publishdate值的内容
draft: true状态的内容
具有过去expirydate值的内容

通过在hugo和hugo server中分别添加以下标志，或者在配置中更改分配给同名字段（不带–）的布尔值，可以在本地开发和部署期间覆盖全部这三个：

–buildFuture
–buildDrafts
–buildExpired

实时重载

Hugo内置LiveReload,不需要额外安装包。在开发站点时使用Hugo最常用的方法是运行命令hugo server，并观察变化。

这将运行功能完备的Web服务器，同时在项目组织的以下区域内监控文件系统的添加，删除或更改：

/static/*
/content/*
/data/*
/i18n/*
/layouts/*
/themes//*
config

每当您进行更改时，Hugo将同时重建网站并继续提供内容。一旦构建完成，LiveReload就会告诉浏览器静默重新加载页面。

大多数Hugo构建都非常快，除非直接在浏览器中查看站点，否则您可能不会注意到更改。这意味着在第二台显示器（或当前显示器的另一半）上保持站点打开，可以让您查看最新版本的网站，而无需离开文本编辑器。

Hugo在模板中关闭</body>之前注入了LiveReload<script>，因此如果此标记不存在则不起作用。

禁用LiveReload

LiveReload通过将JavaScript注入Hugo生成的页面来工作。该脚本创建从浏览器的Web socket客户端到Hugo Web socket服务器的连接。

LiveReload非常适合开发。但是，一些Hugo用户可能会在生产中使用hugo server来即时显示更新的内容。以下方法可以轻松禁用LiveReload：

hugo server --watch=false

或

hugo server --disableLiveReload

通过将以下键值分别添加到config.toml或config.yml文件中，可以省略后一个标志：

1

disableLiveReload = true

1

disableLiveReload: true

部署您的网站

在运行hugo server进行本地Web开发之后，您需要运行没有server部分的hugo命令来重建您的站点。然后，您可以通过将public/目录复制到生产Web服务器来部署站点。

由于Hugo生成静态网站，您的网站可以使用任何Web服务器托管在任何地方。有关由Hugo社区提供的托管和自动化部署的方法，请参阅主机和部署。

运行hugo不会在构建之前删除生成的文件。这意味着您应该在运行hugo命令之前删除您的public/目录（或通过标志或配置文件指定的发布目录）。如果您不删除这些文件，则存在错误文件（例如，草稿或将来的帖子）留在生成的网站中的风险。

Dev vs Deploy Destinations

Hugo在构建之前不会删除生成的文件。一个简单的解决方法是使用不同的目录进行开发和生产。

要启动构建草稿内容的服务器（有助于编辑），您可以指定不同的目标;例如，dev/目录：

hugo server -wDs ~/Code/hugo/docs -d dev

当内容准备好发布时，使用默认的public/目录：

hugo -s ~/Code/hugo/docs

这可以防止草稿内容意外变为可用。

目录结构

新建站点Scaffolding

从命令行运行hugo new site生成器将创建一个包含以下元素的目录结构：

.
├── archetypes
├── assets
├── config
├── content
├── data
├── layouts
├── static
└── themes

目录结构解释

以下是每个目录的高级概述，其中包含指向Hugo文档中各个部分的链接。

archetypes

您可以使用hugo new命令在Hugo中创建新的内容文件。默认情况下，Hugo将创建至少包含date，title（从文件名推断）和draft = true的新内容文件。这节省了时间并提高了使用多种内容类型的网站的一致性。您也可以使用自定义预配置的前端字段字段创建自己的archetypes。

assets

存储Hugo Pipes需要处理的所有文件。只有使用.Permalink或.RelPermalink的文件才会发布到public目录。

config

Hugo附带了大量配置指令。 config目录是将这些指令存储为JSON，YAML或TOML文件的位置。每个根设置对象都可以作为自己的文件并由环境构建。设置最少且不需要环境感知的项目可以在其根目录下使用单个config.toml文件。许多站点可能几乎不需要任何配置，但Hugo附带了大量配置指令，可以更详细地说明您希望Hugo如何构建您的网站。

content

您网站的所有内容都将位于此目录中。 Hugo中的每个顶级文件夹都被视为内容部分。例如，如果您的网站有三个主要部分 - 博客，文章和教程 - 您将在内容/博客，内容/文章和内容/教程中有三个目录。 Hugo使用部分来分配默认内容类型。

data

此目录用于存储Hugo在生成您的网站时可以使用的配置文件。您可以使用YAML，JSON或TOML格式编写这些文件。除了添加到此文件夹的文件之外，您还可以创建从动态内容中提取的数据模板。

layouts

以.html文件的形式存储模板，指定如何将内容的视图呈现到静态网站中。模板包括列表页面，主页，分类模板，部分，单页模板等。

static

存储所有静态内容：图像，CSS，JavaScript等。当Hugo构建您的站点时，静态目录中的所有资源都将按原样复制。使用静态文件夹的一个很好的示例是在Google Search Console上验证网站所有权，您希望Hugo在其中复制整个HTML文件而不修改其内容。

从Hugo 0.31开始，您可以拥有多个静态目录。

Table of Contents

开始