基于Hugo和gh-pages快速搭建静态网站

静态网页生成器

无论您需要搭建个人博客还是为您的项目创建文档，静态网页生成器（static site generator）都是一个不错的选择。无需服务器、数据库，只要你熟悉 Markdown，喜欢GitHub，使用生成器创建静态 HTML 文件，然后推送到 GitHub Pages 等免费服务即可。

常见的静态网页生成器

Hugo是由Go语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。
jekyll 是一个静态网页、博客生成器
vuepress是基于 Vue 的静态网页生成器
Hexo 是一个由Nodejs驱动的快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。

参考：静态网页生成器

快速使用Hugo搭建个人博客站点

安装Hugo

根据自己的操作系统，下载已经构建好的Hugo二进制文件官方地址
- 官方推荐下载扩展版，支持的功能更多

解压之后，将hugo可执行文件加入到PATH环境变量中，即可使用

1
2
3
hugo version # 查看版本，扩展版含这个extended标签
hugo -h # 显示帮助信息
hugo subcommand -h # 获取子命令的帮助信息

使用Hugo

hugo需要配合git一起使用，并且官方推荐使用bash作为终端

创建项目并安装主题hugo-theme-stack

1
2
3
4
5
hugo new site quickstart # 创建目录结构
cd quickstart

git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack # 安装主题

添加内容并使用安装主题的默认配置
- 使用安装主题的实例进行快速添加内容
  - 只需要进入主题文件中的exampleSite中的content拷贝到quickstart根目录中
- 同理，在主题文件中的exampleSite中的hugo.yaml拷贝到quickstart根目录中，重命名为,并删除hugo.toml

最后运行

1
2
hugo server # 本地启动一个http服务器，便于开发和测试站点，默认热更新
hugo server --navigateToChanged # 自动重定向：编辑内容时，浏览器会自动重定向到上次修改的页面

会使用到的命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
hugo new content post/fist-post.md # 会在content目录下创建post/fist-post.md文件
# 执行完后，会在content/post目录自动生成一个MarkDown格式的first.md文件：
+++
date = "2015-01-08T08:36:54-07:00"
draft = true
title = "Fist Post"
+++
# draft 默认为true，构建网站时不会构建该文档
	# 要构建草稿文档可以用-D或--buildDrafts选项启动服务
	hugo server -D
# title 默认为文件名首字母大写

构建命令
- 进入项目目录，运行
  1
  hugo
- hugo命令会构建生成静态文件，会将文件发布项目的public目录下
- 要将站点发布到其他目录，请使用该标志--destination或在站点配置中设置publishDir
  注意：每次构建不会清空public目录，只会覆盖旧内容。
  这样做是为了防止，构建之后在public添加的文件被删除
草稿、未来和过期内容
- Hugo 允许在内容的前面设置draft、date、publishDate和expiryDate。默认情况下，Hugo 在以下情况下不会发布内容：
  - 其draft值为true
  - 是date在未来
  - 是publishDate在未来
  - 已经expiryDate过去了
  - 下面的行为可以取消
    1 2 3
    hugo --buildDrafts # or -D hugo --buildExpired # or -E hugo --buildFuture # or -F
    注意：当这样构建之后，需要手动删除不期望构建的文件，在推送站点
    否则当推送到远程会出现意外的内容
    所以建议运行上面的命令之后，前提public中没有手动添加的文件，在构建之前手动清空public目录，防止出现草稿、过期和未来的内容
最后将public中的所以文件推送到静态网站托管平台即可
- 也可以使用自动构建和部署

更多内容参考：
使用hugo搭建个人博客站点
（1）带着Stack主题入坑Hugo
（2）部署你的Hugo博客
（3）Stack主题的自定义
自定义主题添加了assets/scss、layouts/_default/、layouts/index.html,不用了删了就行

目录结构

archetypes目录包含新内容的模板
- 目录下的default.md由标记（markdown）和内容格式
  - 内容格式：—yaml—、+++toml+++、{json}
    1 2 3 4 5
    --- # +++/{ date: '{{ .Date }}' # yaml draft: true title: '{{ replace .File.ContentBaseName `-` ` ` | title }}' --- # +++/{
- 当运行hugo new content post/my-first-post.md命令时会根据default.md创建内容文件
  1 2 3 4 5
  --- date: "2023-08-24T11:49:46-07:00" draft: true title: My First Post ---
