A GitHub Pages-compatible Jekyll add-on for easy tooltips syntax.

For the full guide (usages, etc.), view the project on GitHub.

Table of Contents

• What it does
  • Terminology
  • Custom labels
  • Keys with no entries
  • Preventing tooltip generation
• Creating tooltips data
• Extension: Glossary generation
• Glossary

What it does

It can automatically create tooltips for you, from a customizable set of tooltip data:

Original Markdown code:

* An [[ apple ]]

Result:

• An apple

  A round, red fruit.

  Example: Alice said, “Oh, an apple. I love apples!”

  Click to view glossary

Terminology

• key: the key used to search the dictionary/dataset of labels
• entry: the data to be shown inside the tooltip preview
• label: the dotted-underlined tooltip label. If unspecified, it is equal to the key

Custom labels

To specify a different label for the tooltip than the key, map the key to a label using a colon (:).

Keys are case sensitive, which means custom labels can be useful, especially for plural forms and start-of-sentence labels.

* An [[ apple ]]
* Two [[ apple:apples ]]
* [[ apple:Apple ]], not to be confused with the computer company, Apple Inc.

Result:

• An apple

  A round, red fruit.

  Example: Alice said, “Oh, an apple. I love apples!”

  Click to view glossary
• Two apples

  A round, red fruit.

  Example: Alice said, “Oh, an apple. I love apples!”

  Click to view glossary
• Apple

  A round, red fruit.

  Example: Alice said, “Oh, an apple. I love apples!”

  Click to view glossary , not to be confused with the computer company, Apple Inc.

Keys with no entries

When there is no tooltip entry to be found for the corresponding key, it leaves the syntax untouched:

* A [[ banana ]]

Result:

• A [[ banana ]]

Preventing tooltip generation

In order to prevent a tooltip for being generated for a specific key (e.g. “apple”), we explicitly say that “apple” is a label, not a key. In order to do so, map an empty key (“”) to the label to prevent the tooltip generation. This is equivalent to prefixing the “apple” key with a colon.

This has actually been used in this page in order to prevent the tooltips from being generated in the Markdown code examples.

* An [[ :apple ]]

Result:

• An [[ apple ]]

Creating tooltips data

Simply add to the YAML frontmatter in the page(s) you want your tooltips to be available in. This also means you are free to have different entries for different keys in different pages. Full Markdown is supported, which means you can style the tooltip entries to your liking.

tooltips:
  - name: apple
    content: |
      A round, red fruit.

      _Example:_ Alice said, "Oh, an apple. I **love** apples!"
  # ... and so on

Extension: Glossary generation

Since the tooltips generated also include links to a specific reference/fragment of the page, it can also be useful to automatically generate glossaries. You can easily generate a glossary that links to each tooltip, just like the one at the bottom of this page.

---

Glossary

This glossary is automatically generated from the available tooltip entries on this page, and so is the quick reference table below:

Quick Reference
apple

A

apple

A round, red fruit.

Example: Alice said, “Oh, an apple. I love apples!”