jekyll_href

Published 2020-10-03. Last modified 2024-08-21.
Time to read: 6 minutes.

This page is part of the jekyll_plugins collection.

jekyll_href

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

Features

Generates 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 ( and ).

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:

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

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. 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"
%}

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 1: Most Verbose

This is the most verbose syntax, but it provides most reliable results. If match is specified, the title from the matching page is used as the link text unless overridden by the value of the option parameter.