大家好啊!我是Parzival,这篇文章主要是记录了一下我这个萌新从零开始搭建自己的个人博客的步骤。

观前须知:本人也是超级超级小白,弄这个博客之前对前端几乎是一无所知,搜了好几个教程,前前后后花了十几个小时才弄好个人博客,写的这个教程出现差错也是正常的,欢迎各位指正~

同时,如果你也是一枚萌新,那一定一定要做好心理建设,弄这个东西出错是很正常的,我当时看教程,觉得就这么六七步,轻轻松松两个小时包拿下,结果前前后后花了2天时间才弄好,期间真的是无数次红温😡项目重开了无数次。所以,请你不要被失败打击到,出现错误后就想办法去调试解决,解决不了的话就删库重开,没什么大不了的,加油!


前期准备工作

  1. 个人电脑一台,并了解一些基本的命令行相关知识,同时电脑安装有git;

  2. Github账号一个;

  3. 参考资料查阅准备:

  1. 这篇文章的目的是实现一个比较完整的个人博客搭建,包括Github Action自动生成静态内容 并且发布以及gh-pages关联自己的域名等操作,如果你只是想搭建一个 简单的个人博客,那么可以不必详细阅读我的博文,第一个参考资料使用hugo+github-pages部署个人博客 会是一个更好的选择,通过学习那一篇博文,你可以用更简单的操作,更短的时间快速搭建一个个人博客

第一步:创建仓库

我已经默认读到这篇文章的你拥有了Github账户

那么第一步是创建两个Github仓库,一个用来存放自己的整个博客项目,它是私有的 我们称之为博客源仓库,或简称为源仓库,另一个仓库则用来发布自己的博客,我称之为public 仓库。

首先,我们来创建自己的源仓库: 创建博客源仓库 仓库的名称随意,例如我给它命名为“MyBlog”,但请你最好不要把它命名为username.github.io 形式😂

接下来,请勾选Private,因为我希望我的博客源仓库仅自己可见,如果你不介意把它公开的话, 那么完全不需要创建两个仓库,可以参考id1自行完成1个仓库的创建以及后续流程

然后请勾选Add a Readme File,这样会自动把这个仓库的branch 初始化为Main,如果不这么做的话 你的仓库会是空的,后续添加新东西的时候,git应该会把默认branch初始化为Master,本质上二者没什么区别 只是我学到的教程都教我这么做,所以我也习惯这么做了😂

下面来创建第二个仓库,也就是我们用来发布博客的远程仓库。 创建Public仓库 注意!这里的仓库名称必须使用username.github.io的格式,其中,username就是图片中 左侧的“Owner”显示的内容,它是独一无二的,例如,我的username叫做Parzival-Chen, 所以我这里就应该填写parzival-chen.github.io,大小写本质上没什么区别,看你心情填写即可。 因为我已经创建过自己的这个仓库了,所以这里出现了报错,提示我“这个仓库已经存在”,如果你之前没有用这个名字创建过 仓库,那么这里应该是不会报什么错误的


第二步 安装Hugo

请参考hugo官方文档或者英文版里的安装步骤进行,例如,我使用的是MacBook,那么我 需要在命令行里输入brew install hugo,安装完成后,可以输入hugo version来检查自己 是否安装成功以及自己的hugo版本


第三步 本地创建博客项目文件夹

本地博客文件夹 现在,我们需要挑选一个合适的风水宝地,建立自己的博客项目文件夹,例如,我随意地在桌面上 新建了一个文件夹,并命名为“Parzival Blog”

然后回到第一步中创建的博客源仓库,复制SSH链接 复制博客源仓库ssh链接 接着打开位于刚刚创建的本地博客项目文件夹的终端,windows用户请win+R然后输入cmd进入命令行, 接着cd “文件夹的路径”进入这个文件夹, 然后输入git init 把它初始化为一个git 仓库,

输入git remote add origin+“刚刚复制的SSH链接”

然后输入 git remote -v检验是否链接成功远程仓库

保险起见,接下来我们pull一下,在命令行输入git pull


第四步 创建hugo博客文件夹并导入主题

仍然是在刚刚那个文件夹的命令行里,输入

hugo new site YourBlogName

其中,yourblogname可以任意替换为你想要的名字。从现在开始,我们需要对两个文件夹作严格的区分, 第三步中创建的文件夹是我们的整个博客项目的文件夹,我称之为源文件夹,而刚刚用hugo new site命令创建的 文件夹是我们的hugo博客文件夹,我称之为hugo文件夹。

