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

42fourtytoo2025-05-05 13:49

从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，可以：

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

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

  2. 或者，在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: categories
      name: categories
      url: /categories/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: example
      name: example.org
      url: https://example.org
      weight: 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: false

params: 
  ShowBreadCrumbs: true  
  ShowReadingTime: false
  ShowShareButtons: false
  ShowCodeCopyButtons: true

  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
      url: "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.png
    iconHeight: 35

outputs:
    home:
        - HTML
        - RSS
        - JSON

menu:
  main:
    # - identifier: categories
    #   name: categories
    #   url: /categories/
    #   weight: 10
    # - identifier: tags
    #   name: tags
    #   url: /tags/
    #   weight: 20
    - identifier: 搜索
      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):

  • 资源 (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) 生成&配置

  1. 点击右上角 头像
  2. 选择 Settings
  3. 左侧菜单选择 Developer settings
  4. 选择 Personal access tokens → Tokens (classic)
  5. 点击 Generate new token → Generate new token (classic)
  6. 设置 Token 信息：
    • Token name ：输入名称（如 mywebsite）
    • Expiration ：选择 No expiration（永不过期）
    • 权限勾选：
      • ✅ repo（全仓库权限）
      • ✅ admin:repo_hook（仓库管理权限）
  7. 点击绿色按钮 Generate token
  8. 重要：立即复制生成的密钥并妥善保存（离开页面后将无法再次查看）
  9. 进入源仓库
    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 密钥配置

  1. 检查是否已有 SSH Key

    • Windows：

      进入 C:\Users\你的用户名\.ssh，查看是否存在 id_rsa（私钥）和 id_rsa.pub（公钥）文件。

      • 若有，说明已生成过 SSH Key，可直接使用。
      • 若无，需重新生成。

    • Linux：

      bash 复制代码 
      cd ~/.ssh
ls

      检查是否存在 id_rsa 和 id_rsa.pub 文件。

  2. 生成 SSH Key（若无）

    运行以下命令（替换 xxx@xxx.com 为你的 GitHub 注册邮箱）：

bash 复制代码 
ssh-keygen -t rsa -C "xxx@xxx.com"
  • 连续按 3 次回车（使用默认路径，不设密码）。
  • 生成的文件：
    • id_rsa：私钥（切勿泄露）。
    • id_rsa.pub：公钥（需添加到 GitHub）。

  1. 将公钥添加到 GitHub

  2. 复制公钥内容（id_rsa.pub）：

  3. 登录 GitHub → 点击头像 → Settings → SSH and GPG Keys → New SSH Key。

  4. 测试 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。

相关推荐
非凡ghost36 分钟前
视频剪辑不用等渲染，这款开源工具让切分合并秒级完成
运维·电脑·软件需求
4SAPI2 小时前
多模型请求路由怎么设计？成本、速度和能力如何平衡
人工智能·python·gateway·php
FII工业富联科技服务3 小时前
Omniverse 数字孪生与柔性自动化，如何破解产能与交付、设备与空间的双重困境？
运维·自动化·devops
润滑卫士3 小时前
油液介电常数在线监测：测量原理与油液老化状态评估方法
运维
Rock Chin6974 小时前
把 n8n 接进 Slack：在对话里 @机器人 触发自动化工作流
运维·机器人·自动化
浩浩测试一下4 小时前
Linux 底层知识点 1
linux·运维·服务器
Eloudy4 小时前
全文 - IMEX 第01节 -IMEX overview
运维·服务器·网络
XCDoris4 小时前
郴州logo设计机构
大数据·人工智能·python
物联网软硬件开发-轨物科技5 小时前
【技术白皮书】光伏清检一体化机器人系统解决方案技术白皮书
大数据·运维·网络·人工智能·机器人
gCode Teacher 格码致知5 小时前
Pandas教学-17:Series与Dataframe的关系
开发语言·python·pandas
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05几个好用的ip纯净度检测网站06「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会07苹果iPA游戏软件资源下载网站08昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战09Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）10蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接