Vuepress 備忘

0. 前言

• VuePress文件：英文版，中文版
  • 英文版的文件比中文版的新，但大多數內容中文版都有。
• Reco主題官網
  • 注意，Reco 主題知識 VuePress 官方預設主題的擴充套件，不是一個全新的主題。
• 概述
  • 正如我在以前的部落格裡提到的，其實我對VuePress的印象很不好，主要原因在於，感覺VuePress的文件對於新手（前端小白）來說非常不友好。
  • 公平地說，在我硬著頭皮研究了一段時間，對整體比較熟悉之後，感覺文件還是可以的。（看來，不同受眾不同感受）。
  • 我其實比較爛，以前一直使用Hexo Next，現在研究VuePress的主要原因是：
    • 自己的團隊要輸出一些文件，目前使用的是Gitbook。
    • 團隊文件的主要需求是：能夠快速實現評論功能，必須部署在內網（內網有搭建Gitlab）。
    • 尋找之後，發現Vusse外掛能夠通過Gitlab Issue來實現評論功能，而Vussue不支援Hexo、Doscify，單對於VuePress支援非常好。

1. 感興趣的功能

1.1. 頁面介紹

• 封面
  • 來源：預設主題功能。
  • 其他：reco提供了一個部落格主題的封面，沒仔細研究過。
  • 具體使用參考 文件
  • 文件形式封面的參考配置以及效果如下

---
home: true
heroImage: /hero.png
heroText: Hero 標題
tagline: Hero 副標題
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 簡潔至上
  details: 以 Markdown 為中心的專案結構，以最少的配置幫助你專注於寫作。
- title: Vue驅動
  details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 元件，同時可以使用 Vue 來開發自定義主題。
- title: 高效能
  details: VuePress 為每個頁面預渲染生成靜態的 HTML，同時在頁面被載入的時候，將作為 SPA 執行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

• 導航欄
  • 來源：預設主題功能。
  • 定義方式還是直接參考文件吧。
  • 提供的功能：
    • 普通超連結
    • 下拉選單（可分組）
  • 舉例：下圖中 Guide/Config Reference/Plugin/Theme都是普通超連結，Learn More是分組的下拉選單，Language是無分組的下拉選單。

• 左側邊欄
  • 來源：預設主題自帶。
  • 作用：用來表示多級目錄，可能是文章標題，也可能是文章內的章節標題。
  • 提供的功能：
    • 多級、分組管理，可設定最大深度，可設定組內文章是否展開。
    • 分類名可作為超連結。
    • 可以有多個側邊欄（即不同頁面顯示的側邊欄不同）。
  • 具體使用請參考文件。
  • 舉例：下圖中，Theme 是分類名稱，Introduction/Using a theme等是文件名稱，Homepage/Navbar以及再下一級是文章內章節名稱。

• 右側邊欄
  • 來源：Reco附加功能。
  • 作用：在使用Reco時，左側邊欄只顯示文章多級管理，而不顯示文章內章節標題；右側側邊欄專門用於展示文章內章節標題。
  • 需要先進行配置，具體使用請參考文件。
  • 舉例：

1.2. Markdown 編輯功能

• 基本語法（自帶）：標題、超連結、列表、引用、程式碼塊。
• 數學公式（外掛）
  • 安裝外掛 npm install -D vuepress-plugin-mathjax
  • 修改 .vuepress/config.js 檔案

module.exports = {
    plugins: [
        [
            // 支援數學公式
            // https://vuepress.github.io/zh/plugins/mathjax/
            // npm install -D vuepress-plugin-mathjax
            'vuepress-plugin-mathjax',
            {}
        ]
    ]
}

• TaskList（外掛）
  • 安裝外掛 npm install markdown-it-task-lists -D
  • 分別修改 .vuepress/config.js檔案 和 .vuepress/styles/index.styl

module.exports = {
  markdown: {
    // 支援 task list
    // npm install markdown-it-task-lists -D
    // 除了這個還要在 .vuepress/styles/index.styl 中還要修改
    extendMarkdown: md => {
      md.use(require('markdown-it-task-lists'))
    }
  }
}

.contains-task-list LI
{
	list-style-type:none;
}

1.3. Markdown Front Matter 功能

• 概念：即 Markdown 檔案最開頭使用 ---包裹起來的內容，定義了標題、分類、標籤、釋出時間等一系列功能。

• 預設主題相關

  • 參考文件
  • 預定義引數：title/lang/description/layout/permalink/metaTitle/meta
    • 除了前三個，其他沒見過
  • 預設主題引數：navbar/sidebar/prev/next/search/tags
    • 前5個都是用來設定功能開啟與否
    • 最後一個可以優化內建搜尋，也可以生成Tags介面（reco功能）

• Reco 相關

  • 參考文件
  • 相關引數：title/date/sidebar/categories/tags/keys/publish/sticky
    • 好像沒什麼要多介紹的，都是顧名思義。
    • sticky是置頂與否，keys是設定密碼與否。

1.4. 更多功能

• 站內搜尋
  • 來源：預設主題自帶功能。
  • 具體使用參考文件
  • 功能：站內搜尋，可通過文件tags優化搜尋結果。
• 評論
  • 來源：reco整合外掛Vssue
  • 功能：這是基本需求，想用內建的Vssue評論，即通過issue來儲存評論內容
  • Vssue官網
  • 需要注意的是，如果使用Gitlab，需要將所有文章連結都新增到 callback url 中……
• 加密
  • 來源：reco自帶
  • 參考文件
  • 功能：全域性加密（進入網站就需要輸入密碼，關閉標籤後登入失效）、文章加密
• 最近更新時間
  • 來源：預設主題自帶功能，必須使用git管理。
  • 效果不清楚，需要使用以下試試。
• 在網頁上生成Edit this page連線
  • 來源：預設主題自帶功能。
  • 功能：在頁面中可直接進入對應的github/gitlab連線。

2. 進一步配置備忘

2.1. 配置檔案相關

• vuepress官方參考文件
• reco參考文件
• 配置很多，沒有一個個試過。
• TODO，都試一試。

2.2. 目錄結構

• 參考文件
• 根目錄下包含一個資料夾與package.json檔案
  • 前者包含所有文件內容，一般名為docs，當然，可以改。一般裡面有.vuepress和其他markdown頁面。
  • 後者包含一些基礎命令
• 目錄位置（即基於docs的相對路徑）與相對url的關係

Relatie Path	Page Routing
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

2.3. 靜態資源

• 參考文件
• 作用：用來儲存一些圖片/js/css等，方便頁面訪問。
• 檔案都儲存在 .vuepress/config.js中。

2.4. 特殊頁面

• 時間軸
  • 來源：reco附加功能。
  • 具體使用請參考文件。
  • 作用：生成一條時間線，展示發表論文的時間。該時間可自動生成。
• 標籤與分類：0.x和1.x有不同
  • 第一步都相同，在Front Matter中新增categories和tags資訊。
  • 第二步，一個是新生成頁面，指定FrontMatter資訊，另一個是直接在配置檔案中固定在導航欄中的位置。
  • 1.x文件
  • o.x文件
• About

3. Demo

3.1. 基本流程

3.2. 碰到的問題