jekyll-link-decorator 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d91801b17b914f5fd1b053dabb0ca88e6d814c80dd0a58b929272ddaf636224
-  data.tar.gz: 22127cd8018119d37a82855bed5f73476783f46610b763c4eb31a5095689cdac
+  metadata.gz: ff4ff4aab91fea08f0f9d818a35287da8ad337181e028a2a2da62245866b3420
+  data.tar.gz: 81737c19fc41c5134c6741b0b6ebfb28746ca376f591c46a95a16631d56cfebf
 SHA512:
-  metadata.gz: 22225853f9368b78e14d32a8c44d945acc6c526a225992603d51317892c2c5ae9f958bf6f4882352441087a00d3f442071142f38f7953f2189bb4c1fe9a0daa1
-  data.tar.gz: f83df55c641942409368e632ef79763a669d06d558fe02b2911a4198361d6c81f936360213ce9858c48d32ebd64f465abdca96d42e7bcadc6c6a0613c0cbf002
+  metadata.gz: e912b0fbdc82c9640912f96b5a4f436d378e79fd4f9099eaba218759d7dc6ca688285b6785aa34163d89c749e153b9e5de37623277e66c16f892abe23fe3be02
+  data.tar.gz: 0ba21a73e60ad550d74415a22f06b2ada6bf83d8bef37521e778fcb546ca39bdb0695bdeefe1fb53c6fe65003608c2725f8446f3943f69664e105c4f0d704880

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.6.0'
+    VERSION = '1.7.0'
   end
 end

data/lib/jekyll-link-decorator.rb

@@ -1,82 +1,25 @@
 # frozen_string_literal: true
 
-# 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.
+# This plugin decorates <a> tags in Markdown content with Bootstrap CSS
+# classes, security attributes, and Font Awesome icons. Links inside a
+# Bootstrap alert box get alert-specific classes; other links get the
+# default classes; links carrying a `.btn` class are left untouched.
 #
-# === External Link Icon Support ===
+# For links to a different domain than the site's own (site.url), it adds
+# target="_blank", the rel="noopener noreferrer" security attributes, and an
+# external-link icon at the end of the link text.
 #
-# For links pointing to external domains (different from site.url), the plugin
-# adds a Font Awesome external-link icon (fa-solid fa-external-link) at the
-# end of the link text.
+# It can also inject a permalink icon into each heading (h1-h6) so every
+# section gets a shareable URL.
 #
-# === External Link Detection & Target Management ===
+# Turn these on and customize them from `_config.yml` with the
+# `with_link_decorator`, `with_link_decorator_data`, `with_heading_anchor`,
+# and `with_heading_anchor_data` keys. See docs/configuration.md for the
+# full key reference, defaults, and worked `_config.yml` examples.
 #
-# 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://) get target="_blank"
-# - Links with target="_blank" receive rel="noopener noreferrer" protection against
-#   security vulnerabilities (window.opener access, referrer leakage)
-#
-# === Configuration ===
-#
-# 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`: 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") 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) 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) — 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:
-#     "heading-anchor-hash pe-1", which renders a plain "#" via the
-#     jekyll-theme-centos-base theme's CSS). Accepts any class list, including
-#     Font Awesome icon classes (e.g. "fa-solid fa-hashtag") for sites that
-#     want an icon-font glyph instead.
-#   - `icon_size`: Optional size modifier class appended after the icon classes.
-#
-# Without configuration, the plugin uses its default classes and enables
-# external-link icons.
-#
-# 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 focus-ring"
-#   alert_link_classes: "alert-link focus-ring"
-#   external_link_icon: true
-#   external_link_icon_excluded_tags:
-#     - img
-#     - svg
-#
-# with_heading_anchor: true
-# with_heading_anchor_data:
-#   icon: "heading-anchor-hash pe-1"
-# ```
+# A link that already carries its own Bootstrap link-utility class (see
+# LINK_CLASS_FAMILIES below) keeps that class instead of getting the
+# plugin's default for the same family.
 
 require 'nokogiri'
 require_relative 'jekyll-link-decorator/version'
@@ -141,32 +84,24 @@ module Jekyll
       DEFAULT_EXTERNAL_LINK_ICON = true
       DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS = [].freeze
       DEFAULT_HEADING_ANCHOR      = false
-      DEFAULT_HEADING_ANCHOR_ICON = 'heading-anchor-hash pe-1'
+      DEFAULT_HEADING_ANCHOR_ICON = 'heading-anchor-hash'
 
       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"
+      # Returns a URL's domain, stripped of scheme and path.
+      # "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
+      # True when this link needs the external-link icon: an absolute,
+      # cross-domain link that doesn't already have one.
       def is_external_different_domain_link?(link, site_domain)
         return false unless absolute_different_domain?(link, site_domain)
         return false if EXISTING_ICON_SELECTORS.any? { |sel| link.css(sel).any? }
@@ -174,8 +109,9 @@ module Jekyll
         true
       end
 
