# 用 VuePress 製作說明文件頁面 – 2：config.js 基本設定
## 本篇要解決的問題
上一篇〈 [用 VuePress 製作說明文件頁面 – 1：安裝](https://www.letswrite.tw/vuepress-document-setup/) 〉我們安裝好了 VuePress，也建立了首頁的檔案，但除非我們只想要在頁面上呈現我們的圖跟文，而不加上像是頂部導覽列、側邊導覽列，也不客製我們要的網址路徑，不然，就一定會需要設定一個 config.js 檔。
本系列第二篇，來整理 config.js 上可以有哪些基本設定。
---
## 極重要的目錄結構
首先先看一下 VuePress 的目錄結構，之所以說很重要，是因為畢竟我們在用的是別人家產的開箱即用工具，很多事情必須要按別人的規則走，目錄結構就是其中一個規則。
VuePress 除了安裝後會有的那些資料夾，我們也可以手動照著目錄結構去新增我們的資料夾，官方文件上給的範例是這樣：
可以看到大部份的資料夾、檔案，都是收在一個名為「.vuepress」的資料夾之下。
本篇要寫的 config.js 也是在 .vuepress 下。
大部份的資料夾後面都標示了「Optional」，選填，就是沒有這個檔案也不會妨礙我們使用 VuePress。
文件上有一句很有意思的話：
> VuePress follows the principle of “Convention is better than configuration”.
> VuePress 遵循「約定優於配置」的原则
> [Directory Structure](https://vuepress.vuejs.org/guide/directory-structure.html)
維基了一下「 [約定優於配置](https://zh.wikipedia.org/wiki/%E7%BA%A6%E5%AE%9A%E4%BC%98%E4%BA%8E%E9%85%8D%E7%BD%AE) 」，大概的意思就是，底層的東西，大部份原本需要人工設定的東西，VuePress 都搞定了，我們不用去花時間設定路由、樣式、編譯 Markdown 什麼的，VuePress 統包。But，如果你有更多的需求要滿足，那也可以透過自己寫的配置（config）去達成。
這蠻像我們在用 Vue CLI，或是 Nuxt，背後可能要花幾個月時間學的 Webpack、Router、Loader……都幫我們處理好了，我們只要會用就行。
很難說這對我們是好或不好，但就 VuePress 的使用目的，是快速產一份說明文件來說，確實不需要懂那麼多背後的原理也能達成。
---
## 建立 config.js
參照上一段的目錄結構，我們知道 config.js 檔必須要在 .vuepress 的資料夾底下，因此我們就先建立一個「.vuepress」的資料夾，再建一個 config.js 的檔案放在裡面：
文件上有說 config 的副檔名除了 js，也可以用 .yml 用 YAML 來寫，或是用 .toml 用 TOML 來寫。
因為文件上提供的程式碼都是用 JavaScript 寫的，為了可以無腦複製貼上快速使用，我們就直接存為 config.js。
這個 config.js 檔是用 Node.js 的 export 方式，所以開頭跟結尾要這樣子包起來：
```
module.exports = {
// 裡面寫 config 的設定
}
```
---
## Config 基本設定部份
Config 總共有哪些設定可用，官方文件（ [英文](https://vuepress.vuejs.org/config/) | [簡中](https://vuepress.vuejs.org/zh/config/) ）都寫得很清楚，本篇會寫的是 Augustus 在製作給同事看的說明文件時，實際上有用到的，屬於「基本設定」的部份。
Config 除了基本設定外，還可以安裝佈景主題、外掛，這些就留到後面幾篇。
要注意的是，放在 .vuepress 下的 config.js 是全站的共同設定，如果想要改變每個頁面各自的基本設定也是可以的，請參考文件：Front Matter （ [英文 ](https://vuepress.vuejs.org/guide/frontmatter.html) | [簡中](https://vuepress.vuejs.org/zh/guide/frontmatter.html) ）。
### title
title 會影響的就是 ``，每一頁都可以設定 title，而在 config.js 上設定的 title 會讓整個站共用。
比方我們在 config.js 上設了 `title: "這是站名"`，首頁的 README.md 檔案上也設了 `title: "這是首頁"`，那最後我們在首頁上看到的 `<title>` 就會是：
```
<title>這是首頁 | 這是站名
```
config.js 上的 title 會跟在每一頁 `` 的後面。
除了影響 `<title>`，也會影響到整個頁面左上角，一般來說顯示 Logo 跟站名的地方，所以說這邊的 title 很重要，請勿亂設定。
### description
網頁描述，這邊是設定每一個頁面 `<meta name="description" content="">` 的預設值，如果各自頁面有設定 `description` 的話，就會以各自頁面的設定為主。
因為之前有被同事問過 `title`、`description` 是會影響什麼？這邊稍微補充一下。
我們一般在 Google 搜尋某個關鍵字，比方我們搜尋「Let’s Write 前端工程師」，會看到這樣子的結果：
藍色大字就是我們寫在 title 上的，灰色小字就是我們寫在 description 上的。
一般我們做 SEO 時，都會建議說 title 上要寫到關鍵字，description 則是要寫使用者看到後會想點擊的文案。這二個也都有建議的字數，SEO 就請各站各自努力啦~
### base
基本路徑，一般來說像 Let’s Write 所有的頁面都是在 `https://www.letswrite.tw/` 根目錄底下，放在根目錄下的不用改，因為 VuePress 的預設值就是 `/`。
但今天會有一種情況，比方我們的文件檔最後是被規定要放在 `https://www.example.tw/docs/` 下的話，base 就要設成：
```
base: /docs/
```
文件上是寫 `base` 的值要以「/」開始，也以「/」結束。
為了讓之後放到 GitHub Pages 時可以抓到靜態檔，本篇用的 Demo 是設為：
```
/letswrite-vuepress-document/
```
### head
寫在這邊的值，會被插進 `<head>` 中。
`<head>` 裡除了放 `title`、`description`，也會放一些像是 icon、social meta 等的東西，像是想要加上 icon 的話就寫：
```
head: [
['link', { rel: 'icon', href: '圖檔路徑' }]
]
```
### dest
設定產出的靜態檔案要放在哪個資料夾，預設值是 `.vuepress/dist`。
這個值建議修改，畢竟我們打開資料夾時，常常 . 開頭的資料夾會被隱藏起來，不太好被找到。
像我們可以設定：
```
dest: 'docs'
```
或：
```
dest: 'dist'
```
那當我們用終端機開啟 VuePress 的資料夾並輸入 `yarn build` 後，VuePress 就會把靜態檔案放進根目錄下「docs」或「dist」的資料夾裡。
為了讓之後放到 GitHub Pages 時可以抓到靜態檔，本篇用的 Demo 是設為 `docs`。
---
## 原始碼、Demo
本篇開始，原始碼跟 Demo 都會放在 GitHub 上，歡迎取用。
Demo 會隨著系列文更新，所以看到的程式碼會逐漸豐富。
取用之前可以先對本篇點個讚或分享~
原始碼：<https://github.com/letswritetw/letswrite-vuepress-document>
Demo：<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/)