Mike Slinn
Mike Slinn

jekyll_href

Published 2020-10-03. Last modified 2023-05-26.
Time to read: 4 minutes.

This page is part of the jekyll_plugins collection, categorized under Jekyll.
jekyll_href
jekyll_href Version
GitHub project for jekyll_href

Generates an a href tag with target="_blank" and rel="nofollow". Also provides a convenient way to generate formatted and clickable URIs.

The href tags in a page can be summarized by the href_summary tag.

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.

CAUTION: if linked text contains a single or double quote, you will see the error message: Liquid Exception: Unmatched quote. Instead, use:

  • ' (')
  • " (")
  • ‘ (‘)
  • ’ (’)
  • “ (“)
  • ” (”)

Installation

Add the following highlighted line to your Jekyll project's Gemfile, within the jekyll_plugins group:

Shell
group :jekyll_plugins do 
  gem 'jekyll_href'
end

And then execute:

Shell
$ bundle

Configuration

In _config.yml, if a section called plugin-vars exists, then its name/value pairs are available for substitution. The names must be enclosed within {{double curly braces}} in order for substitution to occur.

_config.yml
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'

Use it like this:

_config.yml
{% href {{django-github}}/django/core/management/__init__.py#L398-L401
django.core.management.execute_from_command_line %}

Syntax 1: Easiest to Type

This syntax requires that the url does not have embedded spaces.

Shell
{% href [options] url linked text to display %}

Options are:
[match | [follow] [blank|notarget]] [summary="Displayed text" | summary_exclude]

  1. The square brackets denote optional parameters, and should not be typed.
  2. Embedded newlines within the tag are legal.
  3. url should not be enclosed in quotes.
  4. If url is not provided, then the text to display is assumed to be a URI, as described in syntax 4, and is formatted into a clickable link.

Syntax 2: url Option

This syntax is recommended when the URL contains a problematic character, such as a colon (:) or space. It can be combined with an explicit label, described next.

Shell
{% href [options] url="https://blah.com?x:y" linked text to display %}

Options are:
[match | [follow] [blank|notarget]] [summary="Displayed text" | summary_exclude]

  1. The square brackets denote optional parameters, and should not be typed.
  2. Embedded newlines within the tag are legal.
  3. The url must be enclosed by either single or double quotes.

Syntax 3: Explicit label Option

This syntax is recommended when the linked text contains an option keyword, such as summary or label. It can be combined with an explicit url, described above.

Shell
{% href [options] blah.com/path/to/page.html %}

Options are:
[match | [follow] [blank|notarget]]] [shy|wbr] [summary="Displayed text" | summary_exclude] label="linked text"

Syntax 4

(implicit URL)

Shell
{% href [options] blah.com/path/to/page.html %}

Options are:
[match | [follow] [blank|notarget]]] [shy|wbr] [summary="Displayed text" | summary_exclude]

  1. The square brackets denote optional parameters, and should not be typed.
  2. Embedded newlines within the tag are legal.
  3. 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. The displayed URI is enclosed in <code></code>, 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, you could use them this way:

Shell
{% href http://$domain.html some text %}

{% href url="$uri" some text %}

{% href https://mslinn.html <code>USER=$USER</code> %}

Usage Examples

Defaults

Shell
{% href https://www.mslinn.com The Awesome %}

This generates:

Shell
<a href='https://www.mslinn.com' target='_blank' rel='nofollow'>The Awesome</a>

Which renders as: The Awesome

The following 3 variants all produce the same output:

Shell
{% href https://www.mslinn.com label="The Awesome" %}
{% href url="https://www.mslinn.com" The Awesome %}
{% href url="https://www.mslinn.com" label="The Awesome" %}

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:

Shell
{% href class='bg_yellow' https://mslinn.com click here %}

This generates:

Shell
<a href='https://mslinn.com' class='bg_yellow' target='_blank' rel='nofollow'>click here</a>

If a stylesheet in use has the following definition:

Shell
.bg_yellow {
  background-color: yellow;
}

Then the above HTML renders as: click here

follow

Shell
{% href follow https://www.mslinn.com The Awesome %}

This generates:

Shell
<a href='https://www.mslinn.com' target='_blank'>The Awesome</a>

Which renders as: The Awesome

notarget

Shell
{% href notarget https://www.mslinn.com The Awesome %}

This generates:

Shell
<a href='https://www.mslinn.com' rel='nofollow'>The Awesome</a>

Which renders as: The Awesome

follow notarget

Shell
{% href follow notarget https://www.mslinn.com The Awesome %}

This generates:

Shell
<a href='https://www.mslinn.com'>The Awesome</a>

Which renders as: The Awesome

match

Looks for a post with a matching URL.
Shell
{% href match my-jekyll-plugins Jekyll plugins %}

This might generate:

Shell
<a href='/jekyll/6200-my-jekyll-plugins.html'>Jekyll plugins</a>

Which renders as: Jekyll plugins

URI

Shell
{% href mslinn.com %}

This generates:

Shell
<a href='https://mslinn.com' target='_blank' rel='nofollow'><code>mslinn.com</code></a>

Which renders as: mslinn.com

Shy

The shy keyword option is only applicable for syntax 3 (implicit URL). This option causes displayed urls to have a &shy; inserted after each slash (/). If both shy and wbr are specified, wbr prevails.

For example:

Shell
{% href shy
mslinn.com/very/very/very/extremely/excessively/long/path/to/page.html %}

Expands to: <a href='https://mslinn.com/very/very/very/extremely//excessively/long/path/to/page.html' target='_blank' rel='nofollow'>mslinn.com/&shy;very/&shy;very/&shy;very/&shy;extremely/&shy;excessively/&shy;long/&shy;path/&shy;to/&shy;page.html

Which renders as: mslinn.com/­very/­very/­very/­extremely/­excessively/­long/­path/­to/­page.html

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:

Shell
{% href style='color: red; font-weight: bold;' https://mslinn.com click here %}

This generates:

Shell
<a href='https://mslinn.com' style='color: red; font-weight: bold;' target='_blank' rel='nofollow'>click here</a>

Which renders as: click here

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 href_summary tag. 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). This option causes displayed urls to have line break opportunities (<wbr>) inserted after each slash (/). If both shy and wbr are specified, wbr prevails.

For example:

Shell
{% href wbr
mslinn.com/very/very/very/extremely/excessively/long/path/to/page.html %}

Expands to: <a href='https://mslinn.com/very/very/very/extremely/excessively/long/path/to/page.html' target='_blank' rel='nofollow'>mslinn.com/<wbr>very/<wbr>very/<wbr>very/<wbr>extremely/<wbr>excessively/<wbr>long/<wbr>path/<wbr>to/<wbr>page.html

Which renders as: mslinn.com/very/very/very/extremely/excessively/long/path/to/page.html

href_summary Tag

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:

Shell
{% href_summary [options] %}

Options are

attribution
Generates HTML like the following after the href summary:
Shell
<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>
include_local
Generates a summary section for references to other pages within the website. Relative links (to sections within the current page) are not included.

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, 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:

Shell
{% 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:

Shell
<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>