Hello, Typo!

基于Hugo框架与Typo主题，从环境搭建、主题配置到自动化部署，记录个人博客的搭建流程

zhihang

2023 Oct 4 · 2 min read

#探索 #博客

一切都源于在论坛上看到了一个简洁的博客主题，一个以内容为上的博客主题。看到的那一刻就默默在笔记上记下了一个TODO: 搭建一个博客。

在看到typo之前，没想过搭建一个个人博客，想着有一个本地化的笔记内容已经够了。加上在网上冲浪，看到的无数个已经被遗忘在互联网的角落里蒙灰的博客。我想，凭我的精力很难一直有内容产出。所以我的博客计划搁置了一段时间。

但我后来想了想，正是这些蒙灰的博客，才真的帮到过我。可能内容简单，甚至有些简陋，但偏偏就是他们记录下了某个冷门问题的解决过程，或者某一步的细节，让我得以顺利过关。

反过来看，这也是它们存在的意义吧。博客不一定要有多少更新、多少阅读量、有多么高大上，只要在某个时刻它帮到了某个人，那它就很有价值。所以，看似被遗忘的内容，其实都还藏着被再次发现和利用的可能——我自己就是这样真实受益的那个人。

下面记录我搭建这个博客的过程吧。

工作主流程 #

笔记软件: Obsidian
框架: Hugo
主题: typo:
远程同步: Git
渲染 & 发布: Github Action & Github Page
Dns 托管: Cloudflare

搭建步骤 #

Hugo #

像我这样先选了主题，再了解博客框架的人应该不多吧。Hugo 是一个使用 Go 语言编写的静态网站生成器，以其高性能、易用性和灵活性而广受欢迎。可以把 Markdown 文件转化成 HTML 文件。但是静态博客也有缺点，维护难，可扩展性较弱，上手门槛高，希望我能坚持下去吧。

Hugo下载安装 #

首先在 Release 根据操作系统以及指令集下载最新版本的 Hugo 压缩包 Windows 则选择例如: hugo_0.148.1_windows-amd64.zip
选择合适的路径进行解压
添加环境变量，在搜索框搜索环境变量，根据解压路径配置hugo.exe所在的路径到PATH
打开一个终端，输入hugo version验证

初始化Hugo结构 #

使用 hugo new site xxxx创建网站初始结构。初始结构如下：

archetypes：存放用 hugo 命令新建的 Markdown 文件应用的 front matter 模版
content：存放内容页面，比如「博客」、「读书笔记」等
layouts：存放定义网站的样式，写在layouts文件下的样式会覆盖安装的主题中的 layouts文件同名的样式
static：存放所有静态文件，如图片
data：存放创建站点时 Hugo 使用的其他数据
public：存放 Hugo 生成的静态网页
themes：存放主题文件
config.toml：网站配置文件

Typo #

正像github上介绍的，Typo 是一个以简洁为基础的主题。目标是创建一个以内容为中心，没有任何其他多余内容的网站。直观感受是具有纯粹的阅读体验。

Typo主题配置 #

不同主题一般都在相应的wiki中给出了配置指南。按照流程配置即可。需要格外注意的是，建议直接使用主题给出的hugo.toml 配置文件作为基础，在这个基础之上进行配置可以避免一些奇怪的问题。

本地测试 #

到这一步即可进行本地测试，在博客主文件夹下运行命令:

hugo server -D

再打开输出的网址即可

工作流搭建 #

创建 2 个 GitHub 仓库
- 博客源仓库：储存所有 Markdown 源文件（博客内容），和博客中用到的图片等。
- GitHub Pages 仓库：储存由 Hugo 从Markdown 文件生成的 HTML 文件。
将在博客源仓库中 Hugo 生成的静态 HTML 文件部署到 GitHub Pages 仓库中。

我学习替他博主的思路。我将博客源码存放到一个private repo里。但也可以将源码直接放到github pages repo中（只需要单独一个远程仓库即可），但这样其他人能获取文章的源文件。

创建博客源仓库 #

命名博客源仓库（whatever you want）
勾选 Private，设置为私有仓库。

创建 GitHub Page 仓库 #

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

添加CNAME文件到static/文件夹（使用自定义域名的额外步骤） #

如果选择为Github Pages使用自定义域名，则这个步骤必须要做，否则自定义域名会隔三差五失效。

原因在于，当在YOUR_NAME.github.io这个仓库的设置里手动添加自定义域名的时候，其实是在github仓库新增了一个CNAME文件，里面内容为自定义域名。

但是每次推送触发actions后，hugo命令都会生成一个全新的public文件夹并强制覆盖到page仓库。这个操作都会覆盖掉github上的CNAME，导致域名失效。

在 hugo 构建网站时，它会把 static 文件夹里的所有内容，原封不动地、完整地复制到最终生成的 public 文件夹的根目录下。所以在static文件夹下添加一个CNAME文件即可。

推送到博客源仓库 #

创建gitignore文件

# Hugo
public/
.hugo_build.lock

推送到远程仓库

# === 项目初始化与首次提交 ===
echo "# my-blog-source" >> README.md
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/xxx/xxx.git
git push -u origin main

自动发布内容 #

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

生成Actions secrets #

生成Personal access tokens 首先点击github头像在下拉栏里进入Setting->Developer Settings->Personal access tokens -> tokens (classic)
选择Generate new token，点击Generate token生成token，并先复制保存该token。(这个token只有显示一次，所以一定要复制保存)
生成Actions secrets 接下来在源码repo中添加上面的personal access token：

进入repo的Settings->Secrets and variable一栏，选择New repository secret

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

配置actions文件 #

在repo根目录新建嵌套的两个文件夹.github/workflows

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

写进去以下配置（从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

      - 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: 用户名/page仓库名	# 发布到哪个repo
          personal_token: ${{ secrets.token名 }}	# 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public	# 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: main	# 发布到哪个branch

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

至此，折腾了半天的自动化流程，总算是搭建完成了。

现在，我终于可以再关心部署的流程细节，把精力放回到最初的目的上——去记录，去成为那些曾经帮助过我的、‘蒙灰的博客’中的一员。

也许我的文章也会很简单，甚至有些简陋，也可能会在未来的某个时刻被遗忘在角落里。但只要它能在某个时刻，帮到某个卡在同样问题上的人，让他得以顺利过关，那这一切的折腾就都值了。

Hello, Typo！