jekyll-kroki 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b7f01538196d5f83bb7d6a53c39ec6f4ea3e341081805564e1bafe3e3aa380
-  data.tar.gz: fad323a88f082cc7bfddb35078246569d1b58e9ffa5a391f1344f4b9f55b5304
+  metadata.gz: 4f2efa9a6bac231d6efdac15ccf493e387cdb1a9890f1b774ddf839b8fb0b599
+  data.tar.gz: f51d26aa98904cd284f8bea24113f6225fdc5511651c0b7a1d432898f47397fa
 SHA512:
-  metadata.gz: fcba83e90f609bddd69e368f1089a0a0fc399647cc8801eee6a021e2c2fd9eb80abdc66805e811d41b26fd3738d595b561a1ae883d0037d6d8ea5e1e5aba383e
-  data.tar.gz: 1a425cdfcfc65488e0f8014a3dcefd7486943ad4d91a71d9e28915b4fe84fef357826614a642acb93d91401b8822d270c2dea20547c14a11c9fb81a648943f5b
+  metadata.gz: 1b4685d93410a2d8ea9ce9a3c97049f28ea2d4fdfcea144357ae388e0c59af9d93fdadb8c872ea80d7b48510358bd9cfedd980ae72cdfef7f586ce6ac49d915b
+  data.tar.gz: 3158b7e07f81b144d249161984b0874c48a383187a3c82c564a818864cc3401b9a5938d2b5e3632a1ed3993acb3f356d42861f6b8ed1d014ce109405537b2ef7

data/.devcontainer/devcontainer.json

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

data/.rubocop.yml

@@ -5,7 +5,7 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.0
 
 Gemspec/DevelopmentDependencies:
   EnforcedStyle: gemspec
@@ -23,4 +23,4 @@ Layout/LineLength:
 Metrics/ClassLength:
   Max: 120
 Metrics/MethodLength:
-  Max: 14
+  Max: 16

data/README.md

