what-i-learned-from-analysis-vuepress

时间 2019-11-24

标签 learned analysis vuepress 繁體版

原文原文链接

本文为 2019 年 6 月 8 日我在第一届滨江缤纷前端技术大会上发表的同名演讲实录。css

我的介绍

首先做下自我介绍，我是来自海康威视的综合安防前端组的相霄 👨‍💻 🏸 🎦html

今天给你们带来我对 vuepress 的一些分析与实战技巧。前端

本文思路参考 vueconf2 的 what-i-learn-from-maintain-vue-clivue

ppt 地址请查看传送门react

原文连接webpack

介绍 vuepress

vuepress 是 vue 全家桶以外的技术，就算是用 vue 全家桶的同窗也不必定会知道 vuepress，我先从几个案例简单介绍一下 vuepressgit

首先是 vue 官方文档，vue，vue-cli，vue-router，vuepress 等都是用了 vuepress 编写github

接下来是 react 系的一些脚手架，umijs 和 dvajs 等也是用了 vuepressweb

还有一些社区优秀的博主也会使用 vuepress，好比我我的关注的每日时报vue-router

最后看一个不同的风格的 vuepress，是我我的博客，也是使用 vuepress 去作的

因此 vuepress 本质是静态网站生成器，主要用于技术文档，技术分享，我的博客等场景

vuepress 帮咱们解决了什么问题呢 🤔

我我的负责公司通用 ui 库的开发工做，我在 2 年前参考了社区某外卖行业的 ui 库进行开发；而在去年这个时候因为业务调整须要对咱们的 ui 库进行一波升级；顺便对咱们整个框架结构进行升级；在研究了老的系统后发现里面的文档系统特别难维护，特别是一些封装的第三方库都不怎么维护了。再参考了 antd 、elementui、 iview 等一些框架之后，我最终决定把文档系统改成 vuepress ；

主要有如下几点：

1.支持 markdown 语法

之因此选用 vuepress，最重要的一点缘由是它自然支持在 markdown 中使用 vue，在咱们内部 ui 库 1.0 的框架中文档也是用 markdown 写的，这也使咱们 ui 升级在文档这块不须要特别大的改动。反而在文档代码中还能够加入 vuepress 默认的不少新语法。

2.提高开发效率，标准化框架

vuepress 的配置很是精简，几乎只须要配置一个 config.js 而之前配置还须要配置 webpack 等不少复杂的 build 文件；在标准化方面也支持 ie11 等主流浏览器；从 0~1 快速搭建项目很是方便，甚至咱们内部的其余一些脚手架也基本都是用 vuepress 写的

3.部署便捷

部署适用于内部的 gitlab 和外部的 github，并且命令也很是简单只需 vuepress run build

4-5.约定式路由以及统一页面风格

这 2 点对于开发人员来讲很是好，开发者不须要关注路由以及页面样式；让开发者花更多的时间关注在文档编写上。

还有一个我的的缘由 vuepress 支持 emoji，这个在枯燥代码文档编写的同时，增长了情感化元素在里面，让内容更加生动

Vuepress 在其余场景的应用 👷‍

固然除了技术文档上的贡献是巨大的，它能作的还有更多

vuepress-plugin-yuque

先说一下公司内部的痛苦，咱们是没法用语雀写文档的，vuepress-plugin-yuque 能够实现将外部的文档数据转化为本地的文档；因此只要你愿意，将来你能够将任意数据源转化成 vuepress；那这有什么好处呢，咱们在公司内部有不少 oa 的数据，它的展示方式并非很是直观，或者咱们有一些业务扩展类的需求无法直接在 oa 上呈现。但咱们能够拿到它的数据，在 vuepress 作展示，咱们有一些定制类的项目每周有不少个分配个不一样的人；咱们将数据拿到用日历的方式展示在 vuepress 中，就能够直观的看到每一个人天天有什么任务了。

vuepress-plugin-gitalk-maker