然后,来到hugo模版库, 挑选一个自己喜欢的模板,例如,我选择PaperMod模板,按照模板的安装步骤完成模板安装: 安装papermod 需要注意的是,安装模版的命令行代码需要输入在hugo博客文件夹的命令行中, 而不是我们第三步中创建的博客项目文件夹。也就是说,我们需要进入第四步创建的“yourblogname”文件夹 的终端中输入模板提供的安装语句:

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

导入模版后,我们还需要修改本地的配置文件(通常是config.yaml),这里大家需要根据不同的模板灵活操作一下。 一般来说,模板会提供一个yaml文件在examplesite文件夹中,有的模板会在你导入的时候默认下载这个examplesite文件夹, 有的则不会,具体请详细查阅你选择的那个模板的安装手册。例如,我这个papermod模板就没有自动下载examplesite文件夹, 因为它没有把examplesite放在模板仓库的主分支里,而是单独开了一个分支,不过无伤大雅,我们可以在安装手册里找到这个示例文件:

baseURL: "https://examplesite.com/"
title: ExampleSite
paginate: 5
theme: PaperMod
......
后续内容省略

一般情况下,我们只需要把这个文件的内容完完整整地复制到“yourblogname”文件夹的 yaml文件里,然后把开头的baseURL中的examplesite.com换成github的username.github.io,同时它也是第一步 创建仓库中的public仓库的名字,例如,我这里的baseurl就是parzival-chen.github.io.


第五步 本地博客调试

进入hugo博客文件夹的命令行,(也就是“yourblogname”文件夹)输入

hugo new post/test.md

然后输入

hugo server -D

接着复制命令行里给出的网址,一般是http://localhost:1313/, 在浏览器中打开,如果能正常显示模版网页以及我们刚刚创建的test帖子, 那么恭喜你已经初步完成了个人博客的搭建了!

需要注意的是,如果只显示了模板网页却没有显示test帖子,那么这种情况也是有问题的, 也许你需要仔细回顾一下之前的步骤,看看有没有纰漏。

更进一步,你可以在文件夹里找到test文件,然后进行一些详细的编辑,例如输入更多的内容, 或者是把draft = true中的true改为false,这样静态内容的搭建就只需要输入 hugo server了。(因为hugo server -D会显示草稿内容)

接着回到浏览器里的网页,看看自己更新的内容有没有同步显示,如果万事大吉, 那么我们可以继续往下走了!


第六步 Github Action 自动发布博客

现在来到github的博客源仓库,也就是第一步创建的那个名字随意的私有仓库, 点击“add new file”,然后我们创建一个新的文件,命名为 .github/workflows/gh-pages.yml,这里不建议复制,最好是自己手打一下, 然后github会为你在当前路径自动创建.github文件夹和workflows文件夹, 并在workflows文件夹里创建一个yml文件,接着在这个yml文件里输入:

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: 'latest' 
          extended: true # 是否启用hugo extended

      - name: Build
        run: hugo --minify
        working-directory: ./myblog # 注意修改成你使用hugo创建的项目名称

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          PERSONAL_TOKEN: ${{ secrets.ACTION_TOKEN }}
          PUBLISH_DIR: ./myblog/public # 注意修改成你使用hugo创建的项目名称
          EXTERNAL_REPOSITORY: parzival-chen/parzival-chen.github.io # 你的Github Pages远程仓库名
          

注意! working-directory和 PUBLISH_DIR中的myblog请修改为“yourblogname”,也就是第四步中的 hugo new site yourblogname中的name,同时也应该是hugo文件夹的名字。 然后,EXTERNAL_REPOSITORY的内容修改为username/username.github.io,第一个username表示是你的github账户, 后面的username.github.io是你在第一步中创建的public仓库名称,千万不要漏掉一个username😂

接着在github页面里点击右上角的头像进入github profile,点击“Settings”, 接着在左侧导航栏最下方点击“Developer Settings”,然后点击“personal access tokens” 和“Tokens(classic)” github generate new token 右侧点击“Generate new token” token权限 expiration自己选择,我本人图偷懒,选了永不过期😂 注意!一定要勾选“repo”和“workflow”两个选项,剩余的权限是否开放看你个人需求。

注意!这个token生成后只会展示一次!所以你需要立刻把它保存到某个地方而不是只留在你的剪切板里。