-      # Returns true when href is an absolute http(s) URL pointing to a domain
-      # different from site_domain. Shared guard used by both domain-check methods.
+      # True when href is an absolute http(s) URL on a domain other than
+      # site_domain. Shared by is_external_different_domain_link? and
+      # cross_domain_external_link? below.
       def absolute_different_domain?(link, site_domain)
         href = link['href'].to_s
         return false unless %r{^https?://}.match?(href)
@@ -187,51 +123,34 @@ module Jekyll
       end
       private :absolute_different_domain?
 
-      # 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
+      # True when this link needs target="_blank": absolute and cross-domain.
+      # Relative URLs (/, ../) are always treated as internal.
       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)
 
         absolute_different_domain?(link, site_domain)
       end
 
-      # Add target="_blank" to external cross-domain links
-      # Only adds if target is not already set
+      # Sets target="_blank" on a cross-domain link, unless it already has a target.
       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 rel="noopener noreferrer" to target="_blank" links, preserving
-      # any existing rel attribute values
+      # Adds rel="noopener noreferrer" to a target="_blank" link, keeping any
+      # rel values the author already set.
       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
 
@@ -269,8 +188,8 @@ module Jekyll
         html
       end
 
-      # Check if the plugin is enabled in configuration
-      # Defaults to true if not explicitly configured
+      # Logs a notice when disabled; returns the given enabled flag unchanged.
+      # The caller (decorate_html) decides what "enabled" defaults to.
       def plugin_enabled?(enabled)
         unless enabled
           Jekyll.logger.info 'LinkDecorator:',
@@ -279,17 +198,16 @@ module Jekyll
         enabled
       end
 
-      # Apply CSS classes to links based on their context (alert or default)
+      # Applies alert_classes to links inside an .alert box, default_classes
+      # to every other link.
       def apply_link_styles(doc, config)
         default_classes = config.fetch('default_link_classes', DEFAULT_LINK_CLASSES)
         alert_classes   = config.fetch('alert_link_classes',   DEFAULT_ALERT_LINK_CLASSES)
 
-        # Apply alert classes to links inside p.alert or blockquote.alert
         doc.css('p.alert a:not(.btn), blockquote.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|
           next if link.ancestors('p.alert, blockquote.alert').any?
 
@@ -310,12 +228,12 @@ module Jekyll
         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
+      # Adds target="_blank", the external-link icon, and rel security
+      # attributes to every link on the page, in that order.
       def add_external_link_features(doc, config)
         site_domain = extract_site_domain
         return if site_domain.empty?
@@ -327,14 +245,14 @@ module Jekyll
         end
       end
 
-      # Extract site domain from Jekyll configuration
       def extract_site_domain
         site_url = @config['url'] || @config['baseurl'] || ''
         extract_domain(site_url)
       end
 
-      # Inject a Font Awesome anchor link inside each heading (h1–h6).
-      # Reads with_heading_anchor and with_heading_anchor_data from @config directly.
+      # Injects a permalink anchor into each heading (h1-h6). The anchor's
+      # glyph defaults to a plain "#"; with_heading_anchor_data can swap it
+      # for a Font Awesome icon or any other class list.
       def add_heading_anchors(doc)
         enabled = @config.key?('with_heading_anchor') ? @config['with_heading_anchor'] : DEFAULT_HEADING_ANCHOR
         return unless enabled
@@ -351,7 +269,7 @@ module Jekyll
           id = resolve_heading_id(heading, id_counts)
 
           anchor = Nokogiri::XML::Node.new('a', doc)
-          anchor['class']            = 'heading-anchor mx-1'
+          anchor['class']            = 'heading-anchor p-1 mx-1 focus-ring'
           anchor['href']             = "##{id}"
           anchor['data-copy-anchor'] = "##{id}"
           anchor['aria-label']       = "Link to #{heading.text.strip}"
@@ -365,8 +283,9 @@ module Jekyll
         end
       end
 
-      # Return the heading's existing id, or generate and assign one from its text.
-      # id_counts tracks generated slugs to produce unique suffixes for duplicates.
+      # Returns the heading's existing id, or generates one from its text and
+      # assigns it. id_counts tracks slugs already used, so repeated headings
+      # get unique "-1", "-2", ... suffixes.
       def resolve_heading_id(heading, id_counts)
         existing = heading['id'].to_s.strip
         return existing unless existing.empty?
@@ -379,8 +298,10 @@ module Jekyll
         final_id
       end
 
-      # Convert heading text to a URL-safe slug matching the link.html.liquid algorithm:
-      # strip → downcase → spaces to hyphens → remove ", ', ?, &, #, / → collapse hyphens
+      # Converts heading text to a URL-safe slug, loosely mirroring the slug
+      # rules in jekyll-theme-centos-base's link.html.liquid (same characters
+      # stripped and replaced), plus collapsing repeated/edge hyphens so
+      # headings with unusual punctuation still get a clean id.
       def slugify(text)
         text.strip
             .downcase
@@ -392,7 +313,9 @@ module Jekyll
 
       private :add_heading_anchors, :resolve_heading_id, :slugify
 
-      # Add external-link icon to cross-domain links
+      # Appends the external-link icon to a cross-domain link, unless the
+      # icon is disabled, the link already has an icon-bearing tag excluded
+      # via external_link_icon_excluded_tags, or one is already present.
       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.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Alain Reguera Delgado