- 可以创建新内容的模版
  1 2 3
  archetypes/ ├── default.md └── post.md
  - 若运行hugo new content post/my-first-post.md查找模版的顺序
    - archetypes/post.md
    - archetypes/default.md
    - themes/my-theme/archetypes/post.md
    - themes/my-theme/archetypes/default.md
    - 如果这些都不存在，Hugo 将使用内置的默认原型
assets目录包含通常通过资产管道传递的全局资源，包括图像、CSS、Sass、JavaScript 和 TypeScript 等资源。
config目录包含站点配置，可能分为多个子目录和文件。对于具有最少配置的项目或不需要在不同环境中表现不同的项目，hugo.toml在项目根目录中命名的单个配置文件就足够了
content目录包含构成站点内容的标记文件（通常是 Markdown）和页面资源。
- 对应stack主题：
  - post存放发布的文章格式md
  - page存放导航区域的md格式配置
    - 不同的语言结尾用.en.md等表示
    - 根据模版进行修改即可，根据自己的需求，没有的需要自己补充和修改文件内容
  - categories存放类别的md格式配置
data目录包含增强内容、配置、本地化和导航的数据文件（JSON、TOML、YAML 或 XML）。
i18n目录包含多语言站点的翻译表。
content目录包含将内容、数据和资源转换为完整网站的模板。
public目录包含运行hugo或hugo server命令时生成的已发布网站。 Hugo 根据需要重新创建该目录及其内容
resources目录包含 Hugo 资产管道的缓存输出，这些输出是在运行hugo或hugo server命令时生成的。默认情况下，此缓存目录包括 CSS 和图像。 Hugo 根据需要重新创建该目录及其内容。
static目录包含在您构建站点时将复制到公共目录的文件。例如：favicon.ico、robots.txt和验证站点所有权的文件.与assets差不多
themes目录包含一个或多个主题，每个主题都位于其自己的子目录中。
联合文件系统：
- 这样理解：安装的主题里面同样有自己站点的目录结构，hugo构建时会将主题里面的文件挂载到站点，优先级是站点的高

配置文件

hugo支持三种配置文件hugo.tomal、hugo.yaml、hugo.json，喜欢用那个就用那个。
每种文件格式的规范：TOML、YAML和JSON。
配置文件可以有多个，可以放到config目录下，默认都是使用hugo开头的文件

指定配置文件构建

1
2
hugo server --config other.toml 
hugo --config a.toml,b.yaml,c.json # 可以指定多个，左边的优先级高

更多内容配置参考

额外的一些关于配置文件的总结
- 默认语言修改为zh-cn，意味着index.md表示中文，index.zh-cn.md也表示中文，此时的英文要用index.en.md表示

更多内容参考：
Hugo官方文档
Hugo中文文档
Hugo theme

文章评论

使用Waline，其教程很完整。

根据Waline教程从头完成到使用Vercel部署完成。

最后在config.yaml中的waline的serverURL给上你的Vercel服务器地址。

以及开启评论，最后waline还可以配置评论通知渠道。

将cloudflare解析的域名绑定到vercel文档
- 概括：添加一条CNAME记录值为cname.vercel-dns.com，开启代理，将SSL/TLS修改为完全
将cloudflare解析的域名绑定到github-pages文档
- 概括：添加一条子域，类型CNAME记录值为username.github.io，开启代理，将SSL/TLS修改为完全,username为你的用户名
更多内容请查阅文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
comments:
        enabled: true
        provider: waline



        
	waline:
            serverURL: url
            lang: zh-cn
            pageview: true
            copyright: false
            emoji:
                - https://unpkg.com/@waline/emojis@1.0.1/weibo
            requiredMeta:
                - name
                - email
            locale:
                admin: 👻Hi!
                placeholder: 🎉留下你的脚印...

搜索引擎优化（SEO）

本网站使用Hugo搭建，而且使用的stack主题支持自动生成基于Open Graph协议（OG协议）的标签，此处记录一下如何在Hugo搭建的网站中做搜索引擎优化（SEO）。

目的：提升网站在搜索引擎中的排名

Open Graph（开放图谱）协议，简称OG协议，是Facebook在2010年公布的一项协议，用来标记网页内容。简单来讲，OG协议就是嵌在网页头部的一些标签，这些标签标记了网页的标题、描述等特征，使得网页成为一个“富媒体对象”，可以被其他社交网站引用。

很多搜索引擎都支持OG协议，在网页中使用OG协议的标签，就更有利于提升我们的网页在搜索引擎中的排名。

