Robin's Blog
Go back

Hugo + Github Pages 搭建个人博客

Edit page

Hugo 是用 Go 实现的博客工具，采用 Markdown 进行文章编辑，自动生成静态站点文件，支持丰富的主题配置，也可以通过 js 嵌入像是评论系统等插件，高度定制化。除了 Hugo 外，还有 Gatsby、Jekyll、Hexo、Ghost 等选择，实现和使用都差不多，可以根据自己的偏好进行选择。

安装 Hugo

我使用的是 macOS，所以使用官方推荐的 homebrew 方式进行 hugo 程序的安装，其他系统也类似。

brew install hugo

完成后，使用以下命令进行验证：

hugo version

创建 Hugo 网站

通过上述命令安装 hugo 程序后，就可以通过 hugo new site 命令进行网站创建、配置与本地调试了。

hugo new site robin-site

创建完成后，根目录 robin-site 包含以下文件：

├── archetypes: default.md是生成博文的模版
├── assets       # 存放被 Hugo Pipes 处理的文件
├── content      # 存放markdown文件作为博文内容
├── data         # 存放 Hugo 处理的数据
├── layouts      # 存放布局文件
├── static       # 存放静态文件 图片 CSS JS文件
├── themes       # 存放不同的主题
└── config.toml  # 博客配置文件支持 JSON YAML TOML 三种格式配置文件

配置主题

当通过上文命令创建我们的站点后，需要进行主题配置，Hugo 社区有很丰富的主题，可以通过官网 Themes 菜单选择自己喜欢的风格，查看预览效果，选择后可以进入主题项目仓库，一般都会有很详细的安装及配置说明。

关联主题仓库

官方更推荐使用 git submodule 方式进行仓库链接，这样后续可以对主题的修改进行单独维护。

cd robin-site/
git init
git submodule add https://github.com/pseudoyu/pure themes/pure

然后在根目录下的 config.toml 文件中添加：

theme = "pure"

更新主题

如果是 clone 了其他人的博客项目进行修改，则需要用以下命令进行初始化：

git submodule update --init --recursive

如果需要同步主题仓库的最新修改：

git submodule update --remote

新建博文

完成后，可以通过 hugo new 命令发布新文章。

hugo new posts/test.md

这个命令会在 content 目录下建立 post 目录，并在 post 下生成 test.md 文件。博文的 front matter 里 draft 选项默认为 true，需要改为 false 才能发表博文，建议直接更改 archetypes 目录下的 default 文件，把 draft: true 改为 draft: false，这样生成的博文就是默认可以发表的。

本地预览

在本地编辑调试时可以通过 hugo server 命令进行本地实时调试预览，无须每次都重新生成。

hugo server -D

通过浏览器 http://localhost:1313/ 地址访问本地预览网页。

GitHub Pages 发布博客

Github Pages 是什么？

Github Pages 本质上是一个静态网站托管系统，你可以使用它为你的每一个仓库制作一个静态网页入口。

它有两种存在方式：

  1. 识别 master branch 根目录下的 README.md 或者 index.html
  2. 识别 master branch 的 /docs 目录下的 README.md 或者 index.html

实战操作：部署 Hugo 作为一个 Github Pages

第一步：创建一个 Github 仓库

Repository name 这里一定要填 [你的github帳號].github.io，像我的帳號是 jianzhnie，所以输入 jianzhnie.github.io。

第二步：创建新文章

hugo new posts/my-first-post.md

需要把 draft: true 修改成 draft: false 才可以上传这篇文章。

第三步：修改配置文件 config.toml

站点目录 config.toml 中 baseURL 要换成自己建立的仓库，如 baseURL = "https://jianzhnie.github.io/"。

第四步：构建站点

进入站点根目录下执行：

hugo

执行后，站点根目录下会生成一个 public 文件夹，该文件下的内容即Hugo生成的整个静态网站。

第五步：上传代码至 master

cd public
git init
git remote add origin https://github.com/jianzhnie/jianzhnie.github.io.git
git add .
git commit -m "init blog"
git push -u origin master

稍等几分钟即可通过域名访问博客站点了。

以后每次站点目录下执行 hugo 命令后，再到 public 下执行推送命令：

git add -A
git commit -m "update"
git push -u origin master

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

根据上面的教程，我们可以创建个人的博客网站，如 https://jianzhnie.github.io，这个网站一般是作为个人博客或者学术主页。如果我们还有其他项目需要展示，如项目文档，产品文档，学习笔记等，那这个主页就不够用了。

