jekyll-link-decorator 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86487049f93f8629a147eb1951acfd42988230e0be214177364a9c1b1125a369
-  data.tar.gz: ec957d708689c5005016bee2ac210ecbd12aefa85f0454873ef28e964492ee3a
+  metadata.gz: 4d91801b17b914f5fd1b053dabb0ca88e6d814c80dd0a58b929272ddaf636224
+  data.tar.gz: 22127cd8018119d37a82855bed5f73476783f46610b763c4eb31a5095689cdac
 SHA512:
-  metadata.gz: 6c419799160ddd533b6119a3182959b3961b101c2a0d3fd7aba9ab0be4c271451eda7cf637eab717f1dfbd4ca59ff0fbe20a1e13fac7c66a67ad88f57f1fab08
-  data.tar.gz: 36b2e3c4a30442c7bf603a3607fa6591b6e347b5471139a71a22626ebce4e7004060783d473848dba9c48e196778691457b06c6ae65f6c682b2e59c1d0409b39
+  metadata.gz: 22225853f9368b78e14d32a8c44d945acc6c526a225992603d51317892c2c5ae9f958bf6f4882352441087a00d3f442071142f38f7953f2189bb4c1fe9a0daa1
+  data.tar.gz: f83df55c641942409368e632ef79763a669d06d558fe02b2911a4198361d6c81f936360213ce9858c48d32ebd64f465abdca96d42e7bcadc6c6a0613c0cbf002

data/lib/jekyll-link-decorator/version.rb

@@ -6,6 +6,6 @@ module Jekyll
     # Regenerated alongside the gemspec on every `make gemspec` run (locally
     # or in CI), so it always matches spec.version in the built gem. Any
     # hand edit is overwritten on the next run.
-    VERSION = '1.5.1'
+    VERSION = '1.6.0'
   end
 end

data/lib/jekyll-link-decorator.rb

@@ -1,54 +1,54 @@
 # 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.
+# This Jekyll plugin, `link_decorator`, enhances `<a>` tags in Markdown content
+# with Bootstrap CSS classes and external-link icons. It applies different
+# classes depending on whether a link sits inside a Bootstrap alert box or
+# stands alone, and skips elements with 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.
+# adds a Font Awesome external-link icon (fa-solid fa-external-link) at the
+# end of the link text.
 #
 # === External Link Detection & Target Management ===
 #
-# The plugin automatically detects external links and manages their behavior:
+# The plugin 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)
+# - Absolute URLs pointing to different domains (http:// or https://) get target="_blank"
+# - Links with target="_blank" 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.
+# Customize the plugin's classes by adding `with_link_decorator` and
+# `with_link_decorator_data` to your `_config.yml`.
 #
 # * `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.
+#   - `default_link_classes`: Classes applied to links outside an .alert.
+#     Example: `default_link_classes: "text-decoration-none"`
+#     If a link already carries its own `link-{color}`, `link-underline-*`,
+#     `link-offset-*`, `link-underline-opacity-*`, `link-opacity-*`, or `focus-ring(-{color})?` class,
+#     the plugin skips the matching default token automatically — see LINK_CLASS_FAMILIES.
+#   - `alert_link_classes`: Classes applied to links inside an .alert box.
+#     Example: `alert_link_classes: "text-decoration-underline"`
+#   - `external_link_icon`: Boolean (default: true) — show the icon on cross-domain
+#     external links. Set to false to disable.
 #   - `external_link_icon_excluded_tags`: List of HTML child tag names (default: []) whose presence
 #     inside an anchor suppresses the external-link icon. Security attributes
-#     (target="_blank", rel="noopener noreferrer") are still applied.
+#     (target="_blank", rel="noopener noreferrer") still apply.
 #     Example: `external_link_icon_excluded_tags: ["img", "svg"]`
 #
 # === Heading Anchor Support ===
 #
-# The plugin can inject a permalink icon inside each heading (h1–h6), giving
-# users a direct, linkable URL to every section. This feature is configured
-# via two top-level keys (separate from `with_link_decorator_data`):
+# The plugin can inject a permalink icon inside each heading (h1–h6) so every
+# section gets a shareable URL. Configure it via two top-level keys (separate
+# from `with_link_decorator_data`):
 #
-# * `with_heading_anchor`: Boolean (default: false) that controls whether heading anchors
-#   are injected. Set to true to enable.
+# * `with_heading_anchor`: Boolean (default: false) — set to true to inject heading anchors.
 #
 # * `with_heading_anchor_data`: A dictionary containing optional configuration keys:
 #   - `icon`: CSS classes applied to the anchor's glyph element (default:
@@ -58,16 +58,16 @@
 #     want an icon-font glyph instead.
 #   - `icon_size`: Optional size modifier class appended after the icon classes.
 #
-# If no configuration is provided, the plugin will use default fallback classes
-# and enable external link icons.
+# Without configuration, the plugin uses its default classes and enables
+# external-link icons.
 #
-# Here is an example `_config.yml` setup:
+# Example `_config.yml`:
 #
 # ```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"
+#   default_link_classes: "link link-offset-3 link-offset-3-hover link-underline-primary link-underline-opacity-0 link-underline-opacity-100-hover focus-ring"
+#   alert_link_classes: "alert-link focus-ring"
 #   external_link_icon: true
 #   external_link_icon_excluded_tags:
 #     - img
