博客主页 😑

Author:

公爵

©

Wordage:

共计 12672 字

needs:

约 6 分钟

Popular:

5 ℃

Created:

目 录

VuePress 介绍

简单介绍一下,VuePress 是尤雨溪 2018 年 04 月 12 日发布的 Vue 静态网站生成器,支持 Vue 语法,内置 webpack,每一个由 VuePress 生成的页面都是通过 SSR 预渲染的 HTML,也因此具有非常好的加载性能和搜索引擎优化。

个人觉得最大的亮点就是:

  1. markdown 文件可以内嵌 Vue 组件
  2. 借助 YAML 来作为驱动和配置文档

安装

在已有项目中安装

如果你想要在一个已有项目中维护文档,就应该将 VuePress 安装为本地依赖。此设置还允许你使用 CI 或 Netlify 服务,在推送时自动部署。

安装为本地依赖项

# 安装为本地依赖项
npm install -D vuepress

初始化项目

# 可以使用 npm 来初始化项目,会生成 package.json
npm init -y

然后在项目的根目录下新建一个 docs 文件夹,以后我们写的 markdown 文件都会放在 docs 文件夹下。

# 创建一个 docs 目录
mkdir docs
# 创建一个 markdown 文件
echo # Hello VuePress > docs/README.md

执行本地服务器启动命令:

vuepress dev docs

就可以看到启动了一个页面:

image-20200426193547122

为了后续运行方便,我们可以把这些命令写在项目的 package.json 文件里面的 scripts

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs",
    "deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
  }
}

然后你就可以开始编写文档了:

执行本地服务器启动命令:

yarn dev # 或者:npm run dev

要生成静态资源(HTML 文件),请运行:

yarn build # 或者:npm run build

默认情况下,构建的文件会位于 .vuepress/dist 中,该文件可以通过 .vuepress/config.js 中的 dest 字段进行配置。构建的文件可以部署到任何静态文件服务器。

目录结构

VuePress 遵循 “约定优于配置” 的原则,推荐的目录结构如下:

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
  • docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
  • docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
  • docs/.vuepress/theme: 用于存放本地主题。
  • docs/.vuepress/styles: 用于存放样式相关的文件。
  • docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级。
  • docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量,或者设置新的 stylus 颜色常量。
  • docs/.vuepress/public: 静态资源目录。
  • docs/.vuepress/templates: 存储 HTML 模板文件。
  • docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
  • docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
  • docs/.vuepress/config.js: 配置文件的入口文件,也可以是 YMLtoml
  • docs/.vuepress/enhanceApp.js: 客户端应用的增强。

基本配置

目前我们只写了一个 markdown 文档,所以只有一个页面,后续我们的博客会陆续加入很多内容,肯定需要做目录分级,配置导航栏,可以看文档里的这部分

官网说明的已经很详细,不妨直接看官网,走起:默认主题设置,如果后面针对于文档网站做个性化优化,会放在下面 "优化文档" 这一标题下说明。

部署

下述的指南基于以下条件:

  • 文档放置在项目的 docs 目录中;
  • 使用的是默认的构建输出位置;
  • VuePress 以本地依赖的形式被安装到你的项目中,并且配置了如下的 npm scripts:
{
  "scripts": {
    "deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
  }
}
  1. docs/.vuepress/config.js 中设置正确的 base

image-20200426182800772

module.exports = {
  base: '/vuepress-demo/',
}
  1. 在你的项目中,创建一个如下的 deploy.sh 文件(根据实际情况修改):
#!/usr/bin/env sh

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

# 生成静态文件
npm run build

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

# 如果是发布到自定义域名
# echo 'www.example.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>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

GitHub Actions 自动构建/部署

大家有注意到 GitHub 悄悄上线了一个 Actions 功能吗?还不了解的同学可以看这篇文章,写的非常全面。

GitHub Actions 是什么

GitHub 官方号称 Actions 可以让你的工作流自动化:GitHub 监听某个事件(可能是某个分支的提交),然后触发你预定义的工作流,让大家在GitHub服务器上直接测试代码、部署代码。所以,我们可以利用这里特性来做 CI/CD,开发者只要写一下 workflow 脚本就可以了,不用费心思去想要用哪个第三方的 CI/CD 服务, ?。

actions 其实就是由一些脚本组成,所以它们是可以复用的,GitHub 做了一个官方市场,可以搜索到他人提交的 actions。另外,还有一个 awesome actions 的仓库,也可以找到不少 action。这样一来,你甚至都不用自己写具体的脚本,直接引用别人的脚本就行啦。

