基于VuePress搭建博客系统及优化过程(持续更新...)

作者:duktig

博客:https://duktig.cn (文章首发)

优秀还努力。愿你付出甘之如饴,所得归于欢喜。

本篇文章将持续更新个人博客平台并置顶:基于VuePress搭建博客系统及优化过程(持续更新…)

博客预览

在这里插入图片描述

本地搭建

直接基于主题 vuepress-theme-reco 进行搭建。

执行初始化命令

方式一:npx

npx @vuepress-reco/theme-cli init 
npx @vuepress-reco/theme-cli init [文件夹名字]

方式一:npm

npm install @vuepress-reco/theme-cli -g theme-cli init
npm install @vuepress-reco/theme-cli -g theme-cli init [文件夹名字]

注意:init 后可以直接加文件夹根目录,避免初始化时需要再次生成目录(不创建目录执行,会发生些报错)。

image-20220118213937581

上图这个步骤,What style do you want your home page to be? 有三个选项,分别是:

  • blog(推荐
  • doc(和blog几乎一致,只不过 init 执行中输入的信息未应用,存在一些问题)
  • 2.x(目前还不成熟)

三个版本测试的时间为:2022.01.18

安装依赖

cd [文件夹名字]
npm install

本地运行

npm run dev

.vuepress/config.js 配置

修改静态文件输出目录

在 vuepress-theme-reco 主题中,"dest" 的值为public;在 vuepress 官方中,"dest" 的值为.vuepress/dist

这个值意为,执行 npm run build 后,静态资源目录生成的位置,会影响到后边GitHub Actions的配置

这里我们将"dest" 的值为.vuepress/dist

部署上线

方式一:GitHub Actions 自动部署

主分支存放代码,gh-pages 用于展示内容。

设置 Secrets

后面部署的 Action 需要有操作你的仓库的权限,因此提前设置好 GitHub personal access(个人访问令牌)。

生成教程可以看 GitHub 官方的帮助文档:创建用于命令行的个人访问令牌 (opens new window)

授予权限的时候只给 repo 权限即可。

1W3GRA.png

令牌名字一定要叫:ACCESS_TOKEN,这是后面的 Action 需要用的。

1W35i4.png

编写 workflow 文件

持续集成一次运行的过程,就是一个 workflow(工作流程)。

创建.github/workflows/main.yml文件,内容如下:

name: Deploy GitHub Pages

# 触发条件:在 push 到 master 分支后
on:
  push:
    branches:
      - main

# 任务
jobs:
  build-and-deploy:
    # 服务器环境:最新版 Ubuntu
    runs-on: ubuntu-latest
    steps:
      # 拉取代码
      - name: Checkout
        uses: actions/checkout@v2
        with:
          persist-credentials: false

      # 生成静态文件
      - name: Build
        run: npm install && npm run build

      # 部署到 GitHub Pages
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .vuepress/dist # 静态资源目录

需要了解 workflow 的基本语法可以查看官方帮助 (opens new window),也可以参考阮一峰老师的 GitHub Actions 入门

具体参看文章:使用 GitHub Actions 自动部署博客

设置GitHub Pages

image-20220118233652096

方式二:两个仓库

新建仓库一: USERNAME.github.io (不用克隆到本地)

USERNAME 必须是你 Github 的账号名称,这个仓库用来展示博客。

新建仓库二:随便起一个名字,比如:vuepressBlog (克隆到本地)

这个项目是用来开发博客的,以后只需要改这个项目就够了。

创建部署脚本:

#!/usr/bin/env sh

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

# 生成静态文件
npm run build

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

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

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

# 如果你想要部署到 https://USERNAME.github.io
git push -f git@github.com:USERNAME/USERNAME.github.io.git master

# 如果发布到 https://USERNAME.github.io/<REPO>  REPO=github上的项目
# git push -f git@github.com:USERNAME/<REPO>.git master:gh-pages

cd -

修改仓库二中的 deploy.sh 发布脚本,把文件中的 USERNAME 改成 Github 账号名。

这样仓库二和仓库一就建立了关联。

简单说二者的关系是:仓库一负责显示网站内容,我们不需要改动它;日常开发和新增内容,都在仓库二中,并通过 npm run deploy 命令,将代码发布到仓库一。

在 package.json 文件夹中添加发布命令
"scripts": {
  "deploy": "bash deploy.sh"
}
运行发布命令
npm run deploy

添加自定义域名

在仓库一 USERNAME.github.io 中找到 Settings > Custom domain 把 域名 添加进去即可。

具体参看文章:手把手教你使用 VuePress 搭建个人博客 (文中含有部署相关)

vuepress-theme-reco 主题优化

代码块样式选择

// .vuepress/config.js

module.exports = {
  theme: 'reco',
  themeConfig: {
    /**
     * support for
     * 'default'
     * 'funky'
     * 'okaidia'
     * 'solarizedlight'
     * 'tomorrow'
     */
    codeTheme: 'tomorrow' // default 'tomorrow'
  }
}

参看:prism代码高亮主题风格展示阁

vuepress-theme-reco 1.6.10版本,设置代码样式失效,详情参看:issues#397

评论系统

评论系统可以使用 Valine 或 Vssue。

两者对比:

Valine

  1. 支持的功能更多。比如邮件提醒、文章阅读量统计(文章多的时候会影响一定的性能)、自定义表情等。

  2. 使用的是Gravatar 作为评论列表头像,需用户注册和配置。

  3. 样式预览:

    image-20220124210601486

Vssue

  1. 最大的特性是支持 GitHub 登录。
  2. 基于 Issues 实现的评论系统。

这里暂时先使用 Vssue 搭建评论系统,详情可参看:

PWA 刷新插件

安装

npm install -D @vuepress/plugin-pwa

使用

本选项开启了一个用于刷新内容的弹窗。这个弹窗将会在站点有内容更新时显示出来,并提供了一个 refresh 按钮,允许用户立即刷新内容。

如果没有“刷新”按钮,则只有在所有的 Clients (opens new window)被关闭后,新的 Service Worker 才会处于活动状态。这意味着用户在关闭你网站的所有标签之前无法看到新内容。但是 refresh 按钮会立即激活新的 Service Worker。

['@vuepress/pwa', {
    serviceWorker: true,
    updatePopup: {
        message: "发现新内容可用",
        buttonText: "刷新"
    }
}],

音乐播放器插件

音乐插件选用:meting

// 音乐插件
['meting', {
    //metingApi: "https://meting.sigure.xyz/api/music",
    meting: {
        // 网易
        server: "netease",
        // 读取歌单
        type: "playlist",
        mid: "696441716",
    },          
    // 不配置该项的话不会出现全局播放器
    aplayer: {
        // 吸底模式
        fixed: true,
        mini: true,
        // 自动播放
        autoplay: true,
        // 歌曲栏折叠
        listFolded:true,
        // 颜色
        theme: '#f9bcdd',
        // 播放顺序为随机
        order: 'random',
        // 初始音量
        volume: 0.1,
        // 关闭歌词显示
        lrcType: 0
    },
    mobile :{
        // 手机端去掉cover图
        cover: false,
    }
}]

好用的MarkDown扩展语法

完整的md扩展,参看:https://vuepress.vuejs.org/zh/guide/markdown.html

GitHub 风格的表格

输入

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

输出

TablesAreCool
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare neat$1

Emoji

输入

:tada: :100:

输出

🎉 💯

你可以在这个列表 (opens new window)找到所有可用的 Emoji。

目录

[[toc]]

自定义容器 (默认主题)

输入

::: tip
这是一个提示
:::

::: warning
这是一个警告
:::

::: danger
这是一个危险警告
:::

::: details
这是一个详情块,在 IE / Edge 中不生效
:::

代码块中的行高亮

输入

```js {4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

以上例子会在 第四行代码 加高亮显示。

除了单行以外,你也可指定多行,行数区间,或是两者都指定。

  • 行数区间: 例如 {5-8}, {3-10}, {10-17}
  • 多个单行: 例如 {4,7,9}
  • 行数区间与多个单行: 例如 {4,7-13,16,23-27,40}

问题及解决

1. md文件名有中文不能正常路由跳转?

方法一:添加文件.vuepress/enhanceApp.js

添加文件.vuepress/enhanceApp.js,写入以下内容

export default ({
    router, // 当前应用的路由实例
}) => {
    // 解决中文路由无法被正确加载的问题
    router.beforeEach((to, from, next) => {
        if (decodeURIComponent(to.path) !== to.path) {
            return next({
                ...to,
                path: decodeURIComponent(to.path),
                fullPath: decodeURIComponent(to.fullPath)
            })
        }
        next()
    })
}

vuepress-theme-reco 版本为 1.6.10 使用这种方式依然没有解决问题。

方法二:使用插件 vuepress-plugin-permalink-pinyin

但是原有的中文路由会转为拼音

当文件名含有中文时,对应页面无法跳转,可通过如下插件解决这个问题,这个插件会将中文路径转换为拼音路径

本地安装:

npm install -D  vuepress-plugin-permalink-pinyin

然后配置插件:

module.exports = {
  plugins: [
      // 支持中文文件名
      [
        "permalink-pinyin",
        {
          lowercase: true, // Converted into lowercase, default: true
          separator: "-", // Separator of the slug, default: '-'
        },
      ],
  ]
}

vuepress-theme-reco 1.6.10 配置如下 永久链接格式,会导致插件 vuepress-plugin-permalink-pinyin 中文路由转拼音失效

module.exports = {
    permalink: "/:year/:month/:day/:slug",
};

参看:https://github.com/vuepress-reco/vuepress-theme-reco/issues/395

2. 文章一级标题不在目录中显示

vuepress-theme-reco 中,请摒弃一级标题,使用 front-matter 生成标题以及其他文章信息,正文从二级标题开始。

参看

  • 3
    点赞
  • 10
    收藏
    觉得还不错? 一键收藏
  • 1
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值