当前位置：首页 > news >正文

从0开始建立Github个人博客(hugoPaperMod)

news 来源：原创 2025/5/8 14:51:53

从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            | 11Paginator pages  |  0Non-page files   |  0Static files     |  0Processed images |  0Aliases          |  2Cleaned          |  0Built 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：

hugo new  posts/first.md

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

---
date: '2025-05-01T18:41:05+08:00'
draft: true
title: 'first'
---

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

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

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

4.定制个人博客

4.1添加菜单

在hugo.yml文件中添加：

menu:main:- identifier: categoriesname: categoriesurl: /categories/weight: 10- identifier: tagsname: tagsurl: /tags/weight: 20- identifier: examplename: example.orgurl: https://example.orgweight: 30

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

4.2置顶帖子

在笔记的md文件里添加：

---
...
weight: 1
---

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

4.3hugo.yaml的可选项

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

baseURL: https://Rook1eChan.github.io
languageCode: zh-cn
title: Chan's Bolg
theme: ["PaperMod"]
buildDrafts: falseparams: ShowBreadCrumbs: true  ShowReadingTime: falseShowShareButtons: falseShowCodeCopyButtons: truefuseOpts:isCaseSensitive: falseshouldSort: truelocation: 0distance: 1000threshold: 0.4minMatchCharLength: 0keys: ["title", "permalink", "summary", "content"]homeInfoParams: Title: "你好，欢迎来到我的博客 \U0001F44B"Content: "welcome!"socialIcons: - name: githuburl: "https://github.com/Rook1eChan"# - name: twitter#   url: "twitter.com"# - name: facebook#   url: "facebook.com"assets:favicon: "/apple-touch-icon.png"label:icon: /apple-touch-icon.pngiconHeight: 35outputs:home:- HTML- RSS- JSONmenu:main:# - identifier: categories#   name: categories#   url: /categories/#   weight: 10# - identifier: tags#   name: tags#   url: /tags/#   weight: 20- identifier: 搜索name: searchurl: /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 (用于菜单项排序)
分类和标签菜单项自选

二、在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，用于在任务环境中获取hugowith:hugo-version: 'latest'	# 获取最新版本的hugoextended: true- name: Buildrun: hugo --minify	# 使用hugo构建静态网页- name: Deployuses: peaceiris/actions-gh-pages@v3	# 一个自动发布github pages的actionwith:# github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repoexternal_repository: Rook1eChan/Rook1eChan.github.io	# 发布到哪个repopersonal_token: ${{ secrets.MYWEBSITE2 }}	# 发布到其他repo需要提供上面生成的personal access tokenpublish_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 连接
在终端运行：

ssh -T git@github.com

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

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

6.上传

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

git init
git add .
git remote add origin git@github.com:XXX/mywebsite.git
git commit -m "Update"
git push -u origin main

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

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

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

三、如何更新网站内容

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

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

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

git init   //初始化git文件夹git add .  //添加变更内容git remote add origin git@github.com:XXX/mywebsite.git   //最后一项改为源仓库的地址，如果使用ssh连接的就复制ssh地址git commit -m "new"   //设置本次操作的名称，new可以随便改git push -u origin main  //把本地文件push到github上，增量更新

常见问题：

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。