前言
公司交给我一个任务，搭建一个公司内部的前端文档，调研一番后，准备使用VuePress开发。当然，网上关于VuePress的好文章有非常多，本来没必要再写一篇了；但是，写文章毕竟是对自己学习的一个总结，还是写一篇吧！
本文基于VuePress 1.x
官方文档
项目初始化
创建文件夹，生成.json文件
// 创建文件夹
mkdir docs
// 项目初始化
npm init
安装配置VuePress
// 进入
cd docs
// 项目安装VuePress
npm install -D vuepress
// 新建文件夹，'docs'不能改成别的名字，不然启动报错，
// error: 'no such file or directory, stat 'F:\web\docs\docs''
mkdir docs
// 新建一个 Markdown 文件
echo "# Hello VuePress!" > docs/README.md
// 启动预览
npx vuepress dev docs
在浏览器输入http://localhost:8080/，能看到Hello VuePress!就表示启动成功了
然后，配置package.json
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
配置后，重新启动
npm run docs:dev
刷新浏览器，还可以看到Hello VuePress!表示配置成功了
测试生成静态HTML
npm run docs:build
在docs文件夹下面多了.vuepress文件夹，.vuepress文件夹下面有个dist文件夹，里面结构如下
|-assets
└──css
└──img
└──js
|-404.html
|-index.html
右键index.html在浏览器打开，你会发现样式有错误，这个的原因是路径的问题，我们设置一下，然后放到服务器上就好了
// 进入
cd .vuepress
// 创建配置文件
vim config.js
// 配置如下
module.exports = {
// 设置网站标题
title: '前端文档',
// 设置输出目录
dest: './dist',
// 设置站点根路径，如果你在访问的地址是 'www.xxxx.com/wxDocs' 那么就设置成 '/wxDocs/'
base: '/wxDocs/'
// 添加 github 链接，但是这个要放在公司的内网服务器，所以为空
// repo: ''
}
// 打包
npm run docs:build
你会发现在项目的根目录多了一个dist文件夹，把这个文件夹里面的所有东西上传到服务器，同时删除.vuepress文件夹下的dist文件夹
配置icon
// 进入
cd .vuepress
// 创建文件夹
mkdir public
使用在线ps打开一张图片，更改图像大小为16*16 或者 32*32 或者64*64px，保存为ico格式，复制到public下面
更改config.js，添加如下代码
head: [['link', { rel: 'icon', href: '/logo.ico' }]]
重新启动，刷新浏览器，看到浏览器导航栏出现图标，表示配置成功
配置首页
如果你想完全自定义首页，那么就这样：
cd .vuepress
// 创建文件夹
mkdir components
// 创建首页文件，以正常写vue的方式在 'login.vue' 写代码
vim login.vue
然后在README.md文件中修改为：
---
layout: login
---
<login />
layout开启自定义设置，目标链接到你自定义的 login.vue 页面，然后下面的 <login /> 引入
如果不想自定义，那么使用默认的就可以了，这个是VuePress官方的默认配置首页
我这里考虑到到是内部文档，不开放给大众，上传到服务器，大众用户有可能会在搜索平台莫名搜索到文档地址，所以需要一个登录页面，需要自定义一个登录的首页，选择了
layout使用vue完全自定义
写好页面UI后，就可以写登录跳转逻辑了，首先，在项目docs文件夹下新建文件夹：
// 在根目录新建home文件夹
mkdir home
// 进入
cd home
// 新建 'README.md' 文件，必须要有，VuePress会自动把文件夹里的 'README.md' 转换为 'index.html' 文件，有这个才能跳转
vim README.md
新建好后项目结构如下：
|-dist
|-docs
└──.vuepress
└──home
└──README.md
└──README.md
|-node_modules
|-package-lock.json
|-package.json
然后给你登录的按钮绑上一个click
methods: {
goHome() {
// 判断账号密码是否正确的逻辑
...
// 正确，跳转
this.$router.push({ path: "/home/index.html" });
}
}
这样你的首页就配置好了
配置导航
VuePress配置导航非常简单，只需要在config.js添加如下代码：
module.exports = {
themeConfig: {
nav: [
{
text: '首页',
link: '/home/'
},
{
text: 'H5',
link: '/H5/'
},
{
text: '规范',
link: '/Standard/'
}
...
]
}
}
然后在项目docs文件夹下新建和link一一对应的文件夹，文件夹下新建README.md就可以了
建好后，重启，刷新浏览器查看效果
tips：新建的文件夹和上面建立的home文件夹平级
配置侧边栏
配置侧边栏也非常的简单，首先配置config.js
module.exports = {
themeConfig: {
sidebar: {
'/H5/': [
'H5和app对接文档',
'管理后台开发文档'
],
'/Standard/': [
'H5开发规范',
'H5版本管理规范'
]
}
}
}
然后，在对应的文件夹下新建.md文件就可以了，如：
|-h5
└──H5和app对接文档.md
└──管理后台开发文档.md
└──README.md
|-Standard
└──H5开发规范.md
└──H5版本管理规范.md
└──README.md
tips: 你在config.js里配置的名字，要和你在文件夹下新建的名字一致，但是实际侧边栏的名字，是你在H5和app对接文档.md文件下写的第一个标题的名字
重新启动，刷新浏览器，你会看到设置已经生效的，但是貌似还是有点问题，你在.md文件下生成的每一个标题都会生成一个二级的页面，设置config.js取消掉
module.exports = {
themeConfig: {
sidebarDepth: '0',
}
}
个性化定制
在config.js里添加
module.exports = {
// 代码块显示行号
markdown: {
lineNumbers: true
},
}
文档的滚动条太丑了，改一个样子
// 进入
cd .vuepress
// 新建'styles'文件夹
mkdir styles
// 新建 'index.styl' 和 'palete.styl'，VuePress使用 'stylus' 预处理器
vim index.styl
vim palete.styl
index.styl为全局自定义的样式，权限在默认之上palete.styl覆盖默认的主题配置
index.styl 样式
/*定义滚动条高宽及背景 高宽分别对应横竖滚动条的尺寸*/
::-webkit-scrollbar
{
width: 8px;
height: 8px;
border-radius: 10px;
background-color: #F5F5F5;
}
/*定义滚动条轨道 内阴影+圆角*/
::-webkit-scrollbar-track
{
border-radius: 10px;
-webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
background-color: #F5F5F5;
}
/*定义滑块 内阴影+圆角*/
::-webkit-scrollbar-thumb
{
border-radius: 10px;
-webkit-box-shadow: inset 0 0 6px rgba(0,0,0,.3);
border-radius: 10px;
/* 线性渐变 */
background-image: -webkit-gradient(linear,
left bottom, left top,
color-stop(0.44, rgb(60,186,146)),
color-stop(0.72, rgb(253,187,45)),
color-stop(0.86, rgb(253,187,45)));
transition: 0.3s ease-in-out;
}
/*定义滑块悬浮样式*/
::-webkit-scrollbar-thumb:hover{
background-image: -webkit-gradient(linear,
left bottom, left top,
color-stop(0.44, rgb(253,187,45)),
olor-stop(0.72, rgb(253,187,45)),
color-stop(0.86, rgb(60,186,146)));
transition: 0.3s ease-in-out;
}
.site-name{
background-image: -webkit-linear-gradient(left,
#22c1c3, #fdbb2d 25%, #22c1c3 50%, #fdbb2d 75%, #22c1c3);
-webkit-text-fill-color: transparent;
-webkit-background-clip: text;
-webkit-background-size: 200% 100%;
-webkit-animation: myGradientChange 4s infinite linear;
animation: myGradientChange 4s infinite linear;
}
@keyframes myGradientChange {
0%{ background-position: 0 0;}
100% { background-position: -100% 0;}
}
palete.styl 样式
// 点击状态
$accentColor = #3eaf7c
// 文字
$textColor = #2c3e50
// 边框
$borderColor = #eaecef
// 代码背景
$codeBgColor = #282c34
如果你想要单独为某个页面写一个样式，可以这样
// 现在某一个页面的 '.md' 文件上添加
---
pageClass: custom-page-class
---
然后在 index.styl 中添加
.theme-container.custom-page-class {
/* page-specific rules */
}
最后
VuePress整体上来说还是比较简单的，想写出新意来真的非常困难！
so，只能这样了。
