jekyll-kroki 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f2efa9a6bac231d6efdac15ccf493e387cdb1a9890f1b774ddf839b8fb0b599
-  data.tar.gz: f51d26aa98904cd284f8bea24113f6225fdc5511651c0b7a1d432898f47397fa
+  metadata.gz: 7b092bf9850f67c8e4bd7bd0d454aeeaa274b372f5ae8976f6fb05cab3f8372a
+  data.tar.gz: 1c8b189b173440b3694156281c41915c204d55b0d35d46bc866a51b0287ea73e
 SHA512:
-  metadata.gz: 1b4685d93410a2d8ea9ce9a3c97049f28ea2d4fdfcea144357ae388e0c59af9d93fdadb8c872ea80d7b48510358bd9cfedd980ae72cdfef7f586ce6ac49d915b
-  data.tar.gz: 3158b7e07f81b144d249161984b0874c48a383187a3c82c564a818864cc3401b9a5938d2b5e3632a1ed3993acb3f356d42861f6b8ed1d014ce109405537b2ef7
+  metadata.gz: bc181d7f3288979cb09d8aeae9f915de5099ecbe2b0d6b3c56f941935e3d7ea264051b7fa1c0c850f476930613bb45a2723f623f3b97867b65283e752466f16a
+  data.tar.gz: 9e46a87b36b24fc80e2a9349044b87c9c0251f59a8b1060ac498b00bf7a012dbf70415be23752988684ba234de27865526db15ea7552a764d6b4953e5fd7f975

data/.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
 	"name": "Ruby",
