使用vuepress建立自己的文档网站

你是不是有过这种困惑？当你写完自己的组件后，无法做一个漂亮等文档来吸引其他用户来读？当你看到element.ui 的网站的时候，是不是很羡慕他们能把网站做的这么漂亮？当你把自己当组件库做好之后，没有服务器将其部署？你是否想要有一个平台来和使用组件的用户有交流，来进一步完善自己的组件？那么，现在的vuepress正是你所需要的产品。

最近，公司正在着力为公司的组件库写一个文档，思来想去，翻来覆去，最后定了使用vuepress这个产品。很荣幸，在此期间，我一直跟着这个组件库文档从零到有，所以今天将这研究的心得做一次分享。

1. vuepress是什么？做什么的？为什么要用这个？
2. vuepress如何使用？
3. vuepress如何部署？
4. vuepress如何与使用者进行交流？

带着这几个疑问，我们走进今天的主题。

1. vuepress是什么？做什么的？为什么要用这个？

     1.vuepress是什么？

       简单来说，vuepress是：Vue 驱动的静态网站生成器。

     2.做什么？

       他的主要目的就是将.md文档生成一个静态网站。

     3.为什么要用他呢，

       因为对于开发而言不管移动端还是web端，不管前端还是后端，.md文档再熟悉不过来，它的语法也十分熟悉，所以写起来也是十分简单。还有一点就是可以很容易的将他部署到gitlab、github             上，从而不需要购买额外的服务器。

      4.优点

1.  简洁至上

   以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。

2. Vue 驱动   

        享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题

     3.高性能

        VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。

2.如何使用

1. 创建并进入一个新目录

mkdir vuepress-starter && cd vuepress-starter

 

2.使用你喜欢的包管理器进行初始化

yarn init # npm init

3.将 VuePress 安装为本地依赖

yarn add -D vuepress # npm install -D vuepress

我们已经不再推荐全局安装 VuePress

4.创建一系列的文件夹，推荐使用的目录如下

.
├─ docs
│  ├─ README.md //此md文档中内容，默认会出现在第一个文件夹中
│  ├─ .vuepress
│  │   ├─ config.js //配置文件
│  │   └─ components //放置自定义组件
│  ├─ 01.指南  //自定义文件夹 根据个人所需，创建文件夹
│  └─ 。。。  //自定义文件夹
├─ dist  //为执行yarn docs:build 构建项目，所生成静态文件
└─ package.json

docs 目录下，新建自己的文件夹，文件夹里，维护 md 文档

文件夹内，README.md 默认第一个展示，其余按照文件名顺序

目录名称，为 md 文件中，第一个 #号的主标题， 二级标题为两个#的标题，现在配置到三级，可在 config.js 中配置显示到层级

ps：为了排序，建议文件夹名以数字开头，例如：01.指南。

例如：

项目中 docs 文件夹下：

config中，配置：

// 自动获取文件到目录结构
const getConfig = require("vuepress-bar");

const config = getConfig(`${__dirname}/..`);
console.log("config.sidebar:", config.sidebar);

module.exports = {
  title: "sina-aio",
  description: "first test demo",
  dest: "dist",
  themeConfig: {
    locales: {
      "/": {
        sidebar: [...config.sidebar],
      },
    },
    sidebarDepth: 3 // 设置左边目录到第几层
  },

 
  

};

这里我用了自动创建左侧目录到插件：vuepress-bar 插件。

### ps:已知 bug：如果使用自动生成目录，需要在 doc 目录下有一个 README.md 文件，并且他会自动归到第一个文件夹内

 

在 docs/.vuepress 下，常用 config.js 中配置，如：

 

1. 左上角标题

module.exports = {

title: 'vuepress 文档'

}

2. 顶部右上角导航栏

 

效果：

 

 

配置：

 

module.exports = {

title: 'vuepress 文档',

themeConfig: {

locales: {

'/': {

nav: [{ text: '测试导航', link: '/02.other/01.seven' }]

}

}

}

}

 

3. 手动配置左侧目录

 

module.exports = {

title: 'vuepress 文档',

themeConfig: {

locales: {

'/': {

//sidebar: ['路径'或者{对象}] 例如：

sidebar: ['/02.进阶/01.five', ...config.sidebar]

}

}

}

}

如果想要自动生成左侧目录，查看上面到配置 的config

4. 左侧目录显示到到层级

 

module.exports = {

title: 'vuepress 文档',

themeConfig: {

sidebarDepth: 3

}

}

 

##### PS: 默认情况下，侧边栏会自动地显示由当前页面的标题（headers）组成的链接，并按照页面本身的结构进行嵌套，你可以通过 themeConfig.sidebarDepth 来修改它的行为。默认的深度是 1，它将提取到 h2 的标题，设置成 0 将会禁用标题（headers）链接，同时，最大的深度为 2，它将同时提取 h2 和 h3 标题。

 

5. build 构建项目生成文件的目录

module.exports = {

title: 'vuepress 文档',

dest: 'dist' //指定build输出目录，默认目录：.vuepress/dist

}

6. 在文档中自动显示目录

 

module.exports = {

markdown: {

toc: { includeLevel: [1, 2, 3] }

}

}[

//在md文档中，如下使用



[toc]

]

 

然后在package.json中配置如下：

"scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },

 

运行  yarn dev  即可在localhost:8080 看到想要的效果

 

3.如何部署

具体的部署教程，看一下官网吧，我这里也没有做什么修改，所以就不多赘述了。

https://vuepress.vuejs.org/zh/guide/deploy.html#github-pages

 

我的效果：https://lq0611.github.io/vuepress-starter/

 

4.vuepress如何与使用者进行交流？

 

我这里使用到的是vssue，好处是可以将评论关联到自己搭建的gitlab上，当然他还支持github 等其他平台。

本着高内聚，低耦合的原则，我觉得vssue应该新开一个章节。

传送门：https://blog.csdn.net/LQ0611/article/details/114788540