下面介绍用 Github 的 gh-pages 分支展示自己的项目。这利用了项目站点（即Project Pages）的方式。

以 deeplearning-notes 仓库为例：

# 新建 Hugo 站点
hugo new site project

# 新建笔记
hugo new posts/deeplearning.md

# 修改 config.toml 中的 baseURL
# baseURL = "https://jianzhnie.github.io/deeplearning-notes/"

# 构建
hugo

# 推送到 gh-pages 分支
cd public
git init
git remote add origin https://github.com/jianzhnie/jianzhnie.github.io.git
git checkout -b gh-pages
git add .
git commit -m "init"
git push -u --set-upstream origin gh-pages

Github Action 自动发布

通过上述命令我们可以手动发布静态文件，但还是有以下弊端：

  1. 发布步骤比较繁琐，本地调试后还需要切换到 public/ 目录进行上传
  2. 无法对博客 .md 源文件进行备份与版本管理

因此可以通过 GitHub Action 进行 CI 自动发布。配置在仓库目录 .github/workflows 下，以 .yml 为后缀：

name: deploy

on:
    push:
    workflow_dispatch:
    schedule:
        - cron: "0 0 * * *"

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v2
              with:
                  submodules: true
                  fetch-depth: 0

            - name: Setup Hugo
              uses: peaceiris/actions-hugo@v2
              with:
                  hugo-version: "latest"

            - name: Build Web
              run: hugo

            - name: Deploy Web
              uses: peaceiris/actions-gh-pages@v3
              with:
                  PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
                  EXTERNAL_REPOSITORY: pseudoyu/pseudoyu.github.io
                  PUBLISH_BRANCH: master
                  PUBLISH_DIR: ./public
                  commit_message: ${{ github.event.head_commit.message }}

on 表示 GitHub Action 触发条件，push、workflow_dispatch 和 schedule 分别对应推送触发、手动调用和定时执行。

其中 Checkout 步骤中 with 配置 submodules 值为 true 可以同步博客源仓库的子模块，即我们的主题模块。

需要将 deploy.yml 中的 EXTERNAL_REPOSITORY 改为自己的 GitHub Pages 仓库。因为需要从博客仓库推送到外部 GitHub Pages 仓库，需要特定权限，要在 GitHub 账户下 Setting - Developer setting - Personal access tokens 下创建一个 Token。

日常使用总结

  1. 站点目录下，新建文章： 
    hugo new post/文章名.md
  2. 添加文章内容或修改，在本地进行调试
  3. 修改完成，站点目录下执行 hugo 进行编译，然后到 public 下推送： 
    git add -A
git commit -m "update"
git push -u origin master

流行的 Hugo 主题推荐

MemE

MemE 是一个强大且可高度定制的 GoHugo 博客主题，专为个人博客设计。专注于优雅、简约、现代，以及代码的正确性。GitHub地址：https://github.com/reuixiy/hugo-theme-meme 。

Clarity

基于 VMware 的开源 Clarity 设计系统，具有丰富的代码支持、暗/光模式、移动支持等特点。GitHub地址：https://github.com/chipzoller/hugo-clarity

LoveIt

LoveIt 是一个简洁、优雅且高效的 Hugo 博客主题。它的原型基于 LeaveIt 主题和 KeepIt 主题。GitHub地址：https://github.com/dillonzq/LoveIt

Hugo Book Theme

Hugo 文档主题，简洁如书。GitHub地址：https://github.com/alex-shpak/hugo-book

Hugo Academic Theme

轻松创建漂亮的学术简历或教育网站。GitHub地址：https://github.com/wowchemy/starter-hugo-academic

Hugo Learn Theme

基于 Grav Learn Theme 的 Hugo 主题，文档完善。访问主题文档查看详情。

Doks

现代文档主题，专注于安全、速度和 SEO。

配置 Hugo 主题

最好的搜索方式是在 GitHub 中搜索关键词 hugo theme。进入到项目目录中，下载安装需要的主题：

git clone https://github.com/theme-demo.git themes/theme-demo
cp -r themes/theme-demo/_source/* source

在 config.toml 中配置主题：

theme = "theme-demo"
Edit page
Share this post:
Share this post on X Share this post on Telegram Share this post via email
Next Post
2020 岁岁年年