使用 Hugo + Github Pages 创建静态网站博客

2022/4/19 6:13:18

编程Tag： github pages 目录主题 2022 Hugo

本文主要是介绍使用 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 posts and docs. Our documentations uses the docs layout. If you're looking for an example that using posts layout, please take a look at Markdown Syntax.

——from：Docs Layout - Hugo Bootstrap (razonyang.com)

优点

页面控件支持超宽布局
代码控件支持超长代码折叠
Docs Layout 可以方便的将整个知识库放上去，这样本地的分类目录就能直接给博客使用，博客无需关心分类、标签的问题。

LoveIt

dillonzq/LoveIt: ❤️A clean, elegant but advanced blog theme for Hugo 一个简洁、优雅且高效的 Hugo 主题 (github.com)

搜索

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 目录的.

引用的优先级符合以上的顺序.

在这个主题中的很多地方可以使用上面的本地资源引用, 例如链接 , 图片 , image shortcode, music shortcode 和前置参数中的部分参数.

页面资源或者 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，页面刷新后，图变小了。
```
![image.png](https://cdn.jsdelivr.net/gh/whuwangyong/whuwangyong.github.io@gh-pages/2022-04-19-hugo/assets/image-20220329160821-l8rh3to.png "图片描述")
```
最重要的，两年没维护了。但这个主题确实不错，所有有不少人fork了一份继续维护。我选择的是Lruihao/FixIt。

FixIt

Lruihao/FixIt:

这篇关于使用 Hugo + Github Pages 创建静态网站博客的文章就介绍到这儿，希望我们推荐的文章对大家有所帮助，也希望大家多多支持为之网！