【搭建博客】在GitHub上使用vitepress快速搭建博客

·  阅读 2168

最近想好好把自己的Github好好营业一下,于是开始了营业的第一步:搭建博客!

花了半天时间搭建博客: gelxgx.github.io/blog/

  • 创建博客仓库

  • 设置GitHub pages

  • 克隆vitepress模板

  • 修改博客内容,提交代码

  • 搞定!

这看上去是一个不太复杂的流程,但是作为第一次搭建踩了不少搭建流程、插件使用的坑,写篇博客总结记录一下

1. 创建博客仓库

Create a new repository

我多勾选了一个README文件

一个博客仓库就创建好了~

2. 设置GitHub pages

进入博客的仓库,选中顶部的Settings,选择Pages选项

设置好对应的Source,以及需要读取的目录地址,点击Save,稍等一小小会

就会生成一个属于自己的博客地址,一般都会以github.io为开头的域名

点击之后就进入到自己的博客页面了!

3. 部署vitepress项目

我这里使用了一个阅读源码同组纪年小姐姐的项目进行克隆,非常感谢这位小姐姐~里面已经预设好了主题,只需要进行内容修改即可,当然有兴趣的话也可以自己从0搭建博客主题

小姐姐的博客:jexlau.github.io/blog/

克隆项目:

git clone https://github.com/JexLau/blog.git
cd blog

# 安装依赖
yarn

# 在本地启动服务器
yarn dev

# 构建静态文件 > .vitepress/dist
yarn build
复制代码

至此,已经拿到一个博客的模板了,模板文件目录结构如下图所示,接下来需要对博客内容进行修改~

  • .vitepress 是项目页面的配置

  • docs中用于存放自己的md文档

  • more中用于存放导航栏的标签

另外项目中还内置了Gitalk评论功能,这部分配置起来会有一些小坑,一会再说~

最重要的一步!修改打包产物部署的地址

进入deploy.sh页面 修改git push -f 的地址为自己名下的仓库地址

配置好页面、文章内容后,提交代码至origin main分支,最后在本地npm run deploy即可完成博客的部署~

此时如果使用的是MacOS系统,执行时可能会报错command not found: deploy.sh,此时可以进入package.json修改路径为./deploy.sh从当前路径查找。

接着可能又会提示Permission denied,没有权限,执行chmod 777 deploy.sh 此时再进行npm run deploy即可完成博客项目的部署

部署完成后,我们需要再次进入Settings-Pages-Source路径,将博客读取路径Branch改为gh-pages,点击Save即可完成页面的部署,再次进入博客时,就能完美展示自己的博客啦~

4. 一些小坑

这部分的坑主要为Gitalk配置的坑,主要表现为:

  • 初始化时字段配置
  • issues配置

4.1 配置Gitalk

项目中Gitalk存放于.vitepress/theme/components/Comment.vue

进入右边这个链接,申请一个OAuth application 允许程序操作你的GitHub账号,github.com/settings/ap…

Application name:必填,OAuth的名字
Homepage URL:必填,你应用的网址,哪个网站用了Gitalk组件,就填写这个网址
Application description:选填,该OAuth的说明
Authorization callback URL:必填,授权成功后回调网址,跟Homepage URL参数保持一致就好
这些参数在注册成功后是可以修改。

填写好后点击Register Application完成注册

注册成功后

复制自己的clientID以及生成并复制一个clientSecret

主要的参数为以下这几个配置:

var gitalk = new Gitalk({
  clientID: '', // GitHub Application Client ID
  clientSecret: '',
  repo: 'blog'      // 存放评论的仓库
  owner: 'gelxgx',          // 仓库的创建者,
  admin: ['gelxgx'],        // 如果仓库有多个人可以操作,那么在这里以数组形式写出
  id: decodeURI(window.location.pathname),      // 用于标记评论是哪个页面的
  proxy: 'https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token'  //避免跨域
})
复制代码

设置完成之后通常会有一个报错:未找到相关Issues进行评论,请联系@XXX 初始化创建

此时的解决方案为:

进入设置issues的仓库中,创建一条issues,并设置两个location

  • Gitalk
  • id(window.location.pathname)

再次刷新页面,即可正常显示

5. 自动化部署

每次提交博客更新时,都需要手动在本地进行一次npm run deploy进行页面打包部署,太麻烦了,于是我打算做一个自动化处理:

  • 提交代码时,自动进行打包
  • 将打包产物自动提交部署至gh-pages

这部分需要调用到仓库的Action能力~

5.1 创建Action

进入博客仓库中,点击Aciton,选择new workflows,这里我没有选模板,直接set up a workflow yourself

首先给自己的流水线起一个好听的名字,并复制以下代码进入配置中

name: pushDocs

on:
  // 配置当push进入什么分支的时候执行
  push:
    branches: 
     - main


jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

     // 具体的执行步骤
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Checkout
        uses: actions/checkout@main

     // 使用的node版本   
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@main
        with:
          node-version:  ${{ matrix.node }}
      
		// 执行安装
      - name: Install dependencies
        run: npm install
    
    // 执行打包
      - name: Build VuePress
        run: npm run build
      
    // 执行部署
      - name: Deploy to Pages
        run: |
          cd .vitepress/dist 
          git init
          git config user.name "gelxgx"
          git config user.email "${{ secrets.GIT_EMAIL }}"
          git add -A
          git commit -m 'deploy'
          git push -f https://gelxgx:${{ secrets.ACCESS_TOKEN }}@github.com/gelxgx/blog.git master:gh-pages
          cd -
复制代码

部署的过程中需要使用到secrets.GIT_EMAILsecrets.ACCESS_TOKEN

5.1 生成secrets.GIT_EMAIL

进入仓库的Setting->Secrets->new

name部分填写GIT_EMAIL,value填写要提交的账号

5.2 生成ACCESS_TOKEN

进入GitHub token 如下图所示,生成一个无限期且勾选repo&workflow的token

点击生成,生成完成之后,以同样的方式new Secret即可完成流水线的配置~

此时只需要我们对博客提交一次代码,进入Action即可查看执行的流程~

如果出现红色感叹号,那就是配置有误,点击进入即可看到具体的报错信息

6. 总结

作为一名切图仔,之前从来没有重视过自己的GitHub,最近更换了新设备,有了梯子,打算将自己的沉淀都迁移至GitHub中

于是花了半天的时间进行了博客的搭建,总的来说够用了【doge】

后续还打算继续部署一些自动化工程,让博客文章同步效率更高~

特别感谢:

Gitalk使用教程:segmentfault.com/a/119000001…

Gitalk中文文档:

Gitalk报错解决:blog.csdn.net/liu13403083…

自动化部署:juejin.cn/post/699719…

分类:
前端
标签:
收藏成功!
已添加到「」, 点击更改