前边想整理下文档,结果发现没有好用且免费支持md的软件,感觉 Vue官网 的风格还不错,简单明了,那就自己也搭建一个咯。
如果你也想搭建一个类似这样的网站,可以使用 VuePress ,高效快捷,写文档简直不要太爽。
特点:
官网 介绍:
- 简洁至上
- Vue 驱动
- 高性能
使用总结:
- 内置Markdown拓展
- 在Markdown中可以使用vue
- 自动生成service worker
- 响应式
- 包含默认主题也可自定义
- 支持多种插件
快速上手
直接根据官网安装步骤依次操作即可,注意点是Nodejs版本需 >= 8.6
创建本地目录并进入
mkdir <file name> && cd <file name>
初始化
// 使用 npm 、 yarn 、 cnpm 都可
npm init
安装本地依赖
// 使用 npm 、 yarn 、 cnpm 都可
npm yarn add -D vuepress
官网不推荐全局安装,其实都可以,根据自己喜好即可
创建文档根目录
mkdir docs
在docs下创建 .vupress 文件夹
所有vuepress相关的文件都会放在这里
在 .vuepress 下创建配置文件
touch config.js
config.js 是VuePress项目必要的配置文件,会导出一个对象。
在初始化生成的package.json文件补充scripts
{
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
}
}
官网的 docs:dev 和 docs:build 命令太麻烦,直接简写成dev和build即可,你也可以根据自己喜好命名。
启动服务
npm run dev
然后打开 http://localhost:8080/ 即可预览。
构建
npm run build
build后会在 .vuepress 下生成一个dist文件,里边则是打包好生成的HTML静态文件。
文件的目录结构可以参考 VuePress推荐目录结构
网站配置
像刚才提到config.js文件,网站的配置都在这里,详细配置参考文档API,这里列举常用的。
title和描述
module.exports = {
title: '萤火之森',
description: '这里是高佳睿的学习空间'
}
网站logo
module.exports = {
themeConfig: {
logo: 'xxxxxx' // 可以引用本地静态文件,也可以使用外部链接
}
}
导航栏配置
module.exports = {
themeConfig: {
nav: [
// 首页, / 代表docs下的README.md或index.md
{ text: 'home', link: '/' },
// 直接路径, /web/ 代表 docs下的web下的README.md或index.md
{ text: 'web', link: '/web/'},
// 下拉列表
{
text: 'language',
items: [
{ text: '中文', link: '/language/zh.md' }
{ text: '英文', link: '/language/en.md' }
]
},
// 外部链接
{ text: '萤火之森', link: 'https://www.scar.vip' }
]
}
}
link中的路径,如/web/,后边没有跟具体的文件名,代表访问的是默认文件,默认文件命名通常为README.md 或 index.md 。若想链接某个具体的文件的话,直接写全路径就好,如/language/zh.md,也可省略.md拓展名。
第一个 / 都代表的是docs文件。
侧边栏配置
sidebar支持数组和对象,简单配置直接像官网似的直接在数组中添加页面路由即可
module.exports = {
themeConfig: {
sidebar: [
'/',
'/page-a',
['/page-b', 'Explicit link text']
]
}
}
我们用到的多个侧边栏和分组侧边栏会可能会多点,下边举例,并在备注里边详细说明
多个侧边栏
多个侧边栏会跟文档对应的目录有关
module.exports = {
themeConfig: {
sidebar: {
// 在docs文件夹下的web文件夹下的md文档(和导航栏上web对应)
'/web/': [
'http', // docs文件夹下的web文件夹下的http.md 文件,
// 层叠标题
{
title: '框架', // 侧标栏层叠标题的名称
children: [
'vue', // 直接这样写找的是docs文件夹下的web文件夹下的vue.md文件
'/react/test' // 这样写找的是docs文件夹下的react文件夹下的test.md 文件
]
}
]
}
}
}
分组侧边栏
module.exports = {
themeConfig: {
sidebar: [
{
title: 'group1', 侧边栏分组标题为group1
children: [
'/web/http' // group1下的文档,路径为docs文件夹下的web文件夹下的http.md文件
]
}
]
}
}
侧边栏其他配置
深度展示slidebar 2是最大值,展示到h3, 默认展示h2,可以配置在最外层,也可以在分组或多个侧边栏具体选项里具体配置
sidebarDepth: 0
自动生成侧栏
sidebar: 'auto'
禁用侧边栏
sidebar: false
搜索配置
直接参照官方文档即可,很简单。
主题修改
默认样式修改
在.vuepress文件夹下创建一个styles文件夹,并创建palette.styl文件
$accentColor =blue //默认主题颜色
$textColor = red //默认字体颜色
$borderColor = rgb(255, 255, 0) //默认边框颜色
$codeBgColor = #ccc //默认背景颜色
修改某个具体的样式直接根据css样式去写就可以了,如:
div > .test {
color: pink
}
#title {
font-size: 20px;
}
自定义页面修改
在具体的md文件中声明页面class,如:
---
pageClass: page-class-test
---
具体修改方法直接和上边一样,直接写写对应class下的css即可。
Markdown拓展
对于Markdown的支持还是比较全面的,里边还支持Emoji等,直接参考官方Markdown文档即可。
支持多语言
多语言支持首先你需要准备对应语言的文档,参考官方多语言配置文档。
部署
官方介绍了好几种部署方案。我的呢是直接部署到服务器的,这里就直接介绍这一种,其余的可多方参考。
写好服务器的nginx的server配置后,然后我们执行 npm run build命令后,会在.vuepress 文件夹下生成一个dist文件,直接把这个dist文件部署到服务器对应的地方(具体的文件地址和你nginx 相关server里的root对应好即可),然后打开你的网站就可以看到。
还有很多需要具体补充的点,后续完善...
Comments | NOTHING