这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

Learning Hugo

Hugo学习笔记

1 - 介绍

Hugo的介绍，选择Hugo的理由，以及Hugo的资料收集

1.1 - Hugo介绍

Hugo是什么？Hugo可以用来做什么？

静态网站生成器，专注内容，快速创作。

Hugo是什么？

Hugo是由Go语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。

Hugo以速度快著称，号称是世界上最快的网站生成框架。

The world’s fastest framework for building websites

Hugo可以用来做什么？

1.2 - 为什么选择Hugo

为什么我选择了Hugo，而放弃了gitbook/hexo？

非常重要的额外理由：找到了两个很喜欢的主题 academic 和 docsy，分别用于技术博客网站和学习笔记

Hugo的特点

Hugo以速度快著称，号称是世界上最快的网站生成框架。

The world’s fastest framework for building websites

来自1Password的评价

这里有一段来自1Password的对hugo的评价，很有代表性。

内容翻译自 https://gohugo.io/showcase/1password-support/

在1Password，我们过去每个月都会经历一个不同的文档平台：博客引擎，电子书，维基，用Ruby和JavaScript编写的网站生成器。 每个方式都有自己的不足。然后我们找到了hugo。我们做了最后一次切换，我们很高兴我们做到了。

并非所有静态站点生成器都是相同的

找到一个能让您的客户，作者，设计师和DevOps团队满意的工具并非易事，但我们通过Hugo进行了管理：

  • Hugo是静态的。我们是一家安全公司，所以我们坚持静态网站并尽可能地使用它们。我们觉得客户在HTML文件上比在需要强化的复杂服务器上更安全。

  • Hugo是基于Go的。在1Password我们喜欢Go编程语言，我们很高兴得知Hugo使用了我们的设计师和前端开发人员已经掌握的相同的Go模板语法。

  • Hugo很快。我们以前的静态站点生成器花费将近一分钟来编译我们的（那时还小得多）站点。开发人员可能已经习惯了这一点，但对于希望看到工作实时预览的作家来说，这并不合适。Hugo在几毫秒内完成了同样的工作，到现在，转瞬之间就可以编译五种语言编写的400多个页面。

  • Hugo很灵活。感谢Hugo的内容和布局系统，我们能够保留现有的文件和文件夹结构，并在几天内移植整个生产站点。然后我们可以创建以前不可能的新内容类型，比如这些时髦的陈列柜。

  • Hugo非常适合作家。我们的文档团队已经对Markdown和Git感到满意，并且可以开始为Hugo创建内容而无需停顿。一旦我们添加了短代码，我们的作者就可以通过少量的新语法来使用类似平台盒(platform boxes)的功能来装饰文章。

  • Hugo有一个惊人的开发者社区。Hugo更新频繁，充满了功能和修复。在我们开发网站的多语言版本时，我们提交了所需功能的PR，并通过@bep和其他人的流程得到了帮助。

  • Hugo易于部署。 Hugo拥有适量的配置选项，可以适应我们的构建系统而不会太复杂。

我的个人感受

个人技术博客网站的变迁

我的个人技术博客网站，十几年来经历过很多变更，从csdn，blogjava，javaeye，hexo+github page，gitbook一路走来，在2018年2月，开始转换到hugo，迄今整三年。

这些年博客的历程，有兴趣了解的同学可以看看我在2018年改用hugo时写的文章：十年一觉扬州梦，赢得青楼薄幸名

目前的博客网站使用了自行修改订制之后的 academic 主题，非常满意，点击 这里 可以看到实际效果。

学习笔记

而现在这份Hugo学习笔记则采用的是定制版本的 Google Docsy 主题，后续会将目前大大小小的四五十份学习笔记逐步迁移到 Hugo+Docsy 上来。