话不多说,赶紧用起来!

写 workflow 脚本

首先我们需要到项目仓库的页面上进入 Actions 这个 tab, 选择 Node 环境进入脚本的编辑页面

image-20200426201144851

这里我直接使用了 peaceiris 的 actions-gh-pages,这个 action 可以帮你把打包好的静态文件部署到 GitHub Pages 上去。

最终我的 workflow 脚本如下:

# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: vuepress-demo
on:
  push:
    branches:
    - master

jobs:
  build-deploy:
    runs-on: ubuntu-18.04
    steps:
    - uses: actions/checkout@master

    # - name: Setup Node
    #   uses: actions/setup-node@v1
    #   with:
    #     node-version: '10.x'

    # - name: Cache dependencies
    #   uses: actions/cache@v1
    #   with:
    #     path: ~/.npm
    #     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    #     restore-keys: |
    #       ${{ runner.os }}-node-

    - run: npm ci

    - run: npm run build

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      env:
        ACTIONS_DEPLOY_KEY: ${{ secrets.ACCESS_TOKEN }}
        PUBLISH_BRANCH: gh-pages
        PUBLISH_DIR: docs/.vuepress/dist

注意

因为我用的 action 是第三方的,所以 action 可能会经常更改,如果你是过了一段时间才看到这篇文章,peaceiris 的 actions-gh-pages 很可能已经发生了更新,所以脚本的内容建议直接参照它的官方文档来写。

更详细的语法可以去看 GitHub Actions 的官方文档

注意

设置 workflow 的环境变量

因为我们需要 GitHub Actions 把构建成果发到 GitHub 仓库,因此需要 GitHub 密钥,相当于是给 GitHub actions 授权。

首先运行下面的命令生成一对密钥:

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
#   gh-pages.pub (public key)
#   gh-pages     (private key)

像这样:

image-20200426202933017

密钥在这:

image-20200426203943738

然后:

  1. 在博客项目的仓库的 Settings 栏下,找到 Deploy keys这一项,把你的公钥加进去,注意勾选Allow write access
  2. 同样在博客项目的仓库的 Settings 栏下,找到 Secrets这一项,把你的私钥加进去

image-20200426203453041

image-20200426203753813

如图显示即成功:

image-20200426203837992

image-20200426203823746

优化文档

图片放大显示

1 安装插件

npm install -D @vuepress/plugin-medium-zoom

2 使用

module.exports = {
  plugins: ['@vuepress/medium-zoom']
}

3 效果图

配置 Google Analytics

网站搭建好了,也有人访问了,那我们要怎么统计用户的访问情况呢?可以使用谷歌出品的 Google Analytics (GA)。

Google Analytics (GA)是一个对用户活动进行追踪的工具,利用 GA 我们可以收集到博客当前有多少实时活跃用户,博客的总访问量,以及分析用户的一些访问行为,便于我们对博客网站做一些优化,而且它还是免费的!赶快用起来!

1 下载 google-analytics 插件

yarn add -D @vuepress/plugin-google-analytics
# OR npm install -D @vuepress/plugin-google-analytics

安装完在 config 配置文件里面配置一下 plugins

module.exports = {
  plugins: [
    [
      '@vuepress/google-analytics',
      {
        'ga': '' // UA-00000000-0
      }
    ]
  ]
}

2 注册 GA,获取追踪 ID

上面那个 ga ID从哪里获取呢?别着急,我们需要到 Google Analytics 的官网上去注册一下我们的博客应用:

image-20200427080359014

创建账号:

image-20200427080425558

image-20200427080511842

根据实际情况设置:

image-20200427080634915

然后就会获得追踪 ID,

image-20200427080744798

把获取到的跟踪ID 填到上面?的ga这一项里面就好了。

插件-PWA

1 安装插件

yarn add -D @vuepress/plugin-pwa
# OR npm install -D @vuepress/plugin-pwa

2 添加插件信息

//config,js
module.exports = {
// ...
 plugins: [
    ['@vuepress/pwa', {
        serviceWorker: true,
        //指向自定义组件
        popupComponent: 'MySWUpdatePopup',
        updatePopup: {
            message: "新的风暴已经出现",
            buttonText: "盘他"
        }
    }]
 ]
}