@@ -2,9 +2,11 @@
 [![Gem Version](https://badge.fury.io/rb/jekyll-kroki.svg)](https://badge.fury.io/rb/jekyll-kroki)
 
 # jekyll-kroki
+
 A [Jekyll](https://jekyllrb.com/) plugin to convert diagram descriptions into images using [Kroki](https://kroki.io/).
 
 ## Installation
+
 Add the `jekyll-kroki` Gem to the `:jekyll_plugins` group of your site's Gemfile:
 
 ```ruby
@@ -14,6 +16,7 @@ end
 ```
 
 ## Usage
+
 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.
 
 In Markdown, simply write your diagram descriptions inside a fenced code block with the language specified:
@@ -28,37 +31,53 @@ Kroki --> Jekyll: Rendered diagram in SVG format
 ```
 ````
 
-When Jekyll builds your site, the `jekyll-kroki` plugin will encode the diagrams, send them to the Kroki server for rendering, then replace the diagram descriptions in the generated HTML with the rendered images in SVG format:
+When Jekyll builds your site, the `jekyll-kroki` plugin encodes the diagram descriptions, renders them as SVG images using the Kroki server, then embeds them in the generated HTML:
 
 ![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/244d2ec4-b09b-4a5f-8164-3851574c3dd2)
 
-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.
+Since the images are rendered and embedded at build-time, the Jekyll site remains completely static and doesn't depend on access to the Kroki server later on. This also eliminates all of the client-side processing that is typically used to render diagrams into images.
 
 ### Advantages
 
 #### Consistent syntax
+
 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.
 
 #### 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.
 
 #### 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 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 steps and will thus build faster.
 
 #### Flexibility
-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.
+
+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 can choose to operate their own Kroki instance to ensure consistency and use compute resources efficiently. For individuals, you can also opt to run Kroki locally.
 
 ### 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:
 
 ```yaml
@@ -68,4 +87,5 @@ webrick:
 ```
 
 ## Contributing
+
 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/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Kroki
+    # Reads, validates, and exposes the jekyll-kroki configuration from the Jekyll site config.
+    class Config
+      DEFAULT_KROKI_URL = "https://kroki.io"
+      DEFAULT_HTTP_RETRIES = 3
+      DEFAULT_HTTP_TIMEOUT = 15
+      DEFAULT_MAX_CONCURRENT_DOCS = 8
+
+      attr_reader :kroki_url, :http_retries, :http_timeout, :max_concurrent_docs
+
+      # @param [Hash] The Jekyll site configuration.
+      # @raise [TypeError] If any parameter has an incorrect type.
+      # @raise [ArgumentError] If any parameter is out of the valid range.
+      def initialize(site_config)
+        kroki_config = site_config.fetch("kroki", {})
+
+        @kroki_url = parse_url(kroki_config)
+        @http_retries = parse_integer(kroki_config, "http_retries", DEFAULT_HTTP_RETRIES, min: 0)
+        @http_timeout = parse_integer(kroki_config, "http_timeout", DEFAULT_HTTP_TIMEOUT, min: 0)
+        @max_concurrent_docs = parse_integer(kroki_config, "max_concurrent_docs", DEFAULT_MAX_CONCURRENT_DOCS, min: 1)
+
+        freeze
+      end
+
+      private
+
+      def parse_url(kroki_config)
+        param_name = "url"
+        raw = kroki_config.fetch(param_name, DEFAULT_KROKI_URL)
+        uri = URI.parse(raw)
+        raise TypeError, "'#{param_name}' is not a valid HTTP URL" unless uri.is_a?(URI::HTTP)
+
+        uri
+      end
+
+      def parse_integer(kroki_config, param_name, default, min:)
+        value = kroki_config.fetch(param_name, default)
+        raise TypeError, "'#{param_name}' must be an integer" unless value.is_a?(Integer)
+        raise ArgumentError, "'#{param_name}' must be >= #{min}" if value < min
+
+        value
+      end
+    end
+  end
+end

data/lib/jekyll/kroki/version.rb

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

data/lib/jekyll/kroki.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "kroki/config"
 require_relative "kroki/version"
 
 require "async"
 require "async/semaphore"
 require "base64"
+require "concurrent-ruby"
+require "digest"
 require "faraday"
 require "faraday/retry"
 require "httpx/adapters/faraday"
@@ -15,50 +18,49 @@ require "zlib"
 module Jekyll
   # Converts diagram descriptions into images using Kroki.
   class Kroki
-    KROKI_DEFAULT_URL = "https://kroki.io"
-    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
     HTTP_RETRY_INTERVAL_BACKOFF_FACTOR = 2
     HTTP_RETRY_INTERVAL_RANDOMNESS = 0.5
-    HTTP_RETRY_INTERVAL_SECONDS = 0.1
-    HTTP_TIMEOUT_SECONDS = 15
-    MAX_CONCURRENT_DOCS = 8
+    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
 
     class << self
       # Renders and embeds all diagram descriptions in the given Jekyll site using Kroki.
       #
       # @param [Jekyll::Site] The Jekyll site to embed diagrams in.
       def embed_site(site)
-        kroki_url = kroki_url(site.config)
-        connection = setup_connection(kroki_url)
+        config = Config.new(site.config)
+        connection = setup_connection(config.kroki_url, config.http_retries, config.http_timeout)
 
-        rendered_diag = embed_docs_in_site(site, connection)
+        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 '#{kroki_url}'"
+          puts "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{config.kroki_url}'"
         end
       rescue StandardError => e
-        exit(e)
+        fatal_error(e)
       end
 
       # 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 MAX_CONCURRENT_DOCS.
+      # are rendered concurrently up to the limit defined by 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)
+      def embed_docs_in_site(site, connection, max_concurrent_docs)
         rendered_diag = 0
-        semaphore = Async::Semaphore.new(MAX_CONCURRENT_DOCS)
+        semaphore = Async::Semaphore.new(max_concurrent_docs)
 
         Async do |task|
-          tasks = (site.pages + site.documents).map do |doc|
+          tasks = (site.pages + site.documents).filter_map do |doc|
             next unless embeddable?(doc)
 
             async_embed_single_doc(task, semaphore, connection, doc)
-          end.compact
+          end
 
           rendered_diag = tasks.sum(&:wait)
         end
@@ -66,8 +68,8 @@ module Jekyll
         rendered_diag
       end
 
-      # Renders the supported diagram descriptions in a single document asynchronously, respecting the concurrency limit
-      # imposed by the provided semaphore.
+      # 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.
@@ -83,8 +85,8 @@ module Jekyll
         end
       end
 
-      # Renders the supported diagram descriptions in a single document and embeds them as inline SVGs in the HTML
-      # source.
+      # Renders the supported diagram descriptions in a single document sequentially and embeds them as inline SVGs in
+      # the HTML source.
       #
       # @param [Faraday::Connection] The Faraday connection to use.
       # @param [Jekyll::Page, Jekyll::Document] The document to process.
@@ -109,26 +111,37 @@ module Jekyll
         rendered_diag
       end
 
-      # Renders a single diagram description using Kroki.
+      # Renders a single diagram description using Kroki. The rendered diagram is cached to avoid redundant HTTP
+      # requests across documents, using the diagram language and the SHA1 of the diagram description as the key.
       #
       # @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)}")
-        rescue Faraday::Error => e
-          raise e.message
+        diagram_text = diagram_desc.text
+        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
+          validate_content_type(response)
+          sanitise_diagram(response.body)
         end
+      end
+
+      # Validates that the Kroki response has the expected SVG content type.
+      #
+      # @param [Faraday::Response] The response to validate.
+      def validate_content_type(response)
         expected_content_type = "image/svg+xml"
         returned_content_type = response.headers[:content_type]
-        if returned_content_type != expected_content_type
-          raise "Kroki returned an incorrect content type: " \
-                "expected '#{expected_content_type}', received '#{returned_content_type}'"
+        return if returned_content_type == expected_content_type
 
-        end
-        sanitise_diagram(response.body)
+        raise "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
@@ -154,14 +167,16 @@ module Jekyll
       # Sets up a new Faraday connection.
       #
       # @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)
-        retry_options = { max: HTTP_MAX_RETRIES, interval: HTTP_RETRY_INTERVAL_SECONDS,
+      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: HTTP_TIMEOUT_SECONDS }) 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$/
@@ -169,24 +184,10 @@ module Jekyll
         end
       end
 
-      # 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)
-        else
-          url = KROKI_DEFAULT_URL
-        end
-        URI(url)
-      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 embeddability.
+      # @param [Jekyll::Page or Jekyll::Document] The document to check for embeddable diagrams.
       def embeddable?(doc)
         doc.output_ext == ".html" && (doc.is_a?(Jekyll::Page) || doc.write?)
       end
@@ -199,7 +200,7 @@ module Jekyll
       #              calling method. To specify the calling method's caller, pass in 2.
       #
       # Source: https://www.mslinn.com/ruby/2200-crash-exit.html
-      def exit(error, caller_index = 1)
+      def fatal_error(error, caller_index = 1)
         raise error
       rescue StandardError => e
         file, line_number, caller = e.backtrace[caller_index].split(":")

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-kroki
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Felix van Oost
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.25'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -190,14 +204,13 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- jekyll-kroki.gemspec
 - lib/jekyll/kroki.rb
+- lib/jekyll/kroki/config.rb
 - lib/jekyll/kroki/version.rb
 homepage: https://github.com/felixvanoost/jekyll-kroki
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/felixvanoost/jekyll-kroki
   source_code_uri: https://github.com/felixvanoost/jekyll-kroki
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -207,14 +220,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Jekyll plugin to convert diagram descriptions into images using Kroki
 test_files: []

data/jekyll-kroki.gemspec

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/jekyll/kroki/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "jekyll-kroki"
-  spec.version = Jekyll::Kroki::VERSION
-  spec.authors = ["Felix van Oost"]
-
-  spec.summary = "A Jekyll plugin to convert diagram descriptions into images using Kroki"
-  spec.description = "A Jekyll plugin to convert diagram descriptions written in over 25 popular diagram scripting
-                      languages into images using Kroki"
-  spec.homepage = "https://github.com/felixvanoost/jekyll-kroki"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.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
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  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