Hugo_GithubPages_Papermod实现博客搭建

一、本体安装(win)

Hugo安装指南：https://gohugo.io/installation/windows/

Hugo官方入门指南：https://hugo.opendocs.io/getting-started/

1. 下载hugo二进制文件

1
winget install Hugo.Hugo.Extended

将hugo.exe添加至系统变量

2. 创建站点目录

1
hugo new site my-blog

Hugo 站点的目录结构如下：

 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
my-blog/
├── content              # 存放所有内容文件
│   ├── _index.md        # 博客首页内容
│   ├── posts            # 博客文章
│   │   ├── first-post.md
│   │   └── second-post.md
│   └── pages            # 博客页面
│       └── about.md     # 关于页面
├── data                 # 存放站点数据
│   ├── authors.yml      # 作者信息
│   └── config.toml      # 站点配置文件
├── i18n                 # 国际化语言文件
│   ├── en.toml          # 英文语言文件
│   └── zh.toml          # 中文语言文件
├── layouts              # 存放页面模板
│   ├── _default         # 默认模板
│   ├── partials         # 模板片段
│   └── index.html       # 首页模板
├── assets               # 存放编译前的资源文件
│   ├── css              # 存放 CSS 源文件
│   ├── js               # 存放 JavaScript 源文件
│   └── images           # 存放图片源文件
├── resources            # 存放生成的资源文件
│   └── _gen             # 生成的资源文件
├── static               # 存放静态资源（如图片、CSS、JS）
│   ├── css              # 存放编译后的 CSS 文件
│   ├── js               # 存放编译后的 JavaScript 文件
│   └── images           # 存放图片文件
├── public               # 生成的网站文件
├── themes               # 存放主题文件
│   └── my-theme         # 自定义主题文件
│       ├── layouts      # 存放页面模板
│       ├── static       # 存放主题静态资源
│       └── theme.toml   # 主题配置文件
├── archetypes           # 内容模板文件
│   ├── default.md       # 默认内容模板
│   └── post.md          # 博客文章模板
└── hugo_build.lock      # Hugo 包管理文件

二、配置主题（以papermod为例）

1.下载主题

在hugo根目录下初始化git仓库并

1
2
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)

2.HUGO配置文件示例

  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
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# languageCode: 'en-us'
baseURL: "https://auranlu.cc/" # 主站的 URL
title: 🌇 Endless Soar. # 站点标题
copyright: "[©2025 auranlu's Blog](https://auranlu.cc/)" # 网站的版权声明，通常显示在页脚
theme: PaperMod # 主题
languageCode: zh-cn # 语言
pagination:
  pagerSize: 10

enableInlineShortcodes: true #允许内联带代码
hasCJKLanguage: true # 自动检测是否包含中文日文韩文,如果文章中使用了很多中文引号的话可以开启
enableRobotsTXT: true # 允许爬虫抓取到搜索引擎
buildDrafts: false # 构建时是否包括草稿
buildFuture: false # 构建未来发布的内容
buildExpired: false # 构建过期的内容
enableEmoji: true # 允许 emoji
pygmentsUseClasses: true
defaultContentLanguage: zh # 顶部首先展示的语言界面
defaultContentLanguageInSubdir: false # 是否要在地址栏加上默认的语言代码
# googleAnalytics: UA-123-45 # 谷歌统计
minify:
  disableXML: true
  minifyOutput: true
permalinks: #浏览器链接显示方式
  post: "/:title/"

#导航栏
languages:
  zh:
    languageName: "中文" # 展示的语言名
    weight: 1 # 权重
    taxonomies: # 分类系统
      # category: categories
      tag: tags
    # https://gohugo.io/content-management/menus/#define-in-site-configuration
    menus:
      main:
        # - name: /HOME🗼
        #   pageRef: /
        #   weight: 4 # 控制在页面上展示的前后顺序
        - name: POSTS 🗯
          pageRef: /posts
          weight: 4
        - name: ARCHIVES📄
          pageRef: /archives/
          weight: 5
        # - name: /CATEGORIES🖇
        #   pageRef: categories/
        #   weight: 10
        - name: TAGS🔖
          pageRef: tags/
          weight: 11
        - name: SEARCH🔍
          pageRef: search/
          weight: 20
        - name: ABOUT👇🤓👆
          pageRef: about/
          weight: 21

