为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位置，在其中加入所需的两个插件：

1. gem 'kramdown-plantuml'
3. group :jekyll_plugins do
4.   gem "jekyll-feed", "~> 0.12"
5. #  gem 'jekyll-spaceship'
6. end

复制代码

 
2. 在 _config.yml 中找到 plugins: 位置，并加入两个插件

1. plugins:
2.   - "jekyll-paginate"
3.   - "kramdown-plantuml"
4. #  - "jekyll-spaceship"

复制代码

3. 继续在 _config.yml 中加入两个插件的配置项

1. jekyll-spaceship:
2.   # default enabled processors
3.   processors:
4.     - table-processor
5.     - mathjax-processor
6.     - plantuml-processor
7.     - mermaid-processor
8.     - polyfill-processor
9.     - media-processor
10.     - emoji-processor
11.     - element-processor
12.   mathjax-processor:
13.     src:
14.       - https://polyfill.io/v3/polyfill.min.js?features=es6
15.       - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
16.     config:
17.       tex:
18.         inlineMath:
19.           - ['$','$']
20.           - ['\(','\)']
21.         displayMath:
22.           - ['$$','$$']
23.           - ['\[','\]']
24.       svg:
25.         fontCache: 'global'
26.     optimize: # optimization on building stage to check and add mathjax scripts
27.       enabled: true # value `false` for adding to all pages
28.       include: []   # include patterns for math expressions checking (regexp)
29.       exclude: []   # exclude patterns for math expressions checking (regexp)
30.   plantuml-processor:
31.     mode: default  # mode value 'pre-fetch' for fetching image at building stage
32.     css:
33.       class: plantuml
34.     syntax:
35.       code: 'plantuml!'
36.       custom: ['@startuml', '@enduml']
37.     src: http://www.plantuml.com/plantuml/svg/
38.   mermaid-processor:
39.     mode: default  # mode value 'pre-fetch' for fetching image at building stage
40.     css:
41.       class: mermaid
42.     syntax:
43.       code: 'mermaid!'
44.       custom: ['@startmermaid', '@endmermaid']
45.     config:
46.       theme: default
47.     src: https://mermaid.ink/svg/
48.   media-processor:
49.     default:
50.       id: 'media-{id}'
51.       class: 'media'
52.       width: '100%'
53.       height: 350
54.       frameborder: 0
55.       style: 'max-width: 600px; outline: none;'
56.       allow: 'encrypted-media; picture-in-picture'
57.   emoji-processor:
58.     css:
59.       class: emoji
60.     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 插件的方法也很简单，使用如下源代码形式即可：

1. ```plantuml
2. a --> b
3. ```

复制代码

要注意，使用 jekyll-spaceship 插件的时候，默认的代码块名称加了一个! ，需要手工把上面配置项 code: 'plantuml!' 去掉感叹号。
静态网站生成

静态网站方案

静态网站的最终方案是使用分支进行区分，master 分支存放博客的源代码， gh-pages 分支存放生成的 _site 目录中的内容。 如果尚未创建 gh-pages 分支，可以用如下的方法创建：

1. mkdir gh-pages
2. cd gh-pages
3. git checkout --orphan gh-pages
4. git rm -rf ../gh-pages
5. git commit --allow-empty -m "initial commit"
6. 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了。
创建新文章

初学者对创建新文章的格式会把握不好，所以可以用命令行增加新文章。

1. rake post title="My first blog"

复制代码

自动复制

jekyll 使用指令 bundle exec jekyll build 或 bundle exec jekyll serve 处理页面代码之后的静态内容全部都放在 _site 目录下，需要手工复制到 gh-pages 目录，所以我们需要自动化脚本来处理这些事情。
编辑根目录下的 Rakefile 在尾部增加：

1. # copy from https://www.sitepoint.com/jekyll-plugins-github/
2. #
3. GH_PAGES_DIR = "gh-pages"
5. desc "Build Jekyll site and copy files"
6. task :build do
7.   system "jekyll build"
8.   system "rm -r ../#{GH_PAGES_DIR}/*" unless Dir['../#{GH_PAGES_DIR}/*'].empty?
9.   system "cp -r _site/* ../#{GH_PAGES_DIR}/"
10.   system "echo nojekyll > ../#{GH_PAGES_DIR}/.nojekyll"
11. end
13. desc "commit Jekyll site and push to github repository"
14. task :publish do
15.   title = ENV['TITLE'] || "at #{Date.today}"
17.   system "cd ../#{GH_PAGES_DIR}"
18.   system "git commit -m "publish #{title}""
19.   system "git push origin gh-pages"
20. end

复制代码

然后检查 _config.xml 中的 exclude 项，把 Rakefile 加进去。我的该项配置内容如下，加了好多东西：

1. exclude:
2.   [
3.     "less",
4.     "node_modules",
5.     "Gruntfile.js",
6.     "package.json",
7.     "package-lock.json",
8.     "README.md",
9.     "README.zh.md",
10.     "Rakefile"
11.   ]

复制代码

等你的文章写完了，就到命令行，运行 rake build 命令。如果预览觉得可以，就运行 rake publish title="加了文章" 提交到 github。 记得别忘记源代码也手动去提交，脚本不管源代码的自动提交。
网站预览

静态内容在 gh-pages 目录下，并没有任何支持浏览器访问浏览的功能。为了把这个目录中的内容可网络访问，可以在 gh-pages 目录下启动命令行运行

1. python3 -m http.server

复制代码

我的Mac电脑里有python环境，可以直接使用，如果各位看官运行命令的时候出现异常，请先检查python环境。
自动化辅助功能

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

参考文献

• Github page搭建博客使用自定义插件的方法
  
• Jekyll Plugins on GitHub
  
• Quickstart for GitHub Pages
  
• 在Github Pages中使用第三方插件
  
• 使用GitHub Page部署静态页面，以及.nojekyll的坑。。
  
• jekyll安装plantuml
  
• 有哪些 Jekyll 模板值得推荐？
  
• Jekyll Spaceship
  
• kramdown基本语法
  
• SwedbankPay/kramdown-plantuml
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！