从0开始建立Github个人博客(hugo&PaperMod)

github提供给每个用户一个网址，用户可以建立自己的静态网站。

一、Hugo

hugo是一个快速搭建网站的工具，由go语言编写。

1.安装hugo

到hugo的github标签页Tags · gohugoio/hugo选择一个版本，下载对应的安装包。比如hugo_extended_withdeploy_0.147.0_windows-amd64.zip。

解压后，在根目录打开cmd，输入

hugo new site YourSiteName

为你的网站建立文件夹。YourSiteName更改为你的网站的名字。根目录会出现YourSiteName文件夹。

3.将根目录的hugo.exe复制到YourSiteName里。在YourSiteName文件夹里打开cmd，输入

hugo server -D

会返回如下信息：

                   | EN
-------------------+-----
  Pages            | 11
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  2
  Cleaned          |  0

Built in 79 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

在浏览器中输入http://localhost:1313/，显示Page Not Found，说明服务器正常运行，但是此时网站还没有页面。

2.选择网站主题

在Hugo Themes选择你想要的theme，然后根据theme的安装说明操作就行了。在此以PaperMod为例。官方安装教程界面：Installation · adityatelange/hugo-PaperMod Wiki

安装PaperMod，可以：

在你的网站的theme文件夹使用：

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

或者，在Tags · adityatelange/hugo-PaperMod选择版本，下载zip并解压到theme文件夹。

在你的网站的根文件夹里的hugo.yml文件里添加

theme: ["PaperMod"]

3.新建一个笔记

在你的网站的根页面下使用cmd：

YourSiteName/content/posts/first.md 就会建立，打开后，内容为：

这三条短线围起来的是该笔记的属性。第一行是创建时间；第二行为false时表示草稿状态，改为true才会显示在网站中；第三行为该笔记的标题。之后还可以添加其他的属性。

打开http://localhost:1313/，刷新后就能看到刚才创建的笔记了。如果没有就重新hugo server -D。

你可以通过cmd，或者直接新建md文件来添加笔记。

4.定制个人博客

4.1添加菜单

在hugo.yml文件中添加：

在网站的右上角就能看到菜单了

4.2置顶帖子

在笔记的md文件里添加：

weight为正整数，表示笔记顺序。放到最顶上就设为1。

4.3hugo.yaml的可选项

hugo.yaml是网站根目录的配置文件

# 基础配置
baseURL: https://Rook1eChan.github.io  # 网站部署的根URL（GitHub Pages地址）
languageCode: zh-cn                   # 网站语言代码（简体中文）
title: Chan's Blog                    # 网站标题（
theme: ["PaperMod"]                   # 使用的主题（Hugo PaperMod主题）
buildDrafts: false                    # 构建时是否包含草稿（false表示不构建草稿）

# 主题参数配置
params: 
  # 布局控制
  ShowBreadCrumbs: true               # 显示面包屑导航
  ShowReadingTime: false              # 隐藏文章阅读时间
  ShowShareButtons: false             # 隐藏分享按钮
  ShowCodeCopyButtons: true           # 显示代码复制按钮

  # 搜索功能配置（使用Fuse.js）
  fuseOpts:
    isCaseSensitive: false            # 搜索不区分大小写
    shouldSort: true                  # 对搜索结果排序
    location: 0                       # 匹配位置权重
    distance: 1000                    # 匹配距离阈值
    threshold: 0.4                    # 匹配相似度阈值
    minMatchCharLength: 0             # 最小匹配字符长度
    keys: ["title", "permalink", "summary", "content"]  # 搜索的字段范围
  
  # 首页欢迎信息
  homeInfoParams: 
    Title: "你好，欢迎来到我的博客 \U0001F44B"       # 标题
    Content: "welcome!"               # 内容

  # 社交媒体图标
  socialIcons: 
    - name: github                     # GitHub图标
      url: "https://github.com/Rook1eChan"  # GitHub个人主页
    # 其他社交平台（已注释掉）
    # - name: twitter
    #   url: "twitter.com"

  # 网站图标配置
  assets:
    favicon: "/apple-touch-icon.png"   # favicon路径

  # 导航栏图标
  label:
    icon: /apple-touch-icon.png       # 导航栏图标路径
    iconHeight: 35                    # 图标高度（像素）

# 输出格式配置
outputs:
    home:
        - HTML                        # 生成HTML页面
        - RSS                         # 生成RSS订阅
        - JSON                       # 生成JSON数据（可能用于搜索）

