jekyll-link-decorator 1.2.2 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33285c1668a0edb31f7be980cd4f810232337bd0b627e0b8969349195ebede3e
-  data.tar.gz: e239a936a02e1d02955e888c043346c703b959c740467c0de768f8928f2882fc
+  metadata.gz: 58e0cbaffc8dddaa356b97b7f9523197377c98862ec3398cef26b7436b69d8d1
+  data.tar.gz: 5fab208572e92de8982ed60159799b02b729f196a54ba5f0465c86dee212275a
 SHA512:
-  metadata.gz: ccb6bf72c6dd271fe95379b9074b7f9d21c19f63dd3f064ae25aa91500789cd9cb14481674bbce08b99d1681139820615265b4f8480eb76a8b2dea26500685aa
-  data.tar.gz: 47d5e239f7d65ec8bafd8d2d14dea7b2363f5b726f0fd9312f23473e15d167cffa27c2f49bddb6238e13bb12f2e48bf41e275590b8bfceca7d6527a3932b2b2e
+  metadata.gz: fa74e76b3aed60bd4be998dd4b227268323aabae2f00ec67d718ec71c2b04f85bb356bdea7ac8622b6d4caabbc778cff534d2796dbd06bd55989611db4760ca7
+  data.tar.gz: 233d5cde8f2bfdf617b595a2783633e37d4b3794ba3ccfd8b8e838f8c4906348c4a8cd8979f78ea543861ab648633f004bc81c18aa7b44f6cec3170585d75c4d

data/lib/jekyll-link-decorator.rb

@@ -41,6 +41,23 @@
 #     (target="_blank", rel="noopener noreferrer") are still applied.
 #     Example: `external_link_icon_excluded_tags: ["img", "svg"]`
 #
+# === Heading Anchor Support ===
+#
+# The plugin can inject a Font Awesome link icon inside each heading (h1–h6),
+# giving users a direct, copyable URL to every section. This feature is configured
+# 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_data`: A dictionary containing optional configuration keys:
+#   - `icon`: Font Awesome icon classes (default: "fa-solid fa-link")
+#   - `icon_size`: Font Awesome size modifier appended after icon classes (optional)
+#   - `copy_success_message`: Feedback text after copying (consumed by heading-anchor.js,
+#     default: "Copied!")
+#   - `reset_delay`: Milliseconds before the icon resets (consumed by heading-anchor.js,
+#     default: 2000)
+#
 # If no configuration is provided, the plugin will use default fallback classes
 # and enable external link icons.
 #
@@ -55,6 +72,12 @@
 #   external_link_icon_excluded_tags:
 #     - img
 #     - svg
+#
+# with_heading_anchor: true
+# with_heading_anchor_data:
+#   icon: "fa-solid fa-link"
+#   copy_success_message: "Copied!"
+#   reset_delay: 2000
 # ```
 
 require 'nokogiri'
@@ -79,6 +102,8 @@ module Jekyll
       DEFAULT_ALERT_LINK_CLASSES = 'alert-link'
       DEFAULT_EXTERNAL_LINK_ICON = true
       DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS = [].freeze
+      DEFAULT_HEADING_ANCHOR      = false
+      DEFAULT_HEADING_ANCHOR_ICON = 'fa-solid fa-link'
 
       def self.name
         'LinkDecorator'
@@ -196,6 +221,7 @@ module Jekyll
 
         apply_link_styles(doc, config)
         add_external_link_features(doc, config)
+        add_heading_anchors(doc)
 
         doc.to_html
       rescue StandardError => e
@@ -262,6 +288,65 @@ module Jekyll
         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.
+      def add_heading_anchors(doc)
+        enabled = @config.key?('with_heading_anchor') ? @config['with_heading_anchor'] : DEFAULT_HEADING_ANCHOR
+        return unless enabled
+
+        ha_data    = @config['with_heading_anchor_data'] || {}
+        icon_class = ha_data.fetch('icon', DEFAULT_HEADING_ANCHOR_ICON)
+        icon_size  = ha_data['icon_size']
+        full_icon  = [icon_class, icon_size].compact.join(' ')
+        id_counts  = {}
+
+        doc.css('h1, h2, h3, h4, h5, h6').each do |heading|
+          next if heading.css('.heading-anchor').any?
+
+          id = resolve_heading_id(heading, id_counts)
+
+          anchor = Nokogiri::XML::Node.new('a', doc)
+          anchor['class']            = 'heading-anchor mx-1'
+          anchor['href']             = "##{id}"
+          anchor['data-copy-anchor'] = "##{id}"
+          anchor['aria-label']       = "Link to #{heading.text.strip}"
+
+          icon = Nokogiri::XML::Node.new('i', doc)
+          icon['class']       = full_icon
+          icon['aria-hidden'] = 'true'
+          anchor.add_child(icon)
+
+          heading.add_child(anchor)
+        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.
+      def resolve_heading_id(heading, id_counts)
+        existing = heading['id'].to_s.strip
+        return existing unless existing.empty?
+
+        base = slugify(heading.text)
+        n = id_counts[base].to_i
+        id_counts[base] = n + 1
+        final_id = n.zero? ? base : "#{base}-#{n}"
+        heading['id'] = final_id
+        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
+      def slugify(text)
+        text.strip
+            .downcase
+            .tr(' ', '-')
+            .delete('"\'?&#/')
+            .gsub(/-{2,}/, '-')
+            .gsub(/\A-|-\z/, '')
+      end
+
+      private :add_heading_anchors, :resolve_heading_id, :slugify
+
       # 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', DEFAULT_EXTERNAL_LINK_ICON)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-link-decorator
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.1
 platform: ruby
 authors:
 - ReleaseBot