#为搜索配置JSON
outputs:
  home:
    - HTML # 生成的静态页面
    - RSS # 这个其实无所谓
    - JSON # necessary for search, 这里的配置修改好之后，一定要重新生成一下

params:
  social: true
  env: production
  
  title: auranlu # 网站标题，显示在浏览器标签和搜索引擎结果中
  description: "Endless Soar." # 网站描述，用于SEO和页面预览
  keywords: [auranlu, Blog, IT, safe] # SEO关键词，帮助搜索引擎索引
  author: auranlu # author: ["Me", "You"] # 支持多个作者，注释掉的是示例
  # images: ["<link or path of image for opengraph, twitter-cards>"] # 设置用于OpenGraph和Twitter卡片的图片链接
  # DateFormat: "January 2, 2006" # 显示日期的格式
  DateFormat: "2006-01-02"
  defaultTheme: dark # 默认主题模式，可选dark（暗色）、light（亮色）、auto（根据系统自动切换）
  disableThemeToggle: false # 禁用主题切换按钮

  ShowReadingTime: false # 显示文章的预计阅读时间
  ShowShareButtons: false # 是否显示社交分享按钮
  ShowPostNavLinks: false # 是否显示上一篇和下一篇文章的导航链接
  ShowBreadCrumbs: true # 显示面包屑导航
  ShowCodeCopyButtons: true # 为代码块显示“复制”按钮
  ShowWordCount: false # 显示文章字数统计
  # ShowRssButtonInSectionTermList: false # 是否在部分或分类列表中显示RSS按钮
  UseHugoToc: true # 使用Hugo生成的目录（TOC，Table of Contents）
  disableSpecial1stPost: false # 禁用首页第一篇文章的特殊样式（例如强调）
  disableScrollToTop: false # 禁用“回到顶部”按钮
  comments: false # 是否启用评论功能

  hidemeta: false # 是否隐藏文章的元数据（如日期、标签等）
  hideSummary: false # 是否隐藏文章摘要
  hidefooter: true # 是否隐藏网站页脚

  # showLastMod: true # 显示文章最后修改时间
  # VisitCount: true # 显示文章的访问计数
  
  showtoc: true # 是否显示文章目录
  tocopen: false # 默认是否展开文章目录

  # 主页 HOME - profile-mode
  profileMode:
    enabled: true # needs to be explicitly set
    title: 🌇 Endless Soar.🌇
    subtitle: "过去无法换回，未来可以改变"
    imageUrl: "img/head.jpg"
    imageWidth: 120
    imageHeight: 120
    imageTitle: auranlu
    # buttons:
    #   - name: Archives
    #     url: archives
    #   - name: Blogs
    #     url: posts
    #   - name: Tags
    #     url: tags
  
  # 用来显示HOME
  label:
    text: "⛺Home"
    # icon: img/head.jpg
    # iconHeight: 35

  # home-info mode - 暂时不知道干嘛的
  homeInfoParams:
    Title: "Hi there 👋"
    Content: Welcome to auranlu's blog

  # 主页图标
  socialIcons:
    # - name: telegram
    #   url: "https://t.me/+1I1GfwrvtFY0ODRl"
    - name: github
      url: "https://github.com/Auran-Lu"
  
  # 搜索功能
  fuseOpts:
      isCaseSensitive: false # 是否大小写敏感
      shouldSort: true # 是否排序
      location: 0
      distance: 1000
      threshold: 0.4
      minMatchCharLength: 0
      # limit: 10 # refer: https://www.fusejs.io/api/methods.html#search
      keys: ["title", "permalink", "summary", "content"]
      includeMatches: true

  # 搜索引擎索引
  analytics:
    google:
      SiteVerificationTag: "auranlu"
    bing:
      SiteVerificationTag: "auranlu"
    yandex:
      SiteVerificationTag: "auranlu"

  # 提建议地址 - 还没弄好
  # editPost:
  #   URL: "https://github.com/<path_to_repo>/content"
  #   Text: "Suggest Changes" # edit text
  #   appendFilePath: true # to append file path to Edit link
  
  # 设置网站的标签页的图标，即 favicon
  assets:
      favicon: "favicon.ico"
      favicon16x16: "favicon.ico"
      favicon32x32: "favicon.ico"
      apple_touch_icon: "favicon.ico"
      safari_pinned_tab: "favicon.ico"

