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

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

Readers were constantly getting stuck on core terms.

Kgateway touches so many different domains:

• Kubernetes
• Envoy
• Service Mesh
• AI / Agentic patterns
• Kgateway-specific architecture

So concepts like Clusters (Envoy), Backends, A2A, Ambient Mesh, or Data Plane appear everywhere.

But new readers often had to leave the page just to understand what these terms meant.

Not good for learning flow.

So I decided to solve it the way modern docs teams do (think Stripe, Datadog, GitHub):

I implemented a reusable glossary tooltip hover system using Hugo shortcodes.

It ended up improving clarity, reducing confusion, and making the docs feel far more polished.

In this article, I’ll walk through:

• Why this feature matters
• Where to place (and not place) tooltips
• The exact files I built (gloss.html, YAML store, and CSS)
• Screenshots
• Lessons learned as a documentation contributor

---

Why Glossary Tooltips Matter (Especially in Technical Documentation)

Tooltips look like a small UI detail, but they significantly improve the reading experience.

Here’s why:

1. Faster learning, fewer context switches

Readers shouldn’t need to open three tabs just to understand a sentence.

A simple hover = instant definition.

2. Helps unify mixed terminology

Kgateway mixes:

• Kubernetes CRDs
• Envoy concepts
• Agentic AI terms
• Mesh networking terminology
• Kgateway-specific keywords

A central glossary helps create consistency.

3. Cleaner, more readable pages

Instead of repeating definitions everywhere, a tooltip keeps things neat.

4. One source of truth (via YAML)

Whenever a definition changes, update it once → it updates everywhere.

---

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

While building this feature, the docs maintainer and I agreed on one rule:

Do NOT apply tooltips on every instance of a term.

Too many hover effects distract readers, especially on dense technical pages.

So we adopted a strategic placement model👇

---

Where to Place Tooltips (and Where Not To)

Use tooltips in these places:

Location	Why
Where a term is first introduced	Helps readers build initial understanding
Overview or conceptual pages	These pages often introduce many new ideas
Pages discussing a concept heavily	Add tooltips once or twice only
Glossary page	Optional, but helpful

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)

This is the entire structure I added to the Kgateway docs.

---

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 like a central mini-database for terms. We ended up storing 30+ key concepts.

2. Hugo Tooltip Shortcode

File: layouts/shortcodes/gloss.html

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

{{ if $entry }}
<span class="glossary-term" tabindex="0" data-glossary-term="{{ $key }}">
  {{ .Inner | default $key }}
  <span class="tooltip-content">
    <strong>{{ $key }}</strong>
    <span>{{ $entry.short }}</span>
    {{ if $entry.link }}
    <a href="{{ $entry.link }}" class="tooltip-link" target="_blank">
      Learn more
    </a>
    {{ end }}
  </span>
</span>
{{ else }}
{{ .Inner | default $key }}
{{ end }}

Usage in Markdown:
The translation cycle starts by defining {{< gloss "Cluster (Envoy)" >}}Envoy clusters{{< /gloss >}}...

Fig 1: Tooltip Hover Definition for 'Control Plane' in 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;
}

Accessible, responsive, and subtle.

4. The Glossary Page

We also created a full glossary.md page, which:

• improves SEO

• collects all terms in one place

• creates a complete reference index

Final Thoughts

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

• easier to read

• friendlier to beginners

• more consistent

• more modern

And in my experience contributing to Kgateway docs, this little feature created a big difference in user experience.

If you're building technical documentation on Hugo or not, I highly recommend adding it.

Thanks for reading!
Feel free to ask if you want a reusable template or module version. Meanwhile here's a link my merged Pull Request for this task: Tooltip Hover feature