Glossary

Glossary

Overview

The glossary is implemented as a Jekyll collection plus a small client-side enhancement layer.

Glossary Data Source

  • Glossary terms live in _glossary/.
  • Each glossary file is a Markdown document with front matter such as:
    • title
    • short_definition
    • aliases
    • tags
    • optional source_name
    • optional source_url

Field behavior:

  • title is the canonical glossary label.
  • short_definition is shown in the inline glossary card and glossary directory.
  • aliases are used for alternate matching in the automatic glossary logic.
  • tags are shown in the inline card and directory cards.

Jekyll Configuration

Glossary collection config is in _config.yml.

  • collections.glossary.output: true means each term gets its own generated page.
  • collections.glossary.permalink: /glossary/:name/ defines the URL structure.
  • defaults assigns glossary items the glossary-term layout automatically.

Glossary Pages

  • _pages/glossary.md builds the glossary directory page at /glossary/.
  • _layouts/glossary-term.html renders each individual glossary term page.

The glossary directory lists all terms from site.glossary, sorted by title, and shows:

  • title
  • short definition
  • tags
  • link to the term page
  • optional external source link

Manual Inline Glossary Terms

Manual glossary usage is handled by _includes/glossary-term.html.

Example:

<span class="glossary-term" data-glossary-term><a href="/glossary/semantic-search/" class="glossary-term-trigger" aria-expanded="false"><span class="glossary-term-label">semantic search</span></a><span class="glossary-card" role="note"><span class="glossary-card-kicker">Glossary</span><strong class="glossary-card-title">Semantic Search</strong><span class="glossary-card-body">Search that tries to match by meaning and intent instead of only exact keyword overlap.</span><span class="glossary-card-footer"><span class="glossary-card-tags">Search ยท Retrieval</span><a href="/glossary/semantic-search/" class="glossary-card-link">Read more</a></span></span></span>

How it works:

  • slug is matched against a glossary entry in site.glossary.
  • label controls the visible text in the post.
  • If the slug exists, the include renders the glossary label as a subtle inline trigger plus a definition card.
  • If the slug does not exist, it falls back to plain text.
  • Without JavaScript, the trigger still links to the glossary term page.

Important implementation detail:

  • The include is intentionally rendered as a single inline HTML fragment.
  • Liquid whitespace control is used so Markdown does not treat the emitted markup as a code block or split the sentence unexpectedly.

Automatic Glossary Terms

Automatic glossary enrichment is handled by assets/glossary.js.

The current behavior is:

  • glossary entries are exposed as JSON in _layouts/default.html
  • on page load, assets/glossary.js reads that JSON
  • it scans post body content inside .post .entry
  • it matches glossary titles and aliases in plain text nodes
  • it wraps the first occurrence of each glossary term per post body

Automatic matching deliberately skips:

  • links
  • buttons
  • code
  • preformatted blocks
  • form controls
  • headings
  • existing glossary markup

This is done to avoid breaking layout or annotating code snippets.

Glossary Card Interaction

The inline glossary UI is controlled by assets/glossary.js.

Current interaction behavior:

  • glossary cards are attached to elements with data-glossary-term
  • the term itself is a click target that opens the card
  • click toggles persistent open state
  • click outside closes open cards
  • Escape closes open cards
  • resize recalculates left/right alignment
  • active text selection prevents the card from opening
  • on small screens the card is positioned as a bottom overlay rather than a floating tooltip

Glossary Styling

Glossary styles live in assets/style.scss.

This includes:

  • inline glossary label styling
  • glossary card appearance
  • glossary directory cards
  • glossary term page styling
  • dark mode adjustments
  • mobile behavior for glossary cards

Constraints

  • Automatic glossary matching is client-side, not a Jekyll plugin transformation.
  • This keeps the implementation compatible with a GitHub Pages style Jekyll setup.
  • Automatic matching currently targets blog post bodies, not every page type.
  • Only the first occurrence of a given glossary term is automatically wrapped per post body.
  • Manual include usage is still supported when exact placement matters.

Validation

When verifying glossary behavior locally, check:

  • /glossary/ directory page
  • an individual glossary term page such as /glossary/embedding/
  • a post with manual glossary includes
  • a post where automatic glossary matching should occur
  • desktop and mobile card behavior