Huxley's Blog
Huxley's Blog

Hugo + Github Pages搭建个人博客

Huxley Huxley 收录于 Blog 和 Hugo
  约 3200 字 预计阅读 7 分钟 - 次阅读   - 条评论  

使用Hugo搭建个人博客，并部署到Github Pages上。

安装Hugo等软件

参考Hugo官网安装说明，必要软件包括：Hugo，Go，Git。

Mac用户可直接使用Homebrew进行安装

1
2
3

brew install hugo
brew install go
brew install git

在本地创建博客

初始化博客

下述命令将新建一个名为Blog的文件夹（可以自定义改成其他名字，下文中该文件夹统一都用Blog这个名称），该文件夹用于存放博客的所有文件。进入到新建的Blog文件夹中，进行Git初始化。

1
2
3

hugo new site Blog
cd Blog
git init

使用git submodule add命令下载主题到themes文件夹中，并在配置文件hugo.toml中指定使用的主题的名称，更多主题参考Hugo官网和Github。下述命令下载了一个主题放在了themes/ananke路径下，并在hugo.toml中指定了theme的值为ananke。

注意

主题的名称可以自定义，例如下述命令中可以将ananke替换成其他名称。可以安装多个主题，但应注意hugo.toml文件中theme的值应该是themes文件夹下的某个文件夹的名称。

1
2

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml

最后在Blog路径下运行下述命令，即可在本地运行博客，默认端口是1313，打开网址http://127.0.0.1:1313即可预览博客，具体使用的端口详见命令的输出结果。-D与--buildDrafts等效，作用是会显示草稿文章。

1
2
3

hugo server
hugo server -D
hugo server --buildDrafts

新增博客文章

在Blog路径下执行下述命令，将新建文件content/posts/my-first-post.md，可将所有后续的所有博客文章都放在content下的posts文件夹中。

1

hugo new content/posts/my-first-post.md

注意

默认生成的文章，可以在文章头看到draft为true，即为草稿文章，一般发布网站时不发布草稿文章，因此对于要发布的文章，需将draft值改成false或者直接删除文章头中draft这一行配置。

创建Github Pages

创建一个仓库，名称为<username>.github.io，比如用户名是Huxley927，那么该仓库的名称应该是Huxley927.github.io；并且仓库为Public类型，如下图：

QQ_1731402797188

在后续将博客网站的文件上传到该仓库后，<username>.github.io就是自己博客的网址。

发布网站

注意

手动发布网站的方法可行，但推荐下文提到的用Github Actions自动发布网站，先了解手动发布网站的过程，再看如何用Github Actions自动发布网站

手动发布网站

在Blog路径下运行hugo命令将会生成静态博客网站，网站的文件在都在public文件夹中。

1

hugo

提示

进入到public文件夹，比如可以用python -m http.server命令即可运行一个本地服务器，运行下述命令后就可以在浏览器中打开127.0.0.1:1313看到Hugo生成的博客

1
2

cd public
python -m http.server 1313

将public文件夹上传到上述创建的<username>.github.io仓库中，首次提交到Github上，在public文件中需运行以下命令：

1
2
3
4
5
6

git init
git add .
git commit -m "first commit"
# <username>替换成自己的用户名
git remote add origin git@github.com:<username>/<username>.github.io.git
git push -u origin main

注意

需先配置好Github SSH

以后每次本地博客有修改后，按照以下步骤更新网站：

  1. 在Blog路径下（即上面创建的博客所对应的文件夹）下执行hugo命令
  2. 进入到public文件夹下，将public文件夹中的内容提交到Github上的<username>.github.io仓库中

上述两个步骤是每次更新网站的必要步骤。但是最好还是再创建一个Github仓库（可设置成私有仓库），比如取名为hugo-blog，用来存放博客的所有文件，这样的话，以后每次本地博客有修改后，需完成的事项有：

  • 在Blog路径下中执行hugo命令，并将public文件夹的内容提交到<username>.github.io仓库中。（即上面提到的两个步骤）
  • 将Blog文件夹提交到hugo-blog仓库中

用Github Actions自动发布网站

相较于手动发布网站，用Github Actions自动发布网站达成的效果是，每次需更新网站时，只需将Blog文件夹上传到hugo-blog仓库中，之后Github自动就会更新<username>.github.io仓库中的内容，无需手动将public文件夹上传到<username>.github.io仓库中。

创建access tokens

打开Github网页，点击右上角个人头像，进入Settings界面，点击设置列表中的Developer settings

access-tokens-1

点击Personal access tokens下的Tokens(classic)，然后点击Generate new token下的Generate new token(classic)

access-tokens-2

生成access token时，勾选workflow

access-tokens-3

最后点击页面下方的Generate token按钮即可。生成完成后如下图，将生成的access token复制下来，以后这个aceess token将不可见。

access-tokens-4

创建Actions Secret

进入到上面提到的hugo-blog仓库，依次点击Settings、Secrets and Variables、Actions、New repository secret

./image/actions-secret-1.png

如下图，输入Name和Secret，Name可自定义，这里取名为HUGO_TOKEN，Secret即为上面生成的access token。

actions-secret-2

最后点击Add secret完成。

创建Github Action

在.github/workflows文件夹下创建一个yaml文件，比如.github/workflows/hugo_deploy.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

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    # 这里指定ubuntu为最新版本, 使用指定版本也可, 比如 ubuntu-22.04
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          # 运行hugo version可以查看本地hugo版本
          # 这里使用最新版本的hugo, 也可写具体的版本号, 与本地hugo版本保持一致, 比如 0.138.0
          hugo-version: latest
          # 查看hugo version的结果，如果本地是extended版本，就设置成true，反之设置成false
          extended: true

      - name: Build
        run: hugo  # 命令可以修改，比如草稿文章也想发表可改成hugo -D

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          # HUGO_TOKEN就是上面Actions Secret取的名字，要与自己取的名字保持一致
          personal_token: ${{ secrets.HUGO_TOKEN }}
          # <username>替换成自己的用户名
          external_repository: <username>/<username>.github.io
          # 现在默认分支都用main，比如用的是master分支，则改为master
          publish_branch: main
          publish_dir: ./public
          # 可选配置, 每次博客更新后, 本仓库会自动往<username>.github.io仓库提交一次更新后的网站内容
          # 添加该项配置后, <username>.github.io仓库的提交信息就会使用本仓库的提交信息
          commit_message: ${{ github.event.head_commit.message }}
          cname: https://huxinme.top  # 填写自己的自定义域名, 如果没有自定义域名, 删除该项配置

发布网站

public和resources文件夹都是Hugo生成静态网站时创建的，因此在.gitignore文件中可以添加以下内容

1
2
3

.hugo_build.lock
/public/
/resources/  # hugo生成的文件，也可忽略

最后，将Blog文件夹提交到hugo-blog仓库中即可，首次提交到Github上，用到的命令如下

1
2
3
4
5
6

git add .
git commit -m "first commit"
# <username>替换成自己的用户名，hugo-blog时自己取的仓库的名称
git remote add origin git@github.com:<username>/hugo-blog.git
git branch -M main
git push -u origin main

提交到Github上后，稍等一会儿，打开<username>.github.io就可以看到更新后的网站了。

进一步的配置

参考资料

相关内容

更新于 2024-11-16 
CC BY-NC-SA 4.0
Baidu
HugoBlogGithub Pages
返回 | 主页
0%