jekyll-link-decorator 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0f9b808eb1a08ff1ec662bbe580907599e65a41f0841dcd1fc00afd753b4964
+  data.tar.gz: f013b30a4b34f9da6e30ff10f5d305513f2b2b7a8ef675ff3630a665ce069e58
+SHA512:
+  metadata.gz: 1c3f7778766e27f923060547092f58a3632e46caacb21aeaa0a6c027465ef3c6fd3cf17064379cbe00c10c608a4f2c91c195096816be71bcdd40551a4e21475d
+  data.tar.gz: 97643a1ee4b81a731e9b7f23341f30f38db54de807c94fe54322413e20877e4c675d36863dcd9f69471942706b504c401280977786148c5dd04d77313e40c131

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alain Reguera Delgado
+
+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,15 @@
+# jekyll-link-decorator
+
+A Jekyll plugin that automatically enhances Markdown links with Bootstrap CSS
+classes, security attributes, Font Awesome icons, and context-aware styling.
+Simplifies link management across Jekyll sites by handling styling, external
+link protection, and icon injection without manual intervention.
+
+## Documentation
+
+For complete documentation, configuration options, and examples, visit the
+[documentation site](https://centos.gitlab.io/artwork/centos-web/jekyll-link-decorator/).
+
+## License
+
+MIT License - see LICENSE file for details.

data/lib/jekyll-link-decorator.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+# This Jekyll plugin, `link_decorator`, automatically enhances `<a>` tags
+# within Markdown content by adding specific Bootstrap-related CSS classes and
+# external-link icons. This functionality is conditional, applying different
+# sets of classes based on whether a link is located inside a Bootstrap alert
+# box or is a regular link. It explicitly avoids modifying elements that are
+# designated as buttons by having the `.btn` class.
+#
+# === External Link Icon Support ===
+#
+# For links pointing to external domains (different from site.url), the plugin
+# automatically adds a Font Awesome external-link icon (fa-solid fa-external-link)
+# at the end of the link text, similar to the link component behavior.
+#
+# === External Link Detection & Target Management ===
+#
+# The plugin automatically detects external links and manages their behavior:
+# - Relative URLs (starting with /, ../) and same-domain absolute URLs open in the same window
+# - Absolute URLs pointing to different domains (http:// or https://) automatically get target="_blank"
+# - Links with target="_blank" automatically receive rel="noopener noreferrer" protection
+# against security vulnerabilities (window.opener access, referrer leakage)
+#
+# === Configuration ===
+#
+# You can customize the classes applied by this plugin by adding
+# `with_link_decorator` and `with_link_decorator_data` sections to your `_config.yml` file.
+#
+# * `with_link_decorator`: Boolean (default: true) that controls whether the plugin runs.
+#   Set to false to disable automatic link styling and icon insertion.
+#
+# * `with_link_decorator_data`: A dictionary containing optional configuration keys:
+#   - `default_link_classes`: Defines the classes to be applied to all links that are not
+#     inside an .alert. Example: `default_link_classes: "text-decoration-none"`
+#   - `alert_link_classes`: Defines the classes for links specifically located within an
+#     .alert box. Example: `alert_link_classes: "text-decoration-underline"`
+#   - `external_link_icon`: Boolean (default: true) that controls whether external-link
+#     icons are added to cross-domain external links. Set to false to disable.
+#
+# If no configuration is provided, the plugin will use default fallback classes
+# and enable external link icons.
+#
+# Here is an example `_config.yml` setup:
+#
+# ```yaml
+# with_link_decorator: true
+# with_link_decorator_data:
+#   default_link_classes: "link link-offset-3 link-offset-3-hover link-underline-primary link-underline-opacity-0 link-underline-opacity-100-hover"
+#   alert_link_classes: "alert-link"
+#   external_link_icon: true
+# ```
+
+require 'nokogiri'
+
+module Jekyll
+  module Converters
+    # This custom converter applies specific CSS classes to <a> tags
+    # based on their context (e.g., inside an alert box) and excludes
+    # buttons, all done via Nokogiri's powerful CSS selectors.
+    # It also adds external-link icons for cross-domain external links.
+    class LinkDecorator < Jekyll::Converters::Markdown
+      def self.name
+        'LinkDecorator'
+      end
+
+      # Extract domain from a URL by removing protocol and path components
+      # Example: "https://example.com/path?query=1#anchor" -> "example.com"
+      def extract_domain(url)
+        return '' if url.nil? || url.empty?
+
+        # Remove protocol (http:// or https://)
+        domain = url.sub(%r{^https?://}, '')
+
+        # Extract just the domain part (before /, ?, or #)
+        domain = domain.split(%r{[/?#]}).first
+
+        # Convert to lowercase for case-insensitive comparison
+        domain.downcase
+      end
+
+      # Check if a link is an external link pointing to a different domain
+      # Returns true if:
+      # - Link starts with http:// or https://
+      # - Link domain is different from site.url domain
+      # - Link doesn't already have an external-link icon child
+      def is_external_different_domain_link?(link, site_domain)
+        href = link['href'].to_s
+
+        # Check if it's an absolute URL with http/https
+        return false unless %r{^https?://}.match?(href)
+
+        # Extract domain from the link
+        link_domain = extract_domain(href)
+
+        # Check if domains are different
+        return false if link_domain == site_domain || link_domain.empty?
+
+        # Check if an icon has already been added (avoid duplicates)
+        # Check for both new icons (fa-external-link) and old icons
+        # (fa-external-link-alt, fa-up-right-from-square, etc.)
+        return false if link.css('i[class*="fa-external-link"]').any?
+        return false if link.css('i[class*="up-right-from-square"]').any?
+        return false if link.css('svg[data-icon="external-link"]').any?
+        return false if link.css('svg[data-icon="up-right-from-square"]').any?
+        return false if link.css('svg[data-icon="arrow-up-right-from-square"]').any?
+
+        true
+      end
+
+      # Determine if a link points to an external domain
+      # Returns true if:
+      # - Link is absolute (starts with http:// or https://)
+      # - Link domain is different from site.url domain
+      # Returns false if:
+      # - Link is relative (starts with /, ../)
+      # - Link domain matches site.url domain
+      def cross_domain_external_link?(link, site_domain)
+        href = link['href'].to_s
+
+        # Relative URLs (starting with / or ../) are internal links
+        return false if %r{^(/|\.\.)}.match?(href)
+
+        # Check if it's an absolute URL with http/https
+        return false unless %r{^https?://}.match?(href)
+
+        # Extract domain from the link
+        link_domain = extract_domain(href)
+
+        # Check if domains are different
+        return false if link_domain == site_domain || link_domain.empty?
+
+        true
+      end
+
+      # Add target="_blank" to external cross-domain links
+      # Only adds if target is not already set
+      def add_external_target_blank(link, site_domain)
+        # Skip if link already has a target attribute
+        return if link['target'].to_s.strip != ''
+
+        # Add target="_blank" if this is a cross-domain external link
+        return unless cross_domain_external_link?(link, site_domain)
+
+        link['target'] = '_blank'
+      end
+
+      # Add security attributes to links with target="_blank"
+      # Adds rel="noopener noreferrer" to prevent security vulnerabilities
+      # Preserves any existing rel attribute values
+      def add_external_target_protection(link)
+        target = link['target'].to_s
+
+        # Only add protection for target="_blank"
+        return unless target == '_blank'
+
+        # Get existing rel attribute (if any)
+        existing_rel = link['rel'].to_s.strip
+        rel_values = existing_rel.empty? ? [] : existing_rel.split(/\s+/)
+
+        # Add required security values if not already present
+        rel_values << 'noopener' unless rel_values.include?('noopener')
+        rel_values << 'noreferrer' unless rel_values.include?('noreferrer')
+
+        # Set the updated rel attribute
+        link['rel'] = rel_values.join(' ')
+      end
+
+      def matches(ext)
+        ext =~ /^\.md$/i
+      end
+
+      def output_ext(_ext)
+        '.html'
+      end
+
+      def convert(content)
+        html = super
+        enabled = @config.key?('with_link_decorator') ? @config['with_link_decorator'] : true
+        config = @config['with_link_decorator_data'] || {}
+
+        return html unless plugin_enabled?(enabled)
+
+        doc = Nokogiri::HTML::DocumentFragment.parse(html)
+
+        apply_link_styles(doc, config)
+        add_external_link_features(doc, config)
+
+        doc.to_html
+      rescue StandardError => e
+        Jekyll.logger.error 'LinkDecorator Error:',
+                            "An error occurred during link decoration: #{e.message}"
+        Jekyll.logger.error 'Backtrace:', e.backtrace.join("\n")
+
+        html
+      end
+
+      # Check if the plugin is enabled in configuration
+      # Defaults to true if not explicitly configured
+      def plugin_enabled?(enabled)
+        unless enabled
+          Jekyll.logger.info 'LinkDecorator:',
+                             'Disabled via configuration. Skipping custom link modification.'
+        end
+        enabled
+      end
+
+      # Apply CSS classes to links based on their context (alert or default)
+      def apply_link_styles(doc, config)
+        default_classes = config.fetch('default_link_classes',
+                                       'link link-offset-3 link-offset-3-hover link-underline-primary link-underline-opacity-0 link-underline-opacity-100-hover')
+        alert_classes = config.fetch('alert_link_classes', 'alert-link')
+
+        # Apply alert classes to links inside p.alert
+        doc.css('p.alert a:not(.btn)').each do |link|
+          add_classes(link, alert_classes)
+        end
+
+        # Apply default classes to all other non-alert links
+        doc.css('a:not(.btn)').each do |link|
+          add_classes(link, default_classes) unless link.ancestors('p.alert').any?
+        end
+      end
+
+      # Add CSS classes to a link element
+      def add_classes(link, classes_string)
+        classes_string.split.each { |cls| link.add_class(cls) }
+      end
+
+      # Add external link features: target="_blank", icons, and security attributes
+      def add_external_link_features(doc, config)
+        site_domain = extract_site_domain
+        return if site_domain.empty?
+
+        doc.css('a:not(.btn)').each do |link|
+          add_external_target_blank(link, site_domain)
+          add_external_icon(link, site_domain, config, doc)
+          add_external_target_protection(link)
+        end
+      end
+
+      # Extract site domain from Jekyll configuration
+      def extract_site_domain
+        site_url = @config['url'] || @config['baseurl'] || ''
+        extract_domain(site_url)
+      end
+
+      # Add external-link icon to cross-domain external links
+      def add_external_icon(link, site_domain, config, doc)
+        external_link_icon = config.fetch('external_link_icon', true)
+
+        return unless external_link_icon
+        return unless is_external_different_domain_link?(link, site_domain)
+
+        icon = Nokogiri::XML::Node.new('i', doc)
+        icon['class'] = 'fa-solid fa-external-link ms-1'
+        link.add_child(icon)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,219 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-link-decorator
+version: !ruby/object:Gem::Version
+  version: 1.0.3
+platform: ruby
+authors:
+- ReleaseBot
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.85'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.85'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Jekyll plugin that automatically enhances Markdown links with Bootstrap
+  CSS classes, security attributes, Font Awesome icons, and context-aware styling.
+  Simplifies link management across Jekyll sites by handling styling, external link
+  protection, and icon injection without manual intervention.
+email:
+- group_58921183_bot_c5520aeba366578e2e444dd181ff3e23@noreply.gitlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-link-decorator.rb
+homepage: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator
+  source_code_uri: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator
+  changelog_uri: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator/-/releases
+  documentation_uri: https://centos.gitlab.io/artwork/centos-web/jekyll-link-decorator
+  bug_tracker_uri: https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator/-/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Jekyll plugin that decorates links with Bootstrap classes and external-link
+  icons.
+test_files: []