使用 Hugo + Github Pages 创建静态网站博客
作者：互联网
最好的参考资料仍然是官方。本文仅作一个基本描述
安装Hugo
在此处下载安装包。有两个版本：（1）hugo；（2）hugo_extended。怎么选？很多功能，包括一些主题，都需要hugo_extended的支持，因此，建议安装hugo_extended。下载之后，解压，将hugo.exe加入环境变量即可。
创建站点
仅需一个命令：
> hugo new site my_blog
站点的目录结构如下：
> ls my_blog
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 2022/4/16 16:32 archetypes
d----- 2022/4/16 16:32 content
d----- 2022/4/16 16:32 data
d----- 2022/4/16 16:32 layouts
d----- 2022/4/16 16:32 static
d----- 2022/4/16 16:32 themes
-a---- 2022/4/16 16:32 82 config.toml
最关键的几个文件/目录:
-
config.toml 配置文件，要定制化的东西几乎全在这里修改。
-
themes 存放主题的目录。里面可以放一个或多个主题
-
content 存放博客的目录。后续以markdown格式写的文章，就放在这下面：
content/ └── posts/ └── this-is-my-first-blog/ <-- page bundle | ├── index.md | └── sunset.jpg <-- page resource └—— this-is-my-second-blog.md注意，如果将md文件和引用的图片放在一个文件夹下（官方叫
page bundle），则md文件需命令为index.md，否则md在渲染为html后，里面的图片不会显示。
添加主题
新建的站点是空的，需要添加一个主题后才能正常使用。此处以FixIt主题为例。关于主题的选择，请看下一节主题推荐。
添加主题有两种方式：
（1）将主题下载下来，放在themes目录下即可
（2）将主题以子模块的形式添加到站点，使用git管理。这么做主要是便于以后升级。本文采用此方式。关于git submodule的更多信息查看这里：git submodule - 标签 - 武大路飞 (whuwangyong.github.io)
另外，建议不要直接修改主题里面的文件，以后升级时合并起来很麻烦。没什么问题，主题可以一直使用，没必要频繁升级。
> cd my_blog
> git init
> git submodule add https://github.com/Lruihao/FixIt.git themes/FixIt
# 以后可以使用以下命令升级主题
> git submodule update --remote --merge
主题推荐
官网提供了很多主题，我试用了一些，从以下几个角度进行选择：
最后选出了以下几个。
Stack
Stack | Hugo Themes (gohugo.io)
特点：
- 搜索很快
- 首页和正文的间距都很大
- 博客无修改时间
- 分类与标签的样式是一样的
- favicon图标设置：放在
hugo-theme-stack/static/img/目录下，修改hugo-theme-stack/config.yaml，设置params.favicon为/img/your-favicon.ico，注意是/img不是img - md图片目录不能以 · 开始。否则渲染之后图片src="/"是从根路径开始的，就找不到图片
Bootstrap
Bootstrap Theme for Personal Blog and Documentations | Hugo Themes (gohugo.io)
这个主题的特点是，默认采用的posts layout，这个布局下面的文章，侧边栏的TOC目录是不固定的。如果需要固定，请使用docs layout。
This theme provides several kinds of layouts, such as
postsanddocs. Our documentations uses thedocslayout. If you're looking for an example that usingpostslayout, please take a look at Markdown Syntax.
优点
-
页面控件支持超宽布局
-
代码控件支持超长代码折叠
-
Docs Layout 可以方便的将整个知识库放上去，这样本地的分类目录就能直接给博客使用，博客无需关心分类、标签的问题。
LoveIt
搜索
LoveIt主题支持"lunr"和"algolia"两种搜索：
lunr： 简单，配置type = "lunr"即可。运行hugo会将生成的index.json索引文件放在public/目录下，随网站一起发布。没有 contentLength 的限制，但占用带宽大且性能低 (特别是中文需要一个较大的分词依赖库)。客户端需将整个index.json从网站下载到本地，然后基于此文件进行搜索。下图是使用lunr搜索时，生成的静态文件，可见分词库有3.6MB：
algolia：高性能并且占用带宽低，但需要将 index.json 上传到algolia官网（手动或使用Algolia Atomic脚本）；有 contentLength 的限制。对于免费用户：Your first 10,000 records are free, and every month you’ll receive 10,000 requests for our Search and Recommend products.
经过测试，lunr导致网站加载速度变慢，且搜索效果很不理想。所以我选择了algolia。配置如下：注意 index = "new-index-1649076215"，后面的值是你在algolia网站上创建的索引名。
[params.search]
enable = true
# 搜索引擎的类型 ("lunr", "algolia")
type = "algolia"
# 文章内容最长索引长度
contentLength = 4000
# 搜索框的占位提示语
placeholder = ""
# 最大结果数目
maxResultLength = 10
# 结果内容片段长度
snippetLength = 50
# 搜索结果中高亮部分的 HTML 标签
highlightTag = "em"
# 是否在搜索索引中使用基于 baseURL 的绝对路径
absoluteURL = false
[params.search.algolia]
# 这里填写你在algolia上面创建的索引名
index = "new-index-1649076215"
appID = "YMLXXXXFHL"
searchKey = "9028b251fe4eexxxxxxxxxxxxx5a4f0"
多语言
所有写在[languages]外面的，都是所有语言公用的。Multilingual Mode | Hugo (gohugo.io)。我去故意掉了多语言，只保留了中文：将[languages.zh-cn]下面的所有配置挪到外面，然后删除空的[languages]块。
使用本地资源
有三种方法来引用图片和音乐等本地资源:
- 使用页面包中的页面资源. 你可以使用适用于
Resources.GetMatch的值或者直接使用相对于当前页面目录的文件路径来引用页面资源。所谓的页面包，就是图片和md文件放在一起（使用相对路径访问）。- 将本地资源放在 assets 目录中, 默认路径是
/assets. 引用资源的文件路径是相对于 assets 目录的.- 将本地资源放在 static 目录中, 默认路径是
/static. 引用资源的文件路径是相对于 static 目录的.引用的优先级符合以上的顺序.
在这个主题中的很多地方可以使用上面的本地资源引用, 例如 链接 , 图片 ,
imageshortcode,musicshortcode 和前置参数中的部分参数.页面资源或者 assets 目录中的图片处理会在未来的版本中得到支持. 非常酷的功能!
Front Matter
https://hugoloveit.com/zh-cn/theme-documentation-content/#front-matter
转义字符
https://hugoloveit.com/zh-cn/theme-documentation-content/#escape-character
SRI
启用之后在github.io有问题：
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/lib/lunr/lunr.stemmer.support.min.d73a55668c9df0f2cbb2b14c7d57d14b50f71837e9d511144b75347e84c12ff8.js' with computed SHA-256 integrity 'EVRhgSylsJP5vMLxXSaTpskOj+ONq/I3Xl8Y4cNI2Xw='. The resource has been blocked.
whuwangyong.github.io/:1
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/lib/lunr/lunr.zh.min.e9abb2f5c7c0f738290cd8a5ff2ce1cf5deac6942f44ce5dd89c9ab1ae27006a.js' with computed SHA-256 integrity 's6qyS9abdG0o9DP0qC7PoVVqdbpe+fTKorzHq40yfBQ='. The resource has been blocked.
whuwangyong.github.io/:1
Failed to find a valid digest in the 'integrity' attribute for resource 'https://whuwangyong.github.io/js/theme.min.09729ab43fbb7b49c065c597d41bb70983c7852ea77794a00b8f78099b049b43.js' with computed SHA-256 integrity '9Rk48wZaQO6EG8tVjkMw4x/SbA6lU0P/+HcLiLAxmjw='. The resource has been blocked.
页面现象就是侧边栏目录、评论都不显示。但是在vercel.app没问题。另外，console还有个warning：Error with Permissions-Policy header: Unrecognized feature: 'interest-cohort'.
LoveIt 总结
优点
-
文档很详细
-
默认在新标签页打开链接
-
可以设置代码超过n行折叠
-
标题加粗，更加清晰
-
使用 weight 置顶
--- weight: 1 # 置顶 title: "主题文档 - 基本概念" date: 2020-03-06T21:40:32+08:00 lastmod: 2020-03-06T21:40:32+08:00 draft: false author: "Dillon" authorLink: "https://dillonzq.com" description: "探索 Hugo - LoveIt 主题的全部内容和背后的核心概念." resources: - name: "featured-image" src: "featured-image.jpg" tags: ["installation", "configuration"] categories: ["documentation"] lightgallery: true toc: auto: false ---
缺点
-
搜索没有jekyll + chirpy的好，也没有stack的开箱即用。（
algolia要自己搞上传，lunr分词有问题）。 -
主题不太美观
-
画廊。使用以下语法。不加“图片描述”不会激活。未使用画廊的图片，点击不会响应，只能右键新标签打开，放大查看。还有个小bug，页面刷新后，图变小了。
 -
最重要的，两年没维护了。但这个主题确实不错，所有有不少人fork了一份继续维护。我选择的是Lruihao/FixIt。
FixIt
Lruihao/FixIt: 标签：Github,2022,Hugo,目录,github,主题,hugo,Pages
来源： https://www.cnblogs.com/duanguyuan/p/16163589.html