对于hugo，个人非常喜爱，上面1Password列出的几点都感同身受。仅从个人感受上说，我觉得hugo优势主要体现在以下方面：

  1. 静态文件生成：生成纯静态文件，可以任意找地方托管，无任何特殊依赖。免费的github pages，廉价的虚拟主机，廉价的VPS，都可以轻松完成网站托管。
  2. markdown编写：这是至关重要的一点，在习惯了markdown高效而专注的写作体验之后，markdown的支持成为硬性要求。
  3. 使用方便：无论是偏公共性质的技术博客，还是偏私人性质的学习笔记，从内容创作或者学习心得记录的角度，都是“内容为王”！因此，一个样式简单大方的网站，在一次性的安装调试完成之后，后续就应该可以轻松快捷的进行内容创作。
  4. 速度！：仅以上述三点而言，hexo和gitbook都表现的很好，两者的功能和主题都非常的丰富。但是，hugo在渲染速度上明显高出太多，尤其是对比gitbook，几乎有几十上百倍的性能差距。当站点内容比较多，比如积攒了几年的博客，或者大量细节展开的学习笔记，gitbook的渲染速度就开始从秒级到十几秒再到分钟级，而变得越来越不可接受。Hugo的速度，是我最终放弃hexo和gitbook的最关键的原因。
  5. Go语言：这是讨人喜欢的一点，当然这会因人而异，nodejs的同学可能更愿意用gitbook。仅从个人感受上说，我对基于go的hugo好感更多。
  6. 喜欢的主题：对于hexo、gitbook、hugo，都拥有数以千计的各式主题。而要在众多主题中找到自己的心头好，有时需要一点运气。我自我感觉比较幸运的是：我找到了两个很喜欢的主题，academic 和 docsy，分别用于我的技术博客网站和学习笔记。特点是简单大气，简洁大方，不花俏，不土气，精致而内敛。有特别喜欢的主题，是一个关键的决策依据。

1.3 - 资料收集

收集Hugo的各种资料

官方资料

社区资料

学习资料

2 - 安装

介绍Hugo的安装，使用，配置和优化

2.1 - linux安装Hugo

Hugo在linux操作系统下的安装

准备工作

安装golang

安装hugo之前，先安装好golang，推荐安装最新版本。

安装nodejs/npm

为了使用Google Docsy主题，需要安装nodejs/npm。

在以下网站下载nodejs的安装包：

https://nodejs.org/en/download/package-manager

# installs nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# download and install Node.js (you may need to restart the terminal)
nvm install 22

# verifies the right Node.js version is in the environment
node -v # should print `v22.11.0`

# verifies the right npm version is in the environment
npm -v # should print `10.9.0`

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS.

由于 hugo和主题之间版本有依赖关系，因此我们暂时固定使用 v0.121.1 版本。

找到linux的安装包，对于 ubuntu 可以直接用 deb 文件：

  • hugo_extended_0.121.1_linux-amd64.deb
wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_linux-amd64.deb

deb文件直接安装即可。

sudo dpkg -i hugo_extended_0.121.1_linux-amd64.deb

2.2 - windows安装Hugo

Hugo在 windows 操作系统下的安装

准备工作

安装golang

安装hugo之前，先安装好golang，推荐安装最新版本。

https://go.dev/dl/

下载 windows 安装文件，如 go1.23.3.windows-amd64.msi。

安装时选择安装目录为 C:\Users\sky\work\soft\golang 或者 D:\sky\work\soft\golang。

修改环境变量，将 GOPATH 的值修改为 C:\Users\sky\work\soft\gopath 或者 D:\sky\work\soft\gopath（默认为 %USERPROFILE%\go）。

安装nodejs/npm

为了使用Google Docsy主题，需要安装nodejs/npm。

在以下网站下载nodejs的安装包：

https://nodejs.org/en/download/package-manager

选择 prebuild installer，下载到 node-v22.11.0-x64.msi。

安装时选择安装路径为 C:\Users\sky\work\soft\nodejs 或者 D:\sky\work\soft\nodejs。

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS:

由于 hugo和主题之间版本有依赖关系，因此我们暂时固定使用 v0.121.1 版本。

https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_windows-amd64.zip

下载下来之后，解压缩，将 hugo.exe 文件复制到目录 C:\Users\sky\work\soft\hugo 或者 D:\sky\work\soft\hugo 下。

