為Jekyll靜態網站新增PlantUML外掛

前言

突然想起來要好好整理一下自己的部落格空間，已經荒廢很多年，如果再不撿起來，等到自己知識老化的時候再去寫東西就沒人看了。

使用Github Pages + Jekyll把部落格釋出為靜態網站，給人感覺比較私密，似乎所有的控制權都抓在自己手裡的樣子。但是作為一個技術部落格，如果寫東西沒有PlantUML的加持，當然效率就會差很多。

本文內容記錄了斷斷續續將近一週的折騰。

`PlantUML` 外掛

目前支援 PlantUML 的外掛我找到了好幾個，但是最終使用的是 kramdown-plantuml，另外一個 jekyll-spaceship 外掛支援更多的功能，如果需要安裝的話，只需要裝任意一個就可以支援 PlantUML 了，不需要兩個都裝。但是從我的實踐來看，jekyll-spaceship 外掛生成 PlantUML圖形會直接生成參照 plantuml.com 的生成功能，我覺得還是不可接受的。人家是免費提供給你使用，作為一個靜態網站，你一遍遍讓人家幫你生成圖形幹嘛？不地道！所以我推薦 kramdown-plantuml，沒那麼多功能，但是規矩。

安裝

安裝兩個外掛的功能的方法如下，各位看官可以擇一個安裝：

1. 修改根目錄下的 Gemfile，找到group :jekyll_plugins do位置，在其中加入所需的兩個外掛：

gem 'kramdown-plantuml'

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
#  gem 'jekyll-spaceship'
end

2. 在 _config.yml 中找到 plugins: 位置，並加入兩個外掛

plugins:
  - "jekyll-paginate"
  - "kramdown-plantuml"
#  - "jekyll-spaceship"

3. 繼續在 _config.yml 中加入兩個外掛的設定項

jekyll-spaceship:
  # default enabled processors
  processors:
    - table-processor
    - mathjax-processor
    - plantuml-processor
    - mermaid-processor
    - polyfill-processor
    - media-processor
    - emoji-processor
    - element-processor
  mathjax-processor:
    src:
      - https://polyfill.io/v3/polyfill.min.js?features=es6
      - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
    config:
      tex:
        inlineMath:
          - ['$','$']
          - ['\(','\)']
        displayMath:
          - ['$$','$$']
          - ['\[','\]']
      svg:
        fontCache: 'global'
    optimize: # optimization on building stage to check and add mathjax scripts
      enabled: true # value `false` for adding to all pages
      include: []   # include patterns for math expressions checking (regexp)
      exclude: []   # exclude patterns for math expressions checking (regexp)
  plantuml-processor:
    mode: default  # mode value 'pre-fetch' for fetching image at building stage
    css:
      class: plantuml
    syntax:
      code: 'plantuml!'
      custom: ['@startuml', '@enduml']
    src: http://www.plantuml.com/plantuml/svg/
  mermaid-processor:
    mode: default  # mode value 'pre-fetch' for fetching image at building stage
    css:
      class: mermaid
    syntax:
      code: 'mermaid!'
      custom: ['@startmermaid', '@endmermaid']
    config:
      theme: default
    src: https://mermaid.ink/svg/
  media-processor:
    default:
      id: 'media-{id}'
      class: 'media'
      width: '100%'
      height: 350
      frameborder: 0
      style: 'max-width: 600px; outline: none;'
      allow: 'encrypted-media; picture-in-picture'
  emoji-processor:
    css:
      class: emoji
    src: https://github.githubassets.com/images/icons/emoji/

這裡也要吐槽 jekyll-spaceship，上面這段原文裡的 @startuml 這種標註直接給我解析成了它要識別的指令，加任何折衷都不行。這也是最終被我拋棄的原因之一。

4. 啟動命令列，在git工程目錄執行命令 bundle install 下載並安裝外掛。

如果執行的時候出現類似錯誤 Warning: the fonts "Times" and "Times" are not available for the Java logical font，表示電腦中缺少字型。尤其是Mac電腦，請到這裡下載並安裝字型。