# 内容标记配置
markup:
  highlight:
    codeFences: true                  # 启用代码块高亮
    guessSyntax: true                 # 自动检测代码语言
    hl_Lines: ''                      # 高亮指定行（未设置）
    lineNos: false                    # 不显示行号（与下面配置冲突）
    lineNumbersInTable: true          # 用表格布局行号（避免复制时带行号）
    noClasses: false                  # 使用CSS类（必须为false）
    style: github                    # 代码高亮主题（github、monokai、solarized-dark、dracula）
    tabWidth: 4                       # 代码缩进空格数

  goldmark:
    renderer:
      unsafe: true  # 允许渲染原始HTML/LaTeX
  math: true     # 支持数学公式

# 导航菜单配置
menu:
  main:
    # 已注释的分类和标签菜单
    # - identifier: categories
    #   name: categories
    #   url: /categories/
    #   weight: 10
    - identifier: search                 # 搜索菜单项
      name: search                   # 菜单显示名称（英文，与标识不一致）
      url: /search/                  # 搜索页面路径
      weight: 25                     # 菜单项排序权重

baseURL: 网站的基础URL，这里是 “https://Rook1eChan.github.io”，必须要写，不然导航出现错误。不要写example.com
languageCode: 网站语言代码，“zh-cn” 表示简体中文
title: 网站标题
theme: 使用的主题
buildDrafts: false 表示不设置草稿文章，所有文章都会被展示
显示相关:
- ShowBreadCrumbs: true 显示面包屑导航
- ShowReadingTime: false 不显示文章阅读时间
- ShowShareButtons: false 不显示分享按钮
- ShowCodeCopyButtons: true 显示代码块的复制按钮
搜索功能 (fuseOpts):
- 配置了基于 Fuse.js 的搜索功能参数，包括不区分大小写、排序方式等
主页信息 (homeInfoParams):
- Title：标题
- Content：内容
主页社交媒体图标 (socialIcons):
- 只启用了 GitHub 链接，指向 “https://github.com/Rook1eChan"
- Twitter 和 Facebook 链接
资源 (assets):
- 设置了网站图标 (favicon) 为 “/apple-touch-icon.png”
标签 (label):
- 设置了图标及其高度
指定了主页的输出格式为 HTML、RSS 和 JSON
主菜单 (main) 中只配置了一个 “搜索” 项:
- 标识符: “搜索”
- 名称: “search”
- URL: “/search/”
- 权重: 25 (用于菜单项排序)
分类和标签菜单项自选

4.4更改字体

在 Hugo 项目下新建 assets/css/extended/custom.css ，写入

/* 全局正文字体 - Noto Sans Simplified Chinese */
body, article {
    font-family: "Noto Sans SC", sans-serif;
}

/* 代码块字体 - 保持等宽字体（如 JetBrains Mono 或系统默认） */
pre, code {
    font-family: "JetBrains Mono", monospace;
    font-size: 0.9em; /* 可选：调整代码字体大小 */
}

在 themes/PaperMod/layouts/partials/head.html 中添加 Google Fonts 的链接

可以去Browse Fonts - Google Fonts选字体。代码怎么写问AI。

4.5启用数学公式

以下方法可以使用 $...$ 表示行内公式，$$...$$表示行间公式

在themes\PaperMod\layouts\partials\math.html" 里加上：

{{ if .Page.Params.math }}
<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],  // 行内公式：$...$ 或 \(...\)
    displayMath: [['$$', '$$'], ['\\[', '\\]']] // 块级公式：$$...$$ 或 \[...\]
  }
};
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
{{ end }}

在themes\PaperMod\layouts\_default\baseof.html" 里加上：

<head>
   ...
  {{ if .Param "math" }}
    {{ partialCached "math.html" . }}
  {{ end }}
    ...
</head>

在hugo.yaml里加上：

# 内容标记配置
markup:
  goldmark:
    renderer:
      unsafe: true  # 允许原始 HTML（某些数学公式需要）
    extensions:
      passthrough:
        enable: true
        delimiters:
          block:
            - ['$$', '$$']    # 块级公式：$$...$$
            - ['\\[', '\\]']  # 或者 \[...\]
          inline:
            - ['$', '$']      # 行内公式：$...$
            - ['\\(', '\\)']  # 或者 \(...\)

hugo.yaml不要加math: true，在每篇文章开头的参数里加上：

4.6侧边目录

在config.yml中，添加或修改params对应的配置为以下内容：

虽然PaperMod原生就有目录，但是却是在顶部，便捷性几乎为0，放在侧边就会方便许多。

在项目目录layouts/partials下添加toc.html文件，内容如下：
在项目目录assets/css/extended下添加blank.css文件，内容如下：

