The project is in a healthy, maintained state
kramdown-plantuml allows you to use PlantUML syntax within fenced code blocks with Kramdown (Jekyll's default Markdown parser).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Development

~> 13.0
~> 3.2
~> 1.12
~> 1.3

Runtime

 Project Readme

Kramdown::PlantUml

Gem Version Ruby Gem No Java No PlantUML Shell Codecov Codacy Badge License CLA assistant Contributor Covenant

kramdown-plantuml allows you to use PlantUML syntax within fenced code blocks in Kramdown (Jekyll's default Markdown parser):

```plantuml
@startuml Diagram
actor client
node app
database db
db -> app
app -> client
@enduml
```

Using the 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:

Rendered SVG Diagram

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>

Installation

Add this line to your application's Gemfile:

gem 'kramdown-plantuml'

And then execute:

bundle install

Or install it yourself as:

gem install kramdown-plantuml

And then add the following to your Jekyll site's _config.yml file:

plugins:
  - "kramdown-plantuml"

Then, bundle exec jekyll build or bundle exec jekyll serve will execute kramdown-plantuml, converting code fenced PlantUML diagrams to beautiful SVG.

Requirements

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.

Configuration

kramdown-plantuml can be configured either directly in the options Hash provided through Kramdown or by _config.yml provided through Jekyll.

Theming

In order to theme all PlantUML diagrams fed through kramdown-plantuml, you can configure a global theme with the plantuml.theme.name and 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 !theme 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 spacelab theme in Jekyll's _config.yml:

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: path/to/themes

Contributing

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.

Development

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 Gemfile:

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.

Tests

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

License

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.