kramdown-plantuml allows you to use PlantUML syntax within fenced
code blocks in Kramdown (Jekyll's default
```plantuml @startuml Diagram actor client node app database db db -> app app -> client @enduml ```
plantuml language identifier in fenced code blocks will allow
kramdown-plantuml to pick it up and replace it with a rendered SVG
diagram when the Markdown is rendered to HTML. The above diagram will be
replaced with the following (abbreviated) HTML code:
<div class="plantuml"> <svg> <!-- Snip converted SVG code --> </svg> </div>
Which in place will be rendered as the following:
If you configure theming (described below), the generated HTML will contain the name of the configured theme:
<div class="plantuml theme-spacelab"> <svg> <!-- Snip converted SVG code --> </svg> </div>
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
gem install kramdown-plantuml
And then add the following to your Jekyll site's
plugins: - "kramdown-plantuml"
bundle exec jekyll build or
bundle exec jekyll serve will execute
kramdown-plantuml, converting code fenced PlantUML diagrams to beautiful
kramdown-plantuml is dependent on the Java application PlantUML, which in
turn is dependent on Graphviz. This means that both Java and Graphviz need to
be installed for
kramdown-plantuml to work.
kramdown-plantuml can be configured either directly in the
provided through Kramdown or by
_config.yml provided through Jekyll.
In order to theme all PlantUML diagrams fed through
can configure a global theme with the
plantuml.theme.directory properties. Only
name is required and will allow
any of the built-in themes to be used.
The theme is simply inserted into each PlantUML diagram with the
declaration, so this can be centralized in configuration instead of duplicating
it across all diagrams.
Here's an example of how to configure
kramdown-plantuml to use the
theme in Jekyll's
kramdown: plantuml: theme: name: spacelab
If you have custom, local themes you'd like to use, you need to provide the
directory in which they are placed alongside the
name of the theme you'd
like to use:
kramdown: plantuml: theme: name: my-custom-theme directory: spec/examples
Dimensions and Styling
It's possible to customize the dimensions and scale of the diagram by providing
scale configuration keys. It's also possible to add
arbitrary styling with the
scale is applied before the diagram is generated, while
are applied after, meaning they can be combined (to most likely detrimental
results, but YOLO).
kramdown: plantuml: width: 200px height: 100px scale: 2 style: "border: 1px solid black"
To remove the
style attributes from the
element, set the key's value to
scale does not support a value of
none as it does not need to be removed.
kramdown: plantuml: width: none height: none style: none
kramdown-plantuml will raise an error and crash if something goes
wrong during processing. This can be circumvented by setting the
configuration key to
kramdown: plantuml: raise_errors: false
The default value of
Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct and sign the contributor's license agreement.
In order to do development on
kramdown-plantuml, clone or fork
this repository, perform the changes you want and submit a pull request.
The easiest way to develop and test
kramdown-plantuml is to add it as a
Jekyll plugin installed from a local path in your
gem 'kramdown-plantuml', path: 'path/to/kramdown-plantuml'
Every time you perform a change to
kramdown-plantuml, you can then, within
the directory of your Jekyll site, do a
bundle install to bring the changes
in and then start Jekyll up again afterwards with
bundle exec jekyll serve.
A few tests are exercised with GitHub Actions every time code is pushed to the repository on GitHub. You can execute these tests locally by first installing all dependencies as such:
bundle install # Installs required Ruby Gems bundle exec rake maven:install # Installs the PlantUML .jar file
And then to execute the tests you run the following:
bundle exec rake
The code within this repository is available as open source under the terms of the Apache 2.0 License and the contributor's license agreement.