Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mslinn/jekyll_href
Jekyll plugin that generates an HTML 'a href' tag, possibly with target='_blank' and rel='nofollow'. URLs can contain environment variable references. Also provides a convenient way to generate formatted and clickable URIs. Features optional automatically-generated soft hyphens. The href tags in a page can be summarized by the href_summary tag.
https://github.com/mslinn/jekyll_href
jekyll jekyll-plugin jekyll-tag
Last synced: about 1 month ago
JSON representation
Jekyll plugin that generates an HTML 'a href' tag, possibly with target='_blank' and rel='nofollow'. URLs can contain environment variable references. Also provides a convenient way to generate formatted and clickable URIs. Features optional automatically-generated soft hyphens. The href tags in a page can be summarized by the href_summary tag.
- Host: GitHub
- URL: https://github.com/mslinn/jekyll_href
- Owner: mslinn
- License: mit
- Created: 2022-03-11T19:26:28.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-08-20T14:22:33.000Z (4 months ago)
- Last Synced: 2024-10-01T15:49:46.479Z (2 months ago)
- Topics: jekyll, jekyll-plugin, jekyll-tag
- Language: Ruby
- Homepage: https://www.mslinn.com/jekyll_plugins/jekyll_href.html
- Size: 756 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-jekyll-plugins - **jekyll_href**
README
# `Jekyll_href` [](https://badge.fury.io/rb/jekyll_href)
`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.
```yaml
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`.
```yaml
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](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form)
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)
```html
{% href [match | [follow] [blank|notarget] [summary_exclude]] url="local_page.html" label="text to display" %}
```
1. The url can be #relative, a page in the Jekyll website, or prefaced with a protocol, such as `https:`
2. If `match` is provided, and `label` is not provided, then the title of the matched page is used as the label.
## Syntax 2 (requires `url` without embedded spaces)
```html
{% href [match | [follow] [blank|notarget] [page_title] [summary_exclude]] url text to display %}
```
1. The url must be a single token, without embedded spaces.
2. The url need not be enclosed in quotes.
## Syntax 3 (always works)
This syntax is recommended when the URL contains a colon (:).
```html
{% href [match | [follow] [blank|notarget]] [page_title] [summary_exclude]
url="http://link.com with space.html" some text %}
```
1. Each of the above examples contain an embedded newline, which is legal.
2. The url must be enclosed by either single or double quotes.
## Syntax 4 (implicit URL)
```html
{% 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 `
so the resulting text is `www.domain.com`.
## Environment Variable Expansion
URLs can contain environment variable references.
For example, if `$domain`, `$uri` and `$USER` are environment variables:
```html
{% href http://$domain.html some text %}
{% href url="$uri" some text %}
{% href https://mslinn.html USER=$USER %}
```
## 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:
```html
{% href class='bg_yellow' https://mslinn.com click here %}
```
Expands to:
```html
click here
```
### `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:
```html
{% 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
[`­`](https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens)
inserted after each slash (/).
If both `shy` and `wbr` are specified, `wbr` prevails.
For example:
```html
{% href shy mslinn.com/path/to/page.html %}
```
Expands to:
```html
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:
```html
{% href style='color: red; font-weight: bold;' https://mslinn.com click here %}
```
Expands to:
```html
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](#href_summary).
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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr).
This option causes displayed urls to have an `<wbr>` inserted after each slash (/).
If both `shy` and `wbr` are specified, `wbr` prevails.
For example:
```html
{% href wbr mslinn.com/path/to/page.html %}
```
Expands to:
```html
mslinn.com/path/to/page.html
```
## Examples
1. Generates `nofollow` and `target` attributes:
```html
{% href https://mslinn.com The Awesome %}
```
2. Does not generate `nofollow` or `target` attributes.
```html
{% href follow notarget https://mslinn.com The Awesome %}
```
3. Does not generate `nofollow` attribute.
```html
{% href follow https://mslinn.com The Awesome %}
```
4. Does not generate `target` attribute.
```html
{% href notarget https://mslinn.com The Awesome %}
```
5. Matches page with URL containing abc.
```html
{% href match abc The Awesome %}
```
6. Matches page with URL containing abc.
```html
{% href match abc.html#tag The Awesome %}
```
7. Substitute name/value pair for the `django-github` variable defined above:
```html
{% href {{django-github}}/django/core/management/__init__.py#L398-L401
django.core.management.execute_from_command_line %}
```
Substitutions are only made to the URL, not to the linked text.
8. 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$ivy.
Here is a complete invocation:
{% href url="https://ammonite.io/#import$ivy"
label="import $ivy" %}
## 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:
```html
{% 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](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2),
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:
```html
{% 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:
```html
References
Local References
```
You can read about the `attribution` option [here](https://www.mslinn.com/jekyll/10200-jekyll-plugin-support.html#attribution).
## Additional Information
More information is available on my website about
[my Jekyll plugins](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
## Installation
Add this line to your Jekyll website's `Gemfile`, within the `jekyll_plugins` group:
```ruby
group :jekyll_plugins do
gem 'jekyll_href'
end
```
And then execute:
```shell
$ bundle
```
## Generated HTML
### Without Keywords
```html
{% href https://mslinn.com The Awesome %}
```
Expands to this:
```html
The Awesome
```
Which renders as this: The Awesome
### With `follow`
```html
{% href follow https://mslinn.com The Awesome %}
```
Expands to this:
```html
The Awesome
```
### With `notarget`
```html
{% href notarget https://mslinn.com The Awesome %}
```
Expands to this:
```html
The Awesome
```
### With `follow notarget`
```html
{% href follow notarget https://mslinn.com The Awesome %}
```
Expands to this:
```html
The Awesome
```
### With `match`
Looks for a post with a matching URL.
```html
{% href match setting-up-django-oscar.html tutorial site %}
```
Might expand to this:
```html
tutorial site
```
### URI
```html
{% href mslinn.com %}
```
Expands to this:
```html
mslinn.com
```
Which renders as: [`mslinn.com`](https://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:
```shell
$ BUNDLE_WITH="development" bundle
```
To install this gem onto your local machine, run:
```shell
$ bundle exec rake install
```
## Test
A test website is provided in the `demo` directory.
1. Set breakpoints.
2. Initiate a debug session from the command line:
```shell
$ bin/attach demo
```
3. Once the `Fast Debugger` signon appears, launch the test configuration called `Attach rdebug-ide`.
4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
## Release
To release a new version,
1. Update the version number in `version.rb`.
2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
3. Run the following:
```shell
$ 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](https://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](https://opensource.org/licenses/MIT).