本文章没有找到对应的语言版本

前言

由于自己老是喜欢在往上捣鼓一些东西，于是打算搭建一个博客记录一下自己的学习经历，希望这些经历能对你有帮助。因为个人财力有限，没法持久的买服务器，所以就想到了Github Pages，部署的过程还是能学到很多知识的。

GitHub Pages 是一种静态网站托管方案。它会直接从你的 GitHub 仓库抓取 HTML, CSS 及 JavaScript 文件，可以选择性地通过构建流程处理这些文件，最后将成果发布成一个在线网站。

准备工作

  • 一个Github账号，这不是废话吗
  • 一个文本编辑器（如VSCode，当然，记事本也可以）
  • 一个域名（可选），如果有域名，将其指向 Github Pages，能够不用代理访问你的博客

一、概念和搭建思路

什么是 Hugo ？

Hugo 这个工具是用 Go 语言写的，属于静态网站生成器类别，它可以帮你把 Markdown 文档转化为可在浏览器中查看的 HTML 页面。

博客搭建思路

  1. 创建2个 Github 仓库

  • 博客源仓库：用于存储所有博客内容（Markdown源文件），博客要用的视频、图片也可以。

  • Github Pages仓库：用于存储Hugo从Markdown文件生成的HTML文件。

  1. 把 Hugo 在博客源里生成的 HTML 网页文件，传到专门用来展示网页的 GitHub Pages 仓库 里去。

二、创建 Github 仓库

创建博客源仓库

  1. 登录 Github，点击右上角的「 + ∨ 」按钮，选择「 New repository 」。

  2. 在「 Repository name 」输入框中输入你的仓库名称（什么名字都可以）。

  3. 选✓ Private，设置其为私有仓库。

  4. 勾选✓添加 README 文件。

这个博客源仓库的作用是可以存储你的博客源码，防止别人获取到你的文章源文件。当然，如果你不介意，你也可以将源码放到 GitHub Pages 仓库 里去。

  1. 点击「 Create repository 」按钮，创建你的 Github 仓库。

创建仓库

创建 GitHub Pages 仓库

  1. 登录 Github，点击右上角的「 + ∨ 」按钮，选择「 New repository 」。

  2. 在「 Repository name 」输入框中输入你的仓库名称，格式为 <username>.github.io，其中 <username> 是你的 Github 用户名。

  3. 勾选✓ Public，设置其为公开仓库。

  4. 勾选✓添加 README 文件，这样做是为了将 main 分支自动设为仓库的默认主分支，这对于后续向仓库推送博客内容的操作非常重要。

  5. 点击「 Create repository 」按钮，创建你的 Github 仓库。

创建仓库

三、克隆博客源仓库到本地

  1. 打开想在本地存储博客的文件夹（我的是Blog），然后在目录输入 cmd 进入终端（或者直接在终端 cd ）
cd Blog
  1. 克隆博客源仓库到项目文件夹，克隆时使用的 HTTPS 仓库链接在这里查看：

克隆仓库

git clone https://github.com/<username>/Blog.git

四、本地安装 Hugo

  1. 前往 Hugo 的官方Github仓库 release，选择对应的版本进行下载，这里我用 Windows 举例，选择hugo_extended_0.147.8_windows-amd64.zip下载。
gohugoio/hugo
gohugoio/hugo
https://github.com/gohugoio/hugo

  1. 解压hugo_extended_0.147.8_windows-amd64.zip，放在你自己觉得合适的位置，比如D:\hugo

  2. 接下来，找到 hugo.exe 文件所在的文件夹，并将这个文件夹的路径（而不是 hugo.exe 文件本身的完整路径）添加到系统的环境变量 PATH 中。

如果不知道从哪里添加，右键计算机，高级系统设置，环境变量，选择PATH，点击编辑，然后新建，填入文件夹路径

环境变量配置

  1. 添加好变量后，可以输入以下指令验证是否成功安装 Hugo
hugo version

如果安装成功，会显示 Hugo 的版本信息。

安装检测

