coffeebrew_jekyll_mermaid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eac2d44ad41589c248892f0bf3fef43bcd8518ab427bf3fc3318cce18648d434
+  data.tar.gz: d6a61207e231c0b65e08373ab150f1195a8e7379bd4cc7c2de0cdc1945600b3e
+SHA512:
+  metadata.gz: 021065f7e391a54f7fae677ba5578cf45abdef42f4b3958013def4cbb03593c128796f3e0120b5d9799d40e0eaaa25be41cd5b6d0c665a58818d88c82150bef6
+  data.tar.gz: 6b9043de433a4a75316575f6229d4b53f143989369dec53b66c9cf8d764db6b76926e4ea05bf6c26a27d6a7087f5c9298d9fe177ccbfa311f218a969ece25e3e

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Version 0.1.0
+
+[View version doc](https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/blob/v0.1.0/README.md)
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Coffee Brew Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,279 @@
+# Jekyll Mermaid Plugin
+
+A Jekyll plugin to render Mermaid diagrams and flowcharts with options to configure themes.
+
+[![Continuous Integration](https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/actions/workflows/ruby.yml/badge.svg)](https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/actions/workflows/ruby.yml) [![Gem Version](https://badge.fury.io/rb/coffeebrew_jekyll_mermaid.svg)](https://badge.fury.io/rb/coffeebrew_jekyll_mermaid)
+
+## Installation
+
+Add this line to your site's Gemfile:
+
+```ruby
+gem 'coffeebrew_jekyll_mermaid'
+```
+
+And then add this line to your site's `_config.yml`:
+
+```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.
+
+```yml
+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:
+
+```yml
+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-<hash>.js
+- mermaidAPI-<hash>.js
+
+Please check the <a href="https://www.jsdelivr.com/package/npm/mermaid" target="_blank">Mermaid CDN</a> 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
+<a href="https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables">Mermaid documentation</a>
+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):
+
+```html
+{% 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!
+
+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](#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:
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+bundle exec rake coffeebrew:jekyll:mermaid:test:create_success[test_scenario]
+```
+
+This will generate a placeholder file and directory:
+
+```bash
+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:
+
+```ruby
+# 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](LICENSE) file.

data/lib/coffeebrew_jekyll_mermaid/block.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Mermaid
+      class Block < ::Liquid::Block
+        def render(context)
+          config = use_config(context)
+
+          mermaid_source = config["src"]
+          mermaid_theme = config["theme"]
+          theme_base = mermaid_theme["base"]
+          theme_variables = JSON.pretty_generate(mermaid_theme["variables"])
+
+          <<~HTML
+            <script type="module">
+              import mermaid from '#{mermaid_source}';
+              mermaid.initialize({
+                startOnLoad: true,
+              });
+            </script>
+            <pre class="mermaid">
+            %%{
+              init: {
+                'theme': '#{theme_base}',
+                'themeVariables': #{theme_variables}
+              }
+            }%%
+            #{super}
+            </pre>
+          HTML
+        end
+
+        private
+
+        def use_config(context)
+          {
+            "src" => use_source_config(context),
+            "theme" => use_theme_config(context)
+          }
+        end
+
+        def use_source_config(context)
+          context_source_config || user_source_config(context) || default_source_config
+        end
+
+        def use_theme_config(context)
+          ::Jekyll::Utils.deep_merge_hashes(
+            default_theme_config,
+            ::Jekyll::Utils.deep_merge_hashes(user_theme_config(context), context_theme_config)
+          )
+        end
+
+        def context_theme_config
+          @context_theme_config ||= context_config["theme"].to_h
+        end
+
+        def context_source_config
+          @context_source_config ||= context_config["src"]
+        end
+
+        def context_config
+          @context_config ||= @markup.empty? ? {} : JSON.parse(@markup)
+        end
+
+        def user_theme_config(context)
+          user_site_config(context)["theme"].to_h
+        end
+
+        def user_source_config(context)
+          user_site_config(context)["src"]
+        end
+
+        def user_site_config(context)
+          context.registers[:site].config["coffeebrew_jekyll_mermaid"].to_h
+        end
+
+        def default_theme_config
+          @default_theme_config ||= default_config["theme"].to_h
+        end
+
+        def default_source_config
+          @default_source_config ||= default_config["src"]
+        end
+
+        def default_config
+          @default_config ||= YAML.safe_load(File.read(default_config_path))["coffeebrew_jekyll_mermaid"].to_h
+        end
+
+        def default_config_path
+          @default_config_path ||= File.expand_path("config.yml", __dir__)
+        end
+      end
+
+      Liquid::Template.register_tag("mermaid", Coffeebrew::Jekyll::Mermaid::Block)
+    end
+  end
+end

data/lib/coffeebrew_jekyll_mermaid/config.yml

@@ -0,0 +1,11 @@
+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"

data/lib/coffeebrew_jekyll_mermaid/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Mermaid
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/coffeebrew_jekyll_mermaid.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "coffeebrew_jekyll_mermaid/block"
+
+module Coffeebrew
+  module Jekyll
+    module Mermaid
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: coffeebrew_jekyll_mermaid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Coffee Brew Apps
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Jekyll plugin to render Mermaid diagrams and flowcharts with options
+  to configure themes
+email:
+- coffeebrewapps@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- LICENSE
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/coffeebrew_jekyll_mermaid.rb
+- lib/coffeebrew_jekyll_mermaid/block.rb
+- lib/coffeebrew_jekyll_mermaid/config.yml
+- lib/coffeebrew_jekyll_mermaid/version.rb
+homepage: https://coffeebrewapps.com/coffeebrew_jekyll_mermaid
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib/coffeebrew_jekyll_mermaid
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: A Jekyll plugin to render Mermaid diagrams and flowcharts
+test_files: []