07.11.2018

VuePress 初體驗

作者 yesyo

旅人的官網原本是用 Hexo (opens new window) 架的，必須得承認的是當初在選靜態網頁產生器的時候是看誰星星多 (opens new window)。曾經用過 Jekyll (opens new window)，年代有點太久遠，雖然一直蟬聯寶座，不過

對 ruby 的印象一直是有點慢，太久沒接觸目前很陌生，可能設定環境就要一天
每次都會想玩新玩意兒

Hexo 聽說飛快，後起之秀 Hugo (opens new window) 那時候還沒有 SASS 的支援 (opens new window)，所以那時就選了第二名。

這幾天閒閒沒事幹，旅人弟說要把官網中文化，看有沒有辦法騙招攬點生意。我改了改，覺得好像不太來勁，看半天文件改不太動（Hexo 有個最大的問題就是維護的不頻繁），於是旅人兄就冒著餓死的風險，又把 StaticGen 看了一輪。Jekyll 不出所料的仍然高居榜首，然後多了好幾個 React 相關的。正巧讓我看到 VuePress (opens new window)，喔對喔，前陣子有看到 Vue (opens new window) 竟然又多了一個產品，Evan (opens new window) 這人到底是有多厲害。剛好最近常用 Vue，還算熟悉，大概瀏覽過文件，心裡想的功能都有了，就決定是你啦 ^* 其實旅人兄對於挑選技術這件事也沒有很擅長，星星數當然也是相當不錯的一個指標。唯一能給的忠告是，當時間緊迫，你最熟悉的技術就是最好的技術。。

立馬來動手。

# 一秒架官網

# install globally
yarn global add vuepress # OR npm install -g vuepress

# create a markdown file
echo '# Hello VuePress' > README.md

# start writing
vuepress dev

~~今天的故事就到這裡結束，我們下回再會。~~

正如 How to Teach Yourself Programming (opens new window) 一樣，有時光機的話，那白馬王子和白雪公主想必是可以永遠過著幸福快樂的日子。如果你是要寫文件的話，那恭喜你，可以收工了，預設的 theme 就是 VuePress 官網的 theme，因為 VuePress 正是為了解決 Vue 和它許許多多的子專案寫官方文件 (opens new window)的問題才出生的。好巧不巧的是 Vue 之前的文件也是用 Hexo (opens new window) 架的。

# 從專案目錄開始

旅人的官網目錄大概長得像這樣：

.
├─ docs/
│  ├─ README.md            # localhost:8080/index.html
│  ├─ blog/
│  │  │─ README.md         # localhost:8080/blog/index.html
│  │  └─ some-post.md      # localhost:8080/blog/some-post.html
│  └─ .vuepress
│     ├─ components/       # 裡頭的 .vue 都會註冊成全域的 component，可以在 markdown 裡用
│     ├─ dist/             # vuepress build docs 產生的檔案
│     ├─ public/           # 這裡放一些不用經過處理的檔案，像是 favicon，build 的時候會複製一份到根目錄
│     ├─ theme/            # 客製化的 theme
│     │  │─ Layout.vue     # 從這個檔案開始就跟開發一個普通的 Vue app 類似
│     │  └─ enhanceApp.js  # 用來新增 app 全域的功能
│     └─ config.js         # config.yml 或是 config.toml 也可以
└─ package.json

docs 也不一定要叫 doc，我就叫他 src，因為我也不是拿來寫文件的，看你高興。那些 README.md 都會變成 index.html，所以之後我就可以這樣 localhost:8080/blog/ 瀏覽 blog 的主頁面。

enhanceApp.js 這個比較特別的檔案可以拿來安裝 Vue 的 plugin、註冊全域的 component 之類的。我目前是拿來新增全域的 mixin (opens new window)，因為 VuePress 才剛起步，有很多我要的功能沒有，像是 blog 系統常見的分類或是標籤之類的，我就在這個檔案裡加了我想要的功能。

export default ({
    Vue,
    options, // 傳給 vue instance 的參數
    router, // vue-router 的 instance
    siteData // site metadata
}) => {
    Vue.mixin(someMixin);
}

# 客製化 theme

打算用 SASS 的話記得要先安裝：

yarn add node-sass sass-loader

Layout.vue 是 theme 裡面最重要的檔案，每個 markdown 檔案都會執行這個 component，然後會注入一些 metadata，像是 $site 和 $page 這兩個屬性，一個是整個站的屬性，一個是那一個頁面的屬性。例如 $site 的話，就是 config.js 裡的

{
    "title": "VuePress",
    "description": "Vue-powered Static Site Generator",
    "base": "/"
}

所以在你的 component 裡可以用 this.$site.title 拿到網站的名稱。

$page 的話就像：

{
    "lastUpdated": 1524847549000,
    "path": "/blog/some-post.html",
    "title": "Some post",
    "frontmatter": {
        "layout": "Post",
        "date": "2012-05-07"
    }
}

比較重要的是 frontmatter，裡面可以塞些你想要在 theme 裡面可以使用的，像是這個 blog post 要用哪個 layout 啦，tag 有哪些啦，發表日期啦，等等等。

---
layout: Post
title: Some Post
date: 2012-05-07
tags:
    - Tag 1
    - Tag 2
---

就可以在 Layout.vue 裡依據 frontmatter 抽換 component：

<component :is="$page.frontmatter.layout"/>

# 收尾

旅人兄在做 migration 的時候都是參考這位仁兄的 theme (opens new window)，因為文件啊看半天也不會知道怎麼做，看別人會動的 code 比較快喔。也可以參考預設的 theme (opens new window)。

VuePress 還有很長的路要走，不過目前來說用一些 workaround 也不讓人覺得難受，覺得還滿直覺好用的。如果你熟 Vue 的話，VuePress 會是不錯的選擇。