閱讀全文需要15分鍾，動手實踐需要30分鍾，請收藏點贊后再讀。
Github鏈接：https://github.com/Jackson0714/BirdDoc 記得點個Star
一、用互聯網思維來看知識管理工具
1.1 用戶故事
我是一名開發人員，經常會迷失在尋找團隊內的各種開發文檔中，我期望有一個網站，所有文檔都集中在這個網站中，我可以進行根據目錄瀏覽，最好能支持搜索，而且我貢獻的文檔別人不知道，會再跑過來問我。
1.2 用戶痛點
（1）文檔存放位置雜亂
（2）搜索文檔困難
（3）文檔沒有目錄
（4）文檔普及度不高
1.3 產品團隊深挖用戶痛點
根據用戶的痛點，產品團隊設計了一個模型
（1）左側具有菜單導航欄
（2）頂部具有搜索欄
（3）可以通過網站的形式訪問，方便用戶訪問
二、工具選型
這種團隊管理工具有很多，很多大廠出了軟件專門來做知識管理：
比如xx筆記企業版
這些大廠的軟件必須購買企業版才能在團隊內共享，且筆記很雜，不利於管理。而且根本就沒有解決用戶痛點。
最后選擇了vuePress來做，它的好處是可以用markdown語言來做筆記，讓你專注於寫作，還可以將筆記提交到gitlab進行管理，還有變更記錄，而且高度支持自定義主題等等。
於是我們選擇了vuepress。官網鏈接：https://v0.vuepress.vuejs.org/zh/
官網也是用VuePress做的哦。但這個開源工具不是下載下來就可以直接用的，還有些開發工作需要做。
另外有人提出怎么不用GitBook ？
GitBook 最大的問題在於當文件很多時，每次編輯后的重新加載時間長得令人無法忍受。它的默認主題導航結構也比較有限制性，並且，主題系統也不是 Vue 驅動的。GitBook 背后的團隊如今也更專注於將其打造為一個商業產品而不是開源工具。 -- 來源vuepress
三、開始搭建這套工具
3.1 方案一 按照官網搭建
快速上手
注意
請確保你的 Node.js 版本 >= 8。
全局安裝
如果你只是想嘗試一下 VuePress，你可以全局安裝它：
# 安裝 yarn global add vuepress # 或者：npm install -g vuepress # 新建一個 markdown 文件 echo '# Hello VuePress!' > README.md # 開始寫作 vuepress dev . # 構建靜態文件 vuepress build . 現有項目
如果你想在一個現有項目中使用 VuePress，同時想要在該項目中管理文檔，則應該將 VuePress 安裝為本地依賴。作為本地依賴安裝讓你可以使用持續集成工具，或者一些其他服務（比如 Netlify）來幫助你在每次提交代碼時自動部署。
# 將 VuePress 作為一個本地依賴安裝 yarn add -D vuepress # 或者：npm install -D vuepress # 新建一個 docs 文件夾 mkdir docs # 新建一個 markdown 文件 echo '# Hello VuePress!' > docs/README.md # 開始寫作 npx vuepress dev docs WARNING
如果你的現有項目依賴了 webpack 3.x，推薦使用 Yarn 而不是 npm 來安裝 VuePress。因為在這種情形下，npm 會生成錯誤的依賴樹。
接着，在 package.json 里加一些腳本:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
然后就可以開始寫作了:
yarn docs:dev # 或者：npm run docs:dev 要生成靜態的 HTML 文件，運行：
yarn docs:build # 或者：npm run docs:build 默認情況下，文件將會被生成在 .vuepress/dist，當然，你也可以通過 .vuepress/config.js 中的 dest 字段來修改，生成的文件可以部署到任意的靜態文件服務器上，參考 部署 來了解更多。
這些步驟執行完后，只能看到搜索欄和標題，是沒有菜單的，需要自己創建菜單。
3.2 方案二、用我的demo搭建
3.2.2 如何創建菜單
上面只有搜索功能，沒有菜單功能。修改config文件定義菜單，然后加上菜單對應的文件夾。
3.2.2 下載demo
我已經有一份做好的demo供大家使用，該demo的功能：展示接口文檔，供第三方使用。功能如下圖。
github路徑：https://github.com/Jackson0714/BirdDoc
3.3.3 如何編寫文檔
比如想增加一個刪除優惠券的接口，可以在coupon目錄下面創建一個delete.md文件
然后在config.js 文件配置菜單
四、如何編譯運行
如果已經安裝了node.js和npm，則在根目錄執行這條命令就可以運行起來了
npm start
這條命令其實就是執行npm vuepress dev來進行實時編譯
編譯完成后，會提示監聽8080端口，可以打開http://localhost:8080查看效果
五、如何部署到服務器
5.1 打包成靜態文件
npm run build
5.2 配置nginx和hosts
我是部署到ubuntu上的，需要創建nginx 配置文件
// 創建nginx配置文件
sudo vim /etc/nginx/conf.d/interface.conf // interface.conf server { listen 8002; server_name birddoc.com; location / { root /home/user/project/github/BirdDoc/public; index index.html index.htm; try_files $uri $uri/ =404; } } // 重啟nginx服務 sudo service nginx restart // 配置hosts文件，映射網站域名 sudo vim /etc/hosts localhost birddoc.com
5.3 打開站點
六、如何自動部署到雲服務器
6.1 拉取代碼
git clone git@github.com:Jackson0714/BirdDoc.git
6.2 打包鏡像文件
npm run build
> kidsplace-interface@1.0.0 build /home/workspace/BirdDoc/BirdDoc > vuepress build WAIT Extracting site metadata... [9:59:39 AM] Compiling Client [9:59:39 AM] Compiling Server [9:59:45 AM] Compiled Server in 6s [9:59:51 AM] Compiled Client in 13s WAIT Rendering static HTML... DONE Success! Generated static files in public.
生成靜態文件，路徑為 /home/workspace/BirdDoc/BirdDoc/public
6.3 添加域名解析
在雲服務器控制台 添加 birddoc.jay.club的域名解析，網站jay.club是我自己備案的網站。
等待10分鍾就生效了。
6.4 修改nginx配置文件
監聽通過birddoc.jay.club發來的請求，路由到靜態文件目錄 /home/workspace/BirdDoc/BirdDoc/public
server {
listen 80;
server_name birddoc.jayh.club;
location / {
root /home/workspace/BirdDoc/BirdDoc/public;
index index.html index.htm;
try_files $uri $uri/ =404;
}
}
6.5 打開網站
http://birddoc.jayh.club
（臨時網站，后面可能會停掉。）
6.6 如何用jenkins部署
參考我之前寫的文章：1. 容器化部署一套雲服務 第一講 Jenkins（Docker + Jenkins + Yii2 + 雲服務器)）
最后部署成功，控制台輸出如下圖：
查看public目錄下這些文件
6.7 如何自動部署
自動部署的方式很多
6.7.1 Jenkins 定時構建
6.7.2 Crontab定時構建
注意：該腳本還有些編譯問題未解決，僅供參考。
/home/job/build.sh #!/bin/bash cd /home/workspace/BirdDoc/BirdDoc /usr/bin/git pull /usr/local/n/versions/node/10.15.3/bin/npm run build currentTime=$(date) echo $currentTime >> /home/job/build.log crontab -e * * * * * sleep 0; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 5; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 10; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 15; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 20; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 25; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 30; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 35; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 40; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 45; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 55; /home/job/build.sh >> /home/job/cron.log 2>&1 &
遇到的問題：
1 SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode 2 at exports.runInThisContext (vm.js:53:16) 3 at Module._compile (module.js:374:25) 4 at Object.Module._extensions..js (module.js:417:10) 5 at Module.load (module.js:344:32) 6 at Function.Module._load (module.js:301:12) 7 at Function.Module.runMain (module.js:442:10) 8 at startup (node.js:136:18) 9 at node.js:966:3 10 Already up-to-date. 11 /usr/local/n/versions/node/10.15.3/lib/node_modules/npm/bin/npm-cli.js:85 12 let notifier = require('update-notifier')({pkg}) 13 ^^^ 14 15 SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode 16 at exports.runInThisContext (vm.js:53:16) 17 at Module._compile (module.js:374:25) 18 at Object.Module._extensions..js (module.js:417:10) 19 at Module.load (module.js:344:32) 20 at Function.Module._load (module.js:301:12) 21 at Function.Module.runMain (module.js:442:10) 22 at startup (node.js:136:18) 23 at node.js:966:3
6.7.3 Jenkins通過git提交代碼觸發構建
我配置了GitHub hook trigger for GITScm polling，但還是沒有自動觸發。
6.8 如何用docker跑起來
后續再用docker run起來。
作 者：悟空聊架構
出 處：http://www.cnblogs.com/jackson0714/
關於作者：專注於移動開發。如有問題或建議，請多多賜教！
版權聲明：本文版權歸作者和博客園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文鏈接。
特此聲明：所有評論和私信都會在第一時間回復。也歡迎園子的大大們指正錯誤，共同進步。或者直接私信我
聲援博主：如果您覺得文章對您有幫助，可以點擊文章右下角【推薦】一下。您的鼓勵是作者堅持原創和持續寫作的最大動力！
悟空聊架構
關注我，帶你每天進步一點點！
還有111本書籍贈送~~