jekyll-kroki 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '048aeae4ac84f1263d620e1e0a6c434c9186a767132bac28a1c45b211e03be2b'
-  data.tar.gz: 05c14efd136bc6e21c77a9ae5ceaa1d81d32bff50538bc00f31aef804dad4165
+  metadata.gz: 39c2c3f9463c5788864d00c4ed80e9aa826a1aa1d1380dbff2be92407958f0e5
+  data.tar.gz: 38340a5a1deaa705a0b7cde596e5eb007da3d84526b2641e9cad6e9f38e86809
 SHA512:
-  metadata.gz: f0e1a7c0a6886a0ca621617b4bcab1e7fe4871ccaec9c0d7d78f123b5027145c5ba51428f898e00f7d2671051194d31be9510db954f9a0392d118d3f80f75d93
-  data.tar.gz: be573dafbf9f2ed85eab43057845d4cf577f9df5ed6029184400845e51d6301cff14e04d0fbcfb6bf782e457a9cbf0ec67f14c12aaed51e0e464f1935a23d924
+  metadata.gz: dbedea8bbf380c047c91cee38bc7fade0c9a6a0e3aa8735b7a18e3361219cb796fb3b89b17583db402f0b03bf083f13892d53a7677cc904d12f6be6990bfee98
+  data.tar.gz: 6c3cf11ca513c6b16331547bcd69003b77dd62c3a09b46c52e440684a5001f8c47318962037faa3a0bce5cf1e99c2dfe4a2f5f4e00f4bc0eb893ef0fb174efa6

data/.devcontainer/devcontainer.json

