Jekyll plugin that marks external links
In rendered HTML contents of each Jekyll document or page,
updates <a>
elements that point to external sites as follows:
- Adds
rel="external"
attribute - Adds inner HTML markup with external link icon
You can specify a CSS selector for which links are to be evaluated, and a list of selectors for which links are to be ignored (ignored selectors take precedence).
Which links are considered external
A link is considered external if:
- Its
href
attribute value starts with “http” or “https”, and - The domain name following “http(s)://” is not equal to the
domain name part from your site URL
(which you have to specify as
url
in Jekyll configuration).
Configuration
Example configuration with defaults:
external_links:
selector: 'main a'
ignored_selectors:
- a[href*=travis]
- a[href*=coverity]
- a[href*=codecov]
marker_html: "<span class='ico-ext'><i class='fas fa-external-link-square-alt'></i></span>"
Note the assumptions made by the defaults:
Links you want to be marked as external are always within the
<main>
tag.You use Font Awesome in your site.
Links containing “travis”, “coverity” and “codecov” are only used in badges, and you don’t want to process those.
If some of these assumptions don’t apply to your site,
you can add that structure to your _config.yml
and customize the values.
external_links.selector
Only links matching this CSS path will be processed.
external_links.marker_html
The specified HTML markup will be added inside each <a>
tag
that’s detected as external link.
By default, the Font Awesome’s fa-external-link-square-alt
icon is used,
which requires your site to have Font Awesome initialized.
You can set marker_html
to empty string and style links with a custom CSS rule
(e.g., a[rel=external] { border-bottom-style: dashed; }
), though it’s less flexible.
external_links.ignored_selectors
Even if a link matches selector
, it won’t be altered if it also matches any of these
selectors.
url
The url
option in your configuration file is used when deciding
whether a given link is external or not.
Example site
An example site is included in this repo.
Use it to demo the plugin and to test it during development.
The /
path leads to Markdown version, the /asciidoc/
path leads to AsciiDoc version.
- Clone this repository
- Navigate into the example-project directory
- Run
bundle
- Run
bundle exec jekyll serve
- Open in your favorite browser the URL shown