# 用 VuePress 製作說明文件頁面 – 1：安裝

## 本篇要解決的問題

之前常常會需要寫一些 components 的說明文件，給前端同事看或是當作一個如何使用 API 之類的記錄。因為都是比較零星的，所以是用 GitLab 的程式碼功能去存。

但零星的程式碼一多，即便 GitLab 程式碼可以條列出來，還是覺得一眼看過去很花，看不到想找的東西。

之前忘了在哪看到 VuePress 這套開箱即用的靜態網站生成器，想說平常都在用 Vue 了，那不如就用用看這套，看能不能把所有要用的 components 及範例都整理成一個有模有樣的頁面，順便嚇嚇後端 XD~。

用了一下後，如果要求的只是一個單純的靜態站，不用做什麼額外設定，裝完後就能用了，如果要加上一些功能，比如客製樣式、裝外掛，那官方文件上也都寫得蠻清楚的。

本系列是整理這幾天在用的時候，有用到的一些功能，更深入的使用就看以後有沒有機會碰到，畢竟目前已解決了所遇到的問題。

本篇主要參考 VuePress 說明文件： [https://vuepress.vuejs.org/zh/](https://vuepress.vuejs.org/zh/) 。

---

## 安裝前必備

首先，本機必須要安裝好  [Node.js](https://nodejs.org/en/) ，版本在 8.6 以上，還沒裝的朋友可以直接從官網下載安裝。

另外，文件裡面建議是用  [Yarn](https://yarnpkg.com/)  來裝需要的 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 便會執行安裝，安裝完後目前資料夾會看到這樣：

![OVex0ol.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627095192179/3YwVnyZdB.png)

要開啟 VuePress，可以在終端機上輸入：

```
vuepress dev .
```

但我們不太想花間去記一些太長的東西 XD，可以有更簡單的方式。

打開 package.json 的檔案，插入以下：

```
"scripts": {
  "serve": "vuepress dev .",
  "build": "vuepress build ."
}
```

package.json 的檔案最後會像這樣：

![ULjzeM5.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627095439128/nChtEUsPq.png)

這樣我們只需要在終端機上輸入：


```
yarn serve
```

就會開啟我們的 VuePress。

輸入：


```
yarn build
```

就會將我們的 VuePress 打包成靜態檔，讓我們放到主機上。

---

## 建立首頁

在執行 yarn serve 之前，因為我們目前一個檔案都沒有，開啟了也什麼都看不到。我們先在資料夾的根目錄下新增一個「README.md」檔，在檔案裡面寫上：

```
# Hello World
```

![1F2UHQm.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627095534453/riZKQHaGZ1.png)

存檔完後執行 `yarn serve`，終端機最後會顯示一行：

```
success [10:48:56] Build 7270a8 finished in 132 ms! ( http://localhost:8081/ )
```

那個「http://localhost:8081/」就是我們的 VuePress 在開發模式下的網址，打開瀏覽器後貼上網址，就會看見我們的第一個 VuePress 啦~


![aB3R0JC.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1627095590817/-zmDrAyJM.png)

---

## 注意事項

本篇最後列出一下注意事項：

1. VuePress 下所有文件都是用 Markdown 寫成，因此檔名要命成 XXXX.md。
2. 檔名為 `README.md` 的就會當成首頁。

第 1 點，Markdown 不難，可以參考〈 [Markdown常用語法筆記](https://www.letswrite.tw/markdown/) 〉這篇，或是用一些線上的生成器，如  [HackMD](https://hackmd.io/) 。

第 2 點，就像我們剛剛在根目錄下創了一個 README.md 檔，就被當作整站的首頁一樣，如果在各個資料夾內建了 README.md 檔，就會當作是那個目錄下的首頁。

---

## 原始碼、Demo

本篇開始，原始碼跟 Demo 都會放在 GitHub 上，歡迎取用。

Demo 會隨著系列文更新，所以看到的程式碼會逐漸豐富。

取用之前可以先對本篇點個讚或分享~

原始碼： [https://github.com/letswritetw/letswrite-vuepress-document](https://github.com/letswritetw/letswrite-vuepress-document) 

Demo： [https://letswritetw.github.io/letswrite-vuepress-document/](https://letswritetw.github.io/letswrite-vuepress-document/) 

---

## 用 VuePress 製作說明文件頁面系列

1.  [安裝](https://www.letswrite.tw/vuepress-document-setup/) 
2.  [config.js 基本設定](https://www.letswrite.tw/vuepress-document-basic/) 
3.  [導覽列](https://www.letswrite.tw/vuepress-document-nav/) 
4.  [佈景主題、外掛](https://www.letswrite.tw/vuepress-document-theme-plugin/) 
5.  [改樣式、加元件](https://www.letswrite.tw/vuepress-document-style-component/) 
6. https://www.letswrite.tw/vuepress-document-deploy/