jekyll-kroki 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22cd7bfae1fa5a37266559c800563db4352a1f7323a65ce15a8058ddae6a7e55
-  data.tar.gz: d76013092f50d163ab83efde344705ec02e8252043d5cd90eadd68903aec472e
+  metadata.gz: 7f3956d6144278bdd3448613552e1bb2c3db31eaec49333d20a038ca4240205f
+  data.tar.gz: 809c19f518fc91ae2f44e02c573d86b32bb9875f48d7165a80f7263a00218b25
 SHA512:
-  metadata.gz: eeeeb8d251bcdbaa85429189d11c5ab3aae798b34a28fc4b7742fb195e5ba50af9d450f33dc14db629dc901b5a4e632da77d48abb599ed97b16ae2aa80cd5fee
-  data.tar.gz: 1d2bf0763f3551576b8e1d0f47b4aa8d62f14b01fe25698bd7ad1d043f4dad1a0c723f7ec607db4cae11bb4c4183be4018ae62b56a7803e8622ad83ac57aa12d
+  metadata.gz: 7c97db5828301a44fe1db39f97e9a424c826675bc6949e1a2291aba0f271b52a51407f3e517b2c19977ab7c4da6027d7aa055a81880fb980600404846558d9aa
+  data.tar.gz: 8880e382989ebb202ca4d2f92ffea94c43053b41a78eacb2a9281263a7ccac52fc7a1f2485b0ac8252d16f3f9057c83e62604f78d2b374c02d360991e785d6f8

data/.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+	"name": "Ruby",
+	"image": "mcr.microsoft.com/devcontainers/ruby:3.0-bullseye",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"streetsidesoftware.code-spell-checker"
+			]
+		}
+	}
+}

data/.rubocop.yml

@@ -12,4 +12,4 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 Metrics/MethodLength:
-  Max: 12
+  Max: 14

data/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "editor.formatOnSave": true,
+    "editor.rulers": [
+        120
+    ],
+    "rubyLsp.formatter": "rubocop"
+}

data/README.md

