Nothing is true. Everything is permitted.
寫在前面
先聊聊為什么想到了要用Vuepress來代替原來寫在Confluence上的文檔。
大意是有個需要其他部門接入的項目，這個項目有個用md寫的接入文檔，其他部門的人需要看着這個文檔才知道怎么接以及哪些東西需要接。
但是有個問題是這個文檔長的一匹，有多長呢？
而且這個md文件是放在confluence上的。
本身用confluence閱讀md的體驗就不好，這個文檔能夠讓你的滾輪滾個足足十多秒，skr~。
你想要看的某個小章節就藏在這一大坨文字里。即使從最上面的導航錨點定位到了想要看的地方，但是你看着看着，滑着滑着就不知道自己在哪兒了。
然后找了半天，要么你運氣好找到了。要么就只有回到最上面的導航，在一堆導航里再找一次。如果你運氣究極不好，可能還要把上面的步驟重復幾次，真的到了那個時候，你的心態可能就炸了。還接個毛的業務，心里只想找到寫文檔的人，然后一頓操作。
這就是為什么，我想換個方式來展示這個接口文檔。
說到這個，又不得不吐槽。去網上找了很多vuepress的使用，總體下來兩個字，復雜。再去看看vuepress的官方文檔（雖然最后的解決方案都是在官方找到的），總結下來也是兩個字，懵逼（因為我想找的那個地方藏得比較深）。
於是就有了寫這一期硬核教程。
Don't BB, 你這個項目啟起來到底啥樣？
我看的很多教程，都是在沒有背景、沒有代碼、沒有效果的情況就開始了。讓本來希望通過這個教程入門的人懵上加懵（比如我）。
Github地址：-> 戳此 <-
牆裂建議，先拉下來看看效果。
直接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: true
heroImage: /logo.jpg
heroText: 你的標題
tagline: 你的副標題
lang: en-US
actionText: 開始開發 →
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 < item.children.length; i++) {
let childrenPath = item.children[i];
item.children[i] = item.path + childrenPath;
}
sidebar.push(item);
});
return sidebar;
};
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的全棧筆記】，當然也可以直接掃描二維碼關注