@@ -1,9 +1,10 @@
 {
 	"name": "Ruby",
-	"image": "mcr.microsoft.com/devcontainers/ruby:3.0-bullseye",
+	"image": "mcr.microsoft.com/devcontainers/ruby:3.4-bullseye",
 	"customizations": {
 		"vscode": {
 			"extensions": [
+				"GitHub.vscode-github-actions",
 				"streetsidesoftware.code-spell-checker"
 			]
 		}

data/.rubocop.yml

@@ -1,5 +1,14 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
 AllCops:
-  TargetRubyVersion: 2.6
+  NewCops: enable
+  TargetRubyVersion: 2.7
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: gemspec
 
 Style/StringLiterals:
   Enabled: true
@@ -11,5 +20,7 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+Metrics/ClassLength:
+  Max: 120
 Metrics/MethodLength:
-  Max: 14
+  Max: 16

data/README.md

@@ -32,7 +32,7 @@ When Jekyll builds your site, the `jekyll-kroki` plugin will encode the diagrams
 
 ![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/244d2ec4-b09b-4a5f-8164-3851574c3dd2)
 
-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.
+The site remains fully 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.
 
 ### Advantages
 
@@ -49,15 +49,25 @@ The server-side nature of Kroki means that you don't have to deal with installin
 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.
 
 ### Configuration
-You can specify the URL of the Kroki instance to use in the Jekyll `_config.yml` file:
+You can specify the following parameters in the Jekyll `_config.yml` file:
+
+| Parameter | Default value | Description |
+| --------- | ------------- | ----------- |
+| `url` | `https://kroki.io` | The URL of the Kroki instance to use |
+| `http_retries` | `3` | The number of HTTP retries |
+| `http_timeout` | `15` | The HTTP timeout value in seconds |
+| `max_concurrent_docs` | `8` | The maximum number of Jekyll documents to render concurrently |
+
+For example:
 
 ```yaml
 kroki:
   url: "https://my-kroki.server"
+  http_retries: 3
+  http_timeout: 15
+  max_concurrent_docs: 8
 ```
 
-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.
-
 ### 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:
 

data/jekyll-kroki.gemspec

@@ -12,10 +12,11 @@ Gem::Specification.new do |spec|
                       languages into images using Kroki"
   spec.homepage = "https://github.com/felixvanoost/jekyll-kroki"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   # Load the files that are versioned in Git into the RubyGem.
   spec.files = Dir.chdir(__dir__) do
@@ -28,13 +29,17 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "faraday", ["~> 2.7"]
-  spec.add_runtime_dependency "faraday-retry", ["~> 2.2"]
-  spec.add_runtime_dependency "httpx", ["~> 1.1"]
-  spec.add_runtime_dependency "jekyll", ["~> 4"]
-  spec.add_runtime_dependency "nokogiri", ["~> 1.15"]
+  spec.add_dependency "async", ["~> 2.25"]
+  spec.add_dependency "faraday", ["~> 2.7"]
+  spec.add_dependency "faraday-retry", ["~> 2.2"]
+  spec.add_dependency "httpx", ["~> 1.1"]
+  spec.add_dependency "jekyll", ["~> 4"]
+  spec.add_dependency "nokogiri", ["~> 1.15"]
 
   spec.add_development_dependency "minitest", ["~> 5.0"]
   spec.add_development_dependency "rake", ["~> 13.0"]
   spec.add_development_dependency "rubocop", ["~> 1.21"]
+  spec.add_development_dependency "rubocop-minitest", ["~> 0.38"]
+  spec.add_development_dependency "rubocop-performance", ["~> 1.25"]
+  spec.add_development_dependency "rubocop-rake", ["~> 0.7"]
 end

data/lib/jekyll/kroki/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   class Kroki
-    VERSION = "0.3.3"
+    VERSION = "0.5.0"
   end
 end

data/lib/jekyll/kroki.rb

@@ -2,6 +2,8 @@
 
 require_relative "kroki/version"
 
+require "async"
+require "async/semaphore"
 require "base64"
 require "faraday"
 require "faraday/retry"
@@ -11,32 +13,32 @@ require "nokogiri"
 require "zlib"
 
 module Jekyll
-  # Converts diagram descriptions into images using Kroki
+  # Converts diagram descriptions into images using Kroki.
   class Kroki
-    KROKI_DEFAULT_URL = "https://kroki.io"
+    DEFAULT_KROKI_URL = "https://kroki.io"
+    DEFAULT_HTTP_RETRIES = 3
+    DEFAULT_HTTP_TIMEOUT = 15
+    DEFAULT_MAX_CONCURRENT_DOCS = 8
+    EXPECTED_HTML_TAGS = %w[code div].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
-    EXPECTED_HTML_TAGS = %w[code div].freeze
-    HTTP_MAX_RETRIES = 3
 
     class << self
-      # Renders and embeds all diagram descriptions in a Jekyll site using Kroki.
+      # Renders and embeds all diagram descriptions in the given Jekyll site using Kroki.
       #
-      # @param [Jekyll::Site] The Jekyll site to embed diagrams in
+      # @param [Jekyll::Site] The Jekyll site to embed diagrams in.
       def embed_site(site)
-        # Get the URL of the Kroki instance
-        kroki_url = kroki_url(site.config)
-        connection = setup_connection(kroki_url)
-
-        rendered_diag = 0
-        (site.pages + site.documents).each do |doc|
-          next unless embeddable?(doc)
-
-          # Render all supported diagram descriptions in the document
-          rendered_diag += embed_doc(connection, doc)
-        end
+        kroki_url = get_kroki_url(site.config)
+        http_retries = get_http_retries(site.config)
+        http_timeout = get_http_timeout(site.config)
+        connection = setup_connection(kroki_url, http_retries, http_timeout)
 
+        max_concurrent_docs = get_max_concurrent_docs(site.config)
+        rendered_diag = embed_docs_in_site(site, connection, max_concurrent_docs)
         unless rendered_diag.zero?
           puts "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{kroki_url}'"
         end
@@ -44,37 +46,79 @@ module Jekyll
         exit(e)
       end
 
-      # Renders all supported diagram descriptions in a document and embeds them as inline SVGs in the HTML source.
+      # Renders the diagram descriptions in all Jekyll pages and documents in the given Jekyll site. Pages / documents
+      # are rendered concurrently up to the limit defined by DEFAULT_MAX_CONCURRENT_DOCS.
+      #
+      # @param [Jekyll::Site] The Jekyll site to embed diagrams in.
+      # @param [Faraday::Connection] The Faraday connection to use.
+      # @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|
+            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 asynchronously, respecting the concurrency limit
+      # imposed by the provided 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
+      end
+
+      # Renders the supported diagram descriptions in a single document and embeds them as inline SVGs in the HTML
+      # source.
       #
-      # @param [Faraday::Connection] The Faraday connection to use
-      # @param [Nokogiri::HTML4::Document] The parsed HTML document
-      # @param [Integer] The number of rendered diagrams
-      def embed_doc(connection, doc)
-        # Parse the HTML document
+      # @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)
 
         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
+              # 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
         end
 
-        # Convert the document back to HTML
+        # Convert the document back to HTML.
         doc.output = parsed_doc.to_html
         rendered_diag
       end
 
       # Renders a single diagram description using Kroki.
       #
-      # @param [Faraday::Connection] The Faraday connection to use
-      # @param [String] The diagram description
-      # @param [String] The language of the diagram description
-      # @return [String] The rendered diagram in SVG format
+      # @param [Faraday::Connection] The Faraday connection to use.
+      # @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)
         begin
           response = connection.get("#{language}/svg/#{encode_diagram(diagram_desc.text)}")
@@ -94,8 +138,8 @@ module Jekyll
       # 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
-      # @return [String] The sanitised diagram
+      # @param [String] The diagram to santise in SVG format.
+      # @return [String] The sanitised diagram.
       def sanitise_diagram(diagram_svg)
         parsed_svg = Nokogiri::XML(diagram_svg)
         parsed_svg.xpath('//*[name()="script"]').each(&:remove)
@@ -105,21 +149,25 @@ 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
-      # @return [String] The encoded diagram
+      # @param [String, #read] The diagram description to encode.
+      # @return [String] The encoded diagram.
       def encode_diagram(diagram_desc)
         Base64.urlsafe_encode64(Zlib.deflate(diagram_desc))
       end
 
       # Sets up a new Faraday connection.
       #
-      # @param [URI::HTTP] The URL of the Kroki instance
-      # @return [Faraday::Connection] The Faraday connection
-      def setup_connection(kroki_url)
-        retry_options = { max: HTTP_MAX_RETRIES, interval: 0.1, interval_randomness: 0.5, backoff_factor: 2,
+      # @param [URI::HTTP] The URL of the Kroki instance.
+      # @param [Integer] The number of retries.
+      # @param [Integer] The timeout value in seconds.
+      # @return [Faraday::Connection] The Faraday connection.
+      def setup_connection(kroki_url, retries, timeout)
+        retry_options = { max: retries, interval: HTTP_RETRY_INTERVAL,
+                          interval_randomness: HTTP_RETRY_INTERVAL_RANDOMNESS,
+                          backoff_factor: HTTP_RETRY_INTERVAL_BACKOFF_FACTOR,
                           exceptions: [Faraday::RequestTimeoutError, Faraday::ServerError] }
 
-        Faraday.new(url: kroki_url, request: { timeout: 5 }) do |builder|
+        Faraday.new(url: kroki_url, request: { timeout: timeout }) do |builder|
           builder.adapter :httpx, persistent: true
           builder.request :retry, retry_options
           builder.response :json, content_type: /\bjson$/
@@ -129,23 +177,43 @@ module Jekyll
 
       # Gets the URL of the Kroki instance to use for rendering diagrams.
       #
-      # @param The Jekyll site configuration
-      # @return [URI::HTTP] The URL of the Kroki instance
-      def kroki_url(config)
-        if config.key?("kroki") && config["kroki"].key?("url")
-          url = config["kroki"]["url"]
-          raise TypeError, "'url' is not a valid HTTP URL" unless URI.parse(url).is_a?(URI::HTTP)
-
-          URI(url)
-        else
-          URI(KROKI_DEFAULT_URL)
-        end
+      # @param The Jekyll site configuration.
+      # @return [URI::HTTP] The URL of the Kroki instance.
+      def get_kroki_url(config)
+        url = config.fetch("kroki", {}).fetch("url", DEFAULT_KROKI_URL)
+        raise TypeError, "'url' is not a valid HTTP URL" unless URI.parse(url).is_a?(URI::HTTP)
+
+        URI(url)
+      end
+
+      # Gets the number of HTTP retries.
+      #
+      # @param The Jekyll site configuration.
+      # @return [Integer] The number of HTTP retries.
+      def get_http_retries(config)
+        config.fetch("kroki", {}).fetch("http_retries", DEFAULT_HTTP_RETRIES)
+      end
+
+      # Gets the HTTP timeout value.
+      #
+      # @param The Jekyll site configuration.
+      # @return [Integer] The HTTP timeout value in seconds.
+      def get_http_timeout(config)
+        config.fetch("kroki", {}).fetch("http_timeout", DEFAULT_HTTP_TIMEOUT)
+      end
+
+      # Gets the maximum number of documents to render concurrently.
+      #
+      # @param The Jekyll site configuration.
+      # @return [Integer] The maximum number of documents to render concurrently.
+      def get_max_concurrent_docs(config)
+        config.fetch("kroki", {}).fetch("max_concurrent_docs", DEFAULT_MAX_CONCURRENT_DOCS)
       end
 
-      # Determines whether a document may contain embeddable diagram descriptions - it is in HTML format and is either
+      # Determines whether a document may contain embeddable diagram descriptions; it is in HTML format and is either
       # a Jekyll::Page or writeable Jekyll::Document.
       #
-      # @param [Jekyll::Page or Jekyll::Document] The document to check for embedability
+      # @param [Jekyll::Page or Jekyll::Document] The document to check for embeddability.
       def embeddable?(doc)
         doc.output_ext == ".html" && (doc.is_a?(Jekyll::Page) || doc.write?)
       end
@@ -153,7 +221,7 @@ module Jekyll
       # 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 [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.
       #
@@ -162,7 +230,7 @@ module Jekyll
         raise error
       rescue StandardError => e
         file, line_number, caller = e.backtrace[caller_index].split(":")
-        caller = caller.tr("`", "'")
+        caller = caller.tr("", "'")
         warn %([jekyll-kroki] "#{error.message}" #{caller} on line #{line_number} of #{file}).red
         exec "exit 1"
       end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-kroki
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Felix van Oost
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -122,10 +135,51 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.38'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 description: |-
   A Jekyll plugin to convert diagram descriptions written in over 25 popular diagram scripting
                         languages into images using Kroki
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -145,7 +199,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/felixvanoost/jekyll-kroki
   source_code_uri: https://github.com/felixvanoost/jekyll-kroki
-post_install_message: 
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -153,15 +207,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A Jekyll plugin to convert diagram descriptions into images using Kroki
 test_files: []