jekyll_href 1.2.6 → 1.2.8

data/README.md

@@ -1,6 +1,4 @@
-`Jekyll_href`
-[![Gem Version](https://badge.fury.io/rb/jekyll_href.svg)](https://badge.fury.io/rb/jekyll_href)
-===========
+# `Jekyll_href` [![Gem Version](https://badge.fury.io/rb/jekyll_href.svg)](https://badge.fury.io/rb/jekyll_href)
 
 `Jekyll_href` is a Jekyll plugin that provides a new Liquid tag: `href`.
 It provides a convenient way to generate formatted and clickable URIs.
@@ -8,55 +6,77 @@ The Liquid tag generates an `a href` HTML tag,
 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 open in a new tab or window.
+- 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:
+Instead, use one of the following:
 
- - `'` (')
- - `"` (")
- - `‘` (‘)
- - `’` (’)
- - `“` (“)
- - `”` (”)
+- `'` (')
+- `"` (")
+- `‘` (‘)
+- `’` (’)
+- `“` (“)
+- `”` (”)
 
 
 ## 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'
 ```
 
+The following sections and settings can be set:
+`Pry_on_href_error` has priority over `die_on_href_error`.
 
-## Syntax 1 (requires `url` does not have embedded spaces)
+```yaml
+href:
+  die_on_href_error: false # Default value is false
+  die_on_nomatch: true     # Default value is false
+  pry_on_href_error: true  # Default value is false
+href_summary:
+  die_on_href_error: false # Default value is false
+  pry_on_href_error: true  # Default value is false
 ```
-{% href [match | [follow] [blank|notarget] [summary_exclude]] url text to display %}
+
+## Syntax 1 (requires `url` without embedded spaces)
+
+```html
+{% href [match | [follow] [blank|notarget] [page_title] [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.
+
+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)
+
 This syntax is recommended when the URL contains a colon (:).
-```
-{% href [match | [follow] [blank|notarget]] [summary_exclude]
+
+```html
+{% href [match | [follow] [blank|notarget]] [page_title] [summary_exclude]
   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.
+
+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)
+
+```html
+{% href [match | [follow] [blank|notarget] [page_title] [summary_exclude]] [shy|wbr] 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://`,
 in this case the result would be `https://www.domain.com`.
@@ -65,9 +85,11 @@ so the resulting text is `<code>www.domain.com</code>`.
 
 
 ## Environment Variable Expansion
+
 URLs can contain environment variable references.
 For example, if `$domain`, `$uri` and `$USER` are environment variables:
-```
+
+```html
 {% href http://$domain.html some text %}
 
 {% href url="$uri" some text %}
@@ -75,151 +97,199 @@ For example, if `$domain`, `$uri` and `$USER` are environment variables:
 {% href https://mslinn.html <code>USER=$USER</code> %}
 ```
 
+
 ## Optional Parameters
+
+### `page_title`
+
+For local pages, use the linked page title as the link text.
+This value overrides any provided link text.
+
+
 ### `blank`
+
 The `target='_blank'` attribute is not normally generated for relative links.
 To enforce the generation of this attribute, preface the link with the word `blank`.
 The `blank` and `notarget` parameters are mutually exclusive.
 If both are specified, `blank` prevails.
 
+
 ### `class`
+
 This option allows CSS classes to be added to the HTML generated by the `href` tag.
 It has no effect on the `href_summary` tag output.
 
 For example:
 
-```
+```html
 {% href class='bg_yellow' https://mslinn.com click here %}
 ```
+
 Expands to:
-```
+
+```html
 <a href="https://mslinn.com" class="bg_yellow" rel="nofollow" target="_blank">click here</a>
 ```
 
+
 ### `follow`
+
 To suppress the `nofollow` attribute, preface the link with the word `follow`.
 
+
 ### `label='whatever you want'`
+
 If the text to be linked contains an optional keyword argument,
 for example `summary`, that word will be removed from the displayed link text,
 unless the link text is provided via the `label` option.
 Both of the following produce the same output:
-```
+
+```html
 {% href https://mslinn.com label="This is a summary" %}
 {% href label="This is a summary" https://mslinn.com %}
 ```
 
-### `notarget`
-To suppress the `target` attribute, preface the link with the word `notarget`.
-The `blank` and `notarget` parameters are mutually exclusive.
-If both are specified, `blank` prevails.
-
 
 ### `match`
+
 `match` will attempt to match the url fragment (specified as a regex) to a URL in any collection.
 If multiple documents have matching URL an error is thrown.
 The `match` option looks through the pages collection for a URL with containing the provided substring.
 `Match` implies `follow` and `notarget`.
 
 
+### `notarget`
+
+To suppress the `target` attribute, preface the link with the word `notarget`.
+The `blank` and `notarget` parameters are mutually exclusive.
+If both are specified, `blank` prevails.
+
+
 ### `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 (/).
+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:
-```
+
+```html
 {% href shy mslinn.com/path/to/page.html %}
 ```
+
 Expands to:
-```
+
+```html
 <a href="https://mslinn.com/path/to/page.html" rel="nofollow" target="_blank">mslinn.com/&shy;path/&shy;to/&shy;page.html</a>
 ```
 
+
 ### `style`
+
 This option allows CSS styling to be added to the HTML generated by the `href` tag.
 It has no effect on the `href_summary` tag output.
 
 For example:
 
-```
+```html
 {% href style='color: red; font-weight: bold;' https://mslinn.com click here %}
 ```
+
 Expands to:
-```
+
+```html
 <a href="https://mslinn.com" rel="nofollow" style="color: ref; font-weight: bold" target="_blank">click here</a>
 ```
 
+
 ### `summary`
+
 The `summary` name/value option provides an override for the linked text in the **References** section
 generated by the `{% href_summary %}` tag.
 If the value is the empty string, or no value is provided, the `href` tag is not included in the page summary.
 
 
 ### `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).
+ produced by the [`href_summary` 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:
-```
+
+```html
 {% href wbr mslinn.com/path/to/page.html %}
 ```
+
 Expands to:
-```
+
+```html
 <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:
-    ```
-    {% href https://mslinn.com The Awesome %}
-    ```
 
- 2. Does not generate `nofollow` or `target` attributes.
-    ```
-    {% href follow notarget https://mslinn.com The Awesome %}
-    ```
+1. Generates `nofollow` and `target` attributes:
 
- 3. Does not generate `nofollow` attribute.
-    ```
-    {% href follow https://mslinn.com The Awesome %}
-    ```
+   ```html
+   {% href https://mslinn.com The Awesome %}
+   ```
 
- 4. Does not generate `target` attribute.
-    ```
-    {% href notarget https://mslinn.com The Awesome %}
-    ```
+2. Does not generate `nofollow` or `target` attributes.
 
- 5. Matches page with URL containing abc.
-    ```
-    {% href match abc The Awesome %}
-    ```
+   ```html
+   {% href follow notarget https://mslinn.com The Awesome %}
+   ```
 
- 6. Matches page with URL containing abc.
-    ```
-    {% href match abc.html#tag The Awesome %}
-    ```
+3. Does not generate `nofollow` attribute.
 
- 7. Substitute name/value pair for the `django-github` variable defined above:
-    ```
-    {% href {{django-github}}/django/core/management/__init__.py#L398-L401
-      <code>django.core.management.execute_from_command_line</code> %}
-    ```
-    Substitutions are only made to the URL, not to the linked text.
+   ```html
+   {% href follow https://mslinn.com The Awesome %}
+   ```
+
+4. Does not generate `target` attribute.
+
+   ```html
+   {% href notarget https://mslinn.com The Awesome %}
+   ```
+
+5. Matches page with URL containing abc.
+
+   ```html
+   {% href match abc The Awesome %}
+   ```
+
+6. Matches page with URL containing abc.
+
+   ```html
+   {% href match abc.html#tag The Awesome %}
+   ```
+
+7. Substitute name/value pair for the `django-github` variable defined above:
+
+   ```html
+   {% href {{django-github}}/django/core/management/__init__.py#L398-L401
+     <code>django.core.management.execute_from_command_line</code> %}
+   ```
+
+   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.
 
@@ -241,20 +311,23 @@ If a URL appears in more than one `href` with different `follow` values, a warni
 
 
 ### 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.
+- 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.
+- 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
@@ -295,6 +368,7 @@ You can read about the `attribution` option [here](https://www.mslinn.com/jekyll
 
 
 ## Additional Information
+
 More information is available on my website about
 [my Jekyll plugins](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
 
@@ -311,17 +385,21 @@ end
 
 And then execute:
 
-    $ bundle install
+```shell
+$ bundle
+```
 
 
 ## Generated HTML
 
 ### Without Keywords
-```
+
+```html
 {% href https://mslinn.com The Awesome %}
 ```
 
 Expands to this:
+
 ```html
 <a href='https://mslinn.com' target='_blank' rel='nofollow'>The Awesome</a>
 ```
@@ -329,56 +407,69 @@ Expands to this:
 Which renders as this: <a href='https://mslinn.com' target='_blank' rel='nofollow'>The Awesome</a>
 
 ### With `follow`
-```
+
+```html
 {% href follow https://mslinn.com The Awesome %}
 ```
 
 Expands to this:
+
 ```html
 <a href='https://mslinn.com' target='_blank'>The Awesome</a>
 ```
 
 
 ### With `notarget`
-```
+
+```html
  {% href notarget https://mslinn.com The Awesome %}
 ```
 
 Expands to this:
+
 ```html
 <a href='https://mslinn.com' rel='nofollow'>The Awesome</a>
 ```
 
 
 ### With `follow notarget`
-```
+
+```html
 {% href follow notarget https://mslinn.com The Awesome %}
 ```
 
 Expands to this:
+
 ```html
 <a href='https://mslinn.com'>The Awesome</a>
 ```
 
 ### With `match`
+
 Looks for a post with a matching URL.
-```
+
+```html
 {% href match setting-up-django-oscar.html tutorial site %}
 ```
 
 Might expand to this:
+
 ```html
 <a href='/blog/2021/02/11/setting-up-django-oscar.html'>tutorial site</a>
 ```
 
 ### URI
+
 ```html
 {% href mslinn.com %}
 ```
+
 Expands to this:
+
 ```html
 <a href='https://mslinn.com' target='_blank' rel='nofollow'><code>mslinn.com</code></a>
 ```
+
 Which renders as: [`mslinn.com`](https://mslinn.com)
 
 
@@ -388,39 +479,46 @@ After checking out the repo, run `bin/setup` to install dependencies.
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 Install development dependencies like this:
-```
-$ BUNDLE_WITH="development" bundle install
+
+```shell
+$ BUNDLE_WITH="development" bundle
 ```
 
 To install this gem onto your local machine, run:
+
 ```shell
 $ bundle exec rake install
 ```
 
 ## Test
+
 A test website is provided in the `demo` directory.
- 1. Set breakpoints.
 
- 2. Initiate a debug session from the command line:
-    ```shell
-    $ bin/attach demo
-    ```
+1. Set breakpoints.
+2. Initiate a debug session from the command line:
 
-  3. Once the `Fast Debugger` signon appears, launch the test configuration called `Attach rdebug-ide`.
+   ```shell
+   $ bin/attach demo
+   ```
 
-  4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+3. Once the `Fast Debugger` signon appears, launch the test configuration called `Attach rdebug-ide`.
+4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
 
 
 ## Release
+
 To release a new version,
-  1. Update the version number in `version.rb`.
-  2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
-  3. Run the following:
-     ```shell
-     $ bundle exec rake release
-     ```
-     The above creates a git tag for the version, commits the created tag,
-     and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
+
+1. Update the version number in `version.rb`.
+2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
+3. Run the following:
+
+    ```shell
+    $ bundle exec rake release
+    ```
+
+    The above creates a git tag for the version, commits the created tag,
+    and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
 
 
 ## Contributing

data/jekyll_href.gemspec

@@ -33,6 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'ipaddress'
   spec.add_dependency 'jekyll', '>= 3.5.0'
   spec.add_dependency 'jekyll_all_collections', '>= 0.3.3'
-  spec.add_dependency 'jekyll_plugin_support', '>= 0.7.0'
-  spec.add_dependency 'sanitize'
+  spec.add_dependency 'jekyll_plugin_support', '>= 0.8.1'
+  spec.add_dependency 'typesafe_enum'
 end

data/lib/enums.rb

@@ -0,0 +1,21 @@
+require 'typesafe_enum'
+
+class LinkType < TypesafeEnum::Base
+  new :EXTERNAL
+  new :FRAGMENT
+  new :LOCAL
+  new :MAILTO
+  new :UNKNOWN
+end
+
+class LabelSource < TypesafeEnum::Base
+  new :FROM_PAGE_TITLE
+  new :FROM_EXPLICIT_LABEL
+  new :FROM_IMPLICIT_LABEL
+end
+
+class Hyphenation < TypesafeEnum::Base
+  new :NONE
+  new :SHY
+  new :WBR
+end

data/lib/hash_array.rb

@@ -10,7 +10,11 @@ module HashArray
     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}"
+        @logger.warn <<~END_WARN
+          HRef tags for '#{href.link}' have inconsistent 'follow' keyword options on line #{href.line_number} of #{enclosing_page}:
+            Previous value: #{pre_existing.follow}
+             Current value: #{href.follow}
+        END_WARN
       end
     else
       hash[enclosing_page] << href unless href.summary_exclude

data/lib/href_match.rb

@@ -0,0 +1,38 @@
+module MSlinn
+  class HRefTag
+    private
+
+    def compute_link_and_text(all_urls)
+      url_matches = all_urls.select { |url| url&.include? @path }
+      case url_matches.length
+      when 0
+        abort "href error: No url matches '#{@link}', found on line #{@line_number} (after front matter) of #{@path}" if @die_if_nomatch
+        @link_save = @link = '#'
+        @text = "<i>#{@link} is not available</i>"
+      when 1
+        @link = url_matches.first
+        @link = "#{@link}##{@fragment}" if @fragment
+        @link_save = @link
+      else
+        abort "Error: More than one url matched '#{@path}': #{url_matches.join(', ')}"
+      end
+    end
+
+    def handle_match(link)
+      @follow = ''
+      @target = '' unless @blank
+      @path, @fragment = link.split('#')
+
+      @logger.debug do
+        <<~END_DEBUG
+          @link=#{@link}
+          @site.posts.docs[0].url  = #{@site.posts.docs[0].url}
+          @site.posts.docs[0].path = #{@site.posts.docs[0].path}
+        END_DEBUG
+      end
+
+      all_urls = @site.all_collections.map(&:url)
+      compute_link_and_text(all_urls)
+    end
+  end
+end

data/lib/href_page_title.rb

@@ -0,0 +1,34 @@
+module MSlinn
+  class HRefTag
+    private
+
+    @hrefs = {}
+
+    def find_page(path)
+      all_pages = @site.all_collections + @site.pages
+      pages = if @match
+                all_pages.select { |page| page.url&.include? path }
+              elsif @label_source == LabelSource::FROM_PAGE_TITLE
+                all_pages.select { |page| page.url == path }
+              end
+      pages&.first
+    end
+
+    # Handles links to Jekyll pages
+    # Uses the linked page title as the link text
+    def handle_page_title(linkk)
+      @follow = @target = ''
+      raise HRefError, 'href tags with page_title require local links.' unless @link_type == LinkType::LOCAL
+
+      page = find_page linkk
+      unless page
+        msg = "There is no page at path #{linkk}"
+        @text = "<div class='href_error'>HRefError: #{msg}</div>\n<pre>  {% href #{@argument_string.strip} %}</pre>"
+        raise HRefError, msg
+      end
+      @text = @label = page.title
+      handle_empty_text linkk if @text.to_s.empty?
+      @label
+    end
+  end
+end