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

这句很经典，也是表明了vuepress最好的用处：
VuePress 专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。

当前版本v1.0

使用这个框架，不需要服务器，不需要空间，只要有支持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

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

![firstside_01](/vuepress/assets/firstside_01.jpg)

<img :src="$withBase('/assets/firstside_01.jpg')" alt="foo">

效果是这样的

image.png

image.png

最最重要的点来了

打包:

npm run docs:build

image.png

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

然后来到码云的仓库喽

image.png

找到你的仓库，打开Gitee Pages

image.png

点击启动，等待部署完成

image.png

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

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