OG协议的标签在网页中通常表示为类似下面所示的格式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<meta property="og:title" content="The Rock" />
<meta property="og:type" content="video.movie" />
<meta property="og:url" content="https://www.imdb.com/title/tt0117500/" />
<meta property="og:image" content="https://ia.media-imdb.com/images/rock.jpg" />

<meta property='og:url' content='https://arlettebrook.github.io/search/'>
 <meta property='og:site_name' content='Arlettebrook&#39;s blog'>
 <meta property='og:type' content='article'><meta property='article:section' content='P
age' />
-<meta name="twitter:title" content="搜索">
+<meta name="twitter:site" content="@arlettebrook">
+    <meta name="twitter:creator" content="@arlettebrook"><meta name="twitter:title" co
ntent="搜索">
 <meta name="twitter:description" content=""><link rel="alternate" type="application/js
on" href="https://arlettebrook.github.io/search/index.json">
     <link rel="shortcut icon" href="/img/favicon.ico" />

stack主题提供了对OG协议的支持，只需要在网站根目录下的config/_default/params.en.yaml和config/_default/params.zh-cn.yaml配置文件中开启即可：

1
2
3
4
5
6
7
opengraph:
    twitter:
        # Your Twitter username
        site: arlettebrook

        # Available values: summary, summary_large_image
        card: summary_large_image

这样，Hugo在生成和部署网站时就会在网页HTML文件中自动嵌入OG标签。

谷歌搜索优化

在将我们的站点信息提交给谷歌时，谷歌需要验证我们对网站的所有权。验证方式有好几种，例如

在网站根目录下放一个谷歌生成的验证文件
在网页HTML文件头部嵌入谷歌生成的特定标签
使用谷歌分析的Tracking ID（或者Measurement ID）

由于stack主题集成了对谷歌分析的支持，这里我们使用第三种验证方式。

开启谷歌分析

谷歌分析（Google Analytics）是一个分析网站流量的工具，用它可以统计网站的访问量等信息。

首先前往谷歌分析官网注册谷歌分析的账号，也可以直接用已有的谷歌账号登录。现在的谷歌分析一般是谷歌分析4（Google Analytics 4），使用Measurement ID而非之前的Tracking ID来跟踪网站。
参考：谷歌分析（Google Analytics）最新使用教程
获取Measurement ID。具体可参见谷歌分析的帮助文档。下面是具体操作：
- 在用户首页找到“Admin“选项，新建一个“Property”，按照说明填入必要的信息。
- 然后点击“Property”这一列中的“Data Streams”选项。
- 点击“Add stream”，选择“Web”，填入你的网站域名和网站名字。
- 再在“Property”页面点击刚添加的stream，就能看到一个以“G-”开头的Measurement ID。记录下你的网站的Measurement ID。
在网站根目录下的config/_default/config.yaml配置文件中找到“googleAnalytics"配置项，填入你的Measurement ID。
1 2
# GA Tracking ID googleAnalytics: G-measuremntID

提交站点地图

站点地图（Site Map）是一个存储有站点网页信息的XML数据文件，通常命名为sitemap.xml，将它提交给搜索引擎，搜索引擎将可以获取我们网站的网页信息。

Hugo会在生成和部署网站时在public文件夹下自动生成sitemap.xml文件。

我们把站点地图提交到谷歌搜索，具体说明可参见谷歌站长页面的说明，下面是具体操作：

登录谷歌搜索控制台（Google Search Console）https://search.google.com/search-console，可以使用在谷歌分析注册的账号。
点击左上角的“Add property”，选择右侧的“URL prefix”方式，输入以https开头的网站网址。在验证所有权的选项中选择“Google Analytics”，点击验证。如果你在上一步开启谷歌分析后使用Hugo重新部署了网站的话，就可以直接验证通过。
提交站点地图文件sitemap.xml。在左侧菜单栏点击“Sitemaps”选项，然后在添加站点地图的页面填入sitemap.xml所在的URL。例如对于本站，由于是双语站点，Hugo在部署网站时会生成3个sitemap.xml文件，分别是/public/sitemap.xml、/public/zh-cn/sitemap.xml以及/public/en/sitemap.xml。
注意，添加sitemap时不要漏了路径开头的斜杠/，即使网站域名后面已经有一个斜杠了，也不能省略。
提交成功之后“status”会显示“success”。
Hugo生成的3个站点地图中，/public/sitemap.xml中的内容其实是指向/public/zh-cn/sitemap.xml和/public/en/sitemap.xml的，所以我们只提交一个/public/sitemap.xml就可以。

