Vuepress 介绍
类似 hexo 一个极简的静态网站生成器,用来写技术文档不能在爽。当然搭建成博客也不成问题。
Vuepress 特点
快速上手
安装
初始化项目
yarn init -y# 或者 npm init -y
复制代码
安装 vuepress
yarn add -D vuepress# 或者 npm install -D vuepress
复制代码
全局安装 vuepress
yarn global add vuepress# 或者 npm install -g vuepress
复制代码
新建一个 docs 文件夹
设置下 package.json
{ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" }}
复制代码
写作
yarn docs:dev # 或者：npm run docs:dev
复制代码
也就是运行开发环境,直接去 docs 文件下书写文章就可以,打开 http://localhost:8080/可以预览
构建
build 生成静态的 HTML 文件,默认会在 .vuepress/dist 文件夹下
yarn docs:build # 或者：npm run docs:build
复制代码
基本配置
在 .vuepress 目录下新建一个 config.js,他导出一个对象
一些配置可以参考官方文档,这里我配置常用及必须配置的
网站信息
module.exports = { title: '游魂的文档', description: 'Document library', head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], ],}
复制代码
导航栏配置
module.exports = { themeConfig: { nav: [ { text: '主页', link: '/' }, { text: '前端规范', link: '/frontEnd/' }, { text: '开发环境', link: '/development/' }, { text: '学习文档', link: '/notes/' }, { text: '游魂博客', link: 'https://www.iyouhun.com' }, // 下拉列表的配置 { text: 'Languages', items: [ { text: 'Chinese', link: '/language/chinese' }, { text: 'English', link: '/language/English' } ] } ] }}
复制代码
如图：
侧边栏配置
可以省略.md 扩展名,同时以 / 结尾的路径将会被视为 */README.md
module.exports = { themeConfig: { sidebar: { '/frontEnd/': genSidebarConfig('前端开发规范'), } }}
复制代码
上面封装的 genSidebarConfig 函数
function genSidebarConfig(title) { return [{ title, collapsable: false, children: [ '', 'html-standard', 'css-standard', 'js-standard', 'git-standard' ] }]}
复制代码
支持侧边栏分组(可以用来做博客文章分类) collapsable 是当前分组是否展开
module.exports = { themeConfig: { sidebar: { '/note': [ { title:'前端', collapsable: true, children:[ '/notes/frontEnd/VueJS组件编码规范', '/notes/frontEnd/vue-cli脚手架快速搭建项目', '/notes/frontEnd/深入理解vue中的slot与slot-scope', '/notes/frontEnd/webpack入门', '/notes/frontEnd/PWA介绍及快速上手搭建一个PWA应用', ] }, { title:'后端', collapsable: true, children:[ 'notes/backEnd/nginx入门', 'notes/backEnd/CentOS如何挂载磁盘', ] }, ] } }}
复制代码
如图：
成品图
默认主题修改
主题色修改
在.vuepress 目录下的创建一个 override.styl 文件
$accentColor = #3eaf7c // 主题色
$textColor = #2c3e50 // 文字颜色
$borderColor = #eaecef // 边框颜色
$codeBgColor = #282c34 // 代码背景颜色
复制代码
有时需要在不同的页面应用不同的 css,可以先在该页面中声明
---pageClass: custom-page-class---
复制代码
然后在 override.styl 中书写
.theme-container.custom-page-class { /* 特定页面的 CSS */}
复制代码
PWA 设置
设置 serviceWorker 为 true,然后提供 Manifest 和 icons,可以参考我之前的《PWA 介绍及快速上手搭建一个 PWA 应用》
module.exports = { head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], //增加manifest.json ['link', { rel: 'manifest', href: '/manifest.json' }], ], serviceWorker: true,}
复制代码
部署上线
设置基础路径
在 config.js 设置 base
例如：你想要部署在https://foo.github.io 那么设置 base 为/,base 默认就为/,所以可以不用设置
想要部署在https://foo.github.io/bar/,那么 base 应该被设置成 “/bar/”
module.exports = { base: '/documents/',}
复制代码
base 将会自动地作为前缀插入到所有以 / 开始的其他选项的链接中,所以你只需要指定一次。
构建与自动部署
用 gitHub 的 pages 或者 coding 的 pages 都可以,也可以搭建在自己的服务器上。
将 dist 文件夹中的内容提交到 git 上或者上传到服务器就好
yarn docs:build # 或者：npm run docs:build
另外可以弄一个脚本,设置持续集成,在每次 push
代码时自动运行脚本
deploy.sh
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误set -e
# 生成静态文件npm run docs:build
# 进入生成的文件夹cd docs/.vuepress/dist
# 如果是发布到自定义域名# echo 'www.example.com' > CNAME
git initgit add -Agit 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 -
复制代码
注意事项(坑)
把你想引用的资源都放在.vuepress 目录下的 public 文件夹
给 git 仓库绑定了独立域名后,记得修改 base 路径
设置侧边栏分组后默认会自动生成 上/下一篇链接
设置了自动生成侧边栏会把侧边栏分组覆盖掉
设置 PWA 记得开启 SSL
本文转载自公众号云加社区（ID：QcloudCommunity）。
原文链接：
https://mp.weixin.qq.com/s/r3mzUTcWeynuCcVBscyrrw
评论