jekyll-link-decorator 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33285c1668a0edb31f7be980cd4f810232337bd0b627e0b8969349195ebede3e
-  data.tar.gz: e239a936a02e1d02955e888c043346c703b959c740467c0de768f8928f2882fc
+  metadata.gz: 85f578a55d98076ae39a47427c191f790d9f7a804b095849d39897db778a86e7
+  data.tar.gz: 023bfd45a25c076a0b7fe8bc632195fc8e85d60d983e63cfb2c50abbd2c9c807
 SHA512:
-  metadata.gz: ccb6bf72c6dd271fe95379b9074b7f9d21c19f63dd3f064ae25aa91500789cd9cb14481674bbce08b99d1681139820615265b4f8480eb76a8b2dea26500685aa
-  data.tar.gz: 47d5e239f7d65ec8bafd8d2d14dea7b2363f5b726f0fd9312f23473e15d167cffa27c2f49bddb6238e13bb12f2e48bf41e275590b8bfceca7d6527a3932b2b2e
+  metadata.gz: c32eecd6e74d8ab46a664268c0371f63401ff9c94f40b10984f04fbd0b211e44d6e2f375f3f3cabaceeceda17b4ac4f009666ae472f62e3163a7664caeb6b4b1
+  data.tar.gz: b9b1c79b09cb02402fd89740829de88077b59a649936c0e11c4b2034ed0b067e7ae8da6f8bc5e9469af813ac37b2882364e463477e77d46c366869652b15ef4a

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 (default: "fa-xs")
+#   - `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,13 @@
 #   external_link_icon_excluded_tags:
 #     - img
 #     - svg
+#
+# with_heading_anchor: true
+# with_heading_anchor_data:
+#   icon: "fa-solid fa-link"
+#   icon_size: "fa-xs"
+#   copy_success_message: "Copied!"
+#   reset_delay: 2000
 # ```
 
 require 'nokogiri'
@@ -79,6 +103,9 @@ 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'
+      DEFAULT_HEADING_ANCHOR_SIZE = 'fa-xs'
 
       def self.name
         'LinkDecorator'
@@ -196,6 +223,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 +290,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.fetch('icon_size', DEFAULT_HEADING_ANCHOR_SIZE)
+        full_icon  = "#{icon_class} #{icon_size}"
+        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.0
 platform: ruby
 authors:
 - ReleaseBot