jekyll_href 1.1.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0656497a33e45341646549dc55a45747f8418acd5f84298e145134bf7c10eec5'
-  data.tar.gz: 2c938cbc5e5f09bc2b8ea42ea11dde9d28e44e74512d7ebc203bccc2d127a8f6
+  metadata.gz: 9e9e6357f4c5f4d4dd7815aab9142ab5dadfbc48b3ba719fdc6b1cd70265d3d3
+  data.tar.gz: '068d3c6821f1f8578fee4331179be452ad50fdfd620cc990a0dbdb1359f605cc'
 SHA512:
-  metadata.gz: cdbdfe53569e693e1a81cb3e30b773cc239f81ce05f46ad2f20fe638dfef0777ca4cbcafd79ba9faedc9af1bb416f2a9628abbf8d82f423dd66ef36233059402
-  data.tar.gz: 1a74a3ace7f95d965a4db351501b908345257ab6138ab9ad3f4647499230e2d2a24fcd02c17fd0577376c913dc60cb3689b526046097a33a107ccea3ea3ce484
+  metadata.gz: d4411b3c9cfad7062eb75206f487e6e1a5589874479ae09815d044177069fd567b069875b9fabd4018dc9aafed9dc5dcc656354917c90935311ee958b6c1d5c2
+  data.tar.gz: abc4e78a0745ab9f455c5e1a1f85d0a41aa85c242f155c8d064503d5682df69806ef98c06c838833d37b1d3468713d5a21e798b7bf33570d48e2e27f76450fb8

data/.rubocop.yml

@@ -1,37 +1,95 @@
-#require: rubocop-jekyll
-#inherit_gem:
-#  rubocop-jekyll: .rubocop.yml
+require:
+  # - rubocop-jekyll
+  - rubocop-md
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+# inherit_gem:
+#   rubocop-jekyll: .rubocop.yml
 
 AllCops:
   Exclude:
-      - vendor/**/*
-      - Gemfile*
+    - demo/_site/**/*
+    - exe/**/*
+    - vendor/**/*
+    - Gemfile*
   NewCops: enable
   TargetRubyVersion: 2.6
 
-# Gemspec/RequireMFA:
-#   Enabled: false
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
 
 Layout/HashAlignment:
+  EnforcedColonStyle: table
   EnforcedHashRocketStyle: table
 
+Layout/InitialIndentation:
+  Exclude:
+    - README.md
+
 Layout/LineLength:
   Max: 150
+  Exclude:
+    - spec/**/*
 
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 
+Lint/RedundantCopDisableDirective:
+  Exclude:
+    - jekyll_href.gemspec
+
 Metrics/AbcSize:
-  Max: 25
+  Max: 45
+
+Metrics/BlockLength:
+  Exclude:
+    - jekyll_href.gemspec
+    - spec/**/*
+  Max: 40
+
+Metrics/ClassLength:
+  Exclude:
+    - spec/**/*
+  Max: 40
 
 Metrics/CyclomaticComplexity:
-  Max: 10
+  Max: 20
 
 Metrics/MethodLength:
-  Max: 30
+  Max: 40
 
 Metrics/PerceivedComplexity:
-  Max: 10
+  Max: 15
+
+Naming/FileName:
+  Exclude:
+    - Rakefile
+
+RSpec/ExampleLength:
+  Max: 40
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 15
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 20
+
+Style/CommandLiteral:
+  Enabled: false
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
 
 Style/FrozenStringLiteralComment:
   Enabled: false
@@ -42,6 +100,10 @@ Style/PercentLiteralDelimiters:
 Style/RegexpLiteral:
   Enabled: false
 
+Style/StringConcatenation:
+  Exclude:
+    - spec/**/*
+
 Style/StringLiterals:
   Enabled: false
 
@@ -49,4 +111,4 @@ Style/StringLiteralsInInterpolation:
   Enabled: false
 
 Style/TrailingCommaInHashLiteral:
-  Enabled: false
+  EnforcedStyleForMultiline: comma

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 1.2.2 / 2023-03-25
+  * Added **References** capability:
+    * Added `summary_exclude` keyword option to `href` tag.
+    * Added `href_summary` tag.
+  * If a URL appears in more than one `href` with different `follow` values a warning is logged.
+
+## 1.2.1 / 2023-03-21
+  * Added `shy` and `wbr` options.
+
+## 1.2.0 / 2023-02-16
+  * Updated to `jekyll_plugin_support` v1.5.0
+
+## 1.1.1 / 2023-02-14
+  * Now dependent on `jekyll_plugin_support`
+
 ## 1.1.0 / 2023-02-03
   * Updated to `jekyll_all_collections` plugin v0.2.0.
   * Fixed insidious bug where a valid link was not used properly.

