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

2020-01-26


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 只使用了三個參數:

其他選項設定解釋可以看 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 裡面的字型有:

Latin 裡面的字型有:

其中 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

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 寫作的姿勢、心得,與相關連結。