技术

Hugo搭建个人博客

Hugo是由Go语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。

安装

hugo 有两个版本，标准版和扩展版，推荐使用扩展版。

  1. 使用 scoop 安装

    1

    scoop install hugo-extended

    注意：*目前scoop版本过低，编译最新stack主题的时候会报错，所以推荐使用下面方法安装。

  2. 下载二进制安装，github地址

    a. 下载二进制版本 b. 解压文件 c. 配置环境变量

查看 hugo 版本

扩展版可以在输出种看到 +extended 标识

1

hugo version

显示可用命令

1
2
3
4

hugo help

# 获取子指令的说明, 用 --help标志，例如：
hugo server --help

新建站点

一个站点对应本地的一个文件夹，如：希望在 /site_path/site_name 路径创建一个站点

1

hugo new site site_path/site_name

创建成功以后切换到对应路径

1

cd site_path/site_name

可以看到如下文件结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

site_name/  
├── archetypes/  该目录包含新内容的模板，查看[详细资料](https://gohugo.io/content-management/archetypes/)  
│   └── default.md  
├── assets/  该目录包含通常通过资产管道传递的全局资源。这包括图像、CSS、Sass、JavaScript 和 TypeScript 等资源。查看[详细资料](https://gohugo.io/hugo-pipes/introduction/)  
├── content/  该目录包含标记文件（通常是 Markdown）和构成站点内容的页面资源。查看[详细资料](https://gohugo.io/content-management/organization/)  
├── data/  该目录包含数据文件（JSON、TOML、YAML 或 XML），用于增强内容、配置、本地化和导航。查看[详细资料](https://gohugo.io/content-management/data-sources/)  
├── i18n/  该目录包含多语言站点的翻译表。查看[详细资料](https://gohugo.io/content-management/multilingual/)  
├── layouts/  layouts 目录包含用于将内容、数据和资源转换为完整网站的模板。查看[详细资料](https://gohugo.io/templates/)  
├── static/  该目录包含的文件将在您构建站点时复制到公共目录。例如：、 和验证站点所有权的文件。在引入页面捆绑包和资产管道之前，该目录还用于图像、CSS 和 JavaScript。  
├── themes/  该目录包含一个或多个主题，每个主题都位于其自己的子目录中
└── hugo.toml  站点配置，可能分为多个子目录和文件。对于配置最少的项目或不需要在不同环境中表现不同的项目，在项目根目录中命名的单个配置文件就足够了。查看[详细资料](https://gohugo.io/getting-started/configuration/#configuration-directory)

新建文章

新建的文章会根据 archetypes/default.md 模板创建在 content/ 目录下

1

hugo new path/test.md

本地调试

在发布文章之前，你可能希望在本地调试，在站点根路径执行 hugo 命令进行调试

1
2
3
4
5
6
7

# 启动本地服务器
hugo server

# --buildDrafts 包含草稿文章
hugo server --buildDrafts
# or
hugo server -D

在浏览器打开 http://localhost:1313 可查看生成的文章

生成最终页面

将文章中的 draft 修改为 false

1
2
3
4

hugo

#开始代码压缩
hugo --minify

运行以后将在站点目录生成 public 目录，该目录包含生成的已发布网站。Hugo根据需要重新创建此目录及其内容。查看详细资料

⚠️Hugo在构建站点前不会清空目录。 根据当前四个条件的评估结果，构建后你的目录可能包含来自以前构建的多余文件。通常的做法是在每次构建之前手动清空目录的内容以删除草稿、过期和未来的内容。

所以推荐使用代参构建

1
2

# 这个选项会在 Hugo 构建时清理生成目录中的内容，确保只有最新构建的文件保留
hugo --cleanDestinationDir

部署到 Github pages

手动部署

  1. 首先在 github 上创建一个名为 xxx.github.io 的 public 仓库（ xxx 为你个人 github 的用户名）。

  2. 将 public 文件夹关联到刚创建的仓库

    1
2
3
4
5
6
7

    cd public
git init
git remote add origin https://github.com/xxxx/xxxx.github.io.git
git branch -M main
git add .
git commit -m "add test.md"
git push -u origin master

之后可在浏览器访问 http://xxx.github.io 即可看到发布的文章

手动部署需要每次修改文章编译后推送到 xxx.github.io 仓库，这样就需要手动管理两个目录，过于繁琐

自动部署

  1. 仍然需要创建 xxx.github.io 仓库

    目前我们已经有两个仓库：

    • 私有库：MySite
    • 公开库：xxxx.github.io

  2. 创建 Personal Access Token

    Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub Enterprise Server when using the GitHub API or the command line.

    创建PAT的主要目的是给私有库访问目标库的权限，可以让私有 库的actions推送构建好的代码到目标库中去

    1. 打开 github setting 界面
    2. 切换到 Developer settings
    3. 点击 Personal access tokens
    4. 点击 Tokens(classic)
    5. 勾选 workflow 和 write:packages
    6. 生成 PAT
    7. 复制 ghp_ 开头的 tokens

    PAT生成 PAT生成

  3. 在私有库设置 Secret

    1. 打开私有库
    2. 打开 settings 页面
    3. 添加 Secret，保持 Secret 名字，例如：SECERT_BLOG

    设置Secret

  4. 在私有库创建 Action Workflow

    在 github 私有仓库页面，选择 Actions, 创建新的 workflow，在搜索中搜索 hugo, 并创建

    create_workflow

    参照文档并作相应修改

    • hugo-version：修改为本地 hugo 版本，可以通过 hugo version 查看
    • personal_token：修改为 ${{ secrets.XXX }}, XXX 是刚才在私有仓库设置的 SECRET 名字
    • external_repository：公共仓库地址 xxx/xxx.github.io
     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

    name: GitHub Pages

on:
push:
   branches:
      - main  # Set a branch to deploy
pull_request:

jobs:
deploy:
   runs-on: ubuntu-22.04
   concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
   steps:
      - uses: actions/checkout@v4
      with:
         submodules: true  # Fetch Hugo themes (true OR recursive)
         fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
      uses: peaceiris/actions-hugo@v3
      with:
         hugo-version: '0.132.2'
         extended: true

      - name: Build
      run: hugo --minify --cleanDestinationDir

      - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
         personal_token: ${{ secrets.XXX }}
         publish_branch: main
         publish_dir: ./public
         external_repository: xxx/xxx.github.io
         cname: imhy.top

    至此，自动部署已完成，每当 push 到 main 分支的时候，github 会自动生成并且部署到个人页面

12.91k 字
12篇文章

© 2024 君不见