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 功能這麼簡單。