Jekyll Glossary Tooltip Tag Plugin

👉 Live demo: https://erikw.github.io/jekyll-glossary_tooltip/

This plugin simplifies for your readers and you by making it easy to define terms or abbreviations that needs an explanation. Define a common dictionary of terms and their definition in a YAML file. Then inside markdown files you can use the provided glossary liquid tag to insert a tooltip for a defined word from the dictionary. The tooltip will show the term definition on mouse hover.

It's also possible to provide an optional URL to for example a term definition source reference. To also support mobile devices, this URL link is placed inside the tooltip pop-up itself, rather than making the term itself clickable. This is so that on mobile device, you will first tap the word to get the hover tooltip, then click the link in the tooltip if desired.

Installation

1. Add this gem to your Jekyll site's Gemfile in the :jekyll_plugins group:
   • On CLI (in project root directory):

   bundle add --group jekyll_plugins jekyll-glossary_tooltip

   • Or manually:

   group :jekyll_plugins do
     [...]
     gem 'jekyll-glossary_tooltip'
   end

2. Run $ bundle install.
3. In your site's _config.yml, enable the plugin:

   plugins:
     - jekyll-glossary_tooltip

4. Create a _data/glossary.yml file, according to the 'Glossary Term Definition File' section below, with your terms.
5. Use the liquid tag in a page like {% glossary term_name %}
6. Add CSS styling for the tooltip from jekyll-glossary_tooltip.css. You need to make sure that the pages where you will use the glossary tag have this styling applied. Typically this would mean 1) copying this file to your assets/css/ directory 2) editing your theme's template for blog posts (or what pages you desire) to include this CSS in the header like <link rel="stylesheet" href="/assets/css/jekyll-glossary_tooltip.css">. However you could also copy this file's content in to your main.css or main.scss or however you build your site's CSS.
7. Now just build your site and you will get nice nice term definition tooltips on mouse hover (or mobile, tap) for you terms!

   bundle exec jekyll build

Usage

Glossary Term Definition File

Create a file _data/glossary.yml to host your shared term definition entries. This file should contain a list of term entries in the format of:

- term: a_term_name           # Can contain spaces
  definition: A description of the term
  url: https://jekyllrb.com/  # Is optional
- term: another term
  definition: Some other term definition text

This could look something like:

- term: Jekyll
  definition: A Static Site Generator (SSG) built with ruby. Widely adopted as of GitHub Pages inclusion.
  url: https://jekyllrb.com/
- term: SSG
  definition: A Static Site Generator compiles the website before deployment. Then the generated web content is simply retrieved as-is by the client without any code running at retrieve time.
- term: Jamstack
  definition: JavaScript + API + Markup - a way of buildin and hosting websites.
  url: https://jamstack.org/
- term: EmbeddedLiquidURL
  definition: This definition has an URL with embedded liquid tags to make it dynamic at build time. Note special YAML syntax for being able to use liquid (1.)
  url: >
    {{ site.baseurl }}{% link page2.md %}

1. See here for notes on using Liquid in YAML.

Tag Usage

On any page where you've made sure include the needed CSS styling, you can use the glossary tag simply like

Here I'm talking about {% glossary term_name %} in a blog post.

The term name can contain spaces like {% glossary operating system %}.

Even if the term is defined in _data/glossary.yml as 'term_name', the matching is case-insensitive meaning that I can look it up using {% glossary TeRM_NaME %}. Note that the term is displayed as defined in the tag rather than the definition, here meaing 'TeRM_NaME'.

The case-styling above works as there's still a case-insensitive match. But what about when you actually want to dispaly the term differently? Maybe the term is defined as "cat" but you want to use the plural "cats"? Then you can supply an optional `display` argument. The syntax is:
{% glossary <term>, display: <diplay name> %}

This could be e.g.
{% glossary cat, display: cats %}
{% glossary some term, display: some other display text %}

Note that a term name can not contain a ,, as this is the argument separator character.

CSS Style Override