markup:
  highlight:
    noClasses: false
    codeFences: true
    guessSyntax: true
    lineNos: true
    lineNumbersInTable: true
    style: monokai

  goldmark:
    renderer:
      unsafe: true  # 允许渲染 Markdown 中的原始 HTML

3.部署选项页

搜索页：在content文件夹中创建search.md并写入以下配置

1
2
3
4
5
6
---
title: "SEARCH" # in any language you want
layout: "search" # necessary for search
summary: "search"
placeholder: "😋Tell Me, What's Your NEED!" # 栏目内容
---

ps：可以通过添加searchHidden: true来使得特定的文章不会被搜索到。

时间轴页：在content文件夹中创建archive.md并写入以下配置

1
2
3
4
5
6
---
title: "Archives🕑"
layout: "archives"
url: "/archives/"
summary: archives
---

关于页：在content文件夹中创建about.md并写入以下配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
---
title: "👇🤓👆康康驾到👇🤓👆通通闪开"
layout: "about"
url: "/about/"
summary: about

draft: false
cover:
    image: img/danking.png # image path/url
    alt: 'Here AuranLu' # alt text
    caption: 'AuranLu' # display caption under cover
    # relative: false # when using page bundles set this to true
    # hidden: true # only hide on current single page
editPost:
    disabled: true
---


> 有的老将在兜底，有的老将在圈米

以下为参考文档的原文摘录：

PaperMod主题是支持多语言的，但是标签页不支持，需要修改对应的 html 模板。
主题提供的语言支持文件再themes/PaperMod/il8n里面，其中zh.yaml即简体中文。
为了防止更新主题时还原修改过的文件，需要在网站根目录进行修改，这样可以覆盖主题原有文件的效果。

在博客根目录下新建i18n/文件夹，复制themes/PaperMod/i18n/zh.yaml到i18n/zh.yaml。

标签页对应的模板文件为themes/PaperMod/layouts/_default/terms.html。

同以上步骤：在网站根目录新建layouts/_default/文件夹，复制themes/PaperMod/layouts/_default/terms.html到layouts/_default/terms.html，并写入下列配置：

 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
{{- define "main" }}

{{- if .Title }}
<header class="page-header">
    {{- if eq .Title "Categories" }}
    <h1>{{ .Title }}</h1>
    {{- end }}
    {{- if eq .Title "Tags" }}
        <h1>{{ "标签" }}</h1>
        <!-- <h1>{{ .Title }}</h1> -->
    {{- end }}
    <!-- <h1>{{ .Title }}</h1> -->
    {{- if .Description }}
    <div class="post-description">
        {{ .Description }}
    </div>
    {{- end }}
</header>
{{- end }}

<!-- 原始 -->

<ul class="terms-tags">
    {{- $type := .Type }}
    {{- range $key, $value := .Data.Terms.Alphabetical }}
    {{- $name := .Name }}
    {{- $count := .Count }}
    {{- with $.Site.GetPage (printf "/%s/%s" $type $name) }}
    <li>
        <a href="{{ .Permalink }}">{{ .Name }} <sup><strong><sup>{{ $count }}</sup></strong></sup> </a>
    </li>
    {{- end }}
    {{- end }}
</ul>

{{- end }}{{/* end main */ -}}

自定义索引页：以下内容摘自参考文档。

我们写作的内容都是放在content目录下的，因此有必要对其内容有一个基本了解

在官方文档 Content Management 中详尽地介绍了管理博客内容需要了解的所有信息，以下是我的一个目录结构，其中的 about.md、 archive.md 和 search.md 对应博客中的关于、时间轴和搜索：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
content
├── posts
│   ├── _index.md
│   ├── life
│   │   └── _index.md
│   ├── read
│   │   └── _index.md
│   └── tech
│       └── _index.md
├── about.md
├── archive.md
└── search.md

以上目录结构看到出现了很多_index.md,官方参考文档在此Index Pages 。简而言之，这个文件是作为自定义索引页存在。这里给出一个_index.md作为参考：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: "文章"
# description: "Endless Soar."
hidemeta: true # 是否隐藏文章的元信息，如发布日期、作者等

---

过去无法挽回，未来可以改变。

<!-- more -->

三、实现自动化GithubPages部署

1. 建立GitHub库

分别设置为==pravite==库和==public==库,以存储源码并推送生成页面部署

