vuepress官方教程，em...也是用vuepress搭建的，哈哈。

这句很经典，也是表明了vuepress最好的用处：

VuePress 专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。

使用这个框架，不需要服务器，不需要空间，只要有支持pages的git托管仓库就可以搭建一个技术文档站点，任性！当然你也可以放到自己的服务器上直接作为静态网站使用，无所谓。

我这里使用的是码云Gitee，国内的，好用！

在码云上申请账号，然后新建仓库，这些流程不做演示了。我这里的仓库名称是vuepress，划重点，后面要用！！！

image.png

因为后面所作的操作，都在这里面，后面还要用到这个仓库

git到本地(从下图指示找仓库下载地址位置，按个人喜欢的方式把项目clone到本地)

git clone https://gitee.com/axhuangs/vuepress.git

image.png

image.png

进入到本地仓库，并且安装vuepress框架到本地(npm和yarn喜欢哪个都行，但是需要安装相应的工具)

下面开始按顺序来做：

1. 使用你喜欢的包管理器进行初始化， 我比较喜欢npm

npm init

// yarn init

最后会有一句确认信息截图没有截全Is this OK? (yes) 敲入yes或者y直接回车就可以

image.png

2.将 VuePress 安装为本地依赖(就是下载vuepress框架到本地)

npm install -D vuepress

//yarn add -D vuepress

image.png

image.png

不要在意太多黄色的细节，正经的应该这样就表明安装成功了。

另外我一直再用vscode的窗口操作，所以项目完成之后，会出现下面的提示：

image.png

点击是，主要是一般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

经过各种输出和好看的进度条之后，你会看到下面的信息：

image.png

说明启动起来了，浏览器打开: http://localhost:8080/:

image.png

那么现在你修改README.md文件， 这里会实时更新

image.png

到这里，前期搭建基本上及可以算是搞定了。

如果需要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文件都需要重新运行一下项目

这是目前的目录结构:

image.png

这是docs/firstside/README.md下的内容:

# 第一个侧边栏

firstside

firstside

firstside

firstside

## 二级第一个侧边栏

二级第一个侧边栏

二级第一个侧边栏

## 二级第二个侧边栏

二级第二个侧边栏

二级第二个侧边栏

### 三级第一个侧边栏

三级第一个侧边栏

三级第一个侧边栏

三级第一个侧边栏

## 二级第三个侧边栏

二级第三个侧边栏

二级第三个侧边栏

二级第三个侧边栏

重新运行npm run docs:dev之后效果是这样的:

image.png

当然有的时候整篇内容会比较长，或者分不同的模块，那么就可以多建几个md文件，并在config.js中配置一下

比如我在/firstside/文件夹下创建了otherModel.md文件，并创建了child文件夹，如下：

image.png

config.js的配置是这样的：

// 设置侧边栏内容

sidebar: [

{

title: '第一个侧边栏',

collapsable: false,

children: ['/firstside/', '/firstside/otherModel', '/firstside/child/']

}

// 根据自己的需求来订，对应自己在docs下的文件夹名，默认首页是README.md

]

运行效果是这样的：

image.png

config.js中的sidebar的配置方式可以组合各种姿势，下面只是一个小栗子，可以试下，当然开启更多组合，需要你来定，这里只是介绍一下基础方式

这是目录结构：

image.png

这是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'

]

}

]

}

]

最后的展示效果：

image.png

侧边栏差不多就这些了，当然还有顶部导航部分设置

// 设置菜单

nav: [

{ text: '首页', link: '/' },

{ text: '其他文档', items: [

{ text: 'demo1', link: 'http://www.baidu.com' },

{ text: 'demo2', link: 'http://www.baidu.cn' },

] }

],

nav与sidebar为同级

效果：

image.png

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/下面

image.png

然后再使用的地方，基本可以用两种方式引入


效果是这样的

image.png

image.png

最最重要的点来了

打包:

npm run docs:build

image.png

打包完成，使用git把整个源码上传到码云吧

然后来到码云的仓库喽

image.png

找到你的仓库，打开Gitee Pages

image.png

点击启动，等待部署完成

image.png

大工告成，上面已经出现了你的文档链接

注意：每次修改文档内容，哪怕一个标点符号，都需要到这里更新一下，才能正确显示文档