jekyll-kroki 0.2.2 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.devcontainer/devcontainer.json +8 -1
- data/README.md +14 -7
- data/lib/jekyll/kroki/version.rb +1 -1
- data/lib/jekyll/kroki.rb +35 -39
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 7f3956d6144278bdd3448613552e1bb2c3db31eaec49333d20a038ca4240205f
|
4
|
+
data.tar.gz: 809c19f518fc91ae2f44e02c573d86b32bb9875f48d7165a80f7263a00218b25
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7c97db5828301a44fe1db39f97e9a424c826675bc6949e1a2291aba0f271b52a51407f3e517b2c19977ab7c4da6027d7aa055a81880fb980600404846558d9aa
|
7
|
+
data.tar.gz: 8880e382989ebb202ca4d2f92ffea94c43053b41a78eacb2a9281263a7ccac52fc7a1f2485b0ac8252d16f3f9057c83e62604f78d2b374c02d360991e785d6f8
|
@@ -1,4 +1,11 @@
|
|
1
1
|
{
|
2
2
|
"name": "Ruby",
|
3
|
-
"image": "mcr.microsoft.com/devcontainers/ruby:3.0-bullseye"
|
3
|
+
"image": "mcr.microsoft.com/devcontainers/ruby:3.0-bullseye",
|
4
|
+
"customizations": {
|
5
|
+
"vscode": {
|
6
|
+
"extensions": [
|
7
|
+
"streetsidesoftware.code-spell-checker"
|
8
|
+
]
|
9
|
+
}
|
10
|
+
}
|
4
11
|
}
|
data/README.md
CHANGED
@@ -5,7 +5,6 @@
|
|
5
5
|
A [Jekyll](https://jekyllrb.com/) plugin to convert diagram descriptions into images using [Kroki](https://kroki.io/).
|
6
6
|
|
7
7
|
## Installation
|
8
|
-
|
9
8
|
Add the `jekyll-kroki` Gem to the `:jekyll_plugins` group of your site's Gemfile:
|
10
9
|
|
11
10
|
```ruby
|
@@ -15,7 +14,6 @@ end
|
|
15
14
|
```
|
16
15
|
|
17
16
|
## Usage
|
18
|
-
|
19
17
|
Kroki supports over 25 popular diagram scripting languages, including Blockdiag, D2, GraphViz, Mermaid, and PlantUML. The [examples](https://kroki.io/examples.html) page and complete list of [supported diagram languages](https://kroki.io/#support) provide a taste of what's possible.
|
20
18
|
|
21
19
|
In Markdown, simply write your diagram descriptions inside a fenced code block with the language specified:
|
@@ -34,12 +32,23 @@ When Jekyll builds your site, the `jekyll-kroki` plugin will encode the diagrams
|
|
34
32
|
|
35
33
|
![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/244d2ec4-b09b-4a5f-8164-3851574c3dd2)
|
36
34
|
|
37
|
-
The site remains truly static as the images are directly embedded in the HTML files
|
35
|
+
The site remains truly static as the images are directly embedded in the HTML files served by Jekyll. Jekyll only depends on the Kroki server (which can also be run locally) during the build stage, and all of the client-side processing that is normally used to render diagrams into images is eliminated.
|
38
36
|
|
39
|
-
|
37
|
+
### Advantages
|
40
38
|
|
41
|
-
|
39
|
+
#### Consistent syntax
|
40
|
+
Instead of using Liquid tags, `jekyll-kroki` leverages the same Markdown fenced code block syntax used by both [GitLab](https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts) and [GitHub](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) to display diagrams. Besides being more consistent, this means that diagram descriptions in Markdown files can be displayed consistently as images across the GitLab/GitHub UI and on GitLab/GitHub Pages sites generated using Jekyll. GitLab currently supports Mermaid and PlantUML, while GitHub only supports Mermaid.
|
41
|
+
|
42
|
+
#### Seamless GitLab integration
|
43
|
+
Self-managed GitLab instances can additionally enable the [Kroki integration](https://docs.gitlab.com/ee/administration/integration/kroki.html), which adds support for all the same diagram scripting languages used by `jekyll-kroki`. Furthermore, by pointing both GitLab and `jekyll-kroki` to the same Kroki instance, you can guarantee that diagrams are generated using identical versions of the diagram libraries.
|
44
|
+
|
45
|
+
#### Speed
|
46
|
+
The server-side nature of Kroki means that you don't have to deal with installing or updating any diagram library dependencies on your machine. Jekyll sites that are generated in CI/CD pipelines will thus build faster.
|
42
47
|
|
48
|
+
#### Flexibility
|
49
|
+
Kroki is available either as a free service or self-hosted using Docker. Organisations that frequently build large Jekyll sites with many diagrams or want maximum control over their data have the option of running their own Kroki instance to provide consistency and use compute resources efficiently.
|
50
|
+
|
51
|
+
### Configuration
|
43
52
|
You can specify the URL of the Kroki instance to use in the Jekyll `_config.yml` file:
|
44
53
|
|
45
54
|
```yaml
|
@@ -50,7 +59,6 @@ kroki:
|
|
50
59
|
This is useful if you want to run a Kroki instance locally or your organisation maintains its own private Kroki server. The public Kroki instance https://kroki.io is used by default.
|
51
60
|
|
52
61
|
### Security
|
53
|
-
|
54
62
|
Embedding diagrams as SVGs directly within HTML files can be dangerous. You should only use a Kroki instance that you trust (or run your own!). For additional security, you can configure a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) using custom Webrick headers in the Jekyll `_config.yml` file:
|
55
63
|
|
56
64
|
```yaml
|
@@ -60,5 +68,4 @@ webrick:
|
|
60
68
|
```
|
61
69
|
|
62
70
|
## Contributing
|
63
|
-
|
64
71
|
Bug reports and pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
|
data/lib/jekyll/kroki/version.rb
CHANGED
data/lib/jekyll/kroki.rb
CHANGED
@@ -14,47 +14,59 @@ module Jekyll
|
|
14
14
|
# Converts diagram descriptions into images using Kroki
|
15
15
|
class Kroki
|
16
16
|
KROKI_DEFAULT_URL = "https://kroki.io"
|
17
|
+
SUPPORTED_LANGUAGES = %w[actdiag blockdiag bpmn bytefield c4plantuml d2 dbml diagramsnet ditaa erd excalidraw
|
18
|
+
graphviz mermaid nomnoml nwdiag packetdiag pikchr plantuml rackdiag seqdiag structurizr
|
19
|
+
svgbob symbolator tikz umlet vega vegalite wavedrom wireviz].freeze
|
17
20
|
HTTP_MAX_RETRIES = 3
|
18
21
|
|
19
22
|
class << self
|
20
|
-
# Renders all diagram descriptions in
|
23
|
+
# Renders and embeds all diagram descriptions in a Jekyll site using Kroki.
|
21
24
|
#
|
22
|
-
# @param [Jekyll::Site] The site to embed diagrams in
|
25
|
+
# @param [Jekyll::Site] The Jekyll site to embed diagrams in
|
23
26
|
def embed_site(site)
|
24
27
|
# Get the URL of the Kroki instance
|
25
28
|
kroki_url = kroki_url(site.config)
|
26
|
-
puts "[jekyll-kroki] Rendering diagrams using Kroki instance at '#{kroki_url}'"
|
27
|
-
|
28
29
|
connection = setup_connection(kroki_url)
|
29
|
-
supported_languages = get_supported_languages(connection)
|
30
30
|
|
31
|
-
|
32
|
-
|
31
|
+
rendered_diag = 0
|
32
|
+
(site.pages + site.documents).each do |doc|
|
33
|
+
next unless embeddable?(doc)
|
34
|
+
|
35
|
+
# Render all supported diagram descriptions in the document
|
36
|
+
rendered_diag += embed_doc(connection, doc)
|
37
|
+
end
|
33
38
|
|
34
|
-
|
35
|
-
|
36
|
-
embed_page(connection, supported_languages, parsed_page)
|
37
|
-
page.output = parsed_page.to_html
|
39
|
+
unless rendered_diag.zero?
|
40
|
+
puts "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{kroki_url}'"
|
38
41
|
end
|
39
42
|
rescue StandardError => e
|
40
43
|
exit(e)
|
41
44
|
end
|
42
45
|
|
43
|
-
# Renders all diagram descriptions in
|
46
|
+
# Renders all supported diagram descriptions in a document and embeds them as inline SVGs in the HTML source.
|
44
47
|
#
|
45
48
|
# @param [Faraday::Connection] The Faraday connection to use
|
46
|
-
# @param [Array] The supported diagram languages
|
47
49
|
# @param [Nokogiri::HTML4::Document] The parsed HTML document
|
48
|
-
|
49
|
-
|
50
|
-
|
50
|
+
# @param [Integer] The number of rendered diagrams
|
51
|
+
def embed_doc(connection, doc)
|
52
|
+
# Parse the HTML document
|
53
|
+
parsed_doc = Nokogiri::HTML(doc.output)
|
54
|
+
|
55
|
+
rendered_diag = 0
|
56
|
+
SUPPORTED_LANGUAGES.each do |language|
|
57
|
+
parsed_doc.css("code[class~='language-#{language}']").each do |diagram_desc|
|
51
58
|
# Replace the diagram description with the SVG representation rendered by Kroki
|
52
59
|
diagram_desc.replace(render_diagram(connection, diagram_desc, language))
|
60
|
+
rendered_diag += 1
|
53
61
|
end
|
54
62
|
end
|
63
|
+
|
64
|
+
# Convert the document back to HTML
|
65
|
+
doc.output = parsed_doc.to_html
|
66
|
+
rendered_diag
|
55
67
|
end
|
56
68
|
|
57
|
-
# Renders a diagram description using Kroki.
|
69
|
+
# Renders a single diagram description using Kroki.
|
58
70
|
#
|
59
71
|
# @param [Faraday::Connection] The Faraday connection to use
|
60
72
|
# @param [String] The diagram description
|
@@ -64,6 +76,8 @@ module Jekyll
|
|
64
76
|
begin
|
65
77
|
response = connection.get("#{language}/svg/#{encode_diagram(diagram_desc.text)}")
|
66
78
|
rescue Faraday::Error => e
|
79
|
+
raise "'#{connection.url_prefix}' does not point to a valid Kroki instance" if e.response.nil?
|
80
|
+
|
67
81
|
raise e.response[:body]
|
68
82
|
end
|
69
83
|
expected_content_type = "image/svg+xml"
|
@@ -77,10 +91,10 @@ module Jekyll
|
|
77
91
|
end
|
78
92
|
|
79
93
|
# Sanitises a rendered diagram. Only <script> elements are removed, which is the most minimal / naive
|
80
|
-
# implementation possible
|
94
|
+
# implementation possible.
|
81
95
|
#
|
82
96
|
# @param [String] The diagram to santise in SVG format
|
83
|
-
# @return [String] The
|
97
|
+
# @return [String] The sanitised diagram
|
84
98
|
def sanitise_diagram(diagram_svg)
|
85
99
|
parsed_svg = Nokogiri::XML(diagram_svg)
|
86
100
|
parsed_svg.xpath('//*[name()="script"]').each(&:remove)
|
@@ -96,24 +110,6 @@ module Jekyll
|
|
96
110
|
Base64.urlsafe_encode64(Zlib.deflate(diagram_desc))
|
97
111
|
end
|
98
112
|
|
99
|
-
# Gets an array of supported diagram languages from the Kroki '/health' endpoint.
|
100
|
-
#
|
101
|
-
# This only shows which languages the Kroki project supports, not which ones are currently available from the
|
102
|
-
# configured Kroki instance. For example, Mermaid will still show up as a supported language even if the Mermaid
|
103
|
-
# companion container is not running.
|
104
|
-
#
|
105
|
-
# @param [Faraday::Connection] The Faraday connection to use
|
106
|
-
# @return [Array] The supported diagram languages
|
107
|
-
def get_supported_languages(connection)
|
108
|
-
response = connection.get("health")
|
109
|
-
supported_languages = response.body["version"]&.keys
|
110
|
-
raise "'#{connection.url_prefix}' does not point to a valid Kroki instance" if supported_languages.nil?
|
111
|
-
|
112
|
-
supported_languages
|
113
|
-
rescue Faraday::Error => e
|
114
|
-
raise e
|
115
|
-
end
|
116
|
-
|
117
113
|
# Sets up a new Faraday connection.
|
118
114
|
#
|
119
115
|
# @param [URI::HTTP] The URL of the Kroki instance
|
@@ -173,6 +169,6 @@ module Jekyll
|
|
173
169
|
end
|
174
170
|
end
|
175
171
|
|
176
|
-
Jekyll::Hooks.register :site, :post_render do |
|
177
|
-
Jekyll::Kroki.embed_site(
|
172
|
+
Jekyll::Hooks.register :site, :post_render do |site|
|
173
|
+
Jekyll::Kroki.embed_site(site)
|
178
174
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: jekyll-kroki
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.3.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Felix van Oost
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2023-
|
11
|
+
date: 2023-12-10 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: faraday
|