Awesome
Jekyll_href
![Gem Version](https://badge.fury.io/rb/jekyll_href.svg)
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"
.
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 one of the following:
'
(')"
(")‘
(‘)’
(’)“
(“)”
(”)
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'
The following sections and settings can be set:
Pry_on_href_error
has priority over die_on_href_error
.
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
Suppprted Syntaxes
Square brackets in the BNF notation below denote optional keyword parameters, and are not meant to be typed.
Syntax 1 (most verbose, but provides best results and enables implicit matching title)
{% href [match | [follow] [blank|notarget] [summary_exclude]] url="local_page.html" label="text to display" %}
- The url can be #relative, a page in the Jekyll website, or prefaced with a protocol, such as
https:
- If
match
is provided, andlabel
is not provided, then the title of the matched page is used as the label.
Syntax 2 (requires url
without embedded spaces)
{% href [match | [follow] [blank|notarget] [page_title] [summary_exclude]] url text to display %}
- The url must be a single token, without embedded spaces.
- The url need not be enclosed in quotes.
Syntax 3 (always works)
This syntax is recommended when the URL contains a colon (:).
{% href [match | [follow] [blank|notarget]] [page_title] [summary_exclude]
url="http://link.com with space.html" some text %}
- Each of the above examples contain an embedded newline, which is legal.
- The url must be enclosed by either single or double quotes.
Syntax 4 (implicit URL)
{% href [match | [follow] [blank|notarget] [page_title] [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
.
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:
{% href http://$domain.html some text %}
{% href url="$uri" some text %}
{% 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:
{% href class='bg_yellow' https://mslinn.com click here %}
Expands to:
<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:
{% 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 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
&shy;
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/­path/­to/­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:
{% href style='color: red; font-weight: bold;' https://mslinn.com click here %}
Expands to:
<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 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:
{% 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
-
Generates
nofollow
andtarget
attributes:{% href https://mslinn.com The Awesome %}
-
Does not generate
nofollow
ortarget
attributes.{% href follow notarget https://mslinn.com The Awesome %}
-
Does not generate
nofollow
attribute.{% href follow https://mslinn.com The Awesome %}
-
Does not generate
target
attribute.{% href notarget https://mslinn.com The Awesome %}
-
Matches page with URL containing abc.
{% href match abc The Awesome %}
-
Matches page with URL containing abc.
{% href match abc.html#tag The Awesome %}
-
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.
-
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 $.
For example, given this URL: https://ammonite.io/#import$ivy rewrite as: https://ammonite.io/#import&dollar;ivy.
Here is a complete invocation:
{% href url="https://ammonite.io/#import$ivy" label="<code>import $ivy</code>" %}
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:
{% 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:
{% 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>
You can read about the attribution
option here.
Additional Information
More information is available on my website about my Jekyll plugins.
Installation
Add this line to your Jekyll website's Gemfile
, within the jekyll_plugins
group:
group :jekyll_plugins do
gem 'jekyll_href'
end
And then execute:
$ bundle
Generated HTML
Without Keywords
{% href https://mslinn.com The Awesome %}
Expands to this:
<a href='https://mslinn.com' target='_blank' rel='nofollow'>The Awesome</a>
Which renders as this: <a href='https://mslinn.com' target='_blank' rel='nofollow'>The Awesome</a>
With follow
{% href follow https://mslinn.com The Awesome %}
Expands to this:
<a href='https://mslinn.com' target='_blank'>The Awesome</a>
With notarget
{% href notarget https://mslinn.com The Awesome %}
Expands to this:
<a href='https://mslinn.com' rel='nofollow'>The Awesome</a>
With follow notarget
{% href follow notarget https://mslinn.com The Awesome %}
Expands to this:
<a href='https://mslinn.com'>The Awesome</a>
With match
Looks for a post with a matching URL.
{% href match setting-up-django-oscar.html tutorial site %}
Might expand to this:
<a href='/blog/2021/02/11/setting-up-django-oscar.html'>tutorial site</a>
URI
{% href mslinn.com %}
Expands to this:
<a href='https://mslinn.com' target='_blank' rel='nofollow'><code>mslinn.com</code></a>
Which renders as: mslinn.com
Development
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
To install this gem onto your local machine, run:
$ bundle exec rake install
Test
A test website is provided in the demo
directory.
-
Set breakpoints.
-
Initiate a debug session from the command line:
$ bin/attach demo
-
Once the
Fast Debugger
signon appears, launch the test configuration calledAttach rdebug-ide
. -
View the generated website at
http://localhost:4444
Release
To release a new version,
-
Update the version number in
version.rb
. -
Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
-
Run the following:
$ 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.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn/jekyll_href.
License
The gem is available as open source under the terms of the MIT License.