← 所有紀錄

Notes JavaScript

VuePress 初體驗

 · 旅人兄

簡單上手製作靜態網頁。

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

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

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

這幾天閒閒沒事幹,旅人弟說要把官網中文化,看有沒有辦法騙招攬點生意。我改了改,覺得好像不太來勁,看半天文件改不太動(Hexo 有個最大的問題就是維護的不頻繁),於是旅人兄就冒著餓死的風險,又把 StaticGen 看了一輪。Jekyll 不出所料的仍然高居榜首,然後多了好幾個 React 相關的。正巧讓我看到 VuePress,喔對喔,前陣子有看到 Vue 竟然又多了一個產品,Evan 這人到底是有多厲害。剛好最近常用 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 一樣,有時光機的話,那白馬王子和白雪公主想必是可以永遠過著幸福快樂的日子。如果你是要寫文件的話,那恭喜你,可以收工了,預設的 theme 就是 VuePress 官網的 theme,因為 VuePress 正是為了解決 Vue 和它許許多多的子專案寫 官方文件的問題才出生的。好巧不巧的是 Vue 之前的文件也是用 Hexo 架的。

從專案目錄開始

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

.
├─ 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,因為 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,因為文件啊看半天也不會知道怎麼做,看別人會動的 code 比較快喔。也可以參考預設的 theme。

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