jekyll-gem-resolver 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74d9ea3d879cc2078bf4ca0e6b68eaacf59ec41f0d558106b4e05db9ade46642
+  data.tar.gz: d6b0244738b348355b8a02454ab55a7a85e19e34a2deeecc44ed9389fb1d8b0a
+SHA512:
+  metadata.gz: 79f4e904fb806be39b7768bf11c4b5c0669eab0fc8d7d8fd3e1d3d8310c71333ba8d711efdb3fbc7b8b88b81bdf5c7dbb98c9a05330e24c8aef21803ad7afc25
+  data.tar.gz: 7d84e011b33b4495ba69d1baefd8549e769bb12927935696ad1877f4cf3f4d852cafc9dd89426d7eafe7392a6a76abdf169df0cdb5292690d8ee7b8e8c12b292

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lukas Waslowski
+
+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,196 @@
+# jekyll-gem-resolver
+
+Simple Jekyll plugin to allow including resources from non-Jekyll gems into the site build.
+
+### Purpose
+
+When enabled, the plugin scans certain, configurable parts of your `_config.yml` file for references of the form `"gem:package:path/in/package"` (or `"gem:package/path/in/package"`) and replaces them with absolute paths to the correct Gem directory/file, using the Gem version specified in your `Gemfile` / `Gemfile.lock`.
+
+### History
+
+The origin of this plugin is that I wanted to build [Bootstrap][bootstrap-website]
+from source using Jekyll's SASS processor and the [boostrap gem][bootstrap-rubygem]. But there is no easy way to reference the external files of the `bootstrap` gem
+in your `_config.yml`, except for using absolute paths, which feels unsatisfying for a number of reasons.
+This plugin was born to resolve this problem.
+
+## Installation
+
+This plugin is available as a [RubyGem][published-ruby-gem].
+
+Add this line to your application's `Gemfile`:
+
+```
+gem 'jekyll-gem-resoler'
+```
+
+And then execute the `bundle` command to install the gem.
+
+Alternatively, you can also manually install the gem using the following command:
+
+```
+$ gem install jekyll-gem-resolver
+```
+
+After the plugin has been installed successfully, add the following lines to your `_config.yml` in order to tell Jekyll to use the plugin:
+
+```yaml
+plugins:
+- jekyll-gem-resolver
+
+gem_resolver:
+  transform:
+    - sass.load_paths
+```
+
+## Usage
+
+A typical configuration could look like this:
+
+```ruby
+# Excerpt from <your_directory>/Gemfile
+source "https://rubygems.org"
+
+# Or whatever version of Jekyll you are using
+gem "jekyll", "~> 4.3.3"
+
+# Declare the gems that you want to reference
+gem "bootstrap", "~> 5.3.2"
+
+group :jekyll_plugins do
+  gem "jekyll-gem-resolver", "~> 1.0"
+end
+```
+
+```yaml
+# Excerpt from <your_directory>/_config.yml
+plugins:
+  - jekyll-gem-resolver
+
+# A configuration for another plugin that references files and/or folders from a Gem
+sass:
+  load_paths:
+    - 'gem:bootstrap/assets/stylesheets'
+
+
+# Tell jekyll-gem-resolver where in the configuration to look for
+# "gem:" references. The format is explained below.
+gem_resolver:
+  transform:
+    - sass.load_paths"
+```
+
+The usage of the plugin is split into two parts:
+
+1. Specifying where in the configuration `gem:` paths might appear
+   using a JSONPath-like language.
+
+2. Using a `gem:<..>` reference in those places in the configuration.
+
+### Gem Reference Syntax
+
+Gem references are written like this `"gem:package_name:path/in/package"` (or `"gem:package_name/path/in/package"`, if `package_name` does not contain a `'/'` character), which is resolved to something like:
+
+```
+/home/<your_username>/.gems/gems/<package_name>@<version_from_gemfile>/<path_in_package>
+```
+
+Note that you have to use **double or single quotes** around the `gem:` references in your YAML file,
+because without it, the `gem:` prefix would erroneously be parsed as a hash by the YAML parer.
+
+### Path Syntax
+
+A path consists of multiple segments separated by a `'.'` character.
+Each segment is either:
+
+- an identifier (e.g. `myplugin.config_setting`, for hash elements),
+- a number (e.g. `myplugin.items.1`, for array elements), or
+- the string `*` (e.g. `myplugin.items.*.ident`, meaning "all elements of this array or hash").
+
+Each segment can optionally be wrapped in `[brackets]`,
+which is just syntatic sugar for the same thing without brackets. By convention, we write array indidces and `*` in brackets, and hash elements without:
+
+```
+my_plugin.array.[1]
+my_plugin.array.[*]
+my_plugin.hash.something
+my_plugin.hash.[*]
+```
+
+When referring to all items of an array as the last segment of a path (e.g. `my_plugin.array.[*]`), you can omit the final `*` and just write it as: `my_plugin.array`.
+
+#### Some more examples
+
+```yaml
+# You can process global settings
+global_setting: "gem:example" # Matched by: "global-setting"
+
+# You process items in arrays
+global_array:
+  - "gem:package1/assets/js" #  Matched by "global_array", "global_array.[*]" and "global_array.[0]"
+  - "gem:package2/assets/css" # Matched by "global_array", "global_array.[*]" and "global_array.[1]"
+  - "gem:package3/assets/js" #  Matched by "global_array", "global_array.[*]" and "global_array.[2]"
+
+# You can transform items in nested arrays as well
+my_plugin:
+  - name: "I don't know"
+    children:
+      # Matched by:
+      #   "my_plugin.[*].children"
+      #   "my_plugin.[*].children.[*]"
+      #   "my_plugin.[*].children.[1]
+      #   "my_plugin.[0].children.[*]
+      #   "my_plugin.[0].children.[1]"
+      - "gem:package1/assets/js"
+
+  - name: "I don't know either"
+    children:
+      # Matched by:
+      #   "my_plugin.[*].children"
+      #   "my_plugin.[*].children.[*]"
+      #   "my_plugin.[*].children.[0]
+      #   "my_plugin.[1].children.[*]
+      #   "my_plugin.[1].children.[0]"
+      - "gem:package2/assets/css"
+      # Matched by:
+      #   "my_plugin.[*].children"
+      #   "my_plugin.[*].children.[*]"
+      #   "my_plugin.[*].children.[1]
+      #   "my_plugin.[1].children.[*]
+      #   "my_plugin.[1].children.[1]"
+      - "gem:package3/assets/js"
+
+# You can even process items in hashes
+categories:
+  category_a:
+    # Matched by:
+    #   "categories.category_a.template_styles
+    #   "categories.[*].template_styles
+    template_styles: "gem:package4/templates/"
+  category_b:
+    # Matched by:
+    #   "categories.category_a.template_styles
+    #   "categories.[*].template_styles
+    template_styles: "gem:package4/templates/"
+
+# Note that omission of the final ".[*]" only works for arrays,
+# not for hashes:
+my_other_plugin:
+  config_dict:
+    # The string values below are matched by "my_other_plugin.config_dict.[*]",
+    # but NOT by "my_other_plugin.config_dict".
+    entry_a: "gem:package5/abc"
+    entry_b: "gem:package5/def"
+    entry_c: "gem:package5/ghi"
+```
+
+# Contribute
+Fork this repository, make your changes and then issue a pull request. If you find bugs or have new ideas that you do not want to implement yourself, file a bug report.
+
+# Copyright
+Copyright (c) 2024 Lukas Waslowski.
+
+License: MIT
+
+[bootstrap-website]: https://getbootstrap.com
+[bootstrap-rubygem]: https://github.com/twbs/bootstrap-rubygem
+[published-ruby-gem]: https://rubygems.org/gems/jekyll-gem-resolver