2. 配置Token

在Settings>Developer Settings>Personal access tokens>Tokens(classic)中建立token，Token至少带repo, workflow权限。
进入源码私有库中，Settings>Secrets and variables>Actions中将token添加（token要具有workflow工作流权限）

3. 本地git目录配置

本地HUGO根目录Git配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
git init #创建.git目录

git remote add origin https://github.com/yourusername/your-repo.git #与远程私有库建立链接

git branch -M main #将当前目录设置为main分支

git add . #将当前目录下所有文件添加到暂存区中

git config --global user.name "yourname" #设置全局用户名

git config --global user.email "youremail" #设置全局邮箱

git commit -m "Initial commit" #执行提交操作并标名本次提交，将暂存区中的文件变更提交到本地 Git 仓库。

git push -u origin main #是用于将本地默认main分支的提交推送到远程仓库的命令。origin是远程仓库的默认名称

4. 创建工作流

本地添加.github/workflows/deploy.yamlantion文件，内容如下。

 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: Deploy Hugo to another repo  # 工作流名称

on:
  push:
    branches: [main]  # 监听 main 分支推送
  workflow_dispatch:  # 支持手动触发

permissions:
  contents: write  # 允许写操作（部署用）

jobs:
  build:
    runs-on: ubuntu-latest  # 使用最新版 Ubuntu 作为运行环境
    env:
      HUGO_VERSION: 0.148.1  # 指定 Hugo 版
    steps:
      - name: Install Hugo CLI  # 安装 Hugo 可执行文件
        run: |
          wget -O $RUNNER_TEMP/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i $RUNNER_TEMP/hugo.deb

      - name: Install Dart Sass  # 安装 Dart Sass（用于样式编译）
        run: sudo snap install dart-sass

      - name: Checkout source  # 拉取源码（包括子模块）
        uses: actions/checkout@v4
        with:
          submodules: recursive  # 包含主题等子模块
          fetch-depth: 0  # 拉取完整提交历史

      - name: Install Node.js dependencies  # 安装前端依赖（如果存在）
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"

      - name: Build with Hugo  # 生产模式构建 Hugo 网站
        env:
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
          TZ: Asia/Shanghai  # 设置时区为上海
        run: hugo --gc --minify  # 垃圾回收并压缩构建

      - name: Deploy to GitHub Pages repo  # 将构建结果部署到另一个仓库
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.HUGO_TOKEN }}  # 使用 GitHub Secret 中的 Token 认证
          external_repository: Auran-Lu/AuranLu.github.io  # 目标仓库
          publish_dir: ./public  # Hugo 构建输出目录
          publish_branch: main  # 推送到目标仓库的 main 分支

修改HUGO_TOKEN为在GitHub所配置的token名，修改Auran-Lu/AuranLu.github.io为目标github名/仓库

1
2
3
4
5
6
7
      - name: Deploy to GitHub Pages repo  # 将构建结果部署到另一个仓库
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.HUGO_TOKEN }}  # 使用 GitHub Secret 中的 Token 认证
          external_repository: Auran-Lu/AuranLu.github.io  # 目标仓库
          publish_dir: ./public  # Hugo 构建输出目录
          publish_branch: main  # 推送到目标仓库的 main 分支

5. 推送工作流文件

1
2
3
git add .
git commit -m "Add workflow"
git push origin main

tips：如果使用papermod主题本体可以正常渲染页面，但推送至Github后发现文章未正常渲染可尝试在类似路径的文件中更改hugo-themes/layouts/partials/head.html，在head.html文件meta部分添加，以达到所有页面统一的效果。最后就可以git hugo更新public并重新部署云端。

即添加

1
<meta http-equiv="Content-Security-Policy" content="upgrade-insecure-requests">

四、Netlify部署

Netlify

使用Github登录后使用XXX.github.io公有库部署

若有私有二级域名可将域名解析绑定，访问主域名时自动重定向

一、本体安装(win)#

1. 下载hugo二进制文件#

2. 创建站点目录#

3. HUGO目录结构目录结构#

二、配置主题（以papermod为例）#

1.下载主题#

2.HUGO配置文件示例#

3.部署选项页#

三、实现自动化GithubPages部署#

1. 建立GitHub库#

2. 配置Token#

3. 本地git目录配置#

4. 创建工作流#

5. 推送工作流文件#

四、Netlify部署#