Mike Slinn
Mike Slinn

jekyll_href

Published 2020-10-03. Last modified 2025-01-08.
Time to read: 9 minutes.

This page is part of the jekyll_plugins collection.
The version described in this article has not been released yet. Performance is not where I want it to be yet. You can build it as documented, or wait a week or two, and it will probably become available.
jekyll_href version
GitHub project for jekyll_href

This is a flexible tag that is designed to minimize the work of creating and maintaining a Jekyll website.

Features

Provides an a href tag with default options that can be overridden.

The match keyword causes the title of the linked Jekyll page to be used as the link text; an error is displayed if the page does not exist.

Provides a convenient syntax for generating links with monospaced text that display the URL being linked to.

Can generate soft hyphens (&shy; and <wbr>).

If the url starts with http, or the match keyword is specified:

  • The url will open in a new tab or window unless overriden with the notarget option.
  • The url will include rel="nofollow" for SEO purposes unless overriden with the follow option.

URLs can be composed from environment variable references.

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

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

  • &apos; (')
  • &quot; (")
  • &lsquo; (‘)
  • &rsquo; (’)
  • &ldquo; (“)
  • &rdquo; (”)

Installation

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

Gemfile
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. When referenced from a web page, 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 as shown below. The lines have been folded for legibility; whitespace formatting is optional:

HTML or Markdown
{% href
  label="django.core.management.execute_from_command_line"
  url="{{django-github}}/django/core/management/__init__.py#L398-L401"
%}

The following sections and settings can be set: Pry_on_href_error has priority over die_on_href_error.

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

Common Usages

For local links (links within a Jekyll website), the best way to make them is with an incantation like this:

HTML or markdown
{% href match url='trust_winning.html' %}

The above uses the page title of trust_winning.html as the link text; an error is displayed if the page does not exist. It renders like this: Trust, Winning and Losing as an Expert Witness.

To display external links with a monospaced font, and use the URL as the link text, use an incantation like this:

HTML or markdown
{% href url='mslinn.com' %}

The above renders as: mslinn.com.

Supported Syntaxes

Square brackets in the BNF notation below denote optional keyword parameters, and are not meant to be typed.

Additional usage examples follow.

Syntax 0: Most Powerful

This syntax relies upon the match option to look up the title from the page's front matter. If match is specified, the title from the matching page is used as the link text unless overridden by the value of the optional label parameter. Here is an example:

Jekyll page
{% href match "suffix/of/a/page.html" %}

The following links to this very web page:

Jekyll page
{% href match "/jekyll_plugins/jekyll_href.html" %}

The above renders as: jekyll_href.

In addition, if the page being linked to is not found, an error condition is raised.

Syntax 1: Most Verbose

This is the most verbose syntax.

BNF syntax for HTML or markdown
{% href [options] url="page.html"
  label="linked text to display"
  url="local_page.html"
 %}

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

  1. The url can be #relative, a page in the Jekyll website, or prefaced with a protocol, such as https:.
  2. Embedded newlines within the label are legal.
  3. The url and label parameter values can be enclosed in single or double quotes.
  4. If match is specified, and label is not specified, then the title of the matched page is used as the label.

Syntax 2: Easiest to Type

This syntax uses positional parameters instead of labeled parameters. This syntax can only be used if the url does not contain embedded spaces.

BNF syntax for HTML or markdown
{% href [options] url linked text to display %}

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

  1. Embedded newlines within the tag are legal.
  2. url should not be enclosed in quotes.
  3. The match keyword causes the title of the linked page to be used as the link text unless the label option is provided.
  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 4: 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.

BNF syntax for HTML or markdown
{% href [options] blah.com/path/to/page.html label="Sooper Dooper" %}

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

Syntax 5: Positional URL

BNF syntax for HTML or markdown
{% href [options] blah.com/path/to/page.html %}

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

  1. Embedded newlines within the tag are legal.
  2. 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 within a <code></code> tag, 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:

HTML or markdown
Using keyword options:
{% href url="http://$domain.html" label="some text" %}

Using the url option and positional link text:
{% href url="$uri" some text %}

Using positional parameters for the URL and the link text:
{% href https://mslinn.html <code>USER=$USER</code> %}

Optional Parameters

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:

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

Expands to the following, formatted for easier reading: 

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

Which renders as: click here

follow

To suppress the nofollow attribute, preface the link with the word follow.

label

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:

Jekyll web page
{% href https://mslinn.com label="This is a summary" %}
{% href label="This is a summary" https://mslinn.com %}

match

match will attempt to match the url fragment (specified as a regex) to a URL in any collection. If multiple documents have matching URLs 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.

Jekyll web page
{% href match url="page6.html" %}

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.

page_title

For local pages, use the linked page title as the link text. This value overrides any provided link text.

shy

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

For example:

Jekyll web page
{% href shy mslinn.com/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:

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

Expands to the following, formatted for easier reading: 

<a href="https://mslinn.com"
  rel="nofollow"
  style="color: ref; font-weight: bold"
  target="_blank">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). It add line break opportunites. This option causes displayed urls to have an <wbr> inserted after each slash (/). If both shy and wbr are specified, wbr prevails.

For example:

Jekyll web page
{% href wbr mslinn.com/path/to/page.html %}

Expands to the following, formatted for easier reading: 

<a href="https://mslinn.com/path/to/page.html"
  rel="nofollow"
  target="_blank">mslinn.com/<wbr>path/<wbr>to/<wbr>page.html</a>

Which renders as: 

mslinn.com/path/to/page.html

Usage Examples

Defaults

This example uses positional parameters:

HTML or markdown
{% href https://www.mslinn.com The Awesome %}

This generates:

Generated HTML
<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:

HTML or markdown
Positional URL parameter with the label option:
{% href https://www.mslinn.com label="The Awesome" %}

Url parameter with positional linked text:
{% href url="https://www.mslinn.com" The Awesome %}

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

Dollar Signs

If the URL has a dollar sign in it, jekyll_href will attempt to replace an environment variable with its value. That will likely fail silently. To work around the problem, replace dollar signs in URLs with &dollar;.

For example, given this URL:
https://ammonite.io/#import$ivy
rewrite as:
https://ammonite.io/#import&amp;dollar;ivy.

Here is a complete invocation:

Href with $ in the URL
{% href url="https://ammonite.io/#import&dollar;ivy"
      label="<code>import &dollar;ivy</code>"
%}

The above renders as: import $ivy

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 or markdown
{% href class='bg_yellow' https://mslinn.com click here %}

This generates:

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

If a stylesheet in use has the following definition:

CSS
.bg_yellow {
  background-color: yellow;
  padding-left: 0.5em;
  padding-right: 0.5em;
}

Then the above HTML renders as: click here

follow

This example uses the follow keyword option to suppress the generation of rel='nofollow'.

HTML or markdown
{% href follow https://www.mslinn.com The Awesome %}

This generates:

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

Which renders as: The Awesome

notarget

This example uses the notarget keyword option to suppress the generation of target='_blank'.

HTML or markdown
{% href notarget https://www.mslinn.com The Awesome %}

This generates:

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

Which renders as: The Awesome

follow notarget

This example suppresses the generation of rel='nofollow' and target='_blank'.

HTML or markdown
{% href follow notarget https://www.mslinn.com The Awesome %}

This generates:

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

Which renders as: The Awesome

match

The match options looks for a page with a matching URL. You can write the entire filename of a page, or just a portion of the filename, or you can include some of the path as well. Here are two ways of writing the same thing:

HTML or Markdown
{% comment %} Using the url and label parameters: {% endcomment %}
{% href match url="my-jekyll-plugins" label="Jekyll plugins" %}

{% comment %} Using positional parameters for url and label: {% endcomment %}
{% href match my-jekyll-plugins Jekyll plugins %}

Either of the above might generate:

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

The above renders as: Jekyll plugins

A URI fragment can be included in the url to be matched. In the following example, the Jekyll page at jekyll_plugin_support.html is found and linked, and the URI fragment #features is appended to the generated link:

Match parameter with URI fragment
{% href match url="jekyll_plugin_support.html#features" %}

Renders as: jekyll_plugin_support

URI

HTML or markdown
{% href mslinn.com %}

This generates:

Generated HTML
<a href='https://mslinn.com'><code>mslinn.com</code></a>

Which renders as: mslinn.com

Shy

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

For example:

HTML or markdown
{% 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:

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

This generates:

HTML or markdown
<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:

HTML or markdown
{% 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:

HTML or markdown
{% href_summary [options] %}

Options are

attribution
Generates HTML like the following after the href summary:
HTML
<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.

Examples

Given these href and href_summary usages in a web page:

HTML or markdown
{% 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:

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

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:

Jekyll web page
{% 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, 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:

Jekyll web page
{% 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 %}

The generated HTML looks like the following: 

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

Front page
Expert witness USA
17 articles on LLMs
Studio technology USA
Original music by Mike Slinn
General topics
Ruby language USA
Jekyll-generated websites USA
Git and libgit2 USA
Django-powered e-commerce USA
Mainframe image; Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License by PekoeBlaze
* indicates a required field.

Please select the following to receive Mike Slinn’s newsletter:

You can unsubscribe at any time by clicking the link in the footer of emails.

Mike Slinn uses Mailchimp as his marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp’s privacy practices.