
旅人的官網原本是用 Hexo 架的,必須得承認的是當初在選靜態網頁產生器的時候是看誰星星多。曾經用過 Jekyll,年代有點太久遠,雖然一直蟬聯寶座,不過
- 對 ruby 的印象一直是有點慢,太久沒接觸目前很陌生,可能設定環境就要一天
- 每次都會想玩新玩意兒
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 會是不錯的選擇。