jekyll-link-attributes 0.0.3 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21581fa0a3642f3dacb9e62b698bdbaf69eff296c6742fd2f2c10b71b610a650
-  data.tar.gz: f29f049cc12f44ac29fdefbf2de9a0e601c45eb11f96f23d06bb48c1e71a31e9
+  metadata.gz: d791371caa0d64c3b9f0be8b0166c0dee989a8ba462e58c07ccef19625652fae
+  data.tar.gz: 56525b68f3c8ffb2568792b64b1e0e7c271d82cb742d77eaba772db3f7cd5112
 SHA512:
-  metadata.gz: d20810d19c468067b25dccc8ecd427e9da8ef3ea64aaf31975bdf94693140be28d76ce4b657a79111e09850aa3a0e98e3bffb1cc74d901225190834a035b1186
-  data.tar.gz: 6988b43697baf0cefed3379e3a58ab560d542b41c766cabed705420aa23babb079b18d51ecdccba1623ef4f1a2b709cbf3db842d7ea1bb6f09da7e5267c3d87a
+  metadata.gz: 0de1970490f37a7cce17f43303b234957aaf23f9f6fa10514d2e04da2a2c654d4d6b2aa4c9f0099ae1a555701da14f5724c72606c9f2ac610dd3b50a9dbf3bb7
+  data.tar.gz: 10bdda6fbaa8ef263b9a3648391fef15031ef507e36307632fceb011037f38c201b131dc718ce8dd6abd8154afec57cdfbd8febb4bd6290c37ea617d6227f050

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jekyll-link-attributes (0.0.3)
+    jekyll-link-attributes (2.0.1)
 
 GEM
   remote: https://rubygems.org/
@@ -50,6 +50,8 @@ GEM
     mercenary (0.4.0)
     nokogiri (1.13.8-x86_64-darwin)
       racc (~> 1.4)
+    nokogiri (1.13.8-x86_64-linux)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.0)
@@ -82,6 +84,7 @@ GEM
 
 PLATFORMS
   x86_64-darwin-20
+  x86_64-linux
 
 DEPENDENCIES
   bundler (>= 2.0.0)

data/README.md

@@ -1,7 +1,7 @@
 # Jekyll Link Attributes
 
-This plugin adds `rel` and `target` attributes to all external links in your Jekyll site.
-The default configuration opens external links in a new tab and conserves domain authority for your site.
+A Jekyll plugin for managing external link behavior: `rel` attributes, `target` attributes, and UTM tracking parameters.
+Each concern is independently configurable with its own value and exclude list.
 
 ## Setup
 
@@ -18,7 +18,35 @@ The default configuration opens external links in a new tab and conserves domain
 
 ## Configuration
 
-You can override the default configuration by adding the following section to your Jekyll site's `config.yml`:
+### Recommended (v2+)
+
+Each attribute type is its own section with a `value` and optional `exclude` list:
+
+```yaml
+external_links:
+  enabled: true
+
+  rel:
+    value: external nofollow noopener
+    exclude:
+      - https://myotherapp.com(/?|/.*)?
+
+  target:
+    value: _blank
+    exclude:
+      - https://myotherapp.com(/?|/.*)?
+
+  utm:
+    enabled: true
+    source: mysite.com
+    medium: website
+    exclude:
+      - https://github.com(/?|/.*)?
+```
+
+### Legacy (v1, still supported)
+
+The original flat configuration style continues to work. The top-level `rel`, `target`, and `exclude` keys are used as fallbacks when the new-style section config is not present:
 
 ```yaml
 external_links:
@@ -26,18 +54,42 @@ external_links:
   rel: external nofollow noopener
   target: _blank
   exclude:
-    - https://example.com
-    - https://another.example.com/test.html
-    - https://regex.example.com/.+
+    - https://example.com(/?|/.*)?
 ```
 
-### Default Values
-| Key | Default Value | Description |
-| ---------------------------- | ---------------------------- | -------------------------------------------------- |
-| `external_links.enabled` | `true`                       | Enable attribute modifications for external links. |
-| `external_links.rel`     | `external nofollow noopener` | The `rel` attribute to add to external links.      |
-| `external_links.target`  | `_blank`                     | The `target` attribute to add to external links.   |
-| `external_links.exclude` | `[]`                         | A list of URLs to exclude from processing.         |
+### Resolution order
+
+| Setting | Resolved from | Fallback |
+| ------- | ------------- | -------- |
+| rel value | `external_links.rel.value` | `external_links.rel` (string) or `external nofollow noopener` |
+| rel excludes | `external_links.rel.exclude` | `external_links.exclude` |
+| target value | `external_links.target.value` | `external_links.target` (string) or `_blank` |
+| target excludes | `external_links.target.exclude` | `external_links.exclude` |
+| utm excludes | `external_links.utm.exclude` | *(none, defaults to empty)* |
+
+### UTM tracking parameters
+
+When `external_links.utm.enabled` is `true`, UTM query parameters are automatically appended to external links:
+
+| Param | Value | Source |
+| -------------- | -------------------- | ---------------------------------------------------------------- |
+| `utm_source`   | Configured `source`  | Falls back to the site `url` with the protocol stripped.         |
+| `utm_medium`   | Configured `medium`  | Falls back to `website`.                                         |
+| `utm_campaign` | Auto-derived         | `blog` for post/blog layouts, otherwise the first URL path segment (e.g., `about`), or `homepage` for the root page. |
+| `utm_content`  | Auto-derived         | The page slug (e.g., `my-great-post` or `index`).               |
+
+Existing query parameters on links are preserved. UTM parameters already present on a link will not be overwritten.
+
+### Skipping individual links
+
+The `rel` or `target` attributes will not be modified for links that already have those existing attributes.
+This allows you to skip individual links without having to modify the plugin's configuration.
+
+ ```html
+ <a href="https://example.com" rel="nofollow">Example</a> <!-- rel will not be modified, but target will be added. -->
+ <a href="https://example.com" target="_self">Example</a> <!-- target will not be modified, but rel will be added. -->
+ <a href="https://example.com" rel="nofollow" target="_self">Example</a> <!-- Neither rel nor target will be modified. -->
+ ```
 
 ## Contributing
 

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

