Mac下使用hugo和GithubPages搭建个人博客

序章

一直想用博客的形式记录自己的生活、工作、学习的点滴，从2018年开始用Hexo+NEXT写博客上传到GitHub，后来又断断续续的写了一段时间就荒废了。从今年4月开始看着朋友的博客写的有声有色，除了想用博客来记录之外，觉得自己还是需要将所学的东西沉淀下来，有一个回顾的平台，希望博客能为可能遇到同样问题网友提供帮助。
在准备搭建博客之初，想过很多的方案，想过购买云主机、CloudFlare Works、Github Page等方案，最后综合考虑博客是一个自己记录滴滴地方，个人觉得发布到GitHub比较省心，选择了用Github Page来承载博客，方案采用Hugo来生成静态博客，因为Hugo实在太省心了，不会向Hexo方案那样因为node.js导致的各种错误头大，主题采用简约风格的PaperMod。

一、概念及思路

1、什么是GitHub Pages

GitHub Pages 是一项静态站点托管服务，只能托管静态站点，不能运行服务器端源码，比如 PHP、Java、Python等。它可以直接从 GitHub 上的仓库获取 HTML、CSS 和 JavaScript 文件，通过构建过程运行文件，然后发布网站。

2、什么是Hugo

Hugo是由Go语言实现的静态网站生成器，可以把 Markdown 文件转化成 HTML 文件，简单、易用、高效、易扩展、快速部署。

3、博客搭建思路

3.1 需要创建 3个 GitHub 仓库

这里先建好3个仓库，方便后面将博客内容推送到GitHub

博客源仓库：储存所有 Markdown 源文件（博客内容），和博客中用到的图片等。
GitHub Pages 仓库：储存由 Hugo 从Markdown 文件生成的 HTML 文件。
图片仓库：用来存储博客正文中所用到的图片，下一篇搭建图床的文章将介绍。

3.2 推送到GitHub pages

将在博客源仓库中 Hugo 生成的静态 HTML文件推送到远端 GitHub Pages仓库中。

二、创建GitHub仓库

1、创建博客源文件仓库

仓库名可以随意取
勾选 Pricate，设置为私有仓库，这样设置能很好的保护自己的源码文件。
勾选添加 README 文件。

2、创建 GitHub Page 仓库

这个仓库必须使用特殊的命名格式 <username.github.io>， <username> 是自己的 GitHub 的用户名。
勾选 Public，设置为公开仓库。
勾选添加 README 文件。

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

之前从安装hugo，到配置主题papermod，发布测试文章到GitHub，流程全部走通了，只是部分功能需要自己去配置。后来发现已经有很多大佬公开了他们的博客文件，就直接去git clone下来部署，后续再根据自己的需要进行调整，这样会节省很多时间，少踩很多坑。

1、克隆已经开源的博客到本地

1.1 这里我选择的是Sulv题主的开源博客进行部署，打开想要在本地储存项目的文件夹（比如我的项目的文件夹是 Project ）

cd Project

1.2 克隆博客仓库到项目文件夹，克隆时使用的 HTTPS 仓库链接

git clone git@github.com:xyming108/sulv-hugo-papermod.git
# 拉取下来解压是sulv-hugo-papermod文件夹，可以重命名为自己喜欢的名字（BlogSoure）
cd BlogSoure
git submodule update --init # 表示拉取themes/hugo-PaperMod/下的子模块，里面放的是官方主题

1.3 删除Blog、Public文件下的git文件，这里是原作者的信息，不然推送到自己的GitHub会报错

rm -rf .git

四、Mac环境下需要的软件

1、安装包管理器Homebrew

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2、安装Hugo

brew install hugo

3、安装git环境

# git环境，Mac下若安装了开发者环境会带有git，没有的话参考以下方式进行安装
brew install git

五、使用 Hugo 创建博客站点

1、进入刚刚克隆下来的重命名为Blog的文件夹。

cd BlogSoure

2、在这个文件夹里用 Hugo 创建一个博客网站文件夹。

hugo new site myblog

3、用 Hugo 创建的网站共会生成一些文件夹文件。

archetypes：存放用 hugo 生成文章的模版
content：存放博客内容页面
layouts：存放自定义网站样式
static：存放静态文件图片等
data：存放其他数据
public：存放Hugo 生成的静态文件
themes：存放主题
config.toml：网站配置文件，建议改成config.yml格式，这样方便阅读与编辑

4、使用Hugo创建一篇文章，目录沿用开源博客目录，后期可以自己修改。

hugo new posts/blog/xx.md

创建的 Markdown 文件时会套用 archetypes 文件夹中的模版，在空白处用 Markdown 写入文章即可。

5、启动博客生成静态文件，用以下命令表示每次生成的public文件都是全新的。

hugo -F --cleanDestinationDir

进行本地调试

hugo server -D

运行成功后，可以在 http://localhost:1313/ 中预览博客内容

六、在Mac上设置GitHub SSH Key

1、生成 SSH Key

1、点开 GitHub账号头像下的 Settings

2、找到 Settings 下的 SSH and GPG keys，点击 generating SSH keys。

3、在下一步中选择 Generating a new SSH key and adding it to the ssh-agent

4、选择Mac操作系统，往下滑动页面会看到 GitHub 给出的 Mac下生成SSH Key的方法。

5、打开终端，复制粘贴以命令到终端，把 your_email@example.com 替换成你注册 GitHub 时使用的邮箱。

ssh-keygen -t ed25519 -C "your_email@example.com"