-	"image": "mcr.microsoft.com/devcontainers/ruby:4.0-bullseye",
+	"image": "mcr.microsoft.com/devcontainers/ruby:4.0-bookworm",
 	"customizations": {
 		"vscode": {
 			"extensions": [

data/.vscode/settings.json

@@ -3,5 +3,9 @@
     "editor.rulers": [
         120
     ],
-    "rubyLsp.formatter": "rubocop"
+    "rubyLsp.formatter": "rubocop",
+    "cSpell.language": "en-GB",
+    "cSpell.words": [
+        "Kroki"
+    ]
 }

data/README.md

@@ -45,11 +45,11 @@ Instead of using Liquid tags, `jekyll-kroki` leverages the same Markdown fenced
 
 #### Seamless GitLab integration
 
-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.
+Self-managed or dedicated GitLab instances can additionally enable the [Kroki integration](https://docs.gitlab.com/ee/administration/integration/kroki.html), which adds support for all the 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.
 
 #### Speed
 
-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 can bypass these steps and will thus build faster.
+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 can bypass these setup steps and will thus build faster. `jekyll-kroki` is built with performance in mind to minimise the build time of even the largest sites with thousands of diagrams.
 
 #### Flexibility
 
@@ -78,7 +78,7 @@ kroki:
 
 ### Security
 
-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:
+Embedding untrusted SVGs directly in HTML files can introduce security risks. Use a Kroki instance that you trust, or consider hosting your own local/private instance. For added security, you can configure a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) by adding custom Webrick headers in your Jekyll `_config.yml` file:
 
 ```yaml
 webrick:

data/lib/jekyll/kroki/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   class Kroki
-    VERSION = "0.6.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/jekyll/kroki.rb

@@ -18,13 +18,17 @@ require "zlib"
 module Jekyll
   # Converts diagram descriptions into images using Kroki.
   class Kroki
+    SUPPORTED_LANGUAGES = %w[actdiag blockdiag bpmn bytefield c4plantuml d2 dbml diagramsnet ditaa erd excalidraw
+                             graphviz mermaid nomnoml nwdiag packetdiag pikchr plantuml rackdiag seqdiag structurizr
+                             svgbob symbolator tikz umlet vega vegalite wavedrom wireviz].freeze
     EXPECTED_HTML_TAGS = %w[code div].freeze
+    DIAGRAM_SELECTOR = SUPPORTED_LANGUAGES.flat_map do |language|
+      EXPECTED_HTML_TAGS.map { |tag| "#{tag}[class~='language-#{language}']" }
+    end.join(", ").freeze
+
     HTTP_RETRY_INTERVAL_BACKOFF_FACTOR = 2
     HTTP_RETRY_INTERVAL_RANDOMNESS = 0.5
     HTTP_RETRY_INTERVAL = 0.1
-    SUPPORTED_LANGUAGES = %w[actdiag blockdiag bpmn bytefield c4plantuml d2 dbml diagramsnet ditaa erd excalidraw
-                             graphviz mermaid nomnoml nwdiag packetdiag pikchr plantuml rackdiag seqdiag structurizr
-                             svgbob symbolator tikz umlet vega vegalite wavedrom wireviz].freeze
 
     @diagram_cache = Concurrent::Map.new
 
@@ -37,11 +41,11 @@ module Jekyll
         connection = setup_connection(config.kroki_url, config.http_retries, config.http_timeout)
 
         rendered_diag = embed_docs_in_site(site, connection, config.max_concurrent_docs)
-        unless rendered_diag.zero?
-          puts "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{config.kroki_url}'"
-        end
-      rescue StandardError => e
-        fatal_error(e)
+        return unless rendered_diag.positive?
+
+        Jekyll.logger.info(
+          "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{config.kroki_url}'"
+        )
       end
 
       # Renders the diagram descriptions in all Jekyll pages and documents in the given Jekyll site. Pages / documents
@@ -52,63 +56,42 @@ module Jekyll
       # @param [Integer] The maximum number of documents to render concurrently.
       # @return [Integer] The number of successfully rendered diagrams.
       def embed_docs_in_site(site, connection, max_concurrent_docs)
-        rendered_diag = 0
         semaphore = Async::Semaphore.new(max_concurrent_docs)
 
-        Async do |task|
-          tasks = (site.pages + site.documents).filter_map do |doc|
+        Async do
+          (site.pages + site.documents).filter_map do |doc|
             next unless embeddable?(doc)
 
-            async_embed_single_doc(task, semaphore, connection, doc)
-          end
-
-          rendered_diag = tasks.sum(&:wait)
-        end
-
-        rendered_diag
-      end
-
-      # Renders the supported diagram descriptions in a single document. Multiple documents can be rendered concurrently
-      # up to the limit imposed by the given semaphore.
-      #
-      # @param [Async::Task] The parent async task to spawn a child task from.
-      # @param [Async::Semaphore] A semaphore to limit concurrency.
-      # @param [Faraday::Connection] The Faraday connection to use.
-      # @param [Jekyll::Page, Jekyll::Document] The document to process.
-      # @return [Integer] The number of successfully rendered diagrams.
-      def async_embed_single_doc(task, semaphore, connection, doc)
-        task.async do
-          semaphore.async { embed_single_doc(connection, doc) }.wait
-        rescue StandardError => e
-          warn "[jekyll-kroki] Error rendering diagram: #{e.message}".red
-          0
-        end
+            semaphore.async do
+              embed_single_doc(connection, doc)
+            rescue StandardError => e
+              Jekyll.logger.error "[jekyll-kroki] Failed to render diagram in '#{doc.relative_path}': #{e.message}"
+              0
+            end
+          end.sum(&:wait)
+        end.wait
       end
 
       # Renders the supported diagram descriptions in a single document sequentially and embeds them as inline SVGs in
-      # the HTML source.
+      # the HTML source. Returns without modifying the document if no supported diagram descriptions are found.
       #
       # @param [Faraday::Connection] The Faraday connection to use.
       # @param [Jekyll::Page, Jekyll::Document] The document to process.
       # @return [Integer] The number of successfully rendered diagrams.
       def embed_single_doc(connection, doc)
-        # Parse the HTML document.
         parsed_doc = Nokogiri::HTML(doc.output)
+        nodes = parsed_doc.css(DIAGRAM_SELECTOR)
+        return 0 if nodes.empty?
 
-        rendered_diag = 0
-        SUPPORTED_LANGUAGES.each do |language|
-          EXPECTED_HTML_TAGS.each do |tag|
-            parsed_doc.css("#{tag}[class~='language-#{language}']").each do |diagram_desc|
-              # Replace the diagram description with the SVG representation rendered by Kroki.
-              diagram_desc.replace(render_diagram(connection, diagram_desc, language))
-              rendered_diag += 1
-            end
-          end
+        nodes.each do |node|
+          # Extract the diagram language from the class list.
+          language = node["class"].split.grep(/\Alanguage-/).first.delete_prefix("language-")
+          node.replace(render_diagram(connection, node.text, language))
         end
 
         # Convert the document back to HTML.
         doc.output = parsed_doc.to_html
-        rendered_diag
+        nodes.size
       end
 
       # Renders a single diagram description using Kroki. The rendered diagram is cached to avoid redundant HTTP
@@ -118,17 +101,15 @@ module Jekyll
       # @param [String] The diagram description.
       # @param [String] The language of the diagram description.
       # @return [String] The rendered diagram in SVG format.
-      def render_diagram(connection, diagram_desc, language)
-        diagram_text = diagram_desc.text
+      def render_diagram(connection, diagram_text, language)
         cache_key = "#{language}:#{Digest::SHA1.hexdigest(diagram_text)}"
         @diagram_cache.compute_if_absent(cache_key) do
-          begin
-            response = connection.get("#{language}/svg/#{encode_diagram(diagram_text)}")
-          rescue Faraday::Error => e
-            raise e.message
-          end
+          response = connection.get("#{language}/svg/#{encode_diagram(diagram_text)}")
           validate_content_type(response)
           sanitise_diagram(response.body)
+        rescue Faraday::BadRequestError => e
+          kroki_message = e.response_body.to_s.strip
+          raise e, (kroki_message.empty? ? e.message : kroki_message)
         end
       end
 
@@ -140,14 +121,14 @@ module Jekyll
         returned_content_type = response.headers[:content_type]
         return if returned_content_type == expected_content_type
 
-        raise "Kroki returned an incorrect content type: " \
+        raise "[jekyll-kroki] Kroki returned an incorrect content type: " \
               "expected '#{expected_content_type}', received '#{returned_content_type}'"
       end
 
       # Sanitises a rendered diagram. Only <script> elements are removed, which is the most minimal / naive
       # implementation possible.
       #
-      # @param [String] The diagram to santise in SVG format.
+      # @param [String] The diagram to sanitise in SVG format.
       # @return [String] The sanitised diagram.
       def sanitise_diagram(diagram_svg)
         parsed_svg = Nokogiri::XML(diagram_svg)
@@ -158,10 +139,10 @@ module Jekyll
       # Encodes the diagram into Kroki format using deflate + base64.
       # See https://docs.kroki.io/kroki/setup/encode-diagram/.
       #
-      # @param [String, #read] The diagram description to encode.
+      # @param [String] The diagram description to encode.
       # @return [String] The encoded diagram.
       def encode_diagram(diagram_desc)
-        Base64.urlsafe_encode64(Zlib.deflate(diagram_desc))
+        Base64.urlsafe_encode64(Zlib.deflate(diagram_desc, Zlib::BEST_COMPRESSION))
       end
 
       # Sets up a new Faraday connection.
@@ -191,27 +172,13 @@ module Jekyll
       def embeddable?(doc)
         doc.output_ext == ".html" && (doc.is_a?(Jekyll::Page) || doc.write?)
       end
-
-      # Exits the Jekyll process without returning a stack trace. This method does not return because the process is
-      # abruptly terminated.
-      #
-      # @param [StandardError] The error to display in the termination message.
-      # @param [int] The caller index to display in the termination message. The default index is 1, which means the
-      #              calling method. To specify the calling method's caller, pass in 2.
-      #
-      # Source: https://www.mslinn.com/ruby/2200-crash-exit.html
-      def fatal_error(error, caller_index = 1)
-        raise error
-      rescue StandardError => e
-        file, line_number, caller = e.backtrace[caller_index].split(":")
-        caller = caller.tr("", "'")
-        warn %([jekyll-kroki] "#{error.message}" #{caller} on line #{line_number} of #{file}).red
-        exec "exit 1"
-      end
     end
   end
 end
 
 Jekyll::Hooks.register :site, :post_render do |site|
   Jekyll::Kroki.embed_site(site)
+rescue StandardError => e
+  Jekyll.logger.error "[jekyll-kroki] #{e.class}: #{e.message}"
+  raise
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-kroki
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Felix van Oost
@@ -227,7 +227,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Jekyll plugin to convert diagram descriptions into images using Kroki
 test_files: []