使用外掛

在 markdown 中使用 PlantUML 外掛的方法也很簡單，使用如下原始碼形式即可：

```plantuml
a --> b
```

要注意，使用 jekyll-spaceship 外掛的時候，預設的程式碼塊名稱加了一個! ，需要手工把上面設定項 code: 'plantuml!' 去掉感嘆號。

靜態網站生成

靜態網站方案

靜態網站的最終方案是使用分支進行區分，master 分支存放部落格的原始碼， gh-pages 分支存放生成的 _site 目錄中的內容。如果尚未建立 gh-pages 分支，可以用如下的方法建立：

mkdir gh-pages
cd gh-pages
git checkout --orphan gh-pages
git rm -rf ../gh-pages
git commit --allow-empty -m "initial commit"
git push origin gh-pages

Github Pages預設假設 gh-pages 分支中存放的是 jekyll 格式的原始碼，會自動構建之。為了阻止自動構建，需要在 gh-pages 分支的根目錄中存放一個 .nojekyll 檔案。

為了確保工作的自動化，我在磁碟上放置了兩個資料夾，一個是 blog-master 存放原始碼，並和 master分支關聯，一個是 gh-pages 用來存放輸出的靜態網頁，並和 gh-pages 分支關聯。這樣兩個可以互不干擾。

git repositorymastergh-pages作者jekyllblog siteblog mastergithub pagesgithub.io處理copy[git commit][git commit]定期更新推播

簡而言之，就是github裡用兩個分支，對應磁碟上兩個不同的目錄，一個目錄blog-master放部落格原始碼，一個目錄gh-pages放生成的頁面。各自獨立提交就ok了。

建立新文章

初學者對建立新文章的格式會把握不好，所以可以用命令列增加新文章。

rake post title="My first blog"

自動複製

jekyll 使用指令 bundle exec jekyll build 或 bundle exec jekyll serve 處理頁面程式碼之後的靜態內容全部都放在 _site 目錄下，需要手工複製到 gh-pages 目錄，所以我們需要自動化指令碼來處理這些事情。

編輯根目錄下的 Rakefile 在尾部增加：

# copy from https://www.sitepoint.com/jekyll-plugins-github/
# 
GH_PAGES_DIR = "gh-pages"

desc "Build Jekyll site and copy files"
task :build do
  system "jekyll build"
  system "rm -r ../#{GH_PAGES_DIR}/*" unless Dir['../#{GH_PAGES_DIR}/*'].empty?
  system "cp -r _site/* ../#{GH_PAGES_DIR}/"
  system "echo nojekyll > ../#{GH_PAGES_DIR}/.nojekyll"
end

desc "commit Jekyll site and push to github repository"
task :publish do
  title = ENV['TITLE'] || "at #{Date.today}"

  system "cd ../#{GH_PAGES_DIR}"
  system "git commit -m \"publish #{title}\""
  system "git push origin gh-pages"
end

然後檢查 _config.xml 中的 exclude 項，把 Rakefile 加進去。我的該項設定內容如下，加了好多東西：

exclude:
  [
    "less",
    "node_modules",
    "Gruntfile.js",
    "package.json",
    "package-lock.json",
    "README.md",
    "README.zh.md",
    "Rakefile"
  ]

等你的文章寫完了，就到命令列，執行 rake build 命令。如果預覽覺得可以，就執行 rake publish title="加了文章" 提交到 github。記得別忘記原始碼也手動去提交，指令碼不管原始碼的自動提交。

網站預覽

靜態內容在 gh-pages 目錄下，並沒有任何支援瀏覽器存取瀏覽的功能。為了把這個目錄中的內容可網路存取，可以在 gh-pages 目錄下啟動命令列執行

python3 -m http.server

我的Mac電腦裡有python環境，可以直接使用，如果各位看官執行命令的時候出現異常，請先檢查python環境。

自動化輔助功能

自動更新 gh-pages 目錄： rake build
自動提交 gh-pages 目錄到github中： rake publish title="add article MyFirstBlog"