五、使用 Hugo 创建网站

  1. 首先，你需要将当前工作目录切换到刚才克隆的博客源仓库文件夹（例如，直接在你那个文件夹路径那里输入 cmd ）。然后，在这个特定的文件夹里运行 Hugo 命令，目的是生成一个新的网站文件夹。
hugo new site Blog
  1. 用 Hugo 创建的网站共有 7 个文件夹和 1 个文件，介绍一下 Hugo 的目录结构，以下就是站点根目录。

创建网站

.
├─ archetypes         # 存放文章的模板文件
├─ assets             # 存放静态资源文件
├─ content            # 存放文章的目录
├─ i18n               # 存放国际化文件的目录
├─ data               # 存放数据文件的目录
├─ layouts            # 存放布局文件的目录
├─ static             # 存放静态文件的目录
├─ themes             # 存放主题的目录
└─ hugo.toml          # 站点配置文件

六、安装和配置 Hugo 主题

选择 Hugo 主题

可以从 Hugo Themes 选择一个主题应用于自己的博客。

安装 Hugo 主题

  1. 一般来说，在你选择的主题的文档中，会附上「如何安装」的命令，比如我选择的 reimu 的文档中给出
git init
git submodule add https://github.com/D-Sketon/hugo-theme-reimu.git themes/reimu

  1. 打开刚刚用 Hugo 创建的网站文件夹（按照我刚刚的命令执行的话就是 Blog ），在这打开终端，执行文档中给出的命令。

  2. 执行成功后，可以看到在 themes 文件夹中，多出来了刚刚安装的主题文件，说明了你主题安装成功了。

主题安装

需要注意的是：有部分主题会要求安装 extended 版本的 Hugo ，这时候你需要到Hugo的仓库下载名字带有 extended 的文件，比如 hugo_extended_withdeploy_0.147.8_windows-amd64.zip ，然后替换掉之前下载的 Hugo.exe

配置 Hugo 主题

  1. 当你安装 Hugo 主题时，通常会发现一个名字带有 example（或是 content ） 的文件夹。这个文件夹实际上是一个完整的演示网站，旨在为你展示主题的实际效果和配置方法，方便你作为参考。

  2. 将名字带有 example 的文件夹里面的所有文件，全部复制到你博客的根目录中的 content 中，在此基础上进行配置。

我强烈建议你采取这种做法。它能有效消除许多「为什么我明明跟着教程一步步操作，但最终显示效果却大相径庭？」的困惑。这通常是由于不同主题的模板配置文件存在差异所致。

  1. 将主题目录的 config 文件夹拷贝到你博客的根目录，这里面会有你博客网站的详细设置，具体设置参考主题的文档。

  2. 将主题目录的 archetypes 文件夹拷贝到你博客的根目录，这是用命令创建 Markdown 文件时的模板。

  3. 打开你根目录的 hugo.toml ，修改其中的内容：

  • baseURL
baseURL = "https://example.com/" #把https://example.com/改成自己的域名

当你的 GitHub Pages 尚未配置自定义域名时，你需要填写的域名就是 https://<username>.github.io/。

切记：末尾的斜杠 / 务必不能遗漏。

  • themes
themes = "你选择的主题名字"。 #这一行命令代表启用你安装的主题

在 hugo.toml 输入这条命令才能启用主题。

七、用 Hugo 创建你的第一篇文章

用 Hugo 创建文章的命令是

hugo new xxx.md

当你使用此命令创建 Markdown 文件时，它会自动应用 archetypes 文件夹中定义的前置元数据（front matter）模板。你只需在文件主体部分的空白处，用 Markdown 语法撰写你的文章内容即可。

请注意，如果模板中包含 draft: true，则表示该文章被标记为草稿，Hugo 在生成网站时不会将其显示。若要使你的文章在网站主页上可见，你需要将 draft: true 修改为 draft: false，或者直接移除 draft: true 这一行。

八、本地调试、预览

  1. 在正式发布网站之前，你可以在本地环境中预览网站或内容的效果。只需运行命令：
hugo server

  1. 更棒的是，当你本地编辑 Markdown 文件时，hugo server 也能提供实时的显示效果预览。

  2. 命令成功运行后，你可以在浏览器中访问 http://localhost:1313/ 来查看你的网站。