data/lib/jekyll/gem_resolver/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module GemResolver
+    VERSION = '0.0.2'
+  end
+end

data/lib/jekyll_gem_resolver.rb

@@ -0,0 +1,77 @@
+module JekyllGemResolver
+  def self.transform_config(site)
+    options = site.config['gem_resolver'] || {}
+    (options['transform'] || []).each { |path_to_transform| transform_config_node(site.config, path_to_transform.split('.')) }
+  end
+
+  private
+
+  def self.transform_config_node(node, path, use_fallbacks = true)
+    # Have we arrived at the last segment of the path?
+    if path.nil? || path.empty?
+      # Special behavior: If this node is an array, behave as if path contains an additional '.*'
+      return transform_config_node(node, ['*'], false) if node.is_a?(Array) && use_fallbacks
+
+      # Not an array: Directly process this node
+      return transform_config_value(node)
+    end
+
+    # The path has at least one remaining segment
+    key = strip_brackets(path[0])
+    remaining_path = path[1..-1]
+
+    if node.is_a? Array
+      if key == '*'
+        # Transform each value in this array recursively
+        node.map! { |value| transform_config_node(value, remaining_path)  }
+      else
+        # Recurse into the specified array item
+        index = Integer(key)
+        node[index] = transform_config_node(node[index], remaining_path)
+      end
+    elsif node.is_a? Hash
+      if key == '*'
+        # Transform each value in this hash recursively
+        node.transform_values! { |value| transform_config_node(value, remaining_path)  }
+      else
+        # Recurse into the specified hash value
+        node[key] = transform_config_node(node[key], remaining_path)
+      end
+    else
+      # The path has remaining segments, but this is a leaf node.
+      # This means that the specified path does not match, and we therefore
+      # do not modify or transform this node.
+    end
+
+    return node
+  end
+
+  def self.strip_brackets(text)
+      return text unless text
+      return text.gsub(/^\[(.+)\]$/, '\1')
+  end
+
+  def self.transform_config_value(value)
+    return value unless value.is_a? String
+
+    result = if /^gem:(?<gem_name>[^:]+):(?<relative_path>.*)/ =~ value
+      resolve_gem(gem_name, "/#{relative_path}")
+    elsif /^gem:(?<gem_name>[^\/]+)(?<relative_path>.*)/ =~ value
+      resolve_gem(gem_name, relative_path)
+    else
+      nil
+    end
+
+    Jekyll.logger.info("Resolved #{value} to #{result}") unless result.nil?
+    result
+  end
+
+  def self.resolve_gem(gem_name, relative_path)
+    spec = Gem::Specification.find_by_name(gem_name)
+    spec.gem_dir + relative_path
+  end
+
+  Jekyll::Hooks.register :site, :after_init do |site|
+    transform_config(site)
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-gem-resolver
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Lukas Waslowksi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.3
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.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'
+description: Gem resolver for Jekyll
+email:
+- cr7pt0gr4ph7@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll/gem_resolver/version.rb
+- lib/jekyll_gem_resolver.rb
+homepage: https://github.com/cr7pt0gr4ph7/jekyll-gem-resolver
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key: 
+specification_version: 4
+summary: This plugin provides simple support for resolving paths relative to the directory
+  of specific gems.
+test_files: []