Implementing a glossary in Jekyll

Question

Am porting a doc site from Madcap Flare to GitHub Pages using Jekyll. One thing I'm wondering about is that is there a way of implementing an automatic glossary similar to Flare's:

https://www.madcapsoftware.com/blog/guest-post-madcap-flare-101-7-the-glossary/

In summary: I want to have a glossary file comprised of terms and definitions. Then if a term occurs in a topic, it automatically becomes a link or pop-up link to the definition.

If anyone has done this or knows a way to do it I would appreciate it.

Answer 1

Yes, this is possible. Pop-over elements are also possible but I have chosen the link example.

This plugin can create links to the glossary:

module GlossaryData
  def glossary
    self['glossary']
  end
end

module Jekyll
  class GlossaryLinkGenerator < Generator
    def generate(site)
      site.data.extend(GlossaryData)

      glossary_terms = {}
      site.data.glossary.each do |entry|
        glossary_terms[entry['term'].downcase] = entry['definition']
        glossary_terms[entry['term']] = entry['definition']
      end

      # pages 
      site.pages.each do |page|
        glossary_terms.each do |term, definition|

          page.content = page.content.gsub(term) do |match|
            "<a href='/glossary.html##{term}'>#{term}</a>"
          end
        end
      end

      # posts
      site.posts.docs.each do |post|
        glossary_terms.each do |term, definition|
          post.content = post.content.gsub(term) do |match|
            "<a href='/glossary.html##{term}'>#{term}</a>"
          end
        end
      end

      # Notes

      # For all content, use site.documents instead of the two code blocks for posts and pages above
      # The site.documents attribute is an array of all the documents in your site, 
      # including pages, posts, and any other collections that you have defined in your configuration. 
      # You can use this attribute if you want to apply the glossary link generator to all types of documents in your site.
      # You can also use site.collections[COLLECTION_NAME].docs if you want to apply it to a specific collection of documents.
      # Just replace COLLECTION_NAME with the name of the collection you want to use.

      # You can also use site.collections['posts'].docs for the posts instead of site.posts.
      # site.collections is a hash of all the collections defined in your site's configuration, 
      # and each collection has a 'docs' attribute that returns an array of all the documents in the collection.
      # This is useful if you want to apply the glossary link generator to a collection other than 'posts', 
      # or if you want to apply it to multiple collections.

    end
  end
end

Define your glossary in _data/glossary.yml:

- term: Jekyll
  definition: A static site generator written in Ruby.
- term: Liquid
  definition: A template language used by Jekyll to generate dynamic content.
- term: Markdown
  definition: A lightweight markup language used to format plain text.

The test page to see that the glossary is working:

---
layout: post
---

jekyll or Jekyll? Both are matched due to downcasing.