How I Added Glossary Tooltip Hover to Kgateway Docs (Using Hugo Shortcodes)

Source: Dev.to

Introduction

When I joined the Kgateway documentation team as a Technical Writer and contributor, a recurring pattern emerged during reviews and user feedback:

Readers were constantly getting stuck on core terms.

Kgateway spans many domains—Kubernetes, Envoy, Service Mesh, AI/Agentic patterns, and Kgateway‑specific architecture—so concepts like Clusters (Envoy), Backends, A2A, Ambient Mesh, or Data Plane appear everywhere. New readers often had to leave the page just to understand these terms, breaking the learning flow.

To address this, I implemented a reusable glossary tooltip hover system using Hugo shortcodes. The result was clearer documentation, fewer context switches, and a more polished feel.

Why Glossary Tooltips Matter (Especially in Technical Documentation)

Tooltips may seem like a tiny UI detail, but they significantly improve the reading experience.

1. Faster learning, fewer context switches – Readers shouldn’t need to open multiple tabs to grasp a sentence; a simple hover provides an instant definition.
2. Helps unify mixed terminology – Kgateway mixes Kubernetes CRDs, Envoy concepts, Agentic AI terms, mesh networking terminology, and its own keywords. A central glossary creates consistency.
3. Cleaner, more readable pages – Instead of repeating definitions, a tooltip keeps the prose neat.
4. One source of truth (via YAML) – Update a definition once in the data store and it propagates everywhere.

But There’s a Catch: Don’t Overuse Tooltips

We agreed on a simple rule:

Do NOT apply tooltips on every instance of a term.
Too many hover effects distract readers, especially on dense technical pages. We adopted a strategic placement model.

Where to Place Tooltips (and Where Not To)

Use tooltips in these places

Avoid tooltips in

• Every repeated occurrence
• Tables with long text
• Code blocks
• Headings (breaks formatting)

This keeps the UI clean and professional.

How I Implemented Glossary Tooltips (Hugo Shortcodes + YAML + CSS)

1. YAML Glossary Data Store

File: /data/glossary.yaml

A2A:
  short: "Agent-to-Agent Protocol — secure, policy-driven communication between sidecarless agents."

Agentgateway:
  short: "An open-source data plane optimized for agentic AI connectivity."

Cluster (Envoy):
  short: "Envoy 'cluster' — a logical grouping of upstream endpoints used for load balancing."

Backends:
  short: "Destination services or endpoints Kgateway routes traffic to (Kubernetes services, Lambdas, external hosts)."

This acts as a central mini‑database for terms (30+ key concepts).

2. Hugo Tooltip Shortcode

File: layouts/shortcodes/gloss.html

{{ $key := .Get 0 }}
{{ $entry := index site.Data.glossary $key }}

{{ if $entry }}

  {{ .Inner | default $key }}
  
    **{{ $key }}**
    {{ $entry.short }}
    {{ if $entry.link }}
    
      Learn more
    
    {{ end }}
  

{{ else }}
{{ .Inner | default $key }}
{{ end }}

Usage in Markdown

The translation cycle starts by defining {{}}Envoy clusters{{}}...

Fig 1: Tooltip hover definition for “Control Plane” on the Concept Architecture page.

3. Tooltip Styling (CSS)

File: static/css/glossary.css

.glossary-term {
  position: relative;
  cursor: help;
  border-bottom: 1px dotted #666;
}

.glossary-term > span {
  visibility: hidden;
  opacity: 0;
  width: 280px;
  padding: 12px;
  background: #fff;
  border-radius: 6px;
  position: absolute;
  bottom: 125%;
  left: 50%;
  transform: translateX(-50%);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  transition: opacity .3s;
}

.glossary-term:hover > span,
.glossary-term:focus > span {
  visibility: visible;
  opacity: 1;
}

The tooltip is accessible, responsive, and subtle.

4. The Glossary Page

We also created a glossary.md page that:

• Improves SEO
• Collects all terms in one place
• Provides a complete reference index

Final Thoughts

Glossary hover tooltips may be small, but they make your docs:

• Easier to read
• Friendlier to beginners
• More consistent
• More modern

In my experience contributing to Kgateway docs, this feature created a noticeable boost in user experience. Whether you’re using Hugo or another static site generator, I highly recommend adding a reusable tooltip system.

Thanks for reading! If you’d like a reusable template or a module version, feel free to ask. Here’s the merged Pull Request for this task: Tooltip Hover feature