coffeebrew_jekyll_mermaid

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:

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

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

{% raw %}
<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>
{% endraw %}

Contributing

Contribution to the gem is very much welcome!

• Fork it (https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/fork).
• Create your feature branch (git checkout -b my-new-feature).
• 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.
• Commit your changes (git commit -am 'Add some feature').
• If you have added something that is worth mentioning in the README, please also update the README.md accordingly and commit the changes.
• Push to the branch (git push origin my-new-feature).
• 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.

• After forking the repo, go into the repo directory (cd coffeebrew_jekyll_mermaid/).
• Make sure you have the correct Ruby version installed. This gem requires Ruby >= 2.7.0.
• Once you have the correct Ruby version, install the development dependencies (bundle install).
• To test that you have everything installed correctly, run the test cases (bundle exec rspec).
• 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:

File	Description
lib/coffeebrew_jekyll_mermaid/block.rb	This is the custom Liquid block that injects the mermaid.js source and wraps the Mermaid syntax in a <pre> block.
lib/coffeebrew_jekyll_mermaid/config.yml	This contains the default configuration for the plugin to get the mermaid.js source and override theme variables.
lib/coffeebrew_jekyll_mermaid/version.rb	This contains the version number of the gem.
lib/coffeebrew_jekyll_mermaid.rb	This is the entry point of the gem, and it loads the dependencies.

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:

File	Description
spec/coffeebrew_jekyll_mermaid_spec.rb	This is the main RSpec file to be executed. It contains all the contexts of various scenarios.
spec/dest/	This directory is where generated files are located. It will be deleted immediately after each context is executed.
spec/fixtures/	This directory follows the Jekyll site source structure and contains the minimal files required to generate the example pages.
spec/fixtures/_posts	This directory contains the test posts, you can add more to it to test your new feature.
spec/scenarios/	This directory contains the expected files of various test scenarios.
spec/scenarios/<scenario>/	This is the scenario name.
spec/scenarios/<scenario>/_site/	This directory contains the expected example pages.
spec/scenarios/<scenario>/_config.yml	This contains the config overrides for the scenario.
spec/scenarios/<scenario>/context.rb	This is the file that sets up the context for the test case.
spec/spec_helper.rb	This contains RSpec configuration and certain convenience methods for the main RSpec file.

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.