本篇要解決的問題
之前常常會需要寫一些 components 的說明文件,給前端同事看或是當作一個如何使用 API 之類的記錄。因為都是比較零星的,所以是用 GitLab 的程式碼功能去存。
但零星的程式碼一多,即便 GitLab 程式碼可以條列出來,還是覺得一眼看過去很花,看不到想找的東西。
之前忘了在哪看到 VuePress 這套開箱即用的靜態網站生成器,想說平常都在用 Vue 了,那不如就用用看這套,看能不能把所有要用的 components 及範例都整理成一個有模有樣的頁面,順便嚇嚇後端 XD~。
用了一下後,如果要求的只是一個單純的靜態站,不用做什麼額外設定,裝完後就能用了,如果要加上一些功能,比如客製樣式、裝外掛,那官方文件上也都寫得蠻清楚的。
本系列是整理這幾天在用的時候,有用到的一些功能,更深入的使用就看以後有沒有機會碰到,畢竟目前已解決了所遇到的問題。
本篇主要參考 VuePress 說明文件:https://vuepress.vuejs.org/zh/。
安裝前必備
首先,本機必須要安裝好 Node.js,版本在 8.6 以上,還沒裝的朋友可以直接從官網下載安裝。
另外,文件裡面建議是用 Yarn 來裝需要的 Package,所以 Yarn 也安裝一下,在安裝完 Node.js 後,開啟終端機,輸入:
npm install -g yarn
按下 Enter 就會執行安裝。
嗯……用 npm 來裝 Yarn,怎麼覺得有點像拿 IE 裝 Chrome 一樣 XD。
安裝 VuePress
Node.js、Yarn 都安裝完成,先建立一個準備放 VuePress 的資料夾,然後用終端機開啟,首先我們要生成一個 package.json,主要是可以看到我們安裝了哪些 Package,輸入:
yarn init 或 yarn init -y
有沒有「-y」的差別就是會不會詢問我們一些基本問題,如果懶得回答就多打個 -y。
按下 Enter 後,資料夾就會多出一個 package.json 的檔案。
接著要來安裝 VuePress,在終端機輸入:
yarn add -D vuepress
按下 Enter 便會執行安裝,安裝完後目前資料夾會看到這樣:
要開啟 VuePress,可以在終端機上輸入:
vuepress dev .
但我們不太想花間去記一些太長的東西 XD,可以有更簡單的方式。
打開 package.json 的檔案,插入以下:
"scripts": { "serve": "vuepress dev .", "build": "vuepress build ." }
package.json 的檔案最後會像這樣:
這樣我們只需要在終端機上輸入:
yarn serve
就會開啟我們的 VuePress。
輸入:
yarn build
就會將我們的 VuePress 打包成靜態檔,讓我們放到主機上。
建立首頁
在執行 yarn serve
之前,因為我們目前一個檔案都沒有,開啟了也什麼都看不到。我們先在資料夾的根目錄下新增一個「README.md」檔,在檔案裡面寫上:
# Hello World
存檔完後執行 yarn serve
,終端機最後會顯示一行:
success [10:48:56] Build 7270a8 finished in 132 ms! ( http://localhost:8081/ )
那個「http://localhost:8081/」就是我們的 VuePress 在開發模式下的網址,打開瀏覽器後貼上網址,就會看見我們的第一個 VuePress 啦~
注意事項
本篇最後列出一下注意事項:
- VuePress 下所有文件都是用 Markdown 寫成,因此檔名要命成 XXXX.md。
- 檔名為 README.md 的就會當成首頁。
第 1 點,Markdown 不難,可以參考〈Markdown常用語法筆記〉這篇,或是用一些線上的生成器,如 HackMD。
第 2 點,就像我們剛剛在根目錄下創了一個 README.md 檔,就被當作整站的首頁一樣,如果在各個資料夾內建了 README.md 檔,就會當作是那個目錄下的首頁。
原始碼、Demo
本篇開始,原始碼跟 Demo 都會放在 GitHub 上,歡迎取用。
Demo 會隨著系列文更新,所以看到的程式碼會逐漸豐富。
取用之前可以先對本篇點個讚或分享~
原始碼:https://github.com/letswritetw/letswrite-vuepress-document
Demo:https://letswritetw.github.io/letswrite-vuepress-document/