用 VuePress 製作說明文件頁面 – 2:config.js 基本設定

用 VuePress 製作說明文件頁面 – 2:config.js 基本設定
用 VuePress 製作說明文件頁面 – 2:config.js 基本設定

本篇要解決的問題

上一篇〈用 VuePress 製作說明文件頁面 – 1:安裝〉我們安裝好了 VuePress,也建立了首頁的檔案,但除非我們只想要在頁面上呈現我們的圖跟文,而不加上像是頂部導覽列、側邊導覽列,也不客製我們要的網址路徑,不然,就一定會需要設定一個 config.js 檔。

本系列第二篇,來整理 config.js 上可以有哪些基本設定。


極重要的目錄結構

首先先看一下 VuePress 的目錄結構,之所以說很重要,是因為畢竟我們在用的是別人家產的開箱即用工具,很多事情必須要按別人的規則走,目錄結構就是其中一個規則。

VuePress 除了安裝後會有的那些資料夾,我們也可以手動照著目錄結構去新增我們的資料夾,官方文件上給的範例是這樣:

VuePress 目錄結構,來源:Directory Structure
VuePress 目錄結構,來源:Directory Structure

可以看到大部份的資料夾、檔案,都是收在一個名為「.vuepress」的資料夾之下。

本篇要寫的 config.js 也是在 .vuepress 下。

大部份的資料夾後面都標示了「Optional」,選填,就是沒有這個檔案也不會妨礙我們使用 VuePress。

文件上有一句很有意思的話:

VuePress follows the principle of “Convention is better than configuration”.
VuePress 遵循「約定優於配置」的原则

Directory Structure

維基了一下「約定優於配置」,大概的意思就是,底層的東西,大部份原本需要人工設定的東西,VuePress 都搞定了,我們不用去花時間設定路由、樣式、編譯 Markdown 什麼的,VuePress 統包。But,如果你有更多的需求要滿足,那也可以透過自己寫的配置(config)去達成。

這蠻像我們在用 Vue CLI,或是 Nuxt,背後可能要花幾個月時間學的 Webpack、Router、Loader……都幫我們處理好了,我們只要會用就行。

很難說這對我們是好或不好,但就 VuePress 的使用目的,是快速產一份說明文件來說,確實不需要懂那麼多背後的原理也能達成。


建立 config.js

參照上一段的目錄結構,我們知道 config.js 檔必須要在 .vuepress 的資料夾底下,因此我們就先建立一個「.vuepress」的資料夾,再建一個 config.js 的檔案放在裡面:

建立 .vuepress 資料夾、config.js 檔案
建立 .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 的話,就會以各自頁面的設定為主。

因為之前有被同事問過 titledescription 是會影響什麼?這邊稍微補充一下。

我們一般在 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> 裡除了放 titledescription,也會放一些像是 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. 安裝
  2. config.js 基本設定
  3. 導覽列
  4. 佈景主題、外掛
  5. 改樣式、加元件
  6. 部署
Summary
用 VuePress 製作說明文件頁面 – 2:config.js 基本設定
Article Name
用 VuePress 製作說明文件頁面 – 2:config.js 基本設定
Description
本篇大綱:本篇要解決的問題。極重要的目錄結構。建立 config.js。Config 基本設定部份、title、description、base、head、dest、原始碼、Demo。本系列第二篇,來整理 config.js 上可以有哪些基本設定。
Augustus
Let's Write
Let's Write
https://letswrite.tw/wp-content/uploads/2020/08/logo_512.jpg
訂閱
通知
guest

0 Comments
Inline Feedbacks
看所有留言