• Installation
• Configuration
  • Source config
  • Theme config
  • Validation
• Layout
• Contributing
• Development
  • Source directory structure
  • Test cases directory structure
  • Writing test cases
• License

Jekyll Mermaid Plugin

A Jekyll plugin to render Mermaid diagrams and flowcharts with options to configure themes.

Installation

Add this line to your site’s Gemfile:

gem 'coffeebrew_jekyll_mermaid'

And then add this line to your site’s _config.yml:

plugins:
  - coffeebrew_jekyll_mermaid

To use render Mermaid diagrams and flowcharts in your page, use the mermaid Liquid tag like this:

{% mermaid %}
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
{% endmermaid %}

The plugin will automatically inject the mermaid.js source so that the graph will be rendered accordingly.

Configuration

By default, the plugin uses this configuration.

coffeebrew_jekyll_mermaid:
  src: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs"
  theme:
    base: "base"
    variables:
      primaryColor: "#f4e3d7"
      primaryTextColor: "#502d16"
      primaryBorderColor: "#784421"
      lineColor: "#784421"
      secondaryColor: "#a05a2c"
      tertiaryColor: "#c87137"

You can override any of the default configuration values above.

Source config

This tells the plugin where to load the mermaid.js from. It can be a remote source like a CDN, or local file path. Do take note that for local path, it should start with the / path, this tells Jekyll to load from the site’s base url.

For example:

coffeebrew_jekyll_mermaid:
  src: "/assets/js/mermaid/mermaid.js"

And suppose the base url is example.com, then Jekyll will try to load the file from example.com/assets/js/mermaid/mermaid.js.

If you load from local, make sure you have all the sub-modules included under the local directory, eg.

• commonDb-.js
• mermaidAPI-.js

Please check the Mermaid CDN for all the files that should be included.

Theme config

This tells the plugin what color scheme to use for the diagrams and flowcharts.

• base: specifies the base theme from Mermaid
• variables: overrides the colors from the base theme from Mermaid

Please note that the variable keys should be camelCase. Refer to Mermaid documentation for configurable variables.

Validation

Because the number of theme variables are extensive, it is not feasible for the plugin to perform validation. There’s currently no built in validation for the configuration.

Layout

The plugin does not provide a default layout because it only supports a custom Liquid tag. However, if you use the mermaid tag, the rendered page should look something like this (using the example at the start of the doc):

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({
    startOnLoad: true,
  });
</script>
<pre class="mermaid">
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      "primaryColor": "#f4e3d7",
      "primaryTextColor": "#502d16",
      "primaryBorderColor": "#784421",
      "lineColor": "#784421",
      "secondaryColor": "#a05a2c",
      "tertiaryColor": "#c87137"
    }
  }
}%%
graph TD;
    A--&gt;B;
    A--&gt;C;
    B--&gt;D;
    C--&gt;D;
</pre>

Contributing

Contribution to the gem is very much welcome!

1. Fork it (https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/fork).
2. Create your feature branch (git checkout -b my-new-feature).
3. Make sure you have setup the repo correctly so that you can run RSpec and Rubocop on your changes. Read more under the Development section.
4. Commit your changes (git commit -am 'Add some feature').
5. If you have added something that is worth mentioning in the README, please also update the README.md accordingly and commit the changes.
6. Push to the branch (git push origin my-new-feature).
7. Create a new Pull Request.

The repo owner will try to respond to a new PR as soon as possible.

Development

We want to provide a robust gem as much as possible for the users, so writing test cases will be required for any new feature.

If you are contributing to the gem, please make sure you have setup your development environment correctly so that RSpec and Rubocop can run properly.

1. After forking the repo, go into the repo directory (cd coffeebrew_jekyll_mermaid/).
2. Make sure you have the correct Ruby version installed. This gem requires Ruby >= 2.7.0.
3. Once you have the correct Ruby version, install the development dependencies (bundle install).
4. To test that you have everything installed correctly, run the test cases (bundle exec rspec).
5. You should see all test cases pass successfully.

Source directory structure

All the gem logic lives in the /lib directory:

lib
├── coffeebrew_jekyll_mermaid
│   ├── block.rb
│   ├── config.yml
│   └── version.rb
└── coffeebrew_jekyll_mermaid.rb

The files that are currently in the repo:

Test cases directory structure

All the test cases and fixtures live in the /spec directory:

Note: Some files have been omitted for clarity.

spec
├── coffeebrew_jekyll_mermaid_spec.rb
├── dest
├── fixtures
│   ├── _config.yml
│   ├── _layouts
│   │   └── default.html
│   └── _posts
│       ├── 2021-03-12-test-post-1.md
│       ├── 2021-03-28-test-post-2.md
│       ├── 2021-05-03-test-post-3.md
│       └── 2021-05-03-test-post-4.md
├── scenarios
│   └── default
│       ├── _site
│       │   └── posts
│       │       ├── 2021-03-12-test-post-1.html
│       │       ├── 2021-03-28-test-post-2.html
│       │       ├── 2021-05-03-test-post-3.html
│       │       └── 2021-05-03-test-post-4.html
│       └── context.rb
└── spec_helper.rb

The files that are currently in the repo:

Writing test cases

There is a certain convention to follow when writing new test scenarios. The recommendation is to use the rake tasks provided in the gem to generate the scenario files.

For success scenarios, run:

bundle exec rake coffeebrew:jekyll:mermaid:test:create_success[test_scenario]

This will generate a placeholder file and directory:

spec
├── coffeebrew_jekyll_mermaid_spec.rb
├── scenarios
│   └── test_scenario
│       ├── _site
│       ├── _config.yml
│       └── context.rb
└── spec_helper.rb

Where the context.rb file will be pre-populated:

# frozen_string_literal: true

CONTEXT_TEST_SCENARIO = "when using test_scenario config"

RSpec.shared_context CONTEXT_TEST_SCENARIO do
  let(:scenario) { "test_scenario" }
  let(:overrides) {} # TODO: remove if unused
  let(:generated_files) {} # TODO: remove if unused
  let(:expected_files) do
    [
    ]
  end
end

If you do write other test cases that are not asserting the generated files like above, you can initiate your convention. The repo owner will evaluate the PR and accept the convention if it fits the repo existing convention, or will recommend an alternative if it doesn’t.

License

See the LICENSE file.