@@ -92,14 +92,52 @@ EXISTING_ICON_SELECTORS = [
 
 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.
+    # Applies CSS classes to <a> tags based on context (e.g., inside an alert
+    # box) via Nokogiri CSS selectors, excluding buttons. Also adds
+    # external-link icons for cross-domain links.
     class LinkDecorator < Jekyll::Converters::Markdown
       DEFAULT_LINK_CLASSES = 'link link-offset-3 link-offset-3-hover link-underline-primary ' \
-                             'link-underline-opacity-0 link-underline-opacity-100-hover'
-      DEFAULT_ALERT_LINK_CLASSES = 'alert-link'
+                             'link-underline-opacity-0 link-underline-opacity-100-hover focus-ring'
+      DEFAULT_ALERT_LINK_CLASSES = 'alert-link focus-ring'
+
+      # Bootstrap 5 link-utility "families" whose defaults must not silently
+      # override an author's own explicit class from the same family — see
+      # classes_to_add_for.
+      #
+      # Each entry carries a single `pattern:` regex, anchored \A...\z and
+      # matched per class token (not against the whole class string), so a
+      # compound name like "social-link-danger" or "sidebar-link-offset-2" is
+      # never mistaken for an override.
+      #
+      # Enumerated families (offset, both opacity families) lock to Bootstrap's
+      # fixed value set, so an out-of-range value like "link-opacity-42" isn't
+      # recognized as an override either. Color and focus-ring families
+      # (link-{color}, link-underline-{color}, focus-ring(-{color})?) stay
+      # generic (\S+) since Bootstrap themes can define arbitrary custom color names.
+      LINK_CLASS_FAMILIES = [
+        { # link-{color}, e.g. link-primary, link-body-emphasis (bare colored-link class;
+          # excludes link-underline-*, link-offset-*, and link-opacity-* families)
+          pattern: /\Alink-(?!underline\b|offset-|opacity-)\S+\z/
+        },
+        { # link-underline-{color}, e.g. link-underline-success (excludes -opacity-*)
+          pattern: /\Alink-underline-(?!opacity)\S+\z/
+        },
+        { # link-offset-{1,2,3}, each with an optional -hover variant
+          pattern: /\Alink-offset-[123](-hover)?\z/
+        },
+        { # link-underline-opacity-{0,10,25,50,75,100}, each with an optional -hover variant
+          pattern: /\Alink-underline-opacity-(?:0|10|25|50|75|100)(-hover)?\z/
+        },
+        { # link-opacity-{10,25,50,75,100}, each with an optional -hover variant
+          # (controls link-text opacity, distinct from link-underline-opacity-*)
+          pattern: /\Alink-opacity-(?:10|25|50|75|100)(-hover)?\z/
+        },
+        { # focus-ring and focus-ring-{color}, e.g. focus-ring-primary, focus-ring-success
+          # Bootstrap 5.3 focus-ring has no hover, offset, or opacity variants — only bare
+          # and color forms; color stays generic (\S+) for custom theme colors
+          pattern: /\Afocus-ring(-\S+)?\z/
+        }
+      ].freeze
       DEFAULT_EXTERNAL_LINK_ICON = true
       DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS = [].freeze
       DEFAULT_HEADING_ANCHOR      = false
@@ -177,9 +215,8 @@ module Jekyll
         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
+      # Add rel="noopener noreferrer" to target="_blank" links, preserving
+      # any existing rel attribute values
       def add_external_target_protection(link)
         target = link['target'].to_s
 
@@ -256,12 +293,20 @@ module Jekyll
         doc.css('a:not(.btn)').each do |link|
           next if link.ancestors('p.alert, blockquote.alert').any?
 
-          classes_to_add = if link['class'].to_s.match?(/\blink-underline-(?!opacity)\S+/)
-                             default_classes.split.grep_v(/\Alink-underline-(?!opacity)/).join(' ')
-                           else
-                             default_classes
-                           end
-          add_classes(link, classes_to_add)
+          add_classes(link, classes_to_add_for(link, default_classes))
+        end
+      end
+
+      # Drops any default class belonging to a family the link already customizes,
+      # so the author's explicit class wins instead of losing silently to a
+      # same-specificity Bootstrap !important rule declared later in the sheet.
+      # See LINK_CLASS_FAMILIES for how each family's pattern is matched.
+      def classes_to_add_for(link, default_classes)
+        link_classes = link['class'].to_s.split
+        LINK_CLASS_FAMILIES.reduce(default_classes) do |classes, family|
+          next classes unless link_classes.any? { |token| token.match?(family[:pattern]) }
+
+          classes.split.grep_v(family[:pattern]).join(' ')
         end
       end
 
@@ -347,7 +392,7 @@ module Jekyll
 
       private :add_heading_anchors, :resolve_heading_id, :slugify
 
-      # Add external-link icon to cross-domain external links
+      # Add external-link icon to cross-domain links
       def add_external_icon(link, site_domain, config, doc)
         external_link_icon = config.fetch('external_link_icon', DEFAULT_EXTERNAL_LINK_ICON)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-link-decorator
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Alain Reguera Delgado