Vue.js 學習筆記

# 28. VuePress

# VuePress 介紹

VuePress 是由 Vue 官方開發出來的靜態網站生成器，讓我們專注於書寫技術文件、部落格文章。

# VuePress 能做到

  • 使用 Markdown 語法撰寫文件。
  • 使用 Vue 模組開發自定義主題、在 .md 檔中使用 Vue 模組。
  • 使用 SPA 運行，提高效能。

# VuePress 與其他服務的差異

(來源： 為什麼不是 Nuxt/Docsify/Hexo/GitBook？ (opens new window))

# 快速建立

快速上手 (opens new window)

# 建立步驟

  1. 建立並進入一個新資料夾
  2. 使用套件管理工具進行初始化：npm init 或 yarn init
  3. 將 VuePress 安裝為本地依賴：例如 npm install -D vuepress
  4. 在根目錄建立 "docs" 資料夾，並在裡面建立檔案 "README.md" 預設為首頁。
  5. 在 package.json 中添加一些 scripts：
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  1. 在本地端啟動伺服器： 例如 npm run docs:dev
  2. 瀏覽器網址輸入 http://localhost:8080 就能看到結果

# 注意

  • 如果現有項目依賴 webpack 3.x，則推薦使用 Yarn 而非 npm 來安裝 VuePress，以免生成錯誤的依賴樹。

# 專案結構

# 結構

.
├── docs
│   ├── .vuepress (可選的，放 vuepress 全局設定)
│   │   ├── components (可選的)
│   │   ├── theme (可選的)
│   │   │   └── Layout.vue
│   │   ├── public (可選的)
│   │   ├── styles (可選的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可選的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可選的，配置文件的入口文件)
│   │   └── enhanceApp.js (可選的)
│   │ 
│   ├── README.md (預設為專案首頁)
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

# 說明

(來源：目录结构 (opens new window))

# 專案範例

VuePress 專案範例

如果要做出像上圖這樣的專案，我們需要做這些事：

  • 在 docs 資料夾中，建立 "day00.md"，並輸入內容。
  • 在 config.js 檔案中，設定 title、nav、sidebar。

# 建立 day00.md

如上圖，我們可以在 docs 資料夾中建立 .md 檔，專注於使用 Markdown 語法撰寫技術文件、部落格文章。

這些檔案的名稱前面加上 / 就會是這些檔案的路徑，這部分將會在 config.js 進行設定。

# 設定 config.js

在這個範例中，我們會在 config.js 檔案進行以下設定：

module.exports = {
  // 專案的主標題，出現在 nav 左方
  title: 'VuePress Practice',
  themeConfig: {
    // 導覽列，陣列包物件，"/檔案名稱" 為該檔案路徑
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Day 00', link: '/day00' },
      { text: 'Google', link: 'https://google.com' },
    ],
    // 側邊欄，陣列包陣列
    sidebar: [
      ['/', '首頁'],
      ['/day00', 'Day 00']
    ]
  }
}

如此一來，就能建立一個簡潔又方便的部落格了。

# 搜尋功能

根據 Alex 在影片中的測試，VuePress 的搜尋只能搜到 Markdown 裡面的內容。若是寫在 Vue component 裡面，引入到 .md 檔案的內容，就搜尋不到了。

← 29. Nuxt.js →