vuepress官方教程,em...也是用vuepress搭建的,哈哈。
这句很经典,也是表明了vuepress最好的用处:
VuePress 专注在以内容为中心的静态网站上,同时提供了一些为技术文档定制的开箱即用的特性。
当前版本v1.0
使用这个框架,不需要服务器,不需要空间,只要有支持pages的git托管仓库就可以搭建一个技术文档站点,任性!当然你也可以放到自己的服务器上直接作为静态网站使用,无所谓。
我这里使用的是码云Gitee,国内的,好用!
在码云上申请账号,然后新建仓库,这些流程不做演示了。我这里的仓库名称是vuepress
,划重点,后面要用!!!
因为后面所作的操作,都在这里面,后面还要用到这个仓库
git到本地(从下图指示找仓库下载地址位置,按个人喜欢的方式把项目clone到本地)
git clone https://gitee.com/axhuangs/vuepress.git
进入到本地仓库,并且安装vuepress框架到本地(npm
和yarn
喜欢哪个都行,但是需要安装相应的工具)
下面开始按顺序来做:
1. 使用你喜欢的包管理器进行初始化, 我比较喜欢npm
npm init
// yarn init
最后会有一句确认信息截图没有截全Is this OK? (yes)
敲入yes或者y直接回车就可以
2.将 VuePress 安装为本地依赖(就是下载vuepress框架到本地)
npm install -D vuepress
//yarn add -D vuepress
不要在意太多黄色的细节,正经的应该这样就表明安装成功了。
另外我一直再用vscode的窗口操作,所以项目完成之后,会出现下面的提示:
点击
是
,主要是一般node_modules文件有的没有的一大堆(有一部分这个原因,所以node的作者又生了个新儿子deno),占空间比较大,所以一般情况下咱们不上传到远端,浪费空间,有package.json文件,在这个项目下载到别的地方的时候在根目录运行npm install
一下就可以了,你会惊奇的发现,node_modules又出来了。
3.重点来了!新建第一个文档
老老实实创建一个文件夹docs
, 然后新建一个文件README.md
,并且用markdown的方式写上一句,嗯,老老实实..., 我这里用官方提供的方式,报错...
# Hello VuePress
4.在 package.json
中添加下面的话
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
很重要的两句话,一句是运行本地开发环境,一句是打包准备部署到线上的文件
5.在本地启动服务器 来查看成果了
npm run docs:dev
//yarn docs:dev
经过各种输出和好看的进度条之后,你会看到下面的信息:
说明启动起来了,浏览器打开: http://localhost:8080/
:
那么现在你修改
README.md
文件, 这里会实时更新
到这里,前期搭建基本上及可以算是搞定了。
如果需要markdown的书写方式的话,可以去看看
再墨迹点很重要的东西最后在说怎么布置到码云上
现在顶部和左侧还是跟官方文档差点儿东西
左侧导航配置
在docs
文件夹下新建文件夹.vuepress
并且新建config.js
module.exports = {
title: 'vuepress文档', // 文档标题,左上角显示
description: 'vuepress文档描述',
base: '/vuepress/', // 这里写你的仓库名称
head: [
['link', { rel: 'shortcut icon', type: "image/x-icon", href: `/jyjwebdocs/favicon.ico` }]
], //这里配置你的网页头部信息等
themeConfig: {
/**
* 设置侧边栏最大深度
* 一般是以单个md文件中的 # ## ### #### 这几个标题文字为锚点自动生成导航
* **/
sidebarDepth: 4,
// 设置侧边栏内容
sidebar: [
{
title: '第一个侧边栏',
collapsable: false, // 是否具有展开收起功能
children: ['/firstslde/'] // 这个是根据自己的需求来订,对应自己在docs下的文件夹名,默认首页是README.md
}
]
}
}
注意:每次配置config.js文件都需要重新运行一下项目
这是目前的目录结构:
这是docs/firstside/README.md
下的内容:
# 第一个侧边栏
firstside
firstside
firstside
firstside
## 二级第一个侧边栏
二级第一个侧边栏
二级第一个侧边栏
## 二级第二个侧边栏
二级第二个侧边栏
二级第二个侧边栏
### 三级第一个侧边栏
三级第一个侧边栏
三级第一个侧边栏
三级第一个侧边栏
## 二级第三个侧边栏
二级第三个侧边栏
二级第三个侧边栏
二级第三个侧边栏
重新运行npm run docs:dev
之后效果是这样的:
当然有的时候整篇内容会比较长,或者分不同的模块,那么就可以多建几个md文件,并在config.js
中配置一下
比如我在/firstside/文件夹下创建了otherModel.md文件,并创建了child文件夹,如下:
config.js
的配置是这样的:
// 设置侧边栏内容
sidebar: [
{
title: '第一个侧边栏',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/']
}
// 根据自己的需求来订,对应自己在docs下的文件夹名,默认首页是README.md
]
运行效果是这样的:
config.js
中的sidebar
的配置方式可以组合各种姿势,下面只是一个小栗子,可以试下,当然开启更多组合,需要你来定,这里只是介绍一下基础方式
这是目录结构:
这是config.js
侧边栏设置
// 设置侧边栏内容
sidebar: [
{
title: '第一个侧边栏',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/'] // 这个是根据自己的需求来订,对应自己在docs下的文件夹名,默认首页是README.md
},
{
title: '第二个侧边栏',
collapsable: true, // 开启展开收起功能,注意下图中菜单名称旁边的小角标
children: [
'/second/',
{
title: '侧边栏组合',
collapsable: true,
children: [
'/second/child/',
'/second/child/secondChild'
]
}
]
}
]
最后的展示效果:
侧边栏差不多就这些了,当然还有顶部导航部分设置
// 设置菜单
nav: [
{ text: '首页', link: '/' },
{ text: '其他文档', items: [
{ text: 'demo1', link: 'http://www.baidu.com' },
{ text: 'demo2', link: 'http://www.baidu.cn' },
] }
],
nav
与sidebar
为同级
效果:
config.js
的全部内容
module.exports = {
title: 'vuepress文档',
description: 'vuepress文档描述',
base: '/vuepress/', // 这里写你的仓库名称
head: [
['link', { rel: 'shortcut icon', type: "image/x-icon", href: `/jyjwebdocs/favicon.ico` }]
], //这里配置你的网页头部信息等
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '其他文档', items: [
{ text: 'demo1', link: 'http://www.baidu.com' },
{ text: 'demo2', link: 'http://www.baidu.cn' },
] }
],
/**
* 设置侧边栏最大深度
* 一般是以单个md文件中的 # ## ### #### 这几个标题文字为锚点自动生成导航
* **/
sidebarDepth: 4,
// 设置侧边栏内容
sidebar: [
{
title: '第一个侧边栏',
collapsable: false,
children: ['/firstside/', '/firstside/otherModel', '/firstside/child/'] // 这个是根据自己的需求来订,对应自己在docs下的文件夹名,默认首页是README.md
},
{
title: '第二个侧边栏',
collapsable: true,
children: [
'/second/',
{
title: '侧边栏组合',
collapsable: true,
children: [
'/second/child/',
'/second/child/secondChild'
]
}
]
}
]
}
}
基本上页面配置就这些,主要还是config.js
的配置
如果想放入图片的话
个人觉得最好的方式就是哪里需要放哪里,但是目前还没想到怎么配置
目前总结到的方法是,把图片放到新建目录.vuepress/public/assets/
下,
这样打完包之后图片会被load到dist/assets/
下面
然后再使用的地方,基本可以用两种方式引入
![firstside_01](/vuepress/assets/firstside_01.jpg)
效果是这样的
最最重要的点来了
打包:
npm run docs:build
打包完成,使用git把整个源码上传到码云吧
然后来到码云的仓库喽
找到你的仓库,打开Gitee Pages
点击启动,等待部署完成
大工告成,上面已经出现了你的文档链接
注意:每次修改文档内容,哪怕一个标点符号,都需要到这里更新一下,才能正确显示文档