jekyll-glossary_tooltip

KO | EN

gitlite — search

#hacktoberfest #react #ai #llm #golang #go #nodejs #windows #awesome #cli #kubernetes #security #ios #openai

jekyll-glossary_tooltip

(★ 32)

Jekyll plugin providing a glossary liquid tag that will show a tooltip of a term definition.

jekyll-glossary_tooltip 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Jekyll Glossary Tooltip Tag Plugin [![Post on X](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://x.com/intent/tweet?text=Get%20a%20nifty%20tooltip%20for%20term%20definitions%20in%20your%20Jekyll%20blog%20with%20this%20plugin&url=https://github.com/erikw/jekyll-glossary_tooltip&via=erik_westrup&hashtags=jekyll,plugin)
[![Gem Version](https://badge.fury.io/rb/jekyll-glossary_tooltip.svg)](https://badge.fury.io/rb/jekyll-glossary_tooltip)
[![Gem Downloads](https://img.shields.io/gem/dt/jekyll-glossary_tooltip?label=gem%20downloads)](https://rubygems.org/gems/jekyll-glossary_tooltip)
[![Continuous Integration](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/ci.yml/badge.svg)](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/ci.yml)
[![Continuous Deployment](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/cd.yml/badge.svg)](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/cd.yml)
[![CodeQL](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/codeql-analysis.yml)
[![pages-build-deployment](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/erikw/jekyll-glossary_tooltip/actions/workflows/pages/pages-build-deployment)
[![Code Climate Maintainability](https://qlty.sh/gh/erikw/projects/jekyll-glossary_tooltip/maintainability)](https://qlty.sh/gh/erikw/projects/jekyll-glossary_tooltip)
[![Code Climate Test Coverage](https://qlty.sh/gh/erikw/projects/jekyll-glossary_tooltip/test_coverage)](https://qlty.sh/gh/erikw/projects/jekyll-glossary_tooltip)
[![SLOC](https://sloc.xyz/github/erikw/jekyll-glossary_tooltip?lower=true)](https://raw.githubusercontent.com/erikw/jekyll-glossary_tooltip/main/)
[![Number of programming languages used](https://img.shields.io/github/languages/count/erikw/jekyll-glossary_tooltip)](https://raw.githubusercontent.com/erikw/jekyll-glossary_tooltip/main/)
[![Top programming languages used](https://img.shields.io/github/languages/top/erikw/jekyll-glossary_tooltip)](https://raw.githubusercontent.com/erikw/jekyll-glossary_tooltip/main/)
[![License](https://img.shields.io/github/license/erikw/jekyll-glossary_tooltip)](https://raw.githubusercontent.com/erikw/jekyll-glossary_tooltip/main/LICENSE.txt)
[![OSS Lifecycle](https://img.shields.io/osslifecycle/erikw/jekyll-glossary_tooltip)](https://github.com/Netflix/osstracker)

> [!TIP]
> :point_right: **Live demo**: https://erikw.github.io/jekyll-glossary_tooltip/

This plugin simplifies things for your website visitors and you by making it easy to define terms or abbreviations that need an explanation. Define a common dictionary of terms and their definition in a YAML file. Then, inside the markdown file, 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 for, 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 a 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):
   ```shell
   bundle add --group jekyll_plugins jekyll-glossary_tooltip
   ```
   * Or manually:
   ```ruby
   group :jekyll_plugins do
     [...]
     gem 'jekyll-glossary_tooltip'
   end
   ```
1. Run `$ bundle install`.
1. In your site's `_config.yml`, enable the plugin:
   ```yml
   plugins:
     - jekyll-glossary_tooltip
   ```
1. Create a `_data/glossary.yml` file, according to the 'Glossary Term Definition File' section below, with your terms.
1. Use the liquid tag in a page like `{% glossary term_name %}`
1. Now just build your site, and you will get nice, nice term definition tooltips on mouse hover (or mobile, tap) for your terms!
   ```shell
   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:

```markdown
- 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:
```markdown
- 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 retrieval time.
- term: Jamstack
  definition: JavaScript + API + Markup - a way of building and hosting websites.
  url: https://jamstack.org/
- term: EmbeddedLiquidURL
  definition: This definition has a 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](https://documentation.platformos.com/use-cases/using-liquid-markup-yaml) for notes on using Liquid in YAML.

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

```markdown
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 meaning 'TeRM_NaME'.

The case-styling above works as there's still a case-insensitive match. But what about when you
actually want to display 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 %}

When `display:` is used, the tooltip prepends the original glossary term before the definition so
readers still get the term's original context.
```

> [!WARNING]
> A term name can not contain a `,`, as this is the argument separator character.

## CSS Style Override
The plugin automatically injects its bundled tooltip CSS as a `<style>` block into every rendered HTML page, so no manual CSS setup is required.

The injected styles are placed at the start of `<head>`, which means any CSS your site loads afterward will naturally take precedence. To override specific rules, simply add your own declarations in your site's stylesheet — they will win without any extra configuration.

If you want full control (e.g., to replace the styles entirely with your own stylesheet), you can disable the built-in injection in `_config.yml`:

```yml
glossary_tooltip:
  include_default_style: false
```

Then add your own CSS based on [jekyll-glossary_tooltip.css](lib/jekyll-glossary_tooltip/jekyll-glossary_tooltip.css). View the generated HTML output to see the HTML tags that are styled, or check the [tag.rb](lib/jekyll-glossary_tooltip/tag.rb) implementation in the method `render()`.

## Page listing all terms
Thanks to this user-submitted [idea](https://github.com/erikw/jekyll-glossary_tooltip/issues/6) we have a way to create a page listing all terms with definitions and URLs.

:point_right: **Live demo**: https://erikw.github.io/jekyll-glossary_tooltip/glossary.html

Steps:
1. Install [jekyll-liquify](https://github.com/gemfarmer/jekyll-liquify) to your site according to its README instructions.
1. Create a new page in your site similar to [glossary.md](https://github.com/erikw/jekyll-glossary_tooltip/blob/gh-pages-source/glossary.md?plain=1)
1. Build your site and access your new page listing all terms!

# Development
The structure of this plugin was inspired by [https://ayastreb.me/writing-a-jekyll-plugin/](https://ayastreb.me/writing-a-jekyll-plugin/), the plugin jekyll-sitemap and the [Bundler Gem tutorial](https://bundler.io/guides/creating_gem.html).

After checking out the repo;
1. Install [RVM](https://rvm.io/rvm/install) and install a supported Ruby version (see .gemspec)
1. run `scripts/setup` to install dependencies
1. run `scripts/test` to run the tests
   * Run a specific test with `bundle exec rspec -e "name of test example"`
1.  You can also run `scripts/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](https://rossta.net/blog/how-to-specify-local-ruby-gems-in-your-gemfile.html), 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`
1. 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'`
1. Configure bundler to use a local path for this gem in this project:
   - `$ bundle config --local local.jekyll-glossary_tooltip ~/src/jekyll-glossary_tooltip`
1. Update the project: `$ bundle install`
1. Now the project will build with the local clone of this plugin when issuing e.g., `bundle exec jekyll build`
1. When you're done:
  - Remove the local override with: `$ bundle config --delete local.jekyll-glossary_tooltip`
  - Optionally restore the original gem included in `Gemfile` or keep building from a branch in the GitHub repo.

## Releasing
Instructions for releasing on rubygems.org are below. Optionally make a GitHub [release](https://github.com/erikw/jekyll-glossary_tooltip/releases) after this for the pushed git tag.

## Using bundler/gem_tasks rake tasks
Following instructions from [bundler.io](https://bundler.io/guides/creating_gem.html#releasing-the-gem):
```shell
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
```

## [recommended] Using gem-release gem extension
Using [gem-release](https://github.com/svenfuchs/gem-release):
```shell
vi CHANGELOG.md && git add CHANGELOG.md && git commit -m "Update CHANGELOG.md" && git push
gem signin
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 versions specified in `.gemspec`.
* To run with different jekyll versions, [Appraisal](https://github.com/thoughtbot/appraisal) is used with [`Appraisals`](Appraisals) to generate different [`gemfiles/`](gemfiles/)
   - To use a specific Gemfile, run like
      ```shell
      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:
      ```shell
      bundle exec appraisal rake spec
      ```
   - To generate new/updated gemfiles from `Appraisals`
      ```shell
      bundle exec appraisal install
      bundle exec appraisal generate
      ```

## Live Demo GitHub Pages
The live demo source is in the branch [`gh-pages-source`](https://github.com/erikw/jekyll-glossary_tooltip/tree/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](https://opensource.org/licenses/MIT).

# Acknowledgement
Thanks to [ayastreb/jekyll-maps](https://github.com/ayastreb/jekyll-maps) for inspiration on project structure and options parsing!

# More Jekyll
Check out my other Jekyll repositories [here](https://github.com/erikw?tab=repositories&q=jekyll-&type=&language=&sort=).

jekyll-glossary_tooltip

jekyll-glossary_tooltip 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

jekyll-glossary_tooltip

jekyll-glossary_tooltip 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README