what-i-learned-from-analysis-vuepress

本文為 2019 年 6 月 8 日我在第一屆濱江繽紛前端技術大會上發表的同名演講實錄。

個人介紹

首先作下自我介紹，我是來自海康威視的綜合安防前端組的相霄 ?‍? ? ?

今天給大家帶來我對 vuepress 的一些分析與實戰技巧。

本文思路參考 vueconf2 的 what-i-learn-from-maintain-vue-cli

ppt 地址請檢視傳送門

原文連結

介紹 vuepress

vuepress 是 vue 全家桶之外的技術，就算是用 vue 全家桶的同學也不一定會知道 vuepress，我先從幾個案例簡單介紹一下 vuepress

首先是 vue 官方文件，vue，vue-cli，vue-router，vuepress 等都是用了 vuepress 編寫

接下來是 react 系的一些腳手架，umijs 和 dvajs 等也是用了 vuepress

還有一些社群優秀的博主也會使用 vuepress，比如我個人關注的每日時報

最後看一個不一樣的風格的 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 功能這麼簡單。