本篇要解決的問題
上一篇〈用 VuePress 製作說明文件頁面 – 1:安裝〉我們安裝好了 VuePress,也建立了首頁的檔案,但除非我們只想要在頁面上呈現我們的圖跟文,而不加上像是頂部導覽列、側邊導覽列,也不客製我們要的網址路徑,不然,就一定會需要設定一個 config.js 檔。
本系列第二篇,來整理 config.js 上可以有哪些基本設定。
極重要的目錄結構
首先先看一下 VuePress 的目錄結構,之所以說很重要,是因為畢竟我們在用的是別人家產的開箱即用工具,很多事情必須要按別人的規則走,目錄結構就是其中一個規則。
VuePress 除了安裝後會有的那些資料夾,我們也可以手動照著目錄結構去新增我們的資料夾,官方文件上給的範例是這樣:
可以看到大部份的資料夾、檔案,都是收在一個名為「.vuepress」的資料夾之下。
本篇要寫的 config.js 也是在 .vuepress 下。
大部份的資料夾後面都標示了「Optional」,選填,就是沒有這個檔案也不會妨礙我們使用 VuePress。
文件上有一句很有意思的話:
VuePress follows the principle of “Convention is better than configuration”.
Directory Structure
VuePress 遵循「約定優於配置」的原则
維基了一下「約定優於配置」,大概的意思就是,底層的東西,大部份原本需要人工設定的東西,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 總共有哪些設定可用,官方文件(英文 | 簡中)都寫得很清楚,本篇會寫的是 August 在製作給同事看的說明文件時,實際上有用到的,屬於「基本設定」的部份。
Config 除了基本設定外,還可以安裝佈景主題、外掛,這些就留到後面幾篇。
要注意的是,放在 .vuepress 下的 config.js 是全站的共同設定,如果想要改變每個頁面各自的基本設定也是可以的,請參考文件:Front Matter (英文 | 簡中)。
title
title 會影響的就是 <title>
,每一頁都可以設定 title,而在 config.js 上設定的 title 會讓整個站共用。
比方我們在 config.js 上設了 title: "這是站名"
,首頁的 README.md 檔案上也設了 title: "這是首頁"
,那最後我們在首頁上看到的 <title>
就會是:
<title>這是首頁 | 這是站名</title>
config.js 上的 title 會跟在每一頁 <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/