可以打开md_「硬核教程」只需1秒—你也可以有自己的API文档

Nothing is true. Everything is permitted.

写在前面

先聊聊为什么想到了要用Vuepress来代替原来写在Confluence上的文档。

大意是有个需要其他部门接入的项目，这个项目有个用md写的接入文档，其他部门的人需要看着这个文档才知道怎么接以及哪些东西需要接。

但是有个问题是这个文档长的一匹，有多长呢？

而且这个md文件是放在confluence上的。

本身用confluence阅读md的体验就不好，这个文档能够让你的滚轮滚个足足十多秒，skr~。

你想要看的某个小章节就藏在这一大坨文字里。即使从最上面的导航锚点定位到了想要看的地方，但是你看着看着，滑着滑着就不知道自己在哪儿了。

然后找了半天，要么你运气好找到了。要么就只有回到最上面的导航，在一堆导航里再找一次。如果你运气究极不好，可能还要把上面的步骤重复几次，真的到了那个时候，你的心态可能就炸了。还接个毛的业务，心里只想找到写文档的人，然后一顿操作。

这就是为什么，我想换个方式来展示这个接口文档。

说到这个，又不得不吐槽。去网上找了很多vuepress的使用，总体下来两个字，复杂。再去看看vuepress的官方文档(虽然最后的解决方案都是在官方找到的)，总结下来也是两个字，懵逼(因为我想找的那个地方藏得比较深)。

于是就有了写这一期硬核教程。

Don't BB, 你这个项目启起来到底啥样？

我看的很多教程，都是在没有背景、没有代码、没有效果的情况就开始了。让本来希望通过这个教程入门的人懵上加懵(比如我)。

Github地址：https://github.com/detectiveHLH/vuepress-demo

墙裂建议，先拉下来看看效果。

直接npm install安装完依赖之后，直接npm start即可。在你本地的8080端口就会运行一个如下的界面。

并不是自动打开浏览器，需要手动进入本地项目地址

首页

然后点开始开发会进入到如下的详细界面。

详情

左边就是我们需要详细展示的文档，可以看到我简单的分了两类作为样例。

好了好了，效果看到了，Show me the code

首先，这个项目的目录长这样。

.├── .vuepress│   ├── config.js│   ├── public│   │   └── logo.jpg│   └── router.js├── LICENSE├── README.md├── groupA│   ├── README.md│   └── 类别A的李四.md├── groupB│   ├── README.md│   └── 类别B的张三.md├── package-lock.json└── package.json

接下来就分别讲一下首页和详情页是怎么来的，以及如果需要加一个页面(也就是路由)该怎么做。

首先是首页

项目的根目录下的README.md就是你刚刚看到的首页。里面的源码长这样，你可以对比首页来看。

---home: trueheroImage: /logo.jpgheroText: 你的标题tagline: 你的副标题lang: en-USactionText: 开始开发 →actionLink: /groupA/features:- title: 吹  details: 这是吹的详情- title: 继续吹  details: 这是继续吹的详情- title: 再继续吹  details: 这是再继续吹的详情footer: MIT Licensed | Copyright © 2019-present LunhaoHu---

没错，不用你去写任何的JavaScript和CSS，全部都是基于配置的。

配成上面这样，你就可以看到刚刚那个首页。

顺嘴一提，只要你把图片放在了.vuepress的public目录下，那么写图片src的时候可以直接/你的图片名即可。

然后是详情页

可以看到，在首页的配置中，有一个actionLink，这个是指点了首页中的开始开发，需要跳转到的路由。这个就是我们众多详情中的其中一个页面的路由。

你可以对比刚刚详情页的图片。我们之所以能够看到左边的侧边栏，是因为在config.js里配置了sidebar这个属性。如下。

const router = require('./router');module.exports = {    smoothScroll: true,    title: '需要你在config.js里单独配的标题',    themeConfig: {        sidebar: router.getSidebar()    },    plugins: ['vuepress-plugin-smooth-scroll'],};

我这里只用了一个插件，但是我展示出了用插件的正确姿势，vuepress有很多插件，如果需要可以自己按需安装。

你可能看到了，最终的sidebar是通过一个函数生成的。

router.js在vuepress中本身没有，是我做的一个简单抽象，里面长这样。

let data = [    {        'title': '类别A',        'path': '/groupA/',        'children': [            '类别A的李四',        ]    },    {        'title': '类别B',        'path': '/groupB/',        'children': [            '类别B的张三',        ]    }];/** * 生成sidebar数据 * * @param data 上面定义的抽象侧边栏路由静态文件 */exports.getSidebar = () => {    let sidebar = [];    data.forEach((item) => {        if (item.children.length === 0) {            sidebar.push(item);            return;        }        for (let i = 0; i 

getSidebar这个函数，大意就是给所有的children加上了一个前缀path。因为vuepress本身需要你配置成这样。例如，如果你直接使用的话，路由就会变成这样。

注意，以下不是正确打开方式

[  {    title: '类别A',    path: '/groupA/',    children: [      '/groupA/类别A的李四'    ]  },  {    title: '类别B',    path: '/groupB/',    children: [      '/groupB/类别B的张三',    ]  }]

在children中再加前缀，显得很没有必要。所以我简单的做了一层抽象。

那么如果你要加一个页面要怎么做呢？

举个例子，假如你要在项目目录groupA中新建一个叫类别A的王五.md的md文件，那么你只需要在对应的router中，找到groupA这个类别，然后在children数组中再加一个类别A的王五即可。如下。

正确打开方式

[    {        'title': '类别A',        'path': '/groupA/',        'children': [            '类别A的李四',            '类别A的王五'        ]    },    {        'title': '类别B',        'path': '/groupB/',        'children': [            '类别B的张三',        ]    }]

然后就可以在详情多看到一些页面了。

值得注意的是，groupA和groupB的目录下的README文件就是你点击类别A这个分组显示的默认页面。

在vuepress中，如果路由以/结尾，那么就是指的这个目录下的README.md文件

还有一点很方便的是，单个文件里如果你有二级标题，vuepress会自动的生成该文件下的二级标题导航。点击相应的二级标题还可以直接跳转到对应的锚点，如下图。

自动生成锚点

如果你还需要更多功能

如果你作为一个后端开发， 要想展示你的文档，其实我认为完全够了。

不过你还需要更多功能的话，建议还是直接去vuepress官网查看对应的文档。

好了，以上就是本篇博客的全部内容

欢迎微信关注「SH的全栈笔记」，查看更多相关的文章