data/README.md

@@ -5,52 +5,57 @@
 `Jekyll_href` is a Jekyll plugin that provides a new Liquid tag: `href`.
 It provides a convenient way to generate formatted and clickable URIs.
 The Liquid tag generates an `a href` HTML tag,
-which by default contains `target="_blank"` and `rel=nofollow`.
+which by default contains `target="_blank"` and `rel="nofollow"`.
 
 If the url starts with `http`, or the `match` keyword is specified:
  - The url will open in a new tab or window.
- - The url will include `rel=nofollow` for SEO purposes.
+ - The url will include `rel="nofollow"` for SEO purposes.
 
 CAUTION: if linked text contains a single or double quote,
 you will see the error message: `Liquid Exception: Unmatched quote`.
-Instead, use ' (`'`), " (`"`), ‘ (`‘`),
-’ (`’`), “ (`“`), and ” (`”`)
+Instead, use:
 
+ - `'` (')
+ - `"` (")
+ - `‘` (‘)
+ - `’` (’)
+ - `“` (“)
+ - `”` (”)
+
+
+## Configuration
 In `_config.yml`, if a section called `plugin-vars` exists,
 then its name/value pairs are available for substitution.
 ```yaml
-  plugin-vars:
-    django-github: 'https://github.com/django/django/blob/3.1.7'
-    django-oscar-github: 'https://github.com/django-oscar/django-oscar/blob/3.0.2'
+plugin-vars:
+  django-github: 'https://github.com/django/django/blob/3.1.7'
+  django-oscar-github: 'https://github.com/django-oscar/django-oscar/blob/3.0.2'
 ```
 
 
-## Syntax 1 (requires `url` does not have embedded spaces):
+## Syntax 1 (requires `url` does not have embedded spaces)
 ```
-{% href [match | [follow] [blank|notarget]] url text to display %}
+{% href [match | [follow] [blank|notarget] [summary_exclude]] url text to display %}
 ```
  1. The url must be a single token, without embedded spaces.
  2. The url need not be enclosed in quotes.
  3. The square brackets denote optional keyword parameters, and should not be typed.
 
 
-## Syntax 2 (always works):
+## Syntax 2 (always works)
 This syntax is recommended when the URL contains a colon (:).
 ```
-{% href [match | [follow] [blank|notarget]]
+{% href [match | [follow] [blank|notarget]] [summary_exclude]
   url="http://link.com with space.html" some text %}
-
-{% href [match | [follow] [blank|notarget]]
-  url='http://link.com with space.html' some text %}
 ```
   1. Each of the above examples contain an embedded newline, which is legal.
   2. The url must be enclosed by either single or double quotes.
   3. The square brackets denote optional keyword parameters, and should not be typed.
 
 
-## Syntax 3 (implicit URL):
+## Syntax 3 (implicit URL)
 ```
-{% href [match | [follow] [blank|notarget]] www.domain.com %}
+{% href [match | [follow] [blank|notarget] [summary_exclude]] [shy|wbr] www.domain.com %}
 ```
 The URI provided, for example `www.domain.com`,
 is used to form the URL by prepending `https://`,
@@ -94,6 +99,63 @@ The `match` option looks through the pages collection for a URL with containing
 `Match` implies `follow` and `notarget`.
 
 
+### `shy`
+`shy` is only applicable for syntax 3 (implicit URL).
+This option causes displayed urls to have an ­ inserted after each slash (/).
+If both `shy` and `wbr` are specified, `wbr` prevails.
+
+For example:
+```
+{% href shy mslinn.com/path/to/page.html %}
+```
+Expands to:
+```
+<a href="https://mslinn.com/path/to/page.html">mslinn.com/&shy;path/&shy;to/&shy;page.html</a>
+```
+
+### `shy`
+The `shy` keyword option is only applicable for syntax 3 (implicit URL).
+This option causes displayed urls to have an [`&amp;shy;`](https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens) inserted after each slash (/).
+If both `shy` and `wbr` are specified, `wbr` prevails.
+
+For example:
+```
+{% href shy mslinn.com/path/to/page.html %}
+```
+Expands to:
+```
+<a href="https://mslinn.com/path/to/page.html" rel="nofollow" target="_blank">mslinn.com/&shy;path/&shy;to/&shy;page.html</a>
+```
+
+### `summary`
+The `summary` name/value option provides an override for the linked text in the **References** section
+generated by the `{% href_summary %}` tag.
+
+
+### `summary_exclude`
+The `summary_exclude` keyword option prevents this `href` tag from appearing in the summary
+ produced by the [<code>href_summary</code> tag](#href_summary).
+You probably want all of your menu items (whose links are generated by the `href` tag) to have this keyword option.
+
+`mailto:` links are always excluded, so there is no need to use this keyword option for those types of links.
+
+
+### `wbr`
+The `wbr` keyword option is only applicable for syntax 3 (implicit URL).
+It add [line break opportunites](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr).
+This option causes displayed urls to have an `&lt;wbr&gt;` inserted after each slash (/).
+If both `shy` and `wbr` are specified, `wbr` prevails.
+
+For example:
+```
+{% href wbr mslinn.com/path/to/page.html %}
+```
+Expands to:
+```
+<a href="https://mslinn.com/path/to/page.html" rel="nofollow" target="_blank">mslinn.com/<wbr>path/<wbr>to/<wbr>page.html</a>
+```
+
+
 ## Examples
  1. Generates `nofollow` and `target` attributes:
     ```
@@ -133,6 +195,81 @@ The `match` option looks through the pages collection for a URL with containing
     Substitutions are only made to the URL, not to the linked text.
 
 
+## References Generation
+The `href` usages on each page can be summarized at the bottom of the pages in a **References** section.
+Links are presented in the summary in the order they appear in the page.
+
+The summary is produced by the `href_summary` tag.
+Usage is:
+
+```html
+{% href_summary [options] %}
+```
+
+`Href` tag options are used to generate the summary links,
+just as they were in the text above the **References** summary section.
+The only exception is the `summary` option, which overrides the linked text.
+
+If more than one `href` tag specifies a URL,
+the first one that appears in the page sets the value of the linked text.
+
+If a URL appears in more than one `href` with different `follow` values, a warning is logged.
+
+
+### Included `href` Tags
+The following `href` tags are included in the summary:
+
+ - Those with links that start with `http` are always included.
+ - Those with [relative links](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2),
+   and have the `include_local` keyword option.
+
+### Excluded `href` Tags
+The following `href` tags are excluded from the summary:
+
+ - Those with links that start with `mailto:`.
+ - Those having the `summary_exclude` keyword option.
+
+
+### Example
+Given these `href` and `href_summary` usages in a web page:
+
+```html
+{% href https://rubygems.org RubyGems.org %}
+{% href summary="Mothership" https://jekyllrb.com/ Jekyll %}
+{% href summary="Mike Slinn" mslinn.com %}
+{% href https://mslinn.com Mike Slinn %}
+{% href summary="Front page of this website" / Front page %}
+
+{% href_summary attribution include_local %}
+```
+
+Then the generated HTML looks like the following:
+
+```html
+<h2 id="reference">References</h2>
+<ol>
+  <li><a href='https://rubygems.org' rel='nofollow' target='_blank'>RubyGems.org</a></li>
+  <li><a href='https://jekyllrb.com/' rel='nofollow' target='_blank'>Mothership</a></li>
+  <li><a href='https://mslinn.com/' rel='nofollow' target='_blank'><code>mslinn.com</code></a></li>
+</ol>
+
+<h2 id="local_reference">Local References</h2>
+<ol>
+  <li><a href='/'>Front page of this website</a></li>
+</ol>
+
+<div id="jps_attribute_735866" class="jps_attribute">
+  <div>
+    <a href="https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#href" target="_blank" rel="nofollow">
+      Generated by the jekyll_href v1.2.2 Jekyll plugin, written by Mike Slinn 2023-04-13.
+    </a>
+  </div>
+</div>
+```
+
+You can read about the `attribution` option [here](https://www.mslinn.com/jekyll/10200-jekyll-plugin-support.html#attribution).
+
+
 ## Additional Information
 More information is available on my website about
 [my Jekyll plugins](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).

data/Rakefile

@@ -1,2 +1,3 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+
 task default: %i[]

data/jekyll_href.gemspec

@@ -1,6 +1,6 @@
 require_relative 'lib/jekyll_href/version'
 
-Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
+Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_href'
 
   spec.authors = ['Mike Slinn']
@@ -10,7 +10,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   END_OF_DESC
   spec.email = ['mslinn@mslinn.com']
   spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
-  spec.homepage = 'https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#href'
+  spec.homepage = 'https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#href'
   spec.license = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
@@ -32,8 +32,6 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.version = JekyllHrefVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_all_collections', '>= 0.2.0'
-  spec.add_dependency 'jekyll_plugin_logger'
-  spec.add_dependency 'key-value-parser'
-  spec.add_dependency 'shellwords'
+  spec.add_dependency 'jekyll_all_collections', '~> 0.3.0', '>= 0.3.1'
+  spec.add_dependency 'jekyll_plugin_support', '~> 0.6.0', '>= 0.6.1'
 end

data/lib/hash_array.rb

@@ -0,0 +1,32 @@
+module HashArray
+  def reset
+    @local_hrefs = {}
+    @global_hrefs = {}
+  end
+
+  def add_link_for_page(href, hash)
+    enclosing_page = href.path
+    hash[enclosing_page] = [] if hash[enclosing_page].nil?
+    pre_existing = hash[enclosing_page].find { |h| h.link_save == href.link_save }
+    if pre_existing
+      if pre_existing.follow != href.follow
+        @logger.warn "HRef tags for '#{href.link}' have inconsistent 'follow' keyword options on line #{href.line_number} of #{enclosing_page}"
+      end
+    else
+      hash[enclosing_page] << href unless href.summary_exclude
+    end
+  end
+
+  def add_local_link_for_page(href)
+    add_link_for_page(href, HashArray.instance_variable_get(:@local_hrefs))
+  end
+
+  def add_global_link_for_page(href)
+    add_link_for_page(href, HashArray.instance_variable_get(:@global_hrefs))
+  end
+
+  module_function :add_link_for_page, :add_local_link_for_page, :add_global_link_for_page, :reset
+  public :add_local_link_for_page, :add_global_link_for_page, :reset
+
+  reset
+end

data/lib/href_summary_tag.rb

@@ -0,0 +1,79 @@
+require 'jekyll_plugin_logger'
+require 'jekyll_plugin_support'
+require_relative 'jekyll_href/version'
+
+module HrefSummaryTag
+  class HrefSummary < JekyllSupport::JekyllTag # rubocop:disable Metrics/ClassLength
+    include JekyllHrefVersion
+
+    # Class instance variables accumulate hrefs across invocations.
+    # These are hashes of arrays;
+    # the hash keys are page paths (strings) and the hash values are arrays of HRefTags.
+    # {
+    #   'path/to/page1.html': [ HRefTag1, HRefTag2 ],
+    #   'path/to/page2.html': [ HRefTag3, HRefTag4 ],
+    # }
+    @hrefs = {}
+    @hrefs_local = {}
+
+    class << self
+      attr_accessor :hrefs, :hrefs_local
+    end
+
+    include JekyllHrefVersion
+
+    # Method prescribed by the Jekyll plugin lifecycle.
+    # @param liquid_context [Liquid::Context]
+    # @return [String]
+    def render_impl
+      @helper.gem_file __FILE__ # Enables attribution
+      @include_local = @helper.parameter_specified? 'include_local'
+      global_refs = render_global_refs
+      local_refs  = render_local_refs
+      have_refs = !(global_refs + local_refs).empty?
+      <<~END_RENDER
+        #{global_refs}
+        #{local_refs}
+        #{@helper.attribute if @helper.attribution && have_refs}
+      END_RENDER
+    end
+
+    def render_global_refs
+      hrefs = HashArray.instance_variable_get(:@global_hrefs)
+      path = @page['path']
+      entries = hrefs[path]&.select { |h| h.path == path }
+      return '' if entries.nil? || entries.empty?
+
+      summaries = entries.map { |href| "<li>#{href.summary_href}</li>" }
+
+      <<~END_RENDER
+        <h2 id="reference">References</h2>
+        <ol>
+          #{summaries.join "\n  "}
+        </ol>
+      END_RENDER
+    rescue StandardError => e
+      @logger.error { "#{self.class} died with a #{e.full_message}" }
+      exit 1
+    end
+
+    def render_local_refs
+      return '' unless @include_local
+
+      hrefs = HashArray.instance_variable_get(:@local_hrefs)
+      path = @page['path']
+      entries = hrefs[path]&.select { |h| h.path == path }
+      return '' if entries.nil? || entries.empty?
+
+      summary = entries.map { |href| "<li>#{href.summary_href}</li>" }
+      <<~END_RENDER
+        <h2 id="local_reference">Local References</h2>
+        <ol>
+        #{summary.join("\n  ")}
+        </ol>
+      END_RENDER
+    end
+
+    JekyllPluginHelper.register(self, 'href_summary')
+  end
+end