coffeebrew_jekyll_mermaid 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: eac2d44ad41589c248892f0bf3fef43bcd8518ab427bf3fc3318cce18648d434
4
+ data.tar.gz: d6a61207e231c0b65e08373ab150f1195a8e7379bd4cc7c2de0cdc1945600b3e
5
+ SHA512:
6
+ metadata.gz: 021065f7e391a54f7fae677ba5578cf45abdef42f4b3958013def4cbb03593c128796f3e0120b5d9799d40e0eaaa25be41cd5b6d0c665a58818d88c82150bef6
7
+ data.tar.gz: 6b9043de433a4a75316575f6229d4b53f143989369dec53b66c9cf8d764db6b76926e4ea05bf6c26a27d6a7087f5c9298d9fe177ccbfa311f218a969ece25e3e
data/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # Changelog
2
+
3
+ ## Version 0.1.0
4
+
5
+ [View version doc](https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/blob/v0.1.0/README.md)
6
+
7
+ - Initial release
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Coffee Brew Apps
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,279 @@
1
+ # Jekyll Mermaid Plugin
2
+
3
+ A Jekyll plugin to render Mermaid diagrams and flowcharts with options to configure themes.
4
+
5
+ [![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)
6
+
7
+ ## Installation
8
+
9
+ Add this line to your site's Gemfile:
10
+
11
+ ```ruby
12
+ gem 'coffeebrew_jekyll_mermaid'
13
+ ```
14
+
15
+ And then add this line to your site's `_config.yml`:
16
+
17
+ ```yml
18
+ plugins:
19
+ - coffeebrew_jekyll_mermaid
20
+ ```
21
+
22
+ To use render Mermaid diagrams and flowcharts in your page, use the `mermaid` Liquid tag like this:
23
+
24
+ ```
25
+ {% raw %}
26
+ {% mermaid %}
27
+ graph TD;
28
+ A-->B;
29
+ A-->C;
30
+ B-->D;
31
+ C-->D;
32
+ {% endmermaid %}
33
+ {% endraw %}
34
+ ```
35
+
36
+ The plugin will automatically inject the `mermaid.js` source so that the graph will be rendered accordingly.
37
+
38
+
39
+ ## Configuration
40
+
41
+ By default, the plugin uses this configuration.
42
+
43
+ ```yml
44
+ coffeebrew_jekyll_mermaid:
45
+ src: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs"
46
+ theme:
47
+ base: "base"
48
+ variables:
49
+ primaryColor: "#f4e3d7"
50
+ primaryTextColor: "#502d16"
51
+ primaryBorderColor: "#784421"
52
+ lineColor: "#784421"
53
+ secondaryColor: "#a05a2c"
54
+ tertiaryColor: "#c87137"
55
+ ```
56
+
57
+ You can override any of the default configuration values above.
58
+
59
+ ### Source config
60
+
61
+ This tells the plugin where to load the `mermaid.js` from. It can be a remote source like a CDN, or local file path.
62
+ Do take note that for local path, it should start with the `/` path, this tells Jekyll to load from the site's base
63
+ url.
64
+
65
+ For example:
66
+
67
+ ```yml
68
+ coffeebrew_jekyll_mermaid:
69
+ src: "/assets/js/mermaid/mermaid.js"
70
+ ```
71
+
72
+ And suppose the base url is `example.com`, then Jekyll will try to load the file from
73
+ `example.com/assets/js/mermaid/mermaid.js`.
74
+
75
+ If you load from local, make sure you have all the sub-modules included under the local directory, eg.
76
+
77
+ - commonDb-<hash>.js
78
+ - mermaidAPI-<hash>.js
79
+
80
+ Please check the <a href="https://www.jsdelivr.com/package/npm/mermaid" target="_blank">Mermaid CDN</a> for all the
81
+ files that should be included.
82
+
83
+ ### Theme config
84
+
85
+ This tells the plugin what color scheme to use for the diagrams and flowcharts.
86
+
87
+ - `base`: specifies the base theme from Mermaid
88
+ - `variables`: overrides the colors from the base theme from Mermaid
89
+
90
+ Please note that the variable keys should be camelCase. Refer to
91
+ <a href="https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables">Mermaid documentation</a>
92
+ for configurable variables.
93
+
94
+ ### Validation
95
+
96
+ Because the number of theme variables are extensive, it is not feasible for the plugin to perform validation. There's
97
+ currently no built in validation for the configuration.
98
+
99
+ ## Layout
100
+
101
+ The plugin does not provide a default layout because it only supports a custom Liquid tag. However, if you use the
102
+ `mermaid` tag, the rendered page should look something like this (using the example at the start of the doc):
103
+
104
+ ```html
105
+ {% raw %}
106
+ <script type="module">
107
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
108
+ mermaid.initialize({
109
+ startOnLoad: true,
110
+ });
111
+ </script>
112
+ <pre class="mermaid">
113
+ %%{
114
+ init: {
115
+ 'theme': 'base',
116
+ 'themeVariables': {
117
+ "primaryColor": "#f4e3d7",
118
+ "primaryTextColor": "#502d16",
119
+ "primaryBorderColor": "#784421",
120
+ "lineColor": "#784421",
121
+ "secondaryColor": "#a05a2c",
122
+ "tertiaryColor": "#c87137"
123
+ }
124
+ }
125
+ }%%
126
+ graph TD;
127
+ A--&gt;B;
128
+ A--&gt;C;
129
+ B--&gt;D;
130
+ C--&gt;D;
131
+ </pre>
132
+ {% endraw %}
133
+ ```
134
+
135
+ ## Contributing
136
+
137
+ Contribution to the gem is very much welcome!
138
+
139
+ 1. Fork it (https://github.com/coffeebrewapps/coffeebrew_jekyll_mermaid/fork).
140
+ 2. Create your feature branch (`git checkout -b my-new-feature`).
141
+ 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.
142
+ 4. Commit your changes (`git commit -am 'Add some feature'`).
143
+ 5. If you have added something that is worth mentioning in the README, please also update the README.md accordingly and commit the changes.
144
+ 6. Push to the branch (`git push origin my-new-feature`).
145
+ 7. Create a new Pull Request.
146
+
147
+ The repo owner will try to respond to a new PR as soon as possible.
148
+
149
+ ## Development
150
+
151
+ We want to provide a robust gem as much as possible for the users, so writing test cases will be required for any new
152
+ feature.
153
+
154
+ If you are contributing to the gem, please make sure you have setup your development environment correctly so that
155
+ RSpec and Rubocop can run properly.
156
+
157
+ 1. After forking the repo, go into the repo directory (`cd coffeebrew_jekyll_mermaid/`).
158
+ 2. Make sure you have the correct Ruby version installed. This gem requires Ruby >= 2.7.0.
159
+ 3. Once you have the correct Ruby version, install the development dependencies (`bundle install`).
160
+ 4. To test that you have everything installed correctly, run the test cases (`bundle exec rspec`).
161
+ 5. You should see all test cases pass successfully.
162
+
163
+ ### Source directory structure
164
+
165
+ All the gem logic lives in the `/lib` directory:
166
+
167
+ ```bash
168
+ lib
169
+ ├── coffeebrew_jekyll_mermaid
170
+ │   ├── block.rb
171
+ │   ├── config.yml
172
+ │   └── version.rb
173
+ └── coffeebrew_jekyll_mermaid.rb
174
+ ```
175
+
176
+ The files that are currently in the repo:
177
+
178
+ | File | Description |
179
+ | --- | --- |
180
+ | `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. |
181
+ | `lib/coffeebrew_jekyll_mermaid/config.yml` | This contains the default configuration for the plugin to get the `mermaid.js` source and override theme variables. |
182
+ | `lib/coffeebrew_jekyll_mermaid/version.rb` | This contains the version number of the gem. |
183
+ | `lib/coffeebrew_jekyll_mermaid.rb` | This is the entry point of the gem, and it loads the dependencies. |
184
+
185
+ ### Test cases directory structure
186
+
187
+ All the test cases and fixtures live in the `/spec` directory:
188
+
189
+ Note: Some files have been omitted for clarity.
190
+
191
+ ```bash
192
+ spec
193
+ ├── coffeebrew_jekyll_mermaid_spec.rb
194
+ ├── dest
195
+ ├── fixtures
196
+ │   ├── _config.yml
197
+ │   ├── _layouts
198
+ │   │   └── default.html
199
+ │   └── _posts
200
+ │   ├── 2021-03-12-test-post-1.md
201
+ │   ├── 2021-03-28-test-post-2.md
202
+ │   ├── 2021-05-03-test-post-3.md
203
+ │   └── 2021-05-03-test-post-4.md
204
+ ├── scenarios
205
+ │   └── default
206
+ │      ├── _site
207
+ │      │   └── posts
208
+ │      │      ├── 2021-03-12-test-post-1.html
209
+ │      │      ├── 2021-03-28-test-post-2.html
210
+ │      │      ├── 2021-05-03-test-post-3.html
211
+ │      │      └── 2021-05-03-test-post-4.html
212
+ │      └── context.rb
213
+ └── spec_helper.rb
214
+ ```
215
+
216
+ The files that are currently in the repo:
217
+
218
+ | File | Description |
219
+ | --- | --- |
220
+ | `spec/coffeebrew_jekyll_mermaid_spec.rb` | This is the main RSpec file to be executed. It contains all the contexts of various scenarios. |
221
+ | `spec/dest/` | This directory is where generated files are located. It will be deleted immediately after each context is executed. |
222
+ | `spec/fixtures/` | This directory follows the Jekyll site source structure and contains the minimal files required to generate the example pages. |
223
+ | `spec/fixtures/_posts` | This directory contains the test posts, you can add more to it to test your new feature. |
224
+ | `spec/scenarios/` | This directory contains the expected files of various test scenarios. |
225
+ | `spec/scenarios/<scenario>/` | This is the scenario name. |
226
+ | `spec/scenarios/<scenario>/_site/` | This directory contains the expected example pages. |
227
+ | `spec/scenarios/<scenario>/_config.yml` | This contains the config overrides for the scenario. |
228
+ | `spec/scenarios/<scenario>/context.rb` | This is the file that sets up the context for the test case. |
229
+ | `spec/spec_helper.rb` | This contains RSpec configuration and certain convenience methods for the main RSpec file. |
230
+
231
+ ### Writing test cases
232
+
233
+ There is a certain convention to follow when writing new test scenarios. The recommendation is to use the rake tasks
234
+ provided in the gem to generate the scenario files.
235
+
236
+ For success scenarios, run:
237
+
238
+ ```bash
239
+ bundle exec rake coffeebrew:jekyll:mermaid:test:create_success[test_scenario]
240
+ ```
241
+
242
+ This will generate a placeholder file and directory:
243
+
244
+ ```bash
245
+ spec
246
+ ├── coffeebrew_jekyll_mermaid_spec.rb
247
+ ├── scenarios
248
+ │   └── test_scenario
249
+ │      ├── _site
250
+ │      ├── _config.yml
251
+ │       └── context.rb
252
+ └── spec_helper.rb
253
+ ```
254
+
255
+ Where the `context.rb` file will be pre-populated:
256
+
257
+ ```ruby
258
+ # frozen_string_literal: true
259
+
260
+ CONTEXT_TEST_SCENARIO = "when using test_scenario config"
261
+
262
+ RSpec.shared_context CONTEXT_TEST_SCENARIO do
263
+ let(:scenario) { "test_scenario" }
264
+ let(:overrides) {} # TODO: remove if unused
265
+ let(:generated_files) {} # TODO: remove if unused
266
+ let(:expected_files) do
267
+ [
268
+ ]
269
+ end
270
+ end
271
+ ```
272
+
273
+ If you do write other test cases that are not asserting the generated files like above, you can initiate your
274
+ convention. The repo owner will evaluate the PR and accept the convention if it fits the repo existing convention, or
275
+ will recommend an alternative if it doesn't.
276
+
277
+ ## License
278
+
279
+ See the [LICENSE](LICENSE) file.
@@ -0,0 +1,98 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Coffeebrew
4
+ module Jekyll
5
+ module Mermaid
6
+ class Block < ::Liquid::Block
7
+ def render(context)
8
+ config = use_config(context)
9
+
10
+ mermaid_source = config["src"]
11
+ mermaid_theme = config["theme"]
12
+ theme_base = mermaid_theme["base"]
13
+ theme_variables = JSON.pretty_generate(mermaid_theme["variables"])
14
+
15
+ <<~HTML
16
+ <script type="module">
17
+ import mermaid from '#{mermaid_source}';
18
+ mermaid.initialize({
19
+ startOnLoad: true,
20
+ });
21
+ </script>
22
+ <pre class="mermaid">
23
+ %%{
24
+ init: {
25
+ 'theme': '#{theme_base}',
26
+ 'themeVariables': #{theme_variables}
27
+ }
28
+ }%%
29
+ #{super}
30
+ </pre>
31
+ HTML
32
+ end
33
+
34
+ private
35
+
36
+ def use_config(context)
37
+ {
38
+ "src" => use_source_config(context),
39
+ "theme" => use_theme_config(context)
40
+ }
41
+ end
42
+
43
+ def use_source_config(context)
44
+ context_source_config || user_source_config(context) || default_source_config
45
+ end
46
+
47
+ def use_theme_config(context)
48
+ ::Jekyll::Utils.deep_merge_hashes(
49
+ default_theme_config,
50
+ ::Jekyll::Utils.deep_merge_hashes(user_theme_config(context), context_theme_config)
51
+ )
52
+ end
53
+
54
+ def context_theme_config
55
+ @context_theme_config ||= context_config["theme"].to_h
56
+ end
57
+
58
+ def context_source_config
59
+ @context_source_config ||= context_config["src"]
60
+ end
61
+
62
+ def context_config
63
+ @context_config ||= @markup.empty? ? {} : JSON.parse(@markup)
64
+ end
65
+
66
+ def user_theme_config(context)
67
+ user_site_config(context)["theme"].to_h
68
+ end
69
+
70
+ def user_source_config(context)
71
+ user_site_config(context)["src"]
72
+ end
73
+
74
+ def user_site_config(context)
75
+ context.registers[:site].config["coffeebrew_jekyll_mermaid"].to_h
76
+ end
77
+
78
+ def default_theme_config
79
+ @default_theme_config ||= default_config["theme"].to_h
80
+ end
81
+
82
+ def default_source_config
83
+ @default_source_config ||= default_config["src"]
84
+ end
85
+
86
+ def default_config
87
+ @default_config ||= YAML.safe_load(File.read(default_config_path))["coffeebrew_jekyll_mermaid"].to_h
88
+ end
89
+
90
+ def default_config_path
91
+ @default_config_path ||= File.expand_path("config.yml", __dir__)
92
+ end
93
+ end
94
+
95
+ Liquid::Template.register_tag("mermaid", Coffeebrew::Jekyll::Mermaid::Block)
96
+ end
97
+ end
98
+ end
@@ -0,0 +1,11 @@
1
+ coffeebrew_jekyll_mermaid:
2
+ src: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs"
3
+ theme:
4
+ base: "base"
5
+ variables:
6
+ primaryColor: "#f4e3d7"
7
+ primaryTextColor: "#502d16"
8
+ primaryBorderColor: "#784421"
9
+ lineColor: "#784421"
10
+ secondaryColor: "#a05a2c"
11
+ tertiaryColor: "#c87137"
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Coffeebrew
4
+ module Jekyll
5
+ module Mermaid
6
+ VERSION = "0.1.0"
7
+ end
8
+ end
9
+ end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "jekyll"
4
+ require "coffeebrew_jekyll_mermaid/block"
5
+
6
+ module Coffeebrew
7
+ module Jekyll
8
+ module Mermaid
9
+ end
10
+ end
11
+ end
metadata ADDED
@@ -0,0 +1,76 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: coffeebrew_jekyll_mermaid
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Coffee Brew Apps
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2023-04-21 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: jekyll
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - ">="
18
+ - !ruby/object:Gem::Version
19
+ version: '4.0'
20
+ - - "<"
21
+ - !ruby/object:Gem::Version
22
+ version: '5.0'
23
+ type: :runtime
24
+ prerelease: false
25
+ version_requirements: !ruby/object:Gem::Requirement
26
+ requirements:
27
+ - - ">="
28
+ - !ruby/object:Gem::Version
29
+ version: '4.0'
30
+ - - "<"
31
+ - !ruby/object:Gem::Version
32
+ version: '5.0'
33
+ description: A Jekyll plugin to render Mermaid diagrams and flowcharts with options
34
+ to configure themes
35
+ email:
36
+ - coffeebrewapps@gmail.com
37
+ executables: []
38
+ extensions: []
39
+ extra_rdoc_files:
40
+ - README.md
41
+ - CHANGELOG.md
42
+ - LICENSE
43
+ files:
44
+ - CHANGELOG.md
45
+ - LICENSE
46
+ - README.md
47
+ - lib/coffeebrew_jekyll_mermaid.rb
48
+ - lib/coffeebrew_jekyll_mermaid/block.rb
49
+ - lib/coffeebrew_jekyll_mermaid/config.yml
50
+ - lib/coffeebrew_jekyll_mermaid/version.rb
51
+ homepage: https://coffeebrewapps.com/coffeebrew_jekyll_mermaid
52
+ licenses:
53
+ - MIT
54
+ metadata:
55
+ allowed_push_host: https://rubygems.org
56
+ post_install_message:
57
+ rdoc_options: []
58
+ require_paths:
59
+ - lib/coffeebrew_jekyll_mermaid
60
+ - lib
61
+ required_ruby_version: !ruby/object:Gem::Requirement
62
+ requirements:
63
+ - - ">="
64
+ - !ruby/object:Gem::Version
65
+ version: 2.7.0
66
+ required_rubygems_version: !ruby/object:Gem::Requirement
67
+ requirements:
68
+ - - ">="
69
+ - !ruby/object:Gem::Version
70
+ version: '0'
71
+ requirements: []
72
+ rubygems_version: 3.4.10
73
+ signing_key:
74
+ specification_version: 4
75
+ summary: A Jekyll plugin to render Mermaid diagrams and flowcharts
76
+ test_files: []