安装
下载
前往 Hugo Release 地址下载对应系统的版本， 如 hugo_0.108.0_Linux-64bit.tar.gz，部分主题需要下载 extended 版本
安装
- 解压后把二进制可执行文件
hugo ，把该文件放到 /usr/bin/ 目录即可，或者
- 升级
hugo 只需下载新版本然后替换该可执行文件即可
1
2
3
4
5
6
|
mkdir hugo
tar -C hugo -xzf hugo_0.108.0_Linux-64bit.tar.gz
mv hugo/hugo /usr/local/bin/
export PATH=$PATH:/usr/local/bin
hugo version # 查看 hugo 版本
|
使用
常用命令及参数
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
hugo version # 查看版本
hugo env # 版本和环境详细信息
hugo new site "$mysite" # 创建新站点
hugo new index.md # 创建文章，在 content 文件夹可以看到，此时多了一个 index.md 的 markdown 文件，打开文件可以看到时间和文件名等信息已经自动加到文件开头，包括创建时间，页面名，是否为草稿等。
cd blog
hugo # 编译生成静态文件，Hugo 将编译所有文件并输出到 public 目录
hugo server # 编译生成静态文件并启动web服务
--bind="127.0.0.1" # 服务监听IP地址
-p, --port=1313 # 服务监听端口
-t, --theme="" # 指定主题
-w, --watch[=true] # 监听站点目录，发现文件变更自动编译，不需要重新运行 hugo server
-D, --buildDrafts # 包括被标记为 draft 的文章，生成被标记为草稿的页面是否发布, hugo 会忽略所有通过 draft: true 标记为草稿的文件。必须改为 draft: false 才会编译进 HTML 文件。
-E, --buildExpired # 包括已过期的文章
-F, --buildFuture # 包括将在未来发布的文章
-b, --baseURL="www.andqiu.cn" # 服务监听域名
--log[=false] # 开启日志
--logFile="/var/log/hugo.log" # log输出路径
-v, --verbose[=false] # 输出详细信息
|
- 执行
hugo 命令，站点目录下会新建 public 文件夹，生成的所有静态网站页面都会存储到这个目录
- 如果使用
Github pages 来作为博客的 Host，只需要将 public 里的文件上传就可以
- 如果使用
nginx 作为 web 服务，配置 root dir 指向 public 即可
新建站点
1
2
3
|
cd /data
mkdir website
hugo new site blog
|
即可在 /website/data 目录创建网站根目录 blog
目录结构介绍：
1
2
3
4
5
6
7
|
archetypes/ # 储存 .md 的模板文件，新建一个 .md 文件时会按此模版创建
content/ # 网站内容，全部使用 markdown 格式
data/ # 保存站点可使用的配置文件
layouts/ # 网站模版，选择主题后会将主题中的 layouts 文件夹中的内容复制到此文件夹中
static/ # 包含 CSS、JavaScript、Fonts、media 等。选择主题后会将主题中的 ststic 文件夹中的内容复制到此文件夹中
themes/ # 存放主题
config.toml # 网站的主配置文件
|
下载主题
前往主题官网 Themes 选择自己喜欢的主题，通常每个主题介绍都有对应主题的安装方法
以 even 主题为例
1
2
|
cd blog
git clone https://github.com/olOwOlo/hugo-theme-even themes/even
|
在下载好的主题 themes/even/exampleSite 目录把 config.toml 文件和 content 目录复制到 blog 目录下
1
2
|
cp themes/even/exampleSite/config.toml blog/
cp -rf themes/even/exampleSite/content/ blog/
|
至此，博客网站及主题都已安装好
编译
编译后将在网站目录生成 public 文件夹及生成的静态文件
1
|
hugo --theme=even --baseUrl="https://andyqiu.cn/"
|
有时候会出现报错 Error: module "even" not found; either add it as a Hugo Module or store it in "/data/website/blog ，此时需要检查下报错提示的地址下面是否有对应的主题，如果主题安装位置不在网站目录的主题文件夹，即 blog/themes。此时需要指定主题的路径，即在 config.toml 配置文件中指定主题路径 themesDir = "../themes"
启动 web 服务
如果只是本机写文章，可以使用 hugo server -D 命令，草稿及正式文章的内容修改会自动更新
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
hugo server -t even --buildDrafts --baseURL=http://www.andyqiu.cn --bind=0.0.0.0 --port=20000 -w
Start building sites …
hugo v0.108.0-a0d64a46e36dd2f503bfd5ba1a5807b900df231d linux/amd64 BuildDate=2022-12-06T13:37:56Z VendorInfo=gohugoio
WARN 2022/12/17 17:18:19 The google_news internal template will be removed in a future release. Please remove calls to this template. See https://github.com/gohugoio/hugo/issues/9172 for additional information.
| EN
-------------------+-----
Pages | 60
Paginator pages | 1
Non-page files | 0
Static files | 38
Processed images | 0
Aliases | 22
Sitemaps | 1
Cleaned | 0
Built in 173 ms
Watching for changes in /data/website/{blog,themes}
Watching for config changes in /data/website/blog/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://www.andyqiu.cn:20000/ (bind address 0.0.0.0)
Press Ctrl+C to stop
|
启动完在浏览器输入 http://www.andyqiu.cn:20000/ 即可访问博客
Nginx 部署（非必须）
如果需要把网站部署到 Nginx 服务器，在 Nginx 配置文件中把 server 的 root 路径指定为 /data/website/blog/public 即可
1
2
3
4
5
6
|
location / {
root /data/website/blog/public;
index index.html;
log_not_found off;
error_log off;
}
|
上面配置是 80 端口的配置，nginx -s reload 之后即可访问 http://www.andyqiu.cn
新建文章
在网站的根目录执行 hugo new first.md 后，将会在 content 目录创建对应的 makedown 文件
1
2
|
cd blog
hugo new first.md
|
在 content 目录自动生成如下内容的 first.md 文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
---
title: "Hugo"
subtitle: "Hugo 入门文档"
date: 2022-05-01T16:19:04+08:00
lastmod: 2022-10-01T21:00:00+08:00
draft: false
description: "How to use Hugo"
image: "/images/book.jpg"
tags: ["Hugo", "入门"]
categories: ["Hugo"]
series: ["Hugo"]
summary: "Hugo 安装及使用"
toc: true
author: "Andy"
---
|
两条 --- 间的信息是 markdown 文章的 metadata，其含义如下：
- title: 文章标题
- subtitle: 文章副标题
- date: 文章创建时间
- lastmod: 最近修改时间
- draft: 在生成静态页面时，除非使用了 hugo -D 或者 hugo –buildDrafts 命令, 否则这篇文章将不会被渲染
- description: 文章内容描述
- image: 文章页首图片
- tags: 文章标签
- categories: 文章所属类别
- series: 文章所属系列
- summary: 摘要，Hugo 默认会将内容的前 70 个单词作为摘要
- toc ： 是否开启目录
根据不同的模板文件的配置，可以配置不同的 metadatea
图片资源
如果我们运行 hugo 命令来生成网页，其会自动在 public/ 路径下存放 images 文件夹以及文件
Hugo 在生成页面时，会拷贝静态资源到 public 文件夹，包括：
- 拷贝
theme/static/* 到 public/下
- 拷贝
static/* 到 public/下
- 遍历所有
content/ 下所有文件。
- 获取文件头信息，并把正文
markdown 转换为 html
- 渲染生成相关页面。
- 渲染已生成页面对应的正文页面，生成文件夹对应的列表页面，生成分类页面，生成主页。
因此，只需要把图片资源放到 static 目录下即可在 markdown 中引用。
但这里面存在一个问题，就是写文章的时候如果想要达到 markdown 所写即所得的效果，会出现图片路径不对而无法加载的问题，因为 markdown 的路径是在 content 目录
这个问题可以采用图床，或者自己搭建一个静态资源服务器的方式解决
此处采用的是 Nginx 服务器配置一个静态路径
1
2
3
4
|
location /imgs {
alias /data/imgs/;
index index.html;
}
|
图片上传到服务器 /data/imgs/ 目录下即可通过 https://andyqiu.cn/imgs/favicon.ico 地址访问
Markdown 语法
markdown 语法参考文档 Markdown
Hugo Shortcodes
Hugo 喜欢 Markdown 是因为它的内容格式简单，但有时 Markdown 也不尽如人意。有时候为了达到想要的效果，内容作者不得不将原始 HTML 添加到 Markdown 里。但是，这与 Markdown 语法的优美简洁不是相矛盾了吗。所以 Hugo 创建了 Shortcodes 来避免这些限制。
简单来理解，Shortcodes 就是一组内容样式模板，你可以在 markdown 里像使用 HTML 一样使用 Shortcodes。
Hugo 内置了一组预定义的 Shortcodes，有关其详细介绍请移步
Mermaid
基于 Mermaid 的 mermaid shortcode，可绘制图表和流程图
示例：
1
2
3
4
|
{{< mermaid >}}
flowchart LR
A -- text --> B -- text2 --> C
{{< /mermaid >}}
|
输出：
flowchart LR
A -- text --> B -- text2 --> C
更多语法请移步：Mermaid 官网
Mathjax
基于 MathJax 的 math shortcode，可编辑公式
例1: 行内公式，用 \( 和 \) 表示公式的开始和结束
1
2
3
|
{{< math >}}
这是一个行内公式：\( x = {-b \pm \sqrt{b^2-4ac} \over 2a} \)
{{< /math >}}
|
输出：
$$
这是一个行内公式：( x = {-b \pm \sqrt{b^2-4ac} \over 2a} )
$$
例2: 公式块，用 $$ 和 $$ 表示公式的开始和结束
1
2
3
|
{{< math >}}
这是一个公式块：$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
{{< /math >}}
|
输出：
$$
这是一个公式块：$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
$$
更多语法请移步：MathJax 官网