serviceWorker 的作用大致就页面首次加载时会请求本地的serviceWorker.js 去比对各个文件的版本号
如果不一致则提示用户拉取更新

评论系统-Valine

方案一:valine 官方插件

参考:valine 官方安装教程

  • 获取APP ID 和 APP Key,请先登录或注册 LeanCloud, 进入控制台后点击左下角创建应用
  • 安装并使用 Valine

1 安装插件

npm install --save vuepress-plugin-comment

2 将 vuepress-plugin-comment 添加到vuepress项目的插件配置中:

module.exports = {
  plugins: [
    [
      'vuepress-plugin-comment',
      {
        choosen: 'valine', 
        // options选项中的所有参数,会传给Valine的配置
        options: {
          el: '#valine-vuepress-comment',
          appId: 'Your own appId',
          appKey: 'Your own appKey'
        }
      }
    ]
  ]
}

3 效果

image-20200427133728810

4 修改样式

创建 .vuepress/styles/palette.styl

写入:


#valine-vuepress-comment .veditor {
  min-height: 10rem;
  background-image: url(https://cos.gjcloak.xyz/CS-Notes/20200425091751.png);
  background-size: contain;
  background-repeat: no-repeat;
  background-position: right;
  background-color: rgba(255,255,255,0);
  resize: none;
}

.vat {
  color: #49B1F5 !important;
  font-size: 14px !important;
}
.vpower.txt-right {
  display: none;
}


#valine-vuepress-comment {
  max-width 740px
  padding 10px
  display block;
  margin-left auto;
  margin-right auto;
}

config.js 中写入:

const path = require('path')
palette: path.resolve(__dirname, 'palette.styl'),//样式修改

5 效果图

image-20200428090051466

建议使用方案一,方案二需要进行优化,因为 Valine 部分是被当作内容处理的,但是如果你非要使用方案二,可以把解决方案和我分享喔!

方案二:配合插件手写全局组件

1 安装 Valine

//Install leancloud's js-sdk
npm install leancloud-storage --save

//Install valine
npm install valine --save

2 注册 vuepress 全局组件

创建 .vuepress/components/Valine.vue

(在components下注册的 vue 可供全局使用,文件名为组件名)

<template>
    <div>
        <div id="vcomments"></div>
    </div>

</template>

<script>
    export default {
        name: 'Valine',
        mounted: function(){
            // require window
            const Valine = require('valine');
            if (typeof window !== 'undefined') {
                this.window = window
                window.AV = require('leancloud-storage')

            }

            new Valine({
                el: '#vcomments' ,
                appId: "KIlqXsCmzBUnovnvh5ih8mk9-gzGzoHsz",
                appKey: "e0v6zIg2NGg44PM6MVLa7voo",
                notify:false,
                verify:false,
                avatar: 'monsterid',
                placeholder: "你是我一生只会遇见一次的惊喜 ...",
                path:window.location.pathname,//配置path地址,否则评论混乱
            });
        },
    }
</script>
<style>
    #vcomments{
        margin-top:100px;
    }
</style>

3 使用 Valine

只需要在 markdown 中调用即可

<Valine></Valine>

4 效果

image-20200427134948583

也不错,只是评论被当作内容处理了……

不蒜子访问量统计功能

1 安装插件

yarn add busuanzi.pure.js
# or
npm install busuanzi.pure.js --save
还未实现,待完善

集成 UI 组件

vuepress 支持扩展,支持引入第三方组件,在 .vuepress/ 下创建 enhanceApp.js 文件,这里展示的是引入 vue 生态圈比较知名的ui库 Element, 来自于饿了么。

/**
 * 扩展 VuePress 应用
 */
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
  Vue, 
}) => {
  // ...做一些其他的应用级别的优化
  Vue.use(Element)
}

当然,在这之前,需要先安装 element。

yarn add element-ui
# or 
npm install element-ui --save

在扩展之后,就可以在自定义的组件或者 md 文件中,使用 element 的组件了。

共计 0 条评论,点此发表评论
萌ICP备20226257号 赣ICP备2022001242号-1 闽公网安备35020502000606号 本站已运行 253 天 8 小时 27 分 51统计 百度统计 本站由提供CDN加速服务 自豪地使用 Typecho 建站,并搭配 MyDiary 主题 Copyright © 2022 ~ 2022. 公爵书房 All rights reserved.
历史足迹
分类目录
  • 随笔
  • 知识
  • 分享
  • 书籍
  • 专栏
  • 笔记