用 VuePress 製作說明文件頁面

本篇要解決的問題

之前常常會需要寫一些 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/