yegor256/jekyll-plantuml

PlantUML plugin for Jekyll: helps you embed UML diagrams into static pages

Install it first:

$ gem install jekyll-plantuml

With Jekyll 2, simply add the gem to your _config.yml gems list:

gems: ['jekyll-plantuml', ... your other plugins]

Or for previous versions, create a plugin file within your Jekyll project's _plugins directory:

# _plugins/plantuml-plugin.rb
require "jekyll-plantuml"

Highly recommend to use Bundler. If you're using it, add this line to your Gemfile:

gem "jekyll-plantuml"

The plugin is compatible with Jekyll 3.9.3 and Jekyll 4.3.2. You can find our integration tests, which prove the compatibility, here.

Install plantuml.jar

Then, make sure PlantUML is installed on your build machine, and can be executed with a simple plantuml command.

On Ubuntu, just apt-get install -y plantuml should work. However, if it doesn't, you can create a /usr/bin/plantuml with the following content:

#!/bin/bash
java -jar /home/user/Downloads/plantuml.jar "$1" "$2"

Remember to change the path to the plantuml.jar file.

Then, set the executable permission of the file:

$ chmod +x /usr/bin/plantuml

Test

Now, it's time to create a diagram, in your Jekyll blog page:

{% plantuml %}
[First] - [Second]
{% endplantuml %}

Now, check this blog post: the UML sequence diagram in it is auto-generated using exactly this plugin. The sources of the blog are available in GitHub.

How to contribute

Read these guidelines. Make sure you build is green before you contribute your pull request. You will need to have Ruby 2.3+ and Bundler installed. Then:

$ bundle update
$ bundle exec rake

If it's clean and you don't see any error messages, submit your pull request.

jekyll-plantuml's Issues

Invoke plantuml using code-block syntax

Not sure if Jekyll plugins can do it, but worth the try. It would be awesome to be able to use this syntax for invoking PlantUML:

Alice->Bob: Hello!

Just like regular code. It makes the markdown file very readable even when not rendered by Jekyll. And it's less to type.

README issue: installation

Thanks for the great work!

I thought I should point out that we install the plugin simply by adding it to the plugins config in _config.yml like so:

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-plantuml # <---- our plugin

Would suggest you add this to the README to make installation easier :-) This is just a suggestion.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• Update dependency liquid to v5

Detected dependencies

bundler

Gemfile

• minitest '5.23.1'
• rake '13.2.1'
• rubocop '1.64.0'
• rubocop-rspec '2.29.2'
• simplecov '0.22.0'

test-jekylls/jekyll-3/Gemfile

• jekyll '4.3.3'
• kramdown '2.4.0'
• kramdown-parser-gfm '1.1.0'
• liquid '4.0.4'

test-jekylls/jekyll-4/Gemfile

• jekyll '4.3.3'
• kramdown '2.4.0'
• liquid '4.0.4'

github-actions

.github/workflows/codecov.yml

• actions/checkout v4
• ruby/setup-ruby v1
• codecov/codecov-action v4.0.0-beta.3
• ubuntu 22.04

.github/workflows/pdd.yml

• actions/checkout v4
• ubuntu 22.04

.github/workflows/rake.yml

• actions/checkout v4
• ruby/setup-ruby v1

.github/workflows/xcop.yml

• actions/checkout v4
• ubuntu 22.04

---

• Check this box to trigger a request for Renovate to run again on this repository

plantuml and jekyll or in javascript and nothing work for me.. :S

Hello everybody, i followed this tutorial https://github.com/yegor256/jekyll-plantuml, but not work for me.
The command “jekyll serve” give an error, it’ create well a UML folder, but not content a SVG file, just a UML file like: e05ea5bef2d94438d9a03889b9de5ca4.uml.

I try with JS and jquery version, same problem..

Help me please .

Indie tech review no.1

Review our existing source code and all other technical artifacts and report at least 8 bugs. More about such reviews you can read here. The task will be closed once we have that bugs reported and classified. Don't forget to add itr tag to each of them.

jekyll-plantuml build doesn't work in WSL2 environment due to Liquid exception unknown tag 'plantuml`

What I'm trying to do

Use plantuml in Jekyll blog to generate a diagram, using the below command:

bundle exec jekyll serve --watch --force-polling --livereload

My source codes

• yyyy-mm-dd-title.md file:

  {% plantuml %}
  [First] - [Second]
  {% endplantuml %}

• _config.yml file:

  plugins:
    - jekyll-plantuml

• Gemfile file:

  gem 'jekyll-plantuml', '~> 1.3', '>= 1.3.4'
  

Software versions

• OS: Ubuntu 20.04.5 LTS (using WSL2 on Windows 11)
• Ruby: 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
• Jekyll: 3.9.2
• Bundler: 2.4.8
• Liquid: 4.0.3

Expected behaviour

Jekyll build generates the HTML pages properly with the PlantUML diagrams included

Actual behaviour

Build crashes with following error:

  Liquid Exception: Liquid syntax error (line 1): Unknown tag 'plantuml' in /mnt/c/WORK/dragondive/dragondive.github.io/docs/_posts/2023-03-11-plantuml-in-jekyll-blog.md
jekyll 3.9.2 | Error:  Liquid syntax error (line 1): Unknown tag 'plantuml'
/home/dragondive/.rbenv/versions/3.1.3/lib/ruby/gems/3.1.0/gems/liquid-4.0.3/lib/liquid/document.rb:23:in `unknown_tag': Liquid syntax error (line 1): Unknown tag 'plantuml' (Liquid::SyntaxError)