6、一直按 Enter 直到出现以下画面。

7、SSH Key 已经生成成功，接下来把生成的 SSH Key 添加到 ssh-agent。

2、添加 SSH Key 到 ssh-agent

1、在终端（Terminal）中输入命令，执行完成后终端会给出Agent pid

eval "$(ssh-agent -s)"

2、如果是 macOS Siera 10.12.2 或以上的版本，需要修改 ~/.ssh/config 文件来自动加载密钥到 ssh-agent 和储存 passphrases 到你的钥匙链。

检查电脑中是否存在 ~/.ssh/config 文件

open ~/.ssh/config

出现以下提示表示不存在该文件，需要创建。

touch ~/.ssh/config

3、用编辑器打开 ~/.ssh/config 文件

vim ~/.ssh/config

4、在编辑窗口按i建进入插入模式，把以下代码复制粘贴进去，按esc退出编辑模式，然后按住shift+冒号，输入wq，回车保存退出。

Host *
	AddKeysToAgent yes
	UseKeychain yes
	IdentityFile ~/.ssh/id_ed25519

5、将 SSH Key 添加到 ssh-agent。你使用的是 Mac Monterey(12.0)及以上版本，可以使用以下命令。

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

如果不是 Mac Monterey(12.0)及以上版本，请用以下命令。

ssh-add -K ~/.ssh/id_ed25519

6、出现 Identity added 即表示添加成功。

3、添加 SSH Key 到 GitHub

1、接着，输入以下命令， pbcopy 会复制 SSH Key 内容到剪贴板。

pbcopy < ~/.ssh/id_ed25519.pub

2、再次打开 GitHub Settings 下的 SSH and GPG Key ，点击 New SSH key

3、添加生成的 SSH Key 到 GitHub

在Title中给这个 SSH Key 命名
Key Type选择 Authentication Key
在Key中 Command+V 粘贴刚刚复制的 SSH Key
添加后点击 Add SSH Key

4、添加完成。

4、测试 SSH Key 是否添加成功

1、选择一个要用 SSH Key clone 的仓库，复制这个仓库的 SSH 链接。 2、在终端输入以下命令。

git clone [ssh-url]

3、clone 成功即代表 SSH Key 添加成功。

七、发布内容

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

1、生成Actions secrets

1.1 生成Personal access tokens 首先点击github头像在下拉栏里进入Setting->Developer Settings->Personal access tokens -> tokens (classic)

1.2 选择Generate new token

1.3 点击Generate token生成token，这个token只有显示一次，并先复制保存该token。

2、添加ersonal access token

接下来在blog1仓库源码repo中添加上面的personal access token，进入repo的Settings->Secrets and variable一栏，选择New repository secret。

名称自取，Secret复制上面生成的Personal access tokens。

3、配置actions文件

3.1 在my blog博客根目录新建嵌套的两个文件夹.github/workflows，在workflows里新建一个后缀为.yml的配置文件，名字随意。

将以下配置写进.yml文件里。

name: deploy # 名字自取

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

			- name: Build Web

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

  
			- name: Deploy Web

			  uses: peaceiris/actions-gh-pages@v3 # 一个自动发布github pages的action

			  with:

# github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo

				external_repository: h4m0r/h4m0r.github.io # 发布到哪个repo

				personal_token: ${{ secrets.PERSONAL_TOKEN }} # 发布到其他repo需要提供上面生成的personal access token

				publish_dir: ./public # 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容

				publish_branch: main # 发布到哪个branch

文件中只需要改external_repository为自己的github page仓库，personal_token: ${{ secrets.XXX }} XXX改成Actions secrets生成的名称。

4、推送代码到源码仓库

4.1 将myblog文件夹初始化为 Git 仓库，并设置默认主分支名为 main。GitHub 创建仓库默认主分支名是 main，用 git init 初始化成 main ，再推送给远端仓库，这样才不会报错。

git init -b main

4.2 将 public 文件夹关联远程 GitHub Pages 仓库。

 git remote add origin git@github.com:h4m0r/blog1.git

4.3 推送本地文件到远程仓库。

git pull --rebase origin main
git add .
git commit -m "...(修改的信息)"
git push origin main

推送完成之后，到github仓库中的Actions中就可以看到运行成功，github pages仓库就会有hugo生成的html文件了，然后你就可以通过 https://h4m0r.github.io 访问你的博客。

参考文章

1、Windows下使用hugo和Github Pages配置博客

2、如何用 GitHub Pages + Hugo 搭建个人博客

3、如何用 GitHub Pages + Hugo 搭建个人博客

4、hugo博客搭建 | PaperMod主题

序章#

一、概念及思路#

1、什么是GitHub Pages#

2、什么是Hugo#

3、博客搭建思路#

3.1 需要创建 3个 GitHub 仓库#

3.2 推送到GitHub pages#

二、创建GitHub仓库#

1、创建博客源文件仓库#

2、创建 GitHub Page 仓库#

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

1、克隆已经开源的博客到本地#

四、Mac环境下需要的软件#

1、安装包管理器Homebrew#

2、安装Hugo#

3、安装git环境#

五、 使用 Hugo 创建博客站点#

六、在Mac上设置GitHub SSH Key#

1、 生成 SSH Key#

2、添加 SSH Key 到 ssh-agent#

3、 添加 SSH Key 到 GitHub#

4、测试 SSH Key 是否添加成功#

七、发布内容#

1、生成Actions secrets#

2、添加ersonal access token#

3、配置actions文件#

4、推送代码到源码仓库#

参考文章#

序章