VuePress 介绍
简单介绍一下，VuePress 是尤雨溪 2018 年 04 月 12 日发布的 Vue 静态网站生成器，支持 Vue 语法，内置 webpack，每一个由 VuePress 生成的页面都是通过 SSR 预渲染的 HTML，也因此具有非常好的加载性能和搜索引擎优化。
个人觉得最大的亮点就是：
- markdown 文件可以内嵌 Vue 组件
- 借助 YAML 来作为驱动和配置文档
安装
在已有项目中安装
如果你想要在一个已有项目中维护文档，就应该将 VuePress 安装为本地依赖。此设置还允许你使用 CI 或 Netlify 服务，在推送时自动部署。
安装为本地依赖项
bash 代码:# 安装为本地依赖项
npm install -D vuepress初始化项目
bash 代码:# 可以使用 npm 来初始化项目,会生成 package.json
npm init -y然后在项目的根目录下新建一个 docs 文件夹，以后我们写的 markdown 文件都会放在 docs 文件夹下。
# 创建一个 docs 目录
mkdir docs
# 创建一个 markdown 文件
echo # Hello VuePress > docs/README.md执行本地服务器启动命令：
bash 代码:vuepress dev docs就可以看到启动了一个页面：
为了后续运行方便，我们可以把这些命令写在项目的 package.json 文件里面的 scripts：
{
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs",
"deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
}
}然后你就可以开始编写文档了：
执行本地服务器启动命令：
bash 代码:yarn dev # 或者：npm run dev要生成静态资源（HTML 文件），请运行：
bash 代码:yarn build # 或者：npm run build默认情况下，构建的文件会位于 .vuepress/dist 中，该文件可以通过 .vuepress/config.js 中的 dest 字段进行配置。构建的文件可以部署到任何静态文件服务器。
目录结构
VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
bash 代码:.
├── 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.jsondocs/.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: 配置文件的入口文件，也可以是YML或toml。docs/.vuepress/enhanceApp.js: 客户端应用的增强。
基本配置
目前我们只写了一个 markdown 文档，所以只有一个页面，后续我们的博客会陆续加入很多内容，肯定需要做目录分级，配置导航栏，可以看文档里的这部分
官网说明的已经很详细，不妨直接看官网，走起：默认主题设置，如果后面针对于文档网站做个性化优化，会放在下面 "优化文档" 这一标题下说明。
部署
下述的指南基于以下条件：
- 文档放置在项目的
docs目录中； - 使用的是默认的构建输出位置；
- VuePress 以本地依赖的形式被安装到你的项目中，并且配置了如下的 npm scripts:
{
"scripts": {
"deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
}
}- 在
docs/.vuepress/config.js中设置正确的base。
>module.exports = {
base: '/vuepress-demo/',
}- 在你的项目中，创建一个如下的
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 环境进入脚本的编辑页面
这里我直接使用了 peaceiris 的 actions-gh-pages，这个 action 可以帮你把打包好的静态文件部署到 GitHub Pages 上去。
最终我的 workflow 脚本如下：
bash 代码:# 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 授权。
首先运行下面的命令生成一对密钥：
bash 代码: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)像这样：
密钥在这：
然后：
- 在博客项目的仓库的 Settings 栏下，找到
Deploy keys这一项，把你的公钥加进去，注意勾选Allow write access - 同样在博客项目的仓库的 Settings 栏下，找到
Secrets这一项，把你的私钥加进去
如图显示即成功：
优化文档
图片放大显示
1 安装插件
bash 代码:npm install -D @vuepress/plugin-medium-zoom2 使用
bash 代码:module.exports = {
plugins: ['@vuepress/medium-zoom']
}3 效果图
配置 Google Analytics
网站搭建好了，也有人访问了，那我们要怎么统计用户的访问情况呢？可以使用谷歌出品的 Google Analytics （GA）。
Google Analytics （GA）是一个对用户活动进行追踪的工具，利用 GA 我们可以收集到博客当前有多少实时活跃用户，博客的总访问量，以及分析用户的一些访问行为，便于我们对博客网站做一些优化，而且它还是免费的！赶快用起来！
1 下载 google-analytics 插件
bash 代码:yarn add -D @vuepress/plugin-google-analytics
# OR npm install -D @vuepress/plugin-google-analytics安装完在 config 配置文件里面配置一下 plugins
bash 代码:module.exports = {
plugins: [
[
'@vuepress/google-analytics',
{
'ga': '' // UA-00000000-0
}
]
]
}2 注册 GA，获取追踪 ID
上面那个 ga ID从哪里获取呢？别着急，我们需要到 Google Analytics 的官网上去注册一下我们的博客应用：
创建账号：
根据实际情况设置：
然后就会获得追踪 ID，
把获取到的跟踪ID 填到上面?的ga这一项里面就好了。
插件-PWA
1 安装插件
bash 代码:yarn add -D @vuepress/plugin-pwa
# OR npm install -D @vuepress/plugin-pwa2 添加插件信息
bash 代码://config,js
module.exports = {
// ...
plugins: [
['@vuepress/pwa', {
serviceWorker: true,
//指向自定义组件
popupComponent: 'MySWUpdatePopup',
updatePopup: {
message: "新的风暴已经出现",
buttonText: "盘他"
}
}]
]
}serviceWorker 的作用大致就页面首次加载时会请求本地的serviceWorker.js 去比对各个文件的版本号
如果不一致则提示用户拉取更新
评论系统-Valine
方案一：valine 官方插件
- 获取APP ID 和 APP Key,请先登录或注册 LeanCloud, 进入控制台后点击左下角创建应用
- 安装并使用 Valine
1 安装插件
bash 代码:npm install --save vuepress-plugin-comment2 将 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 效果
4 修改样式
创建 .vuepress/styles/palette.styl
写入：
bash 代码:
#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 中写入：
bash 代码:const path = require('path')
palette: path.resolve(__dirname, 'palette.styl'),//样式修改5 效果图
建议使用方案一，方案二需要进行优化，因为 Valine 部分是被当作内容处理的，但是如果你非要使用方案二，可以把解决方案和我分享喔！
方案二：配合插件手写全局组件
1 安装 Valine
bash 代码://Install leancloud's js-sdk
npm install leancloud-storage --save
//Install valine
npm install valine --save2 注册 vuepress 全局组件
创建 .vuepress/components/Valine.vue
(在components下注册的 vue 可供全局使用，文件名为组件名）
bash 代码:<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 中调用即可
bash 代码:<Valine></Valine>4 效果
也不错，只是评论被当作内容处理了……
不蒜子访问量统计功能
1 安装插件
bash 代码:yarn add busuanzi.pure.js
# or
npm install busuanzi.pure.js --save还未实现，待完善
集成 UI 组件
vuepress 支持扩展，支持引入第三方组件，在 .vuepress/ 下创建 enhanceApp.js 文件，这里展示的是引入 vue 生态圈比较知名的ui库 Element, 来自于饿了么。
bash 代码:/**
* 扩展 VuePress 应用
*/
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
export default ({
Vue,
}) => {
// ...做一些其他的应用级别的优化
Vue.use(Element)
}当然，在这之前，需要先安装 element。
bash 代码:yarn add element-ui
# or
npm install element-ui --save在扩展之后，就可以在自定义的组件或者 md 文件中，使用 element 的组件了。
本站由