上面的例子，数据仍是纯静态的；来讲一个基于 token 认证的动态数据的例子，我的编写的插件 vuepress-pligin-gitalk-maker；gitalk 是基于 github 的一个 issues 展示功能，放在 vuepress 中，支持每一个文档一个 issues；使用这个插件的好处是，在编写文档的时候咱们会发现，文档写的再好仍是会有问，并且一些问题的说明并不只仅须要写在文档中，而是在评论中能够体现；我我的也会常常在 github issues 中寻找本身要的答案，这个插件就提供这种可能性，让评论去驱动你们提 issues，并且好的回复一般都会获得高的点赞数，让排名靠前（这个暂时还没支持）。

这个插件还有 gitlab 版本这个咱们在公司内部作了开源，外部还有一个 vssue 更强大，支持多个社区类 issues；这个就让 vuepress 不只仅是个静态文档了，更像是一个论坛了。

基于这个功能，和 vuepress 强大的博客系统，咱们在内部也作了不少的项目。公司羽毛球官网，组内团建，照片墙，新人成长计划等等一系列网站。而在下面都加了评论功能，能收到很多小伙伴们有爱的回复。

Vuepress 优秀设计理念 🌈

讲了一些实战的例子，咱们回顾分析一下 vuepress 的一些优秀设计理念；这边先分享一个我的对 vuepress 的源码分析，vuepress-analysis；理念来自于 vue-cli-analysis

markdown-it-chain

若是了解 webpack-chain 的同窗们应该能够知道这个是用来干什么的，markdown-it-chain 是支持链式调用 markdown-it 的文档解析工具。刚才又说道 vuepress 是支持 markdown 语法的，而 markdown-it-chain 就是 vuepress 解析 markdown 的灵魂。

咱们看一组官方代码

以上代码就实现了简单的目录和锚点功能，我以前在技术选型中有作过一些对比，有些框架的目录和锚点功能单独封装成插件的形式，虽然也是解耦但对于这种再剥离成语言解析层面的解耦，会用起来更舒服。其实 markdown-it-chain 不只仅可使用于 vuepress，只要是有 markdown 文档解析的软件都是能够适用的，如今 star 人数还不是不少，你们还不操做起来。

Monorepo

这个也是老生常谈的话题，monorepo 是一种项目代码管理的一种方式，指的是在一个项目（repo）中管理多个某块的包，不一样于常见的一个模块一个（repo）；这里蹭一波 vue3 的热度，vue-cli 和 vuepress 都是 monorepo 的实现的，最新 vue3 的 next 也是基于 monorepo 管理，你们使用的时候能够单独引入好比 test，runtime 的一些库。

在 vuepress 中自己的 core 实现了插件化，内部有不少默认的插件，好比 back-to-top，项目不须要是默认不使用的，还有好比 search 是默认使用的。vuepress1.x 将主题也作成了插件化。作社区最重要的是不作什么，而 vuepress 的 monorepo 的一些插件基本都是通用的功能，插件化和 monorepo 的设计是值得咱们去学习的。

monorepo 最先是 babel 在使用，也沉淀了一些对它的理解，这个在 babel 官网能够看到

Single lint, build, test and release process.
Easy to coordinate changes across modules.
Single place to report issues.
Easier to setup a development environment.
Tests across modules are run together which finds bugs that touch multiple modules more easily.

约定大于配置，合理的优先级管理

这些也是体如今插件的默认配置和设计中，特别是文档目录结构的设计以及主题目录的设计。每每好的设计都是少配置甚至 0 配置的。

咱们从 vuepress1.x 的主题系统分析一下这个设计理念。说这个理念以前我先说一个我的很是喜欢玩的游戏炉石传说，炉石传说是 30 张卡 2 人对战的回合制游戏。在炉石区有个说法就是，一套卡组（30 张）只要改一张就是个人卡组了。这个理念就恰好来讲明 vuepress 的主题系统在默认的某个文件夹下面，默认的皮肤都在 theme-default 下，开发人员不须要修改全部的皮肤组件，只须要针对本身想要改的元素适当的修改某个指定的元素就能够了，好比咱们公司内部的 ui 库只改一个首页Home.vue也能够是一个 vuepress 的自定义皮肤，而实现这个原理就是采用 webpack 的 alias 功能这么简单。