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

Background

一直想用 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

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

Blog/css

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

0 directories, 3 files

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

Blog/default

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

0 directories, 2 files

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

以 blog-homepage.yaml 為例：

from: markdown+smart+definition_lists+strikeout+superscript+subscript
to: html

metadata:
  title: 棧列 Staque
  author: Cycatz

highlight-style: monochrome
tab-stop: 2

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

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

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

Blog/filter

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

0 directories, 1 files

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

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

Blog/fonts

[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 分析壓縮過後的檔案，可以大大減少網頁載入中文字型的時間

Blog/template

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

0 directories, 2 files

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

Blog/add-timestamp.sh

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

這是 add-timestamp.sh 的內容：

#!/bin/bash
suff=ttf
fonts=$(find ./build -name \*.${suff})
timestamp=$(date -Isecond)

for font in ${fonts};
do
    mv ${font} ${font%.*}_${timestamp}.${suff}
done
sed -i "s/.ttf/_${timestamp}&/" ./build/css/font.css

Blog/Makefile, symbolic links

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

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

$(OPTIMIZED_FONTS): fonts/ $(BUILD_INDEX_FILE) $(BUILD_HTML_FILES) 
    rm -rf $@
    mkdir -p $@
    cp -r fonts/* $@
    font-spider --no-backup $(BUILD_INDEX_FILE) $(BUILD_HTML_FILES)
    $$(bash ./add-timestamp.sh)
    
build/%.html: %.md template/$(ARTICLE).html css/$(ARTICLE).css css/font.css
    @echo $<
    mkdir -p $(@D) $(CSS_FILES)
    cp css/font.css $(CSS_FILES)
    cp css/$(ARTICLE).css $(CSS_FILES)
    pandoc -o $@ \
        --katex \
        --toc \
        --toc-depth 1\
        -d default/$(ARTICLE).yaml \
        --css ../css/$(ARTICLE).css \
        --lua-filter filter/links-to-html.lua \
        --template $(ARTICLE) $<

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

Conclusion

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