一般在站点地图成功提交之后大约1到2天后，就可以看到自己的网站已经被谷歌收录了。可以在谷歌搜索框中输入site:xxx.com来查看某个网站是否被谷歌搜索收录。

百度搜索优化

针对百度搜索的优化是在百度资源搜索平台上完成的。

前往百度资源搜索平台，登录百度账号。
点击“链接提交”，然后点击"添加站点"。输入你的网站域名，同样需要验证站点的所有权，这里选择下载验证文件，然后把验证文件放在网站static文件夹内，在上传到Github。最后点击“验证”即可。
然后点击左侧菜单栏“资源提交”中的“普通收录”，在资源提交的页面下选择“sitemap”，输入sitemap.xml所在的URL就可以了。
不过在百度提交sitemap有两个限制：
- 不允许提交索引型sitemap
- 对新账号每天只允许提交一个sitemap文件

其他平台收录

其他平台收录就不仔细讲解了，提供一下链接供大家参考。都差不多一样的验证方式。

搜狗收录
搜狗收录不支持站点地图提交，需要你列出所有的url批量提交，每次提交20条，所以没有其他平台那么智能。每次新加新的网页还需要自己主动提交。
搜狗搜索资源平台
Bing收录
Microsoft Bing Webmaster Tools
360提交入口： https://info.so.com/site_submit.html
Backdata 搜索引擎网址提交入口： https://backdata.net/submit-site.html

参考：
个人网站的建立过程（四）：网站的搜索引擎优化（SEO）
从零开始搭建个人博客网站系列五、让搜索引擎收录你的个人博客网站

额外的一些知识

gh-pages 是GitHub 所提供的一个服务，简单来讲就是可以让你不用花钱也可以部署一个静态网页作为展示用，因此对于前端工程师来讲就非常方便而且很实用，但是部署方式有很多。
gh-pages是github-pages的缩写，可以用于个人博客和项目介绍的网站服务。
gh-pages也是github特殊的分支，用来存放网站相关的一些资源，通常网站地址为username.github.io/仓库名
项目名与username.github.io一样的话，可以省略仓库名，跟github个人资料页面一样，所以这个仓库是一个特殊的仓库，默认会自动开启gh-pages服务。别的需要手动。

虽然gh-pages 是属于免费的服务，基本上只要你持有GitHub 帐号就可以使用，但是它基本上有几个重点可以稍微注意一下：

只能放置纯静态网页，也就是说没有后端的网页，例如PHP、Node.js、Python 等等，只能是纯HTML、CSS、JavaScript 等等，因为它并没有运算能力。
gh-pages 是以储存库为单位，也就是说每个储存库都可以有一个gh-pages 分支，但是每个储存库只能有一个gh-pages 分支，因此如果你想要部署多个网页，那么你就需要建立多个储存库。
gh-pages 的容量是有限制的，每个储存库的容量是1GB，如果你的网页超过这个容量，那么就无法部署。
gh-pages 的流量为每月100GB
gh-pages 每小时只能部署10 次，如果是使用自己写的GitHub Actions 就没有这个限制（毕竟要花钱）。
免费的ssh 凭证
预设的网域是https://<username>.github.io/<repository>，如果你想要使用自己的网域，那么你就需要花钱购买网域，并且设定DNS

最后要稍微注意一下gh-pages 虽然是免费提供的静态网页托管服务，但是它并不能拿来作为商业用途或是违法用途，否则你的帐号可能会被封锁

简单说一下如何查看一个仓库是否启用gh-pages：进入项目settings-pages查看即可，有绿色钩就启动成功，没有需要指定分支和根目录，保存，稍等一会就行。

用gh-pages分支展示自己的项目

我们只需要将网页资源上传至gh-pages分支即可

搭建项目网站：将项目网站资源推送到gh-pages分支上,静态资源必须提交了才会成功

1
git subtree push --prefix=dist origin gh-pages # dist为项目网站的目录

拉取指定分支

1
2
3
4
5
6
7
8
git fetch origin # 获取origin仓库的信息
git checkout -b aaa origin/aaa # 创建并检出分支

# git clone之后也也可以检出分支
git checkout gh-page  # 失败用上面办法

# 在git clone 的时候可以指定分支-b选项
git clone -b url

