用 VuePress 製作說明文件頁面 — 3：導覽列
前端工程師 Augustus 的學習筆記 — solving problems, in simple ways.
本篇大綱
本篇要解決的問題
在上一篇〈用 VuePress 製作說明文件頁面 — 2：config.js 基本設定〉我們設定好了 title、description 等重要的基本資訊，本篇要寫的是在網站中重要中的重要項目：導覽列。
導覽列是讓使用者進來時，在短短幾秒內能熟悉「這個網站有什麼」的項目，SEO 上也是讓搜尋引擎蜘蛛能從一頁爬到全部頁面的重點設計。
這麼重要的項目，VuePress 當然能夠讓我們自行設定。
Navbar 頂部導覽列
VuePress 的頂部導覽列上有五個項目：Logo、導覽列連結、語系切換、Repository 連結、搜尋框。
文件上是說四個，但 Augustus 認為 Logo 是整個站很重要的一環，因此把 Logo 列為第五個。
語系切換的部份 Augustus 並未用到，本篇不會寫到，在此附上文件的連結請自行觀看：英文 | 簡中。
搜尋框的部份用的是預設的功能，未做任何改變，說明文件上也是重在使用 Algolia 上，因此也是附上說明文件的連結，請自行觀看：英文 | 簡中。
Logo
要設定 Logo 很簡單，打開「.vuepress/config.js」這個配置檔案，加上：
themeConfig: {
logo: '圖檔路徑'
}
Logo 出現的位置是在頂部導覽列的左方：
Logo 在頂部導覽列的左方
Logo 預設點了是回到整個站的首頁，也就是我們在 config.js 上設定的「base」。
靜態檔放 public 中
Logo 會是圖檔，在 VuePress 上要讀到靜態檔案，像是圖檔，就只能讀出放在「.vuepress/public/」中的檔案。
比方我們要讀的 Logo 是 logo.svg，那我們在 .vuepress 中先建立一個「public」的資料夾，然後把 logo.svg 放進去：
把 logo 放進 public 中
這樣我們就可以使用這個檔案了。
在 config.js 的 logo 路徑上填 './logo.svg'，頁面上就會抓得到這個 Logo 檔。
如果是其它頁面要各自使用，文件上建議把 <img> 的 src 寫成以下：
<img :src="$withBase('/logo.svg')" alt="Logo">
如果哪一天我們改掉 base，$withBase 會自動去抓 base 上的值，避免抓不到圖檔的狀況發生。
Repository 連結
Repository 連結要放的是 GitHub 上的專案連結，一樣寫在 config.js 上，有二個地方可以設定。
頂部導覽列
修改頂部導覽列的連結：
themeConfig: {
repo: 'GitHub Repository 的連結',
repoLabel: '要顯示的文字'
}
repo 是必填，可以填相對路徑如「letswritetw/vuepress」，也可以填絕對路徑。
填相對路徑的話預設是會去到 GitHub 上的連結。但大家都知道，人生難免有意外，除了 GitHub，GitLab 也是可以支持一下的啊，如果專案是存在 GitLab 的話，這邊就要填 GitLab 的絕對路徑囉。
repoLabel 是選填，如果不填的話預設文字會顯示「GitHub」。
顯示在各頁下方
我們一般看一些說明文件，會看見文件底部出現像這樣的一行字：
Edit this page on GitHub
Repository 連結也可以設定這邊的……如果你希望有其他善心人士協助編輯的話。
themeConfig: {
// 假如文件檔的 Repository 跟上面設定的 repo 是不一樣的路徑：
docsRepo: 'letswritetw/other_repo',
// 假如文檔不是在 Repository 的根目錄下
docsDir: 'docs',
// 假如文檔在其他的分支下
docsBranch: 'master',
// 預設是 false，改為 true 就可以開啟這連結
editLinks: true,
// 連結顯示的文字，預設為「Edit this page」
editLinkText: '帮助我们改善此页面！'
}
導覽列連結
導覽列連結就是放到頂部導覽列上的連結，會放在頂部導覽列的右邊，一樣是寫在 config.js 上，如下：
themeConfig: {
nav: [
{ text: '首頁', link: '/' },
{ text: '內部連結', link: '/guide/' },
{ text: '外部連結', link: 'https://google.com' },
{
text: '有第二層選單',
ariaLabel: '第二層選單',
items: [
{ text: '選單2-1', link: '/submenu/1/' },
{ text: '選單2-2', link: '/submenu/2/' },
{
text: '第二層選單的子標題',
items: [
{ text: '選單2-3', link: '/submenu/3/' },
{ text: '選單2-4', link: '/submenu/4/' }
]
}
]
}
]
}
如果連結是外部連結，VuePress 一律會自動加上：target="_blank" rel="noopener noreferrer"，想要改變的話就把外部連結的部份寫成以下：
{
text: "Let's Write",
link: 'https://www.letswrite.tw',
target: '_self',
rel: ''
}
要注意，如果要拿掉 rel="noopener noreferrer"，target 就要設為 _self。
如果有設第二層選單，外觀會是這個樣子：
頂部導覽列有第二層選單、第二層選單子標題
Sidebar 側邊導覽列
除了頂部導覽列，VuePress 也能編輯側邊的導覽列，位置是在頁面的左邊，到了手機時就會改成由一個漢堡按鈕來開啟。
要加入側邊導覽列，一樣是更新 config.js 這個檔案。
一般單純連結
只是單純加上連結的方式如下：
themeConfig: {
sidebar: [
'/',
'/page-a',
['/page-b', '顯示文字']
]
}
連結設為 /，預設就是首頁連結，顯示的文字就是 config.js 裡的 title。
如果只設連結而不設文字，預設的顯示文字是檔案裡最大的那個標題。
如果想設定連結的顯示文字，那就是把連結包進陣列裡，第一個值是連結，第二個值是顯示文字。
將連結分組
我們很常會需要將連結分組，比方網站中分為美食、旅遊，美食下分西式、中式，旅遊下分國內、國外。
分組的設定方式如下：
themeConfig: {
sidebar: [
{
title: '美食', // 必填
path: '/food/', // 選填，一定要有這個資料夾及檔案
collapsable: **false**, // 分組項目是否關上，true 關上、false 打開,
sidebarDepth: 1, // 要抓到檔案中的第幾層標題，預設抓標題 1
// 這個分組底下有哪些連結
children: [
'/'
['/west', '西式'],
]
},
{
title: '旅遊',
children: [
['/', '遊遊首頁']
]
}
]
}
分組的方式，就是把各組寫在各自的 object 裡即可。
path 有填寫的話，分組的標題也會加上連結。
collapsable 為 true，那這個分組的項目就不會被打開，false 就會被打開。
children 這個分組底下有哪些連結，就寫在這裡面，寫的方式跟上面一段的「一般單純連結」相同。
以上這些是 Augusts 目前有用到的部份。
文件裡面還有寫到更多的使用方式，就麻煩自行看文件囉：英文 | 簡中。
原始碼、Demo
本篇開始，原始碼跟 Demo 都會放在 GitHub 上，歡迎取用。
Demo 會隨著系列文更新，所以看到的程式碼會逐漸豐富。
取用之前可以先對本篇點個讚或分享~
