為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 分支關聯。這樣兩個可以互不干擾。
簡而言之，就是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"
參考文獻
公眾號：老翅寒暑
浙公網安備 33010602011771號