如果要项目中不含自己网站的源码，可以忽略public目录，将public目录创建为一个私有仓库的子目录，然后将子目录作为，项目的gh-pages分支。

通过GitHub Actions自动部署gh-pages

简单介绍一下GitHub Actions:
GitHub Actions是一个自动化工具。
可以实现自动化构建、测试、和部署项目。
定义自动化过程是通过编写workflows（工作流）实现的，格式是yaml。

推送部署的github-pages需要git账户认证，方式是SSH秘钥认证。
所以需要设置ssh秘钥。
1. 生成秘钥：在bash中运行ssh-keygen,秘钥类型默认为rsa。可以给这个秘钥设置备注加-C选项，参数一般为拥有者邮箱，一直回车就行。秘钥保存位置：默认用户主目录下的.ssh。公钥就是id_rsa.pub
  1. 建议将生成的这个秘钥对与本机认证的ssh秘钥对分开，保存到另外的一个地方。回车的时候修改位置就行。
2. 设置公钥：
  1. github账户Settings->SSH and GPG keys->New SSH key将公钥复制粘贴保存就行。这种方式，只有有私钥，就能操作所有仓库，不推荐使用。
  2. (自动构建之后)选择要推送的仓库Settings->Deploy keys->Add deploy key将公钥复制粘贴保存就行。title随意。注意勾选Allow write access。只针对该仓库有权限。推荐使用。
3. 设置私钥：
  1. 进入Actions所在的仓库Settings->Secrets and variables->Actions->New repository secret。秘钥名称为ACTIONS_DEPLOY_KEY，值为私钥id_rsa的文件内容。最后保存就行。

添加workflows配置文件

在构建仓库的根目录下创建.github/workflows目录，然后创建auto-deploy-gh-pages.yaml文件，内容如下：

 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
name: Deploy github pages

on:
    push:
        branches:
            - main # main 更新触发
    # Allows you to run this workflow manually from the Actions tab
    workflow_dispatch:

jobs:
    auto-deploy-github-pages:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout code
              uses: actions/checkout@v4
              with:
                  submodules: true # clone submodules
                  fetch-depth: 0 # 克隆所有历史信息

            - name: Setup Hugo
              uses: peaceiris/actions-hugo@v3
              with:
                  hugo-version: "0.125.4" # Hugo 版本
                  extended: true # hugo插件版 Stack主题 必须启用

            - name: Cache resources # 缓存 resource 文件加快生成速度
              uses: actions/cache@v4
              with:
                  path: resources
                  # 检查照片文件变化
                  key: ${{ runner.os }}-hugocache-${{ hashFiles('content/**/*') }}
                  restore-keys: ${{ runner.os }}-hugocache-

            - name: Build # 生成网页 删除无用 resource 文件 削减空行
              run: hugo --minify --gc

            - name: Deploy # 部署到 GitHub Page
              uses: peaceiris/actions-gh-pages@v3
              with:
                  # 如果在同一个仓库下使用请使用 github_token 并注释 deploy_key
                  # github_token: ${{ secrets.GITHUB_TOKEN }}
                  deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}

                  # 如果在同一个仓库请注释
                  external_repository: arlettebrook/arlettebrook.github.io # 你的 GitHub page 仓库 example/example.github.io

                  publish_branch: main # 默认gh-pages
                  # cname: blog.trojan123.top # 自定义域名
                  publish_dir: ./public
                  user_name: "github-actions[bot]"
                  user_email: "github-actions[bot]@users.noreply.github.com"
                  # full_commit_message: ${{ github.event.head_commit.message }} # 不带提交哈希
                  # full_commit_message: Deploy from ${{ github.repository }}@${{ github.sha }} 🚀
                  commit_message: ${{ github.event.head_commit.message }}🚀 # 带提交哈希
                  # full_commit_message: Deploy from ${{ github.repository }}@${{ github.sha }}🚀 ${{ github.event.head_commit.message }}

注意你要将external_repository项里的arlettebrook/arlettebrook.github.io改为你要推送的仓库。cname为你绑定的自定义域名。

忽略不必要的文件
1. 在构建项目根目录下创建.gitignore文件，内容如下：
  1 2 3 4
  public resources assets/jsconfig.json .hugo_build.lock
最后将构建项目推送到远程就行，这样每次推送构建项目的main分支到远程，就会自动构建并推送到指定仓库。
查看是否构建成功：进入构建项目的Actions选项里面即可查看。

参考：（2）部署你的Hugo博客