jekyll-kroki 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20faf867e0d7257dc109beb7013daffedbed2d90642e3b483d1be42a62220008
+  data.tar.gz: b248eeb60615d9343256b79b1524abe5253c5b02c2f1fa01741f3f2d914cef62
+SHA512:
+  metadata.gz: 1aa3042410e6a16d5bc1e5519a3f7e1043611d22d404ed7856c943eba4a29dd36d5bab5f0a2a732c9cce77231927855bf464211d7a1ddfe58c54b4e3ed02a448
+  data.tar.gz: e2b86eed2875b0d846955222023102cbd215bbeebe68247debff8f56af2cbe328c28d60c974e9b321927178e09361758172553dcc863404068eaabb574a822a3

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.rubocop_todo.yml

@@ -0,0 +1,37 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2023-10-18 03:15:03 UTC using RuboCop version 1.57.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 4
+Lint/ShadowedException:
+  Exclude:
+    - 'lib/jekyll-kroki.rb'
+    - 'site/_plugins/jekyll-kroki.rb'
+
+# Offense count: 2
+Naming/AccessorMethodName:
+  Exclude:
+    - 'lib/jekyll-kroki.rb'
+    - 'site/_plugins/jekyll-kroki.rb'
+
+# Offense count: 2
+# Configuration parameters: ExpectMatchingDefinition, CheckDefinitionPathHierarchy, CheckDefinitionPathHierarchyRoots, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# CheckDefinitionPathHierarchyRoots: lib, spec, test, src
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
+Naming/FileName:
+  Exclude:
+    - 'lib/jekyll-kroki.rb'
+    - 'site/_plugins/jekyll-kroki.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/jekyll-kroki.rb'
+    - 'site/_plugins/jekyll-kroki.rb'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Felix van Oost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+# jekyll-kroki
+A Jekyll plugin to convert diagram descriptions into images using Kroki
+
+## Installation
+
+Add the `jekyll-kroki` Gem to the `:jekyll_plugins` group of your site's Gemfile:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-kroki"
+end
+```
+
+## Usage
+
+[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:
+
+````
+```plantuml
+participant Jekyll
+participant Kroki #MediumSpringGreen
+
+Jekyll -> Kroki: Encoded diagram description
+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:
+
+![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/e526864f-c364-49a0-9cca-929a59343af0)
+
+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.
+
+`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.
+
+## 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/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/jekyll-kroki.gemspec

@@ -0,0 +1,37 @@
+# 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 = "Replaces diagram descriptions written in any Kroki-supported language in HTML files with their
+                      visual representation in SVG format"
+  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
+
+  # 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_runtime_dependency "jekyll", ["~> 4"]
+  spec.add_runtime_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"]
+end

data/lib/jekyll/kroki/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Kroki
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll/kroki.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "kroki/version"
+
+require "base64"
+require "jekyll"
+require "json"
+require "net/http"
+require "nokogiri"
+require "zlib"
+
+module Jekyll
+  # Jekyll plugin for the Kroki diagram engine
+  class Kroki
+    KROKI_INSTANCE_URL = "https://kroki.io"
+
+    class << self
+      # Renders all diagram descriptions written in a Kroki-supported language in an HTML document.
+      #
+      # @param [Jekyll::Page or Jekyll::Document] The document to render diagrams in
+      def render(doc)
+        puts "Rendering diagrams using Kroki"
+
+        # Parse the HTML document
+        parsed_doc = Nokogiri::HTML.parse(doc.output)
+
+        # Iterate through every diagram description in each of the supported languages
+        get_supported_languages(KROKI_INSTANCE_URL).each do |language|
+          parsed_doc.css("code[class~='language-#{language}']").each do |diagram_desc|
+            # Get the rendered diagram using Kroki
+            rendered_diagram = render_diagram(KROKI_INSTANCE_URL, diagram_desc, language)
+
+            # Replace the diagram description with the SVG representation
+            diagram_desc.replace(rendered_diagram)
+          end
+        end
+
+        # Generate the modified HTML document
+        doc.output = parsed_doc.to_html
+      end
+
+      # Renders a diagram description using Kroki.
+      #
+      # @param [String] The URL of the Kroki instance
+      # @param [String] The diagram description
+      # @param [String] The language of the diagram description
+      # @return [String] The rendered diagram in SVG format
+      def render_diagram(kroki_url, diagram_desc, language)
+        # Encode the diagram and construct the URI
+        uri = URI("#{kroki_url}/#{language}/svg/#{encode_diagram(diagram_desc.text)}")
+
+        begin
+          response = Net::HTTP.get_response(uri)
+        rescue StandardError => e
+          raise e.message
+        else
+          response.body if response.is_a?(Net::HTTPSuccess)
+        end
+      end
+
+      # Encodes the diagram into Kroki format using deflate + base64.
+      # See https://docs.kroki.io/kroki/setup/encode-diagram/.
+      #
+      # @param [String, #read] The diagram to encode
+      # @return [String] The encoded diagram
+      def encode_diagram(diagram)
+        Base64.urlsafe_encode64(Zlib.deflate(diagram))
+      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 [String] The URL of the Kroki instance
+      # @return [Array] The supported diagram languages
+      def get_supported_languages(kroki_url)
+        uri = URI("#{kroki_url}/health")
+
+        begin
+          response = Net::HTTP.get_response(uri)
+        rescue StandardError => e
+          raise e.message
+        else
+          JSON.parse(response.body)["version"].keys if response.is_a?(Net::HTTPSuccess)
+        end
+      end
+
+      # Determines whether a document may contain renderable 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 renderability
+      def renderable?(doc)
+        doc.output_ext == ".html" && (doc.is_a?(Jekyll::Page) || doc.write?)
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register [:pages, :documents], :post_render do |doc|
+  Jekyll::Kroki.render(doc) if Jekyll::Kroki.renderable?(doc)
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-kroki
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Felix van Oost
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: |-
+  Replaces diagram descriptions written in any Kroki-supported language in HTML files with their
+                        visual representation in SVG format
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- LICENSE
+- README.md
+- Rakefile
+- jekyll-kroki.gemspec
+- lib/jekyll/kroki.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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: A Jekyll plugin to convert diagram descriptions into images using Kroki
+test_files: []