九、发布博客

使用 Github Actions 功能实现提交源码后自动发布。

生成 Actions secret

  1. 要生成 Personal access tokens ，首先点击 github 头像，进入 Setting -> Developer Settings -> Personal access tokens -> tokens (classic)

tokens

  1. 选择 Generate new token (classic) ，Expiration 选择 No expiration ，权限要勾上 rego 和 admin:repo_hook 。然后点 Generate token 生成，一定要马上复制保存此 token ，他只会显示一次。

tokens

  1. 接下来在博客源仓库的 setting 中，进入 Secrets and variable->Actions ，选择 New repository secret ，名字自取， Secret 填上刚刚生成的 Personal access tokens 。

tokens

tokens

配置 Actions 文件

在你博客源根目录新建嵌套的两个文件夹：.github/workflows

在 workflows 里新建一个后缀为 .yml 的配置文件，名字随意。

Actions

写进去以下配置（从 hugo 官方文档修改而来）：

name: github pages # 名字自取

on:
  push:
    branches:
      - main  # 这里的意思是当 main分支发生push的时候，运行下面的jobs，这里先改为github-actions

jobs:
  deploy: # 任务名自取
    runs-on: ubuntu-latest	# 在什么环境运行任务
    steps:
      - uses: actions/checkout@v2	# 引用actions/checkout这个action，与所在的github仓库同名
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive) 获取submodule主题
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo	# 步骤名自取
        uses: peaceiris/actions-hugo@v2	# hugo官方提供的action，用于在任务环境中获取hugo
        with:
          hugo-version: 'latest'	# 获取最新版本的hugo
          # extended: true  如果你的安装了extended的hugo，务必要把注释取消

      - name: Build
        run: hugo --minify	# 使用hugo构建静态网页

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3	# 一个自动发布github pages的action
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          external_repository: <username>/<username>.github.io	# 发布到哪个repo
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}	# 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public	# 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: main	# 发布到哪个branch

.yml文件中，你只需要把 external_repository 改为你自己的 Github Pages 仓库，personal_token: ${{ secrets.XXX }} XXX改成上面生成 Actions secrets 步骤中取得名称。（注意：是名称而不是 token ）

我要提醒的是，如果你的主题要求你安装了 extended 版本的 hugo ，你要取消 extended 那一行的注释！

推送代码到博客源仓库

  1. 首先，你需要将 BlogSource 文件夹初始化为一个 Git 仓库，并直接指定其默认主分支为 main。这通过命令
git init -b main

来实现。之所以这样做，是因为 GitHub 在创建新仓库时默认生成的主分支是 main，而 git init 命令默认创建的却是 master 分支。为了避免将 master 分支推送到远程的 main 分支时可能引发的错误或不必要的重命名操作，我们推荐一开始就统一分支名为 main。

  1. 接下来，你需要将本地生成的 public 文件夹（其中包含了 Hugo 编译后的静态网站文件）与远程的博客源仓库关联起来。请使用该博客源仓库的 SSH 链接，执行命令
git remote add origin [email protected]:<username>/Blog.git。
  1. 关联完成后，就可以将本地文件推送到博客源仓库了。请按照以下步骤操作：
git pull --rebase origin main  #首先拉取远程仓库的最新更改并进行变基，以确保本地分支与远程同步。
git add .  #将所有修改过的文件添加到 Git 暂存区。
git commit -m "...(修改的信息)"  #提交暂存区的文件，并附上本次提交的描述信息。
git push origin main  #将本地 main 分支的提交推送到远程仓库。

成功推送后，访问你的博客源仓库，在“ Actions ”选项卡中，你将看到工作流（ runs ）已成功运行。这意味着你的 GitHub Pages 仓库现在已经包含了由 Hugo 生成的 HTML 文件。随后，你就可以通过 https://<username>.github.io 访问你的博客了。

如果你在 push 的时候遇到了 port 22 报错，可以在你的 C:\Users\username.ssh 文件夹里面，编辑 config ，在末尾添加

Host github.com
  Hostname ssh.github.com
  Port 443
  User git

使用 443 端口来连接。

十、Reference

说些什么吧！

twikoo