用 VuePress 製作說明文件頁面 – 3:導覽列

/

本篇要解決的問題

在上一篇〈用 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 在頂部導覽列的左方

Logo 預設點了是回到整個站的首頁,也就是我們在 config.js 上設定的「base」。

這是廣告,點擊一下可以幫本站多個一點點的廣告收入,謝謝

靜態檔放 public 中

Logo 會是圖檔,在 VuePress 上要讀到靜態檔案,像是圖檔,就只能讀出放在「.vuepress/public/」中的檔案。

比方我們要讀的 Logo 是 logo.svg,那我們在 .vuepress 中先建立一個「public」的資料夾,然後把 logo.svg 放進去:

把 logo.svg 放進 public 中
把 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
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 會隨著系列文更新,所以看到的程式碼會逐漸豐富。

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

原始碼: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 製作說明文件頁面 – 3:導覽列
Article Name
用 VuePress 製作說明文件頁面 – 3:導覽列
Description
本篇大綱:本篇要解決的問題。Navbar 頂部導覽列、Logo、靜態檔放 public 中、Repository 連結、導覽列連結。Sidebar 側邊導覽列、一般單純連結、將連結分組。原始碼、Demo。
Augustus
Let's Write
Let's Write
https://letswrite.tw/wp-content/uploads/2020/08/logo_512.jpg

隨選筆記文

Front-End

不會寫程式,也能自己架一個免費網站:Publii + GitHub Pages

Vue

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

Front-End

用 CSS :target 製作頁籤、手風琴功能

Firebase Google

Firebase Dynamic Links Analytics API 取得短網址分析資料

WordPress

如何用 MAMP 在本機安裝 WordPress

Vue

拿 Trello 當資料庫 建一個店家清單 – 下篇:建立清單頁面

Bot Slack

Slack 通知功能 可互動

Front-End

File API 客製上傳檔案按鈕 / input file

Front-End

漸層色按鈕 hover 效果

Analytics Google

GA 自訂維度的應用 分類之下的文章成效

本站準備替換留言功能,投票調查中,歡迎 參與投票

訂閱
通知
guest
0 Comments
Inline Feedbacks
看所有留言

Let's Write

前端工程師 Augustus 的學習筆記 — solving problems, in simple ways.