草庐IT

为Jekyll静态网站添加PlantUML插件

老翅寒暑 2023-03-28 原文

前言

突然想起来要好好整理一下自己的博客空间，已经荒废很多年，如果再不捡起来，等到自己知识老化的时候再去写东西就没人看了。

使用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"

参考文献

  1. Github page搭建博客使用自定义插件的方法
  2. Jekyll Plugins on GitHub
  3. Quickstart for GitHub Pages
  4. 在Github Pages中使用第三方插件
  5. 使用GitHub Page部署静态页面，以及.nojekyll的坑。。
  6. jekyll安装plantuml
  7. 有哪些 Jekyll 模板值得推荐？
  8. Jekyll Spaceship
  9. kramdown基本语法
  10. SwedbankPay/kramdown-plantuml
PlantUMLJekylllanguage-plaintextcodehighlighter-rouge程序人生

有关为Jekyll静态网站添加PlantUML插件的更多相关文章

  1. ruby - 我需要将 Bundler 本身添加到 Gemfile 中吗？ - 2

    当我使用Bundler时，是否需要在我的Gemfile中将其列为依赖项？毕竟，我的代码中有些地方需要它。例如，当我进行Bundler设置时:require"bundler/setup" 最佳答案 没有。您可以尝试，但首先您必须用鞋带将自己抬离地面。 关于ruby-我需要将Bundler本身添加到Gemfile中吗？，我们在StackOverflow上找到一个类似的问题： https://stackoverflow.com/questions/4758609/

  2. ruby - 如何每月在 Heroku 运行一次 Scheduler 插件？ - 2

    在选择我想要运行操作的频率时，唯一的选项是“每天”、“每小时”和“每10分钟”。谢谢!我想为我的Rails3.1应用程序运行调度程序。 最佳答案 这不是一个优雅的解决方案，但您可以安排它每天运行，并在实际开始工作之前检查日期是否为当月的第一天。 关于ruby-如何每月在Heroku运行一次Scheduler插件？，我们在StackOverflow上找到一个类似的问题： https://stackoverflow.com/questions/8692687/

  3. ruby-on-rails - 无法使用 Rails 3.2 创建插件？ - 2

    我对最新版本的Rails有疑问。我创建了一个新应用程序(railsnewMyProject)，但我没有脚本/生成，只有脚本/rails，当我输入ruby./script/railsgeneratepluginmy_plugin"Couldnotfindgeneratorplugin.".你知道如何生成插件模板吗？没有这个命令可以创建插件吗？PS:我正在使用Rails3.2.1和ruby​​1.8.7[universal-darwin11.0] 最佳答案 随着Rails3.2.0的发布，插件生成器已经被移除。查看变更日志here.现在

  4. ruby - 将 Bootstrap Less 添加到 Sinatra - 2

    我有一个ModularSinatra应用程序，我正在尝试将Bootstrap添加到应用程序中。get'/bootstrap/application.css'doless:"bootstrap/bootstrap"end我在views/bootstrap中有所有less文件，包括bootstrap.less。我收到这个错误:Less::ParseErrorat/bootstrap/application.css'reset.less'wasn'tfound.Bootstrap.less的第一行是://CSSReset@import"reset.less";我尝试了所有不同的路径格式，但它

  5. ruby - 续集在添加关联时访问many_to_many连接表 - 2

    我正在使用Sequel构建一个愿望list系统。我有一个wishlists和itemstable和一个items_wishlists连接表(该名称是续集选择的名称)。items_wishlists表还有一个用于facebookid的额外列(因此我可以存储opengraph操作)，这是一个NOTNULL列。我还有Wishlist和Item具有续集many_to_many关联的模型已建立。Wishlist类也有:selectmany_to_many关联的选项设置为select:[:items.*,:items_wishlists__facebook_action_id].有没有一种方法可以

  6. ruby - Ping ruby 网站？ - 2

    在Ruby中可以使用哪些替代方法来ping一个ip地址？标准库“ping”库的功能似乎非常有限。我对在这里滚动我自己的代码不感兴趣。有没有好的gem？我应该接受它并忍受它吗？(我在Linux上使用Ruby1.8.6编写代码) 最佳答案 net-ping值得一看。它允许TCPping(如标准ruby​​ping)，但也允许UDP、HTTP和ICMPping。ICMPping需要root权限，但其他则不需要。 关于ruby-Pingruby网站？，我们在StackOverflow上找到一个类

  7. ruby - 可以通过多少种方法将方法添加到 ruby​​ 对象？ - 2

    当谈到运行时自省(introspection)和动态代码生成时，我认为ruby​​没有任何竞争对手，可能除了一些lisp方言。前几天，我正在做一些代码练习来探索ruby​​的动态功能，我开始想知道如何向现有对象添加方法。以下是我能想到的3种方法:obj=Object.new#addamethoddirectlydefobj.new_method...end#addamethodindirectlywiththesingletonclassclass这只是冰山一角，因为我还没有探索instance_eval、module_eval和define_method的各种组合。是否有在线/离线资

  8. ruby - 如何在 Ruby 中向现有方法定义添加语句 - 2

    我注意到类定义，如果我打开classMyClass，并在不覆盖的情况下添加一些东西我仍然得到了之前定义的原始方法。添加的新语句扩充了现有语句。但是对于方法定义，我仍然想要与类定义相同的行为，但是当我打开defmy_method时似乎,def中的现有语句和end被覆盖了，我需要重写一遍。那么有什么方法可以使方法定义的行为与定义相同，类似于super，但不一定是子类？ 最佳答案 我想您正在寻找alias_method:classAalias_method:old_func,:funcdeffuncold_func#similartoca

  9. ruby-on-rails - 添加回形针新样式不影响旧上传的图像 - 2

    我有带有Logo图像的公司模型has_attached_file:logo我用他们的Logo创建了许多公司。现在，我需要添加新样式has_attached_file:logo,:styles=>{:small=>"30x15>",:medium=>"155x85>"}我是否应该重新上传所有旧数据以重新生成新样式？我不这么认为……或者有什么rake任务可以重新生成样式吗？ 最佳答案 参见Thumbnail-Generation.如果rake任务不适合你，你应该能够在控制台中使用一个片段来调用重新处理!关于相关公司

  10. ruby - 我如何添加二进制数据来遏制 POST - 2

    我正在尝试使用Curbgem执行以下POST以解析云curl-XPOST\-H"X-Parse-Application-Id:PARSE_APP_ID"\-H"X-Parse-REST-API-Key:PARSE_API_KEY"\-H"Content-Type:image/jpeg"\--data-binary'@myPicture.jpg'\https://api.parse.com/1/files/pic.jpg用这个:curl=Curl::Easy.new("https://api.parse.com/1/files/lion.jpg")curl.multipart_form_

随机推荐