@@ -1,8 +1,10 @@
+![Main Workflow](https://github.com/felixvanoost/jekyll-kroki/actions/workflows/main.yml/badge.svg) 
+[![Gem Version](https://badge.fury.io/rb/jekyll-kroki.svg)](https://badge.fury.io/rb/jekyll-kroki)
+
 # jekyll-kroki
-A Jekyll plugin to convert diagram descriptions into images using 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
@@ -12,10 +14,9 @@ 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.
 
-[Kroki](https://github.com/yuzutech/kroki) supports over 20 popular diagram languages spanning several dozen diagram types. The [examples](https://kroki.io/examples.html) page provides a taste of what's possible.
-
-In Markdown, simply write your diagram description inside a fenced code block with the language specified:
+In Markdown, simply write your diagram descriptions inside a fenced code block with the language specified:
 
 ````
 ```plantuml
@@ -27,16 +28,27 @@ Kroki --> Jekyll: Rendered diagram in SVG format
 ```
 ````
 
-When Jekyll builds your site, the `jekyll-kroki` plugin will encode the diagram, send it to the Kroki server for rendering, then replace the diagram description in the generated HTML with the 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:
 
 ![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/244d2ec4-b09b-4a5f-8164-3851574c3dd2)
 
-The site remains truly static as the SVG is directly embedded in the HTML files that Jekyll serves. 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 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.
 
-`jekyll-kroki` uses the same Markdown fenced code syntax as the [GitLab Kroki integration](https://docs.gitlab.com/ee/administration/integration/kroki.html), allowing diagram descriptions in Markdown files to be displayed seamlessly in both the GitLab UI and on GitLab Pages sites generated using Jekyll.
+### Advantages
 
-### Configuration
+#### 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.
+
+#### 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.
+
+### Configuration
 You can specify the URL of the Kroki instance to use in the Jekyll `_config.yml` file:
 
 ```yaml
@@ -44,10 +56,9 @@ kroki:
   url: "https://my-kroki.server"
 ```
 
-This is useful if you want to run a Kroki instance locally or your organisation maintains its own private Kroki server. `jekyll-kroki` will use the public Kroki instance https://kroki.io by default if a URL is not specified.
+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
@@ -57,5 +68,4 @@ 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/jekyll-kroki.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Felix van Oost"]
 
   spec.summary = "A Jekyll plugin to convert diagram descriptions into images using Kroki"
-  spec.description = "Replaces diagram descriptions written in any Kroki-supported language in HTML files generated by
-                      Jekyll with their visual representation in SVG format."
+  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"
@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
 
   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"]
 

data/lib/jekyll/kroki/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   class Kroki
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/jekyll/kroki.rb

@@ -5,6 +5,7 @@ require_relative "kroki/version"
 require "base64"
 require "faraday"
 require "faraday/retry"
+require "httpx/adapters/faraday"
 require "jekyll"
 require "nokogiri"
 require "zlib"
@@ -13,45 +14,59 @@ 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
     HTTP_MAX_RETRIES = 3
 
     class << self
-      # Renders all diagram descriptions in any Kroki-supported language and embeds them throughout a Jekyll site.
+      # Renders and embeds all diagram descriptions in a Jekyll site using Kroki.
       #
-      # @param [Jekyll::Site] The 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)
-        puts "[jekyll-kroki] Rendering diagrams using Kroki instance at '#{kroki_url}'"
-
-        # Set up a Faraday connection
         connection = setup_connection(kroki_url)
 
-        # Parse the page, render and embed the diagrams, then convert it back into HTML
-        site.pages.each do |page|
-          next unless embeddable?(page)
+        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
 
-          parsed_page = Nokogiri::HTML(page.output)
-          embed_page(connection, parsed_page)
-          page.output = parsed_page.to_html
+        unless rendered_diag.zero?
+          puts "[jekyll-kroki] Rendered #{rendered_diag} diagrams using Kroki instance at '#{kroki_url}'"
         end
+      rescue StandardError => e
+        exit(e)
       end
 
-      # Renders all diagram descriptions in any Kroki-supported language and embeds them in an HTML document.
+      # Renders all supported diagram descriptions in a 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
-      def embed_page(connection, parsed_doc)
-        # Iterate through every diagram description in each of the supported languages
-        get_supported_languages(connection).each do |language|
+      # @param [Integer] The number of rendered diagrams
+      def embed_doc(connection, doc)
+        # Parse the HTML document
+        parsed_doc = Nokogiri::HTML(doc.output)
+
+        rendered_diag = 0
+        SUPPORTED_LANGUAGES.each do |language|
           parsed_doc.css("code[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
+
+        # Convert the document back to HTML
+        doc.output = parsed_doc.to_html
+        rendered_diag
       end
 
-      # Renders a diagram description using Kroki.
+      # Renders a single diagram description using Kroki.
       #
       # @param [Faraday::Connection] The Faraday connection to use
       # @param [String] The diagram description
@@ -61,6 +76,8 @@ module Jekyll
         begin
           response = connection.get("#{language}/svg/#{encode_diagram(diagram_desc.text)}")
         rescue Faraday::Error => e
+          raise "'#{connection.url_prefix}' does not point to a valid Kroki instance" if e.response.nil?
+
           raise e.response[:body]
         end
         expected_content_type = "image/svg+xml"
@@ -74,10 +91,10 @@ module Jekyll
       end
 
       # Sanitises a rendered diagram. Only <script> elements are removed, which is the most minimal / naive
-      # implementation possible and is definitely not secure.
+      # implementation possible.
       #
       # @param [String] The diagram to santise in SVG format
-      # @return [String] The sanitized diagram 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)
@@ -93,23 +110,6 @@ module Jekyll
         Base64.urlsafe_encode64(Zlib.deflate(diagram_desc))
       end
 
-      # Gets an array of supported diagram languages from the Kroki '/health' endpoint.
-      #
-      # This only shows which languages the Kroki project supports, not which ones are currently available from the
-      # configured Kroki instance. For example, Mermaid will still show up as a supported language even if the Mermaid
-      # companion container is not running.
-      #
-      # @param [Faraday::Connection] The Faraday connection to use
-      # @return [Array] The supported diagram languages
-      def get_supported_languages(connection)
-        begin
-          response = connection.get("health")
-        rescue Faraday::Error => e
-          raise e.response[:body]
-        end
-        response.body["version"].keys
-      end
-
       # Sets up a new Faraday connection.
       #
       # @param [URI::HTTP] The URL of the Kroki instance
@@ -118,7 +118,8 @@ module Jekyll
         retry_options = { max: HTTP_MAX_RETRIES, interval: 0.1, interval_randomness: 0.5, backoff_factor: 2,
                           exceptions: [Faraday::RequestTimeoutError, Faraday::ServerError] }
 
-        Faraday.new(url: kroki_url) do |builder|
+        Faraday.new(url: kroki_url, request: { timeout: 5 }) do |builder|
+          builder.adapter :httpx, persistent: true
           builder.request :retry, retry_options
           builder.response :json, content_type: /\bjson$/
           builder.response :raise_error
@@ -147,10 +148,27 @@ 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 exit(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 "echo ''"
+      end
     end
   end
 end
 
-Jekyll::Hooks.register :site, :post_render do |doc|
-  Jekyll::Kroki.embed_site(doc)
+Jekyll::Hooks.register :site, :post_render do |site|
+  Jekyll::Kroki.embed_site(site)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-kroki
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Felix van Oost
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-23 00:00:00.000000000 Z
+date: 2023-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -109,14 +123,16 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.21'
 description: |-
-  Replaces diagram descriptions written in any Kroki-supported language in HTML files generated by
-                        Jekyll with their visual representation in SVG format.
+  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: []
 files:
+- ".devcontainer/devcontainer.json"
 - ".rubocop.yml"
+- ".vscode/settings.json"
 - LICENSE
 - README.md
 - Rakefile
@@ -144,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.5
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: A Jekyll plugin to convert diagram descriptions into images using Kroki