@@ -2,6 +2,6 @@
 
 module Jekyll
   class LinkAttributes
-    VERSION = '0.0.3'
+    VERSION = '2.0.1'
   end
 end

data/lib/jekyll-link-attributes.rb

@@ -3,6 +3,7 @@
 require 'jekyll-link-attributes/hooks'
 require 'jekyll-link-attributes/version'
 require 'nokogiri'
+require 'uri'
 
 module Jekyll
 
@@ -15,13 +16,37 @@ module Jekyll
       config = article.site.config
       return unless external_links_enabled?(config: config)
 
+      ext_config = config['external_links'] || {}
+      utm_params = build_utm_params(ext_config: ext_config, site_config: config, article: article)
+
       output = Nokogiri::HTML(article.output)
       output.css('a').each do |a|
         next unless external_link?(config: config, url: a['href'])
-        next if excludes_external_link?(config: config, url: a['href'])
 
-        a['rel'] = external_link_rel(config: config)
-        a['target'] = external_link_target(config: config)
+        original_href = a['href']
+
+        # UTM: applied to all external links with its own exclude list
+        if utm_params && !excluded?(ext_config: ext_config, section: 'utm', url: original_href)
+          a['href'] = append_utm_params(url: a['href'], utm_params: utm_params)
+        end
+
+        # rel: new-style section config falls back to legacy top-level keys
+        unless a['rel']
+          rel_value = resolve_value(ext_config: ext_config, section: 'rel', legacy_key: 'rel',
+                                    default: 'external nofollow noopener')
+          unless excluded?(ext_config: ext_config, section: 'rel', url: original_href)
+            a['rel'] = rel_value
+          end
+        end
+
+        # target: new-style section config falls back to legacy top-level keys
+        unless a['target']
+          target_value = resolve_value(ext_config: ext_config, section: 'target', legacy_key: 'target',
+                                       default: '_blank')
+          unless excluded?(ext_config: ext_config, section: 'target', url: original_href)
+            a['target'] = target_value
+          end
+        end
       end
 
       article.output = output.to_s
@@ -29,9 +54,32 @@ module Jekyll
 
     private
 
-    def self.excludes_external_link?(config:, url:)
-      excludes = (config.dig('external_links', 'exclude') || [])
-      excludes.any? { |exclude| Regexp.new("^#{exclude}$").match? url }
+    # Resolve value for a section, falling back to legacy top-level key.
+    # New style: external_links.rel.value / external_links.target.value
+    # Legacy:   external_links.rel / external_links.target (string value)
+    def self.resolve_value(ext_config:, section:, legacy_key:, default:)
+      section_config = ext_config[section]
+      if section_config.is_a?(Hash)
+        section_config['value'] || default
+      else
+        section_config || default
+      end
+    end
+
+    # Check if a URL is excluded for a given section.
+    # New style: external_links.<section>.exclude
+    # Legacy fallback (rel/target only): external_links.exclude
+    def self.excluded?(ext_config:, section:, url:)
+      section_config = ext_config[section]
+      excludes = if section_config.is_a?(Hash)
+                   section_config['exclude'] || []
+                 elsif section == 'utm'
+                   []
+                 else
+                   ext_config['exclude'] || []
+                 end
+
+      excludes.any? { |pattern| Regexp.new("^#{pattern}$").match?(url) }
     end
 
     def self.external_link?(config:, url:)
@@ -44,12 +92,43 @@ module Jekyll
       enabled.nil? || enabled
     end
 
-    def self.external_link_rel(config:)
-      config.dig('external_links', 'rel') || 'external nofollow noopener'
+    def self.utm_enabled?(ext_config:)
+      ext_config.dig('utm', 'enabled') == true
+    end
+
+    def self.build_utm_params(ext_config:, site_config:, article:)
+      return nil unless utm_enabled?(ext_config: ext_config)
+
+      utm_config = ext_config['utm'] || {}
+      source = utm_config['source'] || site_config['url']&.sub(%r{\Ahttps?://}, '') || 'website'
+      medium = utm_config['medium'] || 'website'
+
+      campaign = case article.data['layout']
+                 when 'post', 'blog' then 'blog'
+                 else
+                   path = article.url.to_s.gsub(%r{\A/|/\z}, '')
+                   path.empty? ? 'homepage' : path.split('/').first
+                 end
+
+      content = article.data['slug'] || File.basename(article.url.to_s.chomp('/'))
+      content = 'index' if content.empty?
+
+      {
+        'utm_source'   => source,
+        'utm_medium'   => medium,
+        'utm_campaign' => campaign,
+        'utm_content'  => content,
+      }
     end
 
-    def self.external_link_target(config:)
-      config.dig('external_links', 'target') || '_blank'
+    def self.append_utm_params(url:, utm_params:)
+      uri = URI.parse(url)
+      existing = URI.decode_www_form(uri.query || '').to_h
+      utm_params.each { |k, v| existing[k] = v unless existing.key?(k) }
+      uri.query = URI.encode_www_form(existing)
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-link-attributes
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 2.0.1
 platform: ruby
 authors:
 - twinsunllc
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-05 00:00:00.000000000 Z
+date: 2026-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler