[详细]vuepress-theme-hope搭建博客

前言

市面上的博客框架有很多,鉴于vuepress是静态博客框架,可以部署到GitHub Pages而不用自己提供服务器,并且对前端也非常友好,因此我选择了vuepress,主题选用了vuepress-theme-hope。

准备工作

mkdir vuepress-demo
cd vuepress-demo
npm init vuepress-theme-hope docs

这里的 docs 是一个参数,代表 VuePress Theme Hope 项目的文件夹名称,将项目生成至当前目录下的 docs 文件夹。

创建项目时的选项,需要注意的是:
1.如果不想部署到服务器,想部署到GitHub Pages,记得选需要自动部署的工作流
2.创建的项目类型,推荐使用blog,但在此之前也可以先去了解一下docs和blog的界面区别

npm run docs:dev

此时访问localhost:8080即可看到博客页面。

博客配置

先附上官网链接:vuepress-theme-hope文档
具体配置可以直接看官网文档说明。

基本配置

简洁地说就是,navbar下放的是有关顶部导航栏的配置;public放你需要的静态文件,使用的时候根目录直接用/来表示,比如需要用到/public/assets/logo.png,在配置文件的选项中直接输入/assets/logo.png即可;sidebar用来配置侧边栏;主页用README.md来配置;theme.ts放的是主题选项;config.ts放的是站点选项。默认支持两种语言的配置。

博客文章靠markdown文档实现,一级标题不会产生侧边栏,所以正文内标题都要从二级标题开始,第一个标题作为文章的名称。tag和category可以定义文章标签和分类。增加新页面时,.vuepress/.temp/interval/pagesData和pagesComponents都会自动产生对应内容。

部署到GitHub Pages

创建仓库

首先要创建一个公开的仓库。

config.ts中的base配置项决定了你创建仓库的名字格式。

1.如果发布到 https://< USERNAME >.github.io,base就默认是"/",不用修改,但新建的仓库名称必须为:< USERNAME >.github.io,也就是你的仓库地址为https://github.com/< USERNAME >/< USERNAME >.github.io。

2.如果要发布到 https://< USERNAME >.github.io/< REPO >,那么仓库名就为< REPO >,相应地,base配置项要修改成"/< REPO >/"。

创建完成后,在仓库内选择Settings选项,选择Actions下的General,在 Workflow permissions中开放读写权限 Read and write permissions。

提交代码

git init
git add .
git commit -m "第一次提交"
git branch -M main
git remote add origin [email protected]:xxx/xxx.git // 你的仓库地址
git push -u origin main

设置部署分支

打包后的内容会在src/.vuepress/dist中,工作流会自动把这个目录里的内容推送到gh-pages分支中。所以在仓库中,选择Settings-Pages选项,在Build and deployment配置中,将分支从main切换到gh-pages,这意味着这个github页面站点将会从gh-pages分支构建。

切换部署分支后 ,项目会重新执行一次工作流,之后即可访问https://< USERNAME >.github.io/< REPO >来查看博客页面了。

使用deploy.sh脚本实现一键部署到GitHub Pages

在项目的根目录中创建deploy.sh,把以下代码按照你自己的情况进行修改然后复制粘贴。

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd src/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://.github.io
# git push -f [email protected]:/.github.io.git master

# 如果发布到 https://.github.io/
git push -f [email protected]:xxx/xxx.git master:gh-pages

cd -

之后每次在本地更新的时候,直接运行该脚本即可自动部署到github pages中,成功后会发现每次运行脚本,仓库中的gh-pages分支都会有新的提交,从此解放双手
运行脚本可以双击运行或者在Bash命令窗中直接输入脚本文件的相对路径。

整合giscus实现评论功能

在博客项目运行在本地时可能会碰到一个情况就是,本地明明有评论区的功能,为什么部署到gh-pages反而没有了。这是因为远程仓库没有整合评论系统。这里我们选用giscus。

在仓库中选择Settings选项卡,在Features配置项中勾选Discussions。之后在Discussions选项卡中可以选择创建一个新的分类Category,也可以用已有的分类。

然后可以按照giscus文档去进行配置,配置项根据自己的情况选择(页面-讨论映射推荐选URL那个),但是在此之前要先去下载giscus app,并且只对选中的仓库使用该功能。

在前面的内容都完成之后,可以打开本地项目中的config.ts去配置giscus。将【启用giscus】部分里的内容填到对应的配置项,具体可以查看vuepress插件文档

npm i -D vuepress-plugin-comment2
import { commentPlugin } from "vuepress-plugin-comment2";

export default defineUserConfig({
  // 站点选项
 //...省略前面的配置
  plugins: [
    // 配置评论
    commentPlugin({
      provider:"Giscus",
      repo:"",
      repoId:"",
      category:"",
      categoryId:"",
      lazyLoading:true,//懒加载
      strict:false,
      mapping:"url",
      inputPosition:"top",
      reactionsEnabled:true,
    }),
  ],
});

完成后运行脚本部署到gh-pages中,刷新博客地址即可看到效果。

最后

笔者运行自己的博客时感觉打开速度还是比较慢,之后可能会考虑增加CDN优化gh-pages的说明。

你可能感兴趣的:(github,前端,vue)