接下来我们来到github的博客源仓库,上方导航栏里点击“Settings”,再点击左侧导航栏的“Secrets and variables” 博客源仓库的repo secret 点击“Actions”,右侧点击“new repo secret” ActionToken name输入 “ACTION_TOKEN”(这是因为我在刚刚的gh-pages文件里设置personaltoken的值为 ACTION_TOKEN,事实上你可以自定义这个值,只需要保证二者一致即可)

Secret的内容就是刚刚新鲜出炉的Token内容,如果你已经关掉了刚刚那个页面并且碰巧没有复制或者保存, 也无伤大雅,只需要把刚刚那个token删掉,然后按照上面的步骤生成一个新的即可。

然后进入博客源文件夹的命令行,不是hugo文件夹,是第三步创建的那个总项目文件夹! 首先来一个git pull,然后奉上丝滑的更新小连招

Git add .
Git commit -m “请描述你的更改”
Git push origin main

然后回到github的博客源仓库页面 博客源仓库更新 如果这里的“请描述你的更改”后面是✅,就说明这一步更新推送成功了 如果是❌,可以点击Actions,找到详细的报错信息,然后进行后续调试和修改 github actions报错修改

接下来我们来到github的public仓库,也就是你的username.github.io仓库,点击“Settings”, 左侧导航栏点击“Pages” public仓库修改pages分支 在“Build and development”下,“Source”一定要选择“Deploy from a branch”, 然后下面的branch选择“gh-pages”,后面的路径选“root”,然后点“save”保存。

顺便一提,为了方便起见,我们可以把这个public仓库的默认branch改成gh-pages, 这样每次打开仓库首页都会展示gh-pages的内容(在Settings的General页面修改)

至此,大功告成!(真告成吗?)

你只需要在浏览器里输入username.github.io即可访问你的个人博客。

需要注意的是,username.github.io能展示一个模板博客不代表你已经完全成功,你最好在hugo博客文件夹的 命令行里输入hugo server,然后在浏览器里打开那个本地构建的博客,对照一下二者的内容和功能是否完全一致。 如果博文没有正确显示,请检查一下博文文件里的drafts:true,你是否把true改成了false。


第七步 关联自定义域名

首先,你需要拥有一个自己的域名,我本人比较建议在国际域名商租用域名, 因为国内域名还会牵扯到备案的问题,整体步骤上比较麻烦。

剩下的步骤可以参考一下gh-pages如何关联自己的域名,本人实在是懒得写了😂


常见错误解答:

  1. 关联自定义域名后,每次更新仓库都会导致gh-pages与自定义域名的关联失效: 我们注意到,在public仓库的设置里关联自定义域名后,仓库会自动创建一个CNAME文件, 文件内容就是我们自己的域名。但是在本地推送blog仓库更新后,blog仓库会把本地的public文件夹 覆盖云端public仓库,Cname文件消失,导致域名关联失效。 解决办法是在本地博客文件夹的public文件夹里创建一个一模一样的CNAME文件,推送更新后再在public仓库 的设置里更新关联自定义域名。
  2. 无法正常插入图片,本地markdown编辑器里能看到,但是网页博客里看不到图片。 这一点请参考id6,解决办法是在post里为每一篇博文都创建一个文件夹。 例如我有一篇博文叫《搭建个人博客》,那么我先在post文件夹里创建一个叫做“搭建个人博客”的文件夹, 再创建一个同名的md文件,然后把需要用到的图片都放到这个文件夹里,网页端就可以正常渲染了。
  3. 博文没有正确显示,请检查一下博文文件里的drafts:true,你是否把true改成了false。
  4. 配置Github Action时报错“找不到hugo博客文件夹的文件路径”, 反馈这个报错的朋友把博客总项目文件夹和hugo文件夹放在了平行位置,所以出现了这个问题, 因为我们配置的github action是在博客总项目的远程仓库配置的,它会在本仓库的路径下去寻找hugo文件夹, 所以请大家认真阅读帖子,我在创建hugo文件夹那一部分也贴上了配图,提醒大家hugo new site要在博客项目文件夹的命令行里输入。
  5. hugo文件夹或者是hugo里面的public文件夹和github仓库没有任何直接关系。我们在github一共创建了两个仓库,一个私人的博客总项目仓库, 另一个是用于展示发布内容的public仓库,其中,只有私人的博客项目仓库和本地的博客项目文件夹建立了直接的链接,而公共的public仓库和本地文件夹之间没有任何关系, 我们发布博客内容的本质方法是通过github action把博客项目仓库的hugo文件夹里面的public文件夹的内容传到了github的public仓库。
  6. 截屏直接粘贴版本
  7. 截屏2024-09-14 01.19.51.png
  8. 截屏测试111