What I have tried so far

• Run plantuml "standalone" in the same environment [x]

plantuml foo.puml

This properly generates the foo.png with the specified diagram. It confirms that plantuml is properly installed and working.

What else can I try to fix this problem?

---

Make sure the title of the issue explains the problem you are having. ✅ Also, the description of the issue must clearly explain what is broken, not what you want us to implement. ✅ Go through this checklist and make sure you answer "YES" to all points:

• You have all pre-requisites listed in README.md installed ✅
• You are sure that you are not reporting a duplicate (search all issues) ✅
• You say "is broken" or "doesn't work" in the title ✅
• You tell us what you are trying to do ✅
• You explain the results you are getting ✅
• You suggest an alternative result you would like to see ✅

This article will help you understand what we are looking for: http://www.yegor256.com/2014/11/24/principles-of-bug-tracking.html ✅

Estimate project size

There is no estimate in the project yet. We have to create one as explained here

width is custom

render is broken: undefined method "exists" in jekyll-plantuml-svg.rb when running on Ruby 3.2.2

Problem:

With a site on jekyll 4.3.2 with the jekyll-plantuml plugin, on ruby 3.2.2, during bundle exec jekyll build or serve I get

_plugins/jekyll-plantuml-svg.rb:53:in `render': undefined method `exists?' for File:Class (NoMethodError)

      if !File.exists?(uml) or !File.exists?(svg)
              ^^^^^^^^
Did you mean?  exist?

In Ruby 2.7.8 (doc), the exists method was available but marked deprecated. In Ruby 3 (doc), exists is gone but exist seems equivalent.

Suggestion:

Replace exists with exist throughout jekyll-plantuml.

Checklist:
✅ - You have all pre-requisites listed in README.md installed
✅ - You are sure that you are not reporting a duplicate (search all issues)
✅ - You say "is broken" or "doesn't work" in the title
✅ - You tell us what you are trying to do
✅ - You explain the results you are getting
✅ - You suggest an alternative result you would like to see

HTML code

It should be possible to add HTML code to the diagram:

{% plantuml style="width:50%" %}
[script] -down- [log]
[script] -down- [Line]
{% endplantuml %}

The result should look like this:

<p><img src='/uml/#{name}.svg' style="width:50%"
  alt='PlantUML diagram' class='plantuml'/></p>

show full error when plantuml fails

Show an error when unable to invoke PlantUML

I was trying to generate the site for the Thindeck project. I had Ruby installed, but the Maven build failed with the following error:

[INFO] --- exec-maven-plugin:1.3:exec (jekyll-build) @ thindeck ---
Configuration file: C:\Users\Carlos Miranda\git\thindeck/src/jekyll/_config.yml
            Source: C:\Users\Carlos Miranda\git\thindeck/src/jekyll
       Destination: C:\Users\Carlos Miranda\git\thindeck\target/site
      Generating...
jekyll 2.1.1 | Error:  No such file or directory - C:/Users/Carlos Miranda/git/thindeck/src/jekyll/uml/1665d464109d1a4a3c4ca71c9
c856c4f.svg

I couldn't trace the error, until I visited this project's site and saw the following in the README:

Then, make sure PlantUML is installed on your build machine, and can be executed with a simple plantuml command.

So I created a batch file which executed the plantuml.jar by the simple command plantuml and ensured that it was available in my PATH environment variable. After that, the build completed successfully.

It would be very helpful if the plugin raised an error indicating that it couldn't find and execute plantuml, instead of silently failing and causing Jekyll to throw a vague error.

avoid SVG generation cycle if file already exists

Elaborate on how jekyll-plantuml actually invokes PlantUML

This is somewhat related to #1. In our README, we have the following instruction:

Then, make sure PlantUML is installed on your build machine, and can be executed with a simple plantuml command.

I think this is a little vague. PlantUML is distributed as a Java jar file and has to be run by invoking java -jar plantuml.jar or other similar command; installing PlantUML does not actually make a plantuml command available.

It would be better if the README made this clear, for example by saying "create an alias that associates the plantuml command with the execution of java -jar plantuml.jar".

Using standard syntax

Is there any reason preventing usage of (de facto) standard syntax for PlantUML
inclusion using fencing?

I mean: Why use

{% plantuml %}
@startuml
...
@enduml
{% endplantuml %}

instead of:

```puml
@startuml
...
@enduml
```

Could this be considered in future updates?

0.1

Please, publish a new release 0.1 (or higher). Don't forget to update us here regularly (at least once a week), as explained in this article.