二、在GitHubPage部署网站

基本思路：建立两个仓库，一个网站仓库负责展示页面，另一个源仓库负责存储源码、更新内容并自动更新同步到网站仓库。

1.建立网站仓库

在Github页面点击最上面的加号-New repository Repository name 填写 你的GitHub用户名.github.io，这样GitHub才会把它识别为网站仓库选择Public 点击绿色的Create repository

2.建立源仓库

同上建立仓库，随便命名，Public或Private都行这里我命名为mywebsite

3.GitHub 个人访问令牌 (Token) 生成&配置

点击右上角头像
选择 Settings
左侧菜单选择 Developer settings
选择 Personal access tokens → Tokens (classic)
点击 Generate new token → Generate new token (classic)
设置 Token 信息：
- Token name：输入名称（如 mywebsite）
- Expiration：选择 No expiration（永不过期）
- 权限勾选：
  - ✅ repo（全仓库权限）
  - ✅ admin:repo_hook（仓库管理权限）
点击绿色按钮 Generate token
重要：立即复制生成的密钥并妥善保存（离开页面后将无法再次查看）
进入源仓库
1. 点击settings
2. 左侧Secrets and variables-Actions
3. New repository secret
4. 填写刚才的名称和密钥
5. Add sercet

4.配置workflow脚本

在本地网站根目录新建文件夹及文件.github/workflows/hugo.yaml 写入：

name: github pages # 名字自取

on:
  push:
    branches:
      - main  

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

只需要更改personal_token和external_repository

5. SSH 密钥配置

检查是否已有 SSH Key
- Windows：进入 C:\Users\你的用户名\.ssh，查看是否存在 id_rsa（私钥）和 id_rsa.pub（公钥）文件。
  - 若有，说明已生成过 SSH Key，可直接使用。
  - 若无，需重新生成。
- Linux：
```
cd ~/.ssh
ls
```
  检查是否存在 id_rsa 和 id_rsa.pub 文件。
生成 SSH Key（若无）运行以下命令（替换 xxx@xxx.com 为你的 GitHub 注册邮箱）：

ssh-keygen -t rsa -C "xxx@xxx.com"

连续按 3 次回车（使用默认路径，不设密码）。
生成的文件：
- id_rsa：私钥（切勿泄露）。
- id_rsa.pub：公钥（需添加到 GitHub）。

将公钥添加到 GitHub
复制公钥内容（id_rsa.pub）：
登录 GitHub → 点击头像 → Settings → SSH and GPG Keys → New SSH Key。
测试 SSH 连接在终端运行：

若显示 Hi 你的用户名!，说明配置成功。

之后clone或push时都选择SSH地址，而不是https地址。

6.上传

本地网站根目录使用cmd，git@github.com:XXX/mywebsite.git改为源仓库地址：

然后在源仓库的Action下，能看到正在Deploy，变绿色说明成功。此时网站仓库已自动更新了内容。

进入网站仓库-settings-Pages-Build and deployment选择Deploy from a branch 刚才workflow脚本里写的是main，这里就选择main

然后进入xxx.github.io，就可以看到你的网站了！🎉

三、如何更新网站内容

不要在github和本地同时更改内容！不然会导致内容不同步，无法push。

最好是一直都在本地更改，然后push到源仓库。

1.本地更改后，比如新建了笔记，在网站根目录使用cmd：不要复制注释！

常见问题：

git push -u origin main的时候报错： error: src refspec master does not match any error: failed to push some refs to ‘github.com:Rook1eChan/mywebsite.git’
使用git branch -a，查看branch的名称是不是main。如果是master，就把main改为master。

To github.com:Rook1eChan/mywebsite.git ! [rejected] main -> main (fetch first) error: failed to push some refs to ‘github.com:Rook1eChan/mywebsite.git’ hint: Updates were rejected because the remote contains work that you do not
说明你的GitHub和本地不同步。不建议强制合并，可以把GitHub整个repo clone到本地另一个文件，把变化的文件手动更改，再把新文件夹push上去。

感谢GitHub、Hugo和Deekseek。

一、Hugo#

1.安装hugo#

2.选择网站主题#

3.新建一个笔记#

4.定制个人博客#

4.1添加菜单#

4.2置顶帖子#

4.3hugo.yaml的可选项#

4.4更改字体#

4.5启用数学公式#

4.6侧边目录#

二、在GitHubPage部署网站#

1.建立网站仓库#

2.建立源仓库#

3.GitHub 个人访问令牌 (Token) 生成&配置#

4.配置workflow脚本#

5. SSH 密钥配置#

6.上传#

三、如何更新网站内容#