Published 2020-10-03.
Last modified 2023-05-26.
Time to read: 4 minutes.
jekyll_plugins
collection, categorized under Jekyll.
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:
group :jekyll_plugins do gem 'jekyll_href' end
And then execute:
$ bundle
Configuration
In _config.yml
, if a section called plugin-vars
exists,
then its name/value pairs are available for substitution.
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: Easiest to Type
This syntax requires that the url
does not have embedded spaces.
{% href [options] url linked text to display %}
Options are:
[match | [follow] [blank|notarget]] [summary="Displayed text" | summary_exclude]
- The square brackets denote optional parameters, and should not be typed.
- Embedded newlines within the tag are legal.
url
should not be enclosed in quotes.-
If
url
is not provided, then thetext 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.
{% href [options] url="https://blah.com?x:y" linked text to display %}
Options are:
[match | [follow] [blank|notarget]] [summary="Displayed text" | summary_exclude]
- The square brackets denote optional parameters, and should not be typed.
- Embedded newlines within the tag are legal.
- 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.
{% 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)
{% href [options] blah.com/path/to/page.html %}
Options are:
[match | [follow] [blank|notarget]]] [shy|wbr] [summary="Displayed text" | summary_exclude]
- The square brackets denote optional parameters, and should not be typed.
- Embedded newlines within the tag are legal.
-
The URI provided, for example
www.domain.com
, is used to form the URL by prependinghttps://
, in this case the result would behttps://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:
{% href http://$domain.html some text %} {% href url="$uri" some text %} {% href https://mslinn.html <code>USER=$USER</code> %}
Usage Examples
Defaults
{% href https://www.mslinn.com The Awesome %}
This generates:
<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:
{% 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:
{% href class='bg_yellow' https://mslinn.com click here %}
This generates:
<a href='https://mslinn.com' class='bg_yellow' target='_blank' rel='nofollow'>click here</a>
If a stylesheet in use has the following definition:
.bg_yellow { background-color: yellow; }
Then the above HTML renders as: click here
follow
{% href follow https://www.mslinn.com The Awesome %}
This generates:
<a href='https://www.mslinn.com' target='_blank'>The Awesome</a>
Which renders as: The Awesome
notarget
{% href notarget https://www.mslinn.com The Awesome %}
This generates:
<a href='https://www.mslinn.com' rel='nofollow'>The Awesome</a>
Which renders as: The Awesome
follow notarget
{% href follow notarget https://www.mslinn.com The Awesome %}
This generates:
<a href='https://www.mslinn.com'>The Awesome</a>
Which renders as: The Awesome
match
Looks for a post with a matching URL.{% href match my-jekyll-plugins Jekyll plugins %}
This might generate:
<a href='/jekyll/6200-my-jekyll-plugins.html'>Jekyll plugins</a>
Which renders as: Jekyll plugins
URI
{% href mslinn.com %}
This generates:
<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
­
inserted after each slash (/
).
If both shy
and wbr
are specified, wbr
prevails.
For example:
{% href shy
mslinn.com/very/ very/ very/ extremely/ excessively/ long/ path/ to/ page.html %}
Expands to:
<a href='https://mslinn.com/
mslinn.com/­
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:
{% href style='color: red; font-weight: bold;' https://mslinn.com click here %}
This generates:
<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:
{% href wbr
mslinn.com/very/ very/ very/ extremely/ excessively/ long/ path/ to/ page.html %}
Expands to:
<a href='https://mslinn.com/
mslinn.com/<wbr>
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:
{% href_summary [options] %}
Options
are
attribution
- Generates HTML like the following after the
href
summary:
<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:
{% 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:
<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>