Simply modify the rules jekyll-glossary_tooltip.css that you copied to your project. The tooltip is based on this tutorial. View the generated HTML output to see the HTML tags that are styled, or check the tag.rb implementation in the method render().

Development

The structure of this plugin was inspired by https://ayastreb.me/writing-a-jekyll-plugin/, the plugin jekyll-sitemap and the Bundler Gem tutorial.

After checking out the repo;

1. Install RVM and install a supported ruby version (see .gemspec)
2. run script/setup to install dependencies
3. run script/test to run the tests
4. You can also run script/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Local development

Following the setup at how-to-specify-local-ruby-gems-in-your-gemfile, these are the steps needed to build a jekyll site with a local clone of this plugin for local testing.

1. Clone this repo to your machine, say at ~/src/jekyll-glossary_tooltip
2. In your Jekyll project's Gemfile:
   • Remove the gem 'jekyll-glossary_tooltip' part
   • Add instead gem 'jekyll-glossary_tooltip', github: 'erikw/jekyll-glossary_tooltip', branch: 'main'
3. Configure bundler to use a local path for this gem in this project:
   • $ bundle config --local local.jekyll-glossary_tooltip ~/src/jekyll-glossary_tooltip
4. Update the project: $ bundle install
5. Now the project will build with the local clone of this plugin when issuing e.g. bundle exec jekyll build
6. When you're done:

• Remove the local override with: $ bundle config --delete local.jekyll-glossary_tooltip
• Optionally restore the original gem include in Gemfile or keep building from a branch in the github repo.

Releasing

Instructions for releasing on rubygems.org below. Optionally make a GitHub release after this for the pushed git tag.

Using bundler/gem_tasks rake tasks

Following instructions from bundler.io:

vi -p lib/jekyll-glossary_tooltip/version.rb CHANGELOG.md
bundle exec rake build
ver=$(ruby -r ./lib/jekyll-glossary_tooltip/version.rb -e 'puts Jekyll::GlossaryTooltip::VERSION')

# Optional: test locally by including in another project
gem install pkg/jekyll-glossary_tooltip-$ver.gem

bundle exec rake release

Using gem-release gem extension

Using gem-release:

vi CHANGELOG.md && git add CHANGELOG.md && git commit -m "Update CHANGELOG.md" && git push
gem bump --version minor --tag --push --release --sign

For --version, use major|minor|patch as needed.

Multi-versions

• For ruby, just use RVM to switch between supported ruby version specified in .gemspec.
• To run with different jekyll versions, Appraisal is used with Appraisals to generate different gemfiles/
  • To use a specific Gemfile, run like

    BUNDLE_GEMFILE=gemfiles/jekyll_4.x.x.gemfile bundle exec rake spec
    bundle exec appraisal jekyll-4.x.x rake spec

  • To run rake spec for all gemfiles:

    bundle exec appraisal rake spec

  • To generate new/updated gemfiles from Appraisals

    bundle exec appraisal install
    bundle exec appraisal generate --travis

Travis

To use the travis cli client (installed from Gemfile):

1. Get a GitHub OAuth token by
   • going to github.com/settings/tokens
   • create a new token named travis-cli
   • Set the scopes repo, read:org, user:email according to the docs.
2. Set travis.com as the default so we don't need to add --pro to most commands

   bundle exec travis endpoint --set-default --api-endpoint https://api.travis-ci.com/

3. Login with the cli client

   bundle exec travis login --github-token $GITHUB_TOKEN

4. Now the cli client can be used (might need --pro to use travis.com)

   bundle exec travis lint
   bundle exec travis accounts
   bundle exec travis status
   bundle exec travis branches
   bundle exec travis monitor

Live Demo GitHub Pages

The live demo source is in the branch gh-pages-source. Check its README.md!

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/erikw/jekyll-glossary_tooltip.

License

The gem is available as open source under the terms of the MIT License.

Acknowledgement

Thanks to ayastreb/jekyll-maps for inspiration on project structure and options parsing!

More Jekyll

Check out my other Jekyll repositories here.