How I Build My Blog with Pandoc & Vimwiki (Part I)

一直想用 vimwiki 架設個人的blog，網路上用 vimwiki 生成網站的幾乎都是利用 vimwiki 內建的 Vimwiki2HTML 將原生的 .wiki 檔來生成網頁，但是考慮到 .wiki 的支援性不佳， 所以決定用 markdown 寫作然後用 pandoc 與 vimwiki 自己打造生成環境

這是環境的文件結構：

[cycatz@cfzfnf Blog]$ tree --dirsfirst -L 1
.
├── css
├── default
├── filter
├── fonts
├── template
├── add-timestamp.sh
├── blog-article.html -> ./template/blog-article.html
├── blog-homepage.html -> ./template/blog-homepage.html
└── Makefile

5 directories, 4 files

我們照順序來說明每個項目

[cycatz@cfzfnf css]$ tree
.
├── blog-article.css
├── blog-homepage.css
└── font.css

0 directories, 3 files

css 下主要放的是網站主頁與文章的樣式，還有字型的設定，修改自 killercup/pandoc.css

[cycatz@cfzfnf default]$ tree
.
├── blog-article.yaml
└── blog-homepage.yaml

0 directories, 2 files

default 下放的是 pandoc 在編譯時的設定檔，省去編譯時在 pandoc 命令後接一大串參數的麻煩。

以 blog-homepage.yaml 為例：

1: from: markdown+smart+definition_lists+strikeout+superscript+subscript
2: to: html
3: 
4: metadata:
5:   title: 棧列 Staque
6:   author: Cycatz
7: 
8: highlight-style: monochrome
9: tab-stop: 2

在 metadata 設置的參數在網頁中會以 <meta> 被設定，我 metadata 只使用了三個參數：

• author : 作者名稱
• title : 定義網頁名稱，我預設是網站的名稱「棧列 Staque」
• date : 建立文章時間，會在每篇文章檔案中定義

其他選項設定解釋可以看 Pandoc User's Guide

[cycatz@cfzfnf filter]$ tree
.
└── links-to-html.lua

0 directories, 1 files

filter 存放的是用來處理一些特殊規則或增加功能的檔案。

裡面的 links-to-html.lua 是將檔案中的其他 md 連結（其他篇文章等）轉成 html 的連結，才能在網路上跳轉

[cycatz@cfzfnf fonts]$ tree -L 2
.
├── CJK
│   ├── GenRyuMin
│   ├── GenWanMin
│   └── TaipeiSansTCBeta
└── Latin
    ├── EB_Garamond
    ├── Inconsolata
    └── Libre_Baskerville

8 directories, 0 files

fonts 底下有兩個資料夾，一個存放中文字型 CJK ，另一個是拉丁語系 Latin

CJK 裡面的字型有：

• 源流明體GenRyumin
• 源雲明體GenWanMin
• 台北黑體Taipei Sans TC Beta

Latin 裡面的字型有：

• EB Garamond
• Inconsolata
• Libre Baskerville

其中 CJK 裡面的字型是用 font-spider 分析壓縮過後的檔案，可以大大減少網頁載入中文字型的時間

[cycatz@cfzfnf template]$ tree
.
├── blog-article.html
└── blog-homepage.html

0 directories, 2 files

template 存放的是 pandoc 生成 html 的模版，修改自預設檔案 (pandoc ---print-default-template html)

這個 script 的功能主要是幫用 font-spider 優化後的字型打上時間戳，這樣才能讓瀏覽器重新載入新的字型而不是讀取 cache 裡面的

這是 add-timestamp.sh 的內容：

 1: #!/bin/bash
 2: suff=ttf
 3: fonts=$(find ./build -name \*.${suff})
 4: timestamp=$(date -Isecond)
 5: 
 6: for font in ${fonts};
 7: do
 8:     mv ${font} ${font%.*}_${timestamp}.${suff}
 9: done
10: sed -i "s/.ttf/_${timestamp}&/" ./build/css/font.css

在 Makefile 主要是彙整pandoc的參數並編譯與壓縮字體資源

在此節錄在 Makefile 壓縮字型與生成文章網頁的片段：

 1: $(OPTIMIZED_FONTS): fonts/ $(BUILD_INDEX_FILE) $(BUILD_HTML_FILES) 
 2:     rm -rf $@
 3:     mkdir -p $@
 4:     cp -r fonts/* $@
 5:     font-spider --no-backup $(BUILD_INDEX_FILE) $(BUILD_HTML_FILES)
 6:     $$(bash ./add-timestamp.sh)
 7: 
 8: build/%.html: %.md template/$(ARTICLE).html css/$(ARTICLE).css css/font.css
 9:     @echo $<
10:     mkdir -p $(@D) $(CSS_FILES)
11:     cp css/font.css $(CSS_FILES)
12:     cp css/$(ARTICLE).css $(CSS_FILES)
13:     pandoc -o $@ \
14:         --katex \
15:         --toc \
16:         --toc-depth 1\
17:         -d default/$(ARTICLE).yaml \
18:         --css ../css/$(ARTICLE).css \
19:         --lua-filter filter/links-to-html.lua \
20:         --template $(ARTICLE) $<

而那些 sybolic links 是連結到 template/ 資料夾的檔案，原因是 --template 參數不給指定在資料夾裡面的檔案，只好在 Blog 目錄建立連結檔

目前 pandoc 的部分就到此告一段落，下一篇是有關 vimwiki 寫作的姿勢、心得，與相關連結。