jekyll-external-link-accessibility 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 849fc21433dad344657c4a178cdde53743b725dc9c469c8de7cab31b17f9109c
+  data.tar.gz: afab990efcde48e427a61e210ac525181dfe97cee3c994a1e4e06de4585f7747
+SHA512:
+  metadata.gz: d1d54d9b739f5e0e9bc702142c191287001e4e391a01b866697358a629c6cd04c319ee6c44a0c12b060ef1fd786849b87886acb63560614219525228d0b8cd2c
+  data.tar.gz: c5023bb2b680dc49821a78c235e99e7a114db56e55e4dbc785f5fba28b3d1829d49f41e504b5d37934f1b224c1bb83ca8987c5a85d2a07c3dda4dd3de372b518

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# main [(unreleased)](https://github.com/fastruby/jekyll-external-link-accessibility/compare/v0.2.0...main)
+
+- Your changes/patches go here.
+
+# v0.2.0 / 2026-07-15 [(commits)](https://github.com/fastruby/jekyll-external-link-accessibility/compare/v0.1.0...v0.2.0)
+
+- [FEATURE: Detect external links by host instead of URL prefix, ignoring the `www.` prefix and host casing](https://github.com/fastruby/jekyll-external-link-accessibility/pull/4)
+- [FEATURE: Open internal links in a new tab too, without adding `rel="nofollow"`](https://github.com/fastruby/jekyll-external-link-accessibility/pull/4)
+- [FEATURE: Show the new-tab icon on all links, not just external ones](https://github.com/fastruby/jekyll-external-link-accessibility/pull/4)
+
+# v0.1.0
+
+- [FEATURE: Add accessibility attributes (`target`, `title`, new-tab icon, screen-reader note) and `rel="nofollow"` to external links in blog posts](https://github.com/fastruby/jekyll-external-link-accessibility/commit/cbc17d840038fa932f4c1f2f153b885a659fa69e)
+- [FEATURE: Add a `data-no-external` attribute to skip individual links](https://github.com/fastruby/jekyll-external-link-accessibility/commit/49c4721)
+- [FEATURE: Add `post-excerpt` class links to the accessibility code](https://github.com/fastruby/jekyll-external-link-accessibility/pull/1)
+- [BUGFIX: Skip `scss` and `json` files in the hook](https://github.com/fastruby/jekyll-external-link-accessibility/pull/2)
+- [BUGFIX: Skip `xml` files in the hook](https://github.com/fastruby/jekyll-external-link-accessibility/pull/3)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Kudakwashe Siziva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# Jekyll External Link Accessibility
+
+This plugin makes every link in your blog posts open in a new tab accessibly (`target`, `title`, a new-tab icon, and a screen-reader note), and adds `rel="nofollow"` to external links.
+
+## Setup
+
+1. Add the gem to your `Gemfile`:
+    ```ruby
+    gem 'jekyll-external-link-accessibility'
+    ```
+2. Run `bundle install` to install the gem
+3. Add the following to your `_config.yml`:
+    ```yaml
+    plugins:
+      - jekyll-external-link-accessibility
+    ```
+
+## Usage
+The plugin edits every link in a post, internal and external:
+
+- All links open in a new tab so readers don't lose their place, with a `title`, a new-tab icon, and a screen-reader-only "opens a new window" note. Skip a specific link by adding `data-no-external="true"`, e.g. `<a href="...." data-no-external="true">...</a>`.
+- External links (pointing to a host other than your site's `url` in `_config.yml`) also get a `rel` attribute (`external nofollow noopener noreferrer` by default, see Configuration). The `nofollow` keeps them from passing your link equity off-site, so internal links are left without a `rel`. The `www.` prefix and host casing are ignored when comparing hosts.
+
+### Configuration
+You can override the default configuration by adding the following section to your Jekyll site's `_config.yml`:
+
+```yaml
+external_links:
+  rel: external nofollow noopener noreferrer
+  target: _blank
+  title: Opens a new window
+```
+
+### Styling
+Next to each link is a new-tab icon with a `icon-external-link` class name. You need to have the styles in your project. For example, we use icomoon for icons:
+
+```css
+.icon-external-link:before {
+  content: "\ea7e";
+}
+```
+#### Default Configuration
+| Key | Default Value | Description |
+| ---------------------------- | ---------------------------- | -------------------------------------------------- |
+| `external_links.rel`     | `external nofollow noopener noreferrer` | The `rel` attribute to add to external links.      |
+| `external_links.target`  | `_blank`                     | The `target` attribute to add to external links.   |
+| `external_links.title`  | `Opens a new window`                     | The `title` attribute to add title to links.   |
+
+## Steps to release a new version
+
+We follow [Semantic Versioning](https://semver.org/): bump MAJOR for incompatible changes, MINOR for backwards-compatible features, and PATCH for backwards-compatible bug fixes.
+
+1. Update the version in `lib/jekyll-external-link-accessibility/version.rb`
+2. Update `CHANGELOG.md`: move the `main (unreleased)` entries under a new `vX.Y.Z / YYYY-MM-DD` header
+3. Push a `release/vX.Y.Z` branch with those changes
+4. Open a pull request titled "Release vX.Y.Z" and merge it to `main`
+5. Tag the release and push the tag:
+    ```bash
+    git checkout main && git pull
+    git tag vX.Y.Z
+    git push --tags
+    ```
+6. Build the gem:
+    ```bash
+    gem build jekyll-external-link-accessibility.gemspec
+    ```
+7. Push it to RubyGems:
+    ```bash
+    gem push jekyll-external-link-accessibility-X.Y.Z.gem
+    ```

data/lib/jekyll-external-link-accessibility/hooks.rb

@@ -0,0 +1,13 @@
+require 'jekyll/hooks'
+require 'jekyll-external-link-accessibility'
+
+Jekyll::Hooks.register :posts, :post_render do |page|
+  Jekyll::ExternalLinkAccessibility.modify_links(page)
+end
+
+Jekyll::Hooks.register :pages, :post_render do |page|
+  # Only rewrite HTML pages. Running the HTML parser over .xml (rss/sitemap),
+  # .json, .txt, etc. would wrap them in <html><body> and corrupt them.
+  next unless ['.html', '.htm'].include?(page.extname)
+  Jekyll::ExternalLinkAccessibility.modify_links(page)
+end

data/lib/jekyll-external-link-accessibility/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class ExternalLinkAccessibility
+    VERSION = '0.2.0'
+  end
+end

data/lib/jekyll-external-link-accessibility.rb

@@ -0,0 +1,79 @@
+require 'jekyll-external-link-accessibility/hooks'
+require 'nokogiri'
+require 'uri'
+
+module Jekyll
+  class ExternalLinkAccessibility
+    EXTERNAL_SCHEMES = %w[http:// https:// //].freeze
+
+    def self.modify_links(page)
+      config = page.site.config
+      site_host = host_for(config['url'])
+      doc = Nokogiri::HTML5(page.output)
+      doc.css('.post-content a, .post-excerpt a').each do |a|
+        next if a['href'].nil? || a['href'].empty? || a['href'].start_with?('#') || a['data-no-external'] == 'true'
+
+        # Every link opens in a new tab so readers don't lose their place. Add the
+        # icon and a screen-reader note so both sighted and screen-reader users know.
+        a['target'] = external_link_target(config: config) unless a['target']
+        a['title'] = external_link_title(config: config) unless a['title']
+        a.add_child(" <i class='icon-external-link' aria-hidden='true'></i>")
+        a.add_child(
+          "<span
+            style='overflow: hidden;clip: rect(0,0,0,0);
+                  position: absolute !important;
+                  width: 1px;
+                  height: 1px;
+                  border: 0;
+                  word-wrap: normal !important;'>
+            opens a new window
+          </span>"
+        )
+
+        # Only external links get the configured rel (nofollow, etc.) so we don't
+        # pass our link equity to other sites.
+        if external_link?(a['href'], site_host)
+          a['rel'] = external_link_rel(config: config) unless a['rel']
+        end
+      end
+      page.output = doc.to_html
+    end
+
+    # A link is external only when it points to a different host than the site.
+    # Relative links ("/blog/...") and absolute links to our own domain are internal,
+    # so they keep their link equity (no nofollow).
+    def self.external_link?(href, site_host)
+      return false unless href.start_with?(*EXTERNAL_SCHEMES)
+
+      link_host = host_for(href)
+      return true if link_host.nil?
+
+      link_host != site_host
+    end
+
+    # Returns the lowercased host without a leading "www." so hosts match
+    # regardless of case or www prefix.
+    def self.host_for(url)
+      host = URI.parse(url.to_s).host
+      host&.downcase&.sub(/\Awww\./, '')
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def self.external_link_rel(config:)
+      config.dig('external_links', 'rel') || 'external nofollow noopener noreferrer'
+    end
+
+    def self.external_link_target(config:)
+      config.dig('external_links', 'target') || '_blank'
+    end
+
+    def self.external_link_title(config:)
+      config.dig('external_links', 'title') || 'Opens a new window'
+    end
+
+    private_class_method :external_link_rel
+    private_class_method :external_link_target
+    private_class_method :external_link_title
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-external-link-accessibility
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Kudakwashe Siziva
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.5
+description: Knows how to target external `a` tags and accessibility attributes
+email:
+- kudakwashe@ombulabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-external-link-accessibility.rb
+- lib/jekyll-external-link-accessibility/hooks.rb
+- lib/jekyll-external-link-accessibility/version.rb
+homepage: https://github.com/fastruby/jekyll-external-link-accessibility
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fastruby/jekyll-external-link-accessibility
+  source_code_uri: https://github.com/fastruby/jekyll-external-link-accessibility
+  changelog_uri: https://github.com/fastruby/jekyll-external-link-accessibility/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A simple gem to add accessibility to external links in blog posts
+test_files: []