然后修改环境变量，在 Path 中增加一项，路径为 C:\Users\sky\work\soft\hugo 或者 D:\sky\work\soft\hugo 。

验证安装：

$ which hugo
/c/Users/sky/work/soft/hugo/hugo

$ hugo version
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended windows/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio

2.3 - macOS安装Hugo

Hugo在macOS操作系统下的安装

准备工作

安装golang

安装hugo之前，先安装好golang，推荐安装最新版本。

安装nodejs/npm

为了使用Google Docsy主题，需要安装nodejs/npm。

在以下网站下载nodejs的安装包：

https://nodejs.org/en/download/package-manager

TODO

安装Hugo

在Hugo Releases页面下载对应操作系统版本的安装包。

注意：由于Google Docsy主题的需求，需要 extended 版本的hugo 以支持 SCSS:

备注: mac 下安装最简单的方式是用brew命令，但不合适用来安装extended版本，所以还是需要下载之后手工安装

下载下列文件：

wget https://github.com/gohugoio/hugo/releases/download/v0.121.1/hugo_extended_0.121.1_darwin-universal.tar.gz

解压后，将 hugo 可执行文件放在path路径下即可：

cd hugo_extended_0.121.1_darwin-universal
sudo cp hugo /usr/local/bin/hugo

2.4 - 安装后配置Hugo

Hugo安装完成后的配置工作

设置别名

为了方便使用，增加 hugo server 命令的 alias 用来本地编辑时的实时预览：

vi ~/.zshrc

增加内容：

# hugo
alias h='hugo -D -F server --disableFastRender --bind "0.0.0.0"'
alias h2='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 2323'
alias h3='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 3333'
alias h4='hugo -D -F server --disableFastRender --bind "0.0.0.0" --port 4343'

hugo命令行参数说明：

  • -D: 等同--buildDrafts，标记为 Draft 的内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。
  • -F: 等同--buildFuture，发布时间为"未来"(即时间比当前时间还要晚)内容也会一起构建，方便在本地编写和预览新的暂时未发布的内容。
  • --disableFastRender：当内容修改时，进行完整的重新构建，避免预览的内容不够新

h2/h3/h4 指定了不同的端口，当需要在本地打开多个时，可以使用固定端口而不是随机端口。

设置代理

npm代理

主要是 npm 命令需要代理才能顺利下载文件，比如：

npm install -D --save autoprefixer

如果发生报错，并且查看到如下的错误信息：

836 error path /home/sky/work/code/learning/docsy/node_modules/hugo-extended
837 error command failed
838 error command sh -c node postinstall.js
839 error ✖ Hugo installation failed. :(
839 error node:internal/process/promises:391
839 error     triggerUncaughtException(err, true /* fromPromise */);
839 error     ^
839 error
839 error RequestError: getaddrinfo ENOTFOUND github.com

这说明是网络出了问题，导致无法访问 github.com ，需要设置网络代码：

npm config set proxy http://192.168.2.1:7890
npm config set https-proxy http://192.168.2.1:7890

参考：

通用代理

如果之前配置有通用代理命令 proxyon，则执行 proxyon 开启各种代理即可：

# proxy
alias proxyon='export all_proxy=socks5://192.168.2.1:7891;export http_proxy=http://192.168.2.1:7890;export https_proxy=http://192.168.2.1:7890;export no_proxy=127.0.0.1,localhost,local,.local,.lan,192.168.0.0/16,10.0.0.0/16'
alias proxyoff='unset all_proxy http_proxy https_proxy no_proxy'

或者临时性的在当前终端中执行：

export all_proxy=socks5://192.168.2.1:7891

2.5 - 快速开始

详细介绍通过Hugo快速开始启动一个现有的项目

通常我在安装完成 hugo 之后，第一时间使用的是我的学习笔记。因此，以 hugo 学习笔记为例。

具体参考：

本地快速搭建学习笔记

2.6 - 开启HTTPS

如何为Hugo增加HTTPS支持

参考文章：

由于我用的博客服务器是ubuntu 16.04，因此部分命令稍有不同。

生成证书

先安装工具：

sudo apt-get install letsencrypt

生成证书：

sudo letsencrypt certonly --webroot -w /var/www/skyao -d skyao.io

配置nginx

在/etc/nginx/sites-available下增加一个skyao.io.https站点文件，内容如下：

server {
    listen 443 ssl;
    server_name skyao.io www.skyao.io;

    root /var/www/skyao;
    index index.html;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/skyao.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/skyao.io/privkey.pem;
}

然后将http请求都自动转为https，修改原来的skyao.io配置文件：

server {
    listen 80;
    server_name skyao.io www.skyao.io;
    rewrite ^(.*)$  https://$host$1 permanent;
}

重启nginx：

sudo service nginx restart

设置自动更新证书

由于Let’s Encrypt证书的有效期为90天，所有我们需要定期更新以避免证书过期，通常Let’s Encrypt会发邮件提醒的。

更新操作如下：

# 更新证书
sudo letsencrypt renew
# 重新启动nginx
sudo systemctl restart nginx

2.7 - 搜索引擎优化（待更新）

为了让Hugo网站更好的被搜索引擎收录，需要进行搜索引擎优化

站点内容优化

修改配置

修改 hugo/config/_default 目录下的 params.toml 文件：

description = "敖小剑的个人技术博客网站，主要关注服务网格,serverless,kubernetes,微服务等云原生技术。"

修改模板

0.54 版本下基本做的很好了，不再修改。

添加页面信息

首先确保每个页面一定都要设置有 title，description，最好还有 keywords：

title: 前言
keywords:
- hugo
- 学习笔记
- hugo学习笔记
description : "介绍Hugo学习笔记的基本资料和访问方式。"

google搜索优化

提交给Google网站站长

打开 Google网站站长，点击 “SEARCH CONSOLE ” 进入，然后添加资源，如https://skyao.io/learning-hugo/。会要求下载一个html文件如google571325××××.html做验证，将这个文件保存到hugo站点根目录下的static子目录，更新站点内容让google search console可以访问到进行验证即可。

进入资源页面，点"索引"下的"站点地图"，在"添加新的站点地图"处输入当前hugo站点的sitemap，这个文件hugo会默认生成，就在根路径下，如https://skyao.io/learning-hugo/sitemap.xml。

百度搜索优化

打开 百度搜索资源平台 ，点击 链接提交，然后点"添加站点"。同样可以用文件验证的方式来进行网站验证。

进入"数据引入"下的"链接提交"，再点 “自动提交” 下的 “sitemap”，在这里可以提交hugo网站的sitemap文件。注意百度不容许以子目录的方式提交子站点，和google不一样，我们的学习笔记 https://skyao.io/learning-hugo/ 就不能直接提交了，只能在提交sitemap文件时，提交多个sitemap文件。这样也能勉强让百度收录。

Bing搜索优化

在 Bing Webmaster Tools 处用登录，然后选择导入站点。Bing webmaster tools支持直接从 google 导入数据，很方便。

操作界面和google很类似。

参考资料

有参考以下资料，特此鸣谢：

2.8 - 增加更多语言的语法高亮

默认支持的编程语言有限，可以在需要时增加语言的支持，使之也可以做到语法高亮

默认支持的语言列表

hugo 采用 Prism 进行编程语言的语法高亮，由于编程语言数量太多，通常也不需要支持所有的语言（会导致js和css文件过大），因此默认只支持以下语言：

  • markup
  • css
  • clike
  • javascript
  • bash
  • c
  • csharp
  • cpp
  • go
  • java
  • markdown
  • python
  • scss
  • sql
  • toml
  • yaml

其他语言是无法支持的，比如默认 rust 语言就不被支持。如果需要增加对rust语言的支持，可以进行定制。

定制新的语言支持列表

步骤如下：

  1. 打开任意页面，查看源代码，找到 <script src='/js/prism.js'></script> 这段，通常在页面最下方

  2. 打开这个 js 文件，比如 http://localhost:1313/js/prism.js ，可以看到最前面有这么一排注释：

    /* PrismJS 1.25.0
https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+rust+scss+sql+toml+yaml&plugins=toolbar+copy-to-clipboard */

    这里有版本和支持语言列表。

  3. 打开上面的 URL 地址，在该页面增加需要支持的语言，如:

    • HTTP
    • Lua
    • Makefile
    • Rust
    • .properties
    • Protocol Buffers
    • WebAssembly

    也可以添加插件

    • Line Highlight
    • Line Numbers
    • Highlight Keywords

  4. 点击页面下方的“download js”和“download css”，下载 prism.js 文件和 prism.css 文件

    此时 js 文件前面的内容变为：

    /* PrismJS 1.25.0
https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+lua+makefile+markdown+properties+protobuf+python+rust+scss+sql+toml+wasm+yaml&plugins=line-highlight+line-numbers+highlight-keywords+toolbar+copy-to-clipboard */

  5. 将上述文件分别复制到hugo项目根目录下，路径为： static/css/prism.css 和 static/js/prism.js ，这会覆盖默认的文件。

其他：高亮的参数设置

可以高亮某些行，现实代码行数等。

https://gohugo.io/content-management/syntax-highlighting/

3 - 主题

介绍hugo的主题，个人推荐列表，及重度使用的academic和docsy主题

3.1 - Hugo主题介绍

介绍hugo的主题

Hugo有非常丰富的主题。

后面会列出一些个人觉得不错的Hugo主题，然后重点推荐两个我自己在重度用的主题：

  1. academic 主题：用于我的个人博客网站
  2. Docsy 主题：用于我的学习笔记

3.2 - 推荐列表

推荐一些个人觉得不错的Hugo主题

在这里列出一些个人觉得不错的Hugo主题，一方面推荐给有兴趣的同学，另一方面也给自己留个备份。

文档类

官网的分类列表：

https://themes.gohugo.io/tags/documentation/

以下主题觉得还不错的：

3.3 - academic主题

介绍hugo的docsy主题，使用方式和订制化

academic特别适合搭建内容相对比较丰富的网站

主题介绍

academic是一个特别适合搭建内容相对比较丰富的网站的主题，如果我们hugo网站的内容不仅仅是博客，还有其他好几种样式的内容，那么academic会是一个很不错的选择。此外，academic主题简洁大方，也适合作为一个稍有规模的正式网站。

  • 官网介绍：https://academic-demo.netlify.app/
  • 我用academic主题搭建的个人技术博客网站: https://skyao.io

3.4 - docsy主题

介绍hugo的docsy主题，使用方式和订制化

docsy主题非常适合用于开源项目，支持文档和博客。我主要用它来做学习笔记，替代年旧失修的meterial-docs主题。

主题介绍

docsy 主题官网：

https://github.com/google/docsy

这个主题非常适合用于开源项目，支持文档和博客。

我主要用它来做学习笔记，自行修改和定制。

3.5 - material-docs主题

介绍hugo的material-docs主题，使用方式和订制化

material-docs主题非常适合用于文档，但常年不更新，已不能支持新版本的Hugo，不得已放弃改为使用 Google Docsy 主题。

主题介绍

material-docs官网：

这个主题非常适合用于文档，左边的导航栏支持多级菜单，样式也简单美观，而且对移动设备支持很好。

我从2018年出开始使用 material-docs 主题，主要用它来做学习笔记，替代之前长期使用的gitbook（gitbook的问题主要是本地生成内容速度太慢，而gitbook官方网站访问速度又不好）。但很遗憾，material-docs主题的作者已经消失，2017年后再没有更新，包括PR也没有人处理。

随着hugo的版本越来越新，这个主题的问题也越来越多，甚至为了能兼容我的hugo长期停留在0.54版本。

因此，在2021年，正式弃用 material-docs 主题，改为 Google Docsy 主题。当前您看到的这个Hugo学习笔记就是基于 Google Docsy 主题。