Kgateway Docs에 Glossary Tooltip Hover를 추가한 방법 (Hugo Shortcodes 사용)

Source: Dev.to

소개

제가 기술 라이터이자 기여자로서 Kgateway 문서 팀에 합류했을 때, 리뷰와 사용자 피드백에서 반복되는 패턴이 나타났습니다:

독자들이 핵심 용어에서 계속 막히고 있었습니다.

Kgateway는 Kubernetes, Envoy, Service Mesh, AI/Agentic 패턴, 그리고 Kgateway‑특화 아키텍처 등 다양한 도메인을 포괄합니다—그래서 Clusters (Envoy), Backends, A2A, Ambient Mesh, Data Plane 같은 개념이 곳곳에 등장합니다. 새로운 독자들은 종종 이 용어들을 이해하기 위해 페이지를 떠나야 했고, 학습 흐름이 끊겼습니다.

이를 해결하고자 저는 Hugo 단축코드를 활용한 재사용 가능한 용어집 툴팁 호버 시스템을 구현했습니다. 그 결과 문서는 더 명확해졌고, 컨텍스트 전환이 줄어들었으며, 전반적인 완성도가 높아졌습니다.

왜 용어집 툴팁이 중요한가 (특히 기술 문서에서)

툴팁은 사소한 UI 요소처럼 보일 수 있지만, 읽기 경험을 크게 향상시킵니다.

1. 학습 속도 향상, 컨텍스트 전환 감소 – 독자는 문장을 이해하기 위해 여러 탭을 열 필요가 없습니다; 간단한 호버만으로 즉시 정의를 확인할 수 있습니다.
2. 혼합된 용어 통합에 도움 – Kgateway는 Kubernetes CRD, Envoy 개념, Agentic AI 용어, 메쉬 네트워킹 용어, 그리고 자체 키워드를 혼합합니다. 중앙 용어집을 두면 일관성을 유지할 수 있습니다.
3. 페이지가 더 깔끔하고 가독성 향상 – 정의를 반복해서 적는 대신 툴팁으로 텍스트를 깔끔하게 유지합니다.
4. 단일 진실 소스 (YAML 기반) – 정의를 데이터 저장소에 한 번만 업데이트하면 모든 곳에 자동으로 반영됩니다.

하지만 주의점: 툴팁을 남용하지 말 것

우리는 간단한 규칙에 합의했습니다:

용어의 모든 인스턴스에 툴팁을 적용하지 마세요.
너무 많은 호버 효과는 독자를 산만하게 만들며, 특히 내용이 밀집한 기술 페이지에서 그렇습니다. 우리는 전략적 배치 모델을 채택했습니다.

툴팁을 배치할 위치 (배치하지 말아야 할 위치)

다음 경우에 툴팁 사용

툴팁을 피해야 할 경우

• 모든 반복된 등장
• 텍스트가 긴 표
• 코드 블록
• 헤딩(형식 깨짐)

이렇게 하면 UI가 깔끔하고 전문적으로 유지됩니다.

용어집 툴팁 구현 방법 (Hugo 단축코드 + YAML + CSS)

1. YAML 용어집 데이터 저장소

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)."

이 파일은 30개 이상의 핵심 개념을 담은 중앙 미니‑데이터베이스 역할을 합니다.

2. Hugo 툴팁 단축코드

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 }}

Markdown 사용 예시

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

그림 1: Concept Architecture 페이지에서 “Control Plane”에 대한 툴팁 호버 정의.

3. 툴팁 스타일링 (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;
}

툴팁은 접근성이 보장되고, 반응형이며, 눈에 거슬리지 않게 설계되었습니다.

4. 용어집 페이지

우리는 glossary.md 페이지도 만들었으며, 이 페이지는:

• SEO 향상
• 모든 용어를 한 곳에 모음
• 완전한 레퍼런스 인덱스 제공

마무리 생각

용어집 호버 툴팁은 작지만, 문서를 다음과 같이 만들어 줍니다:

• 읽기 쉬움
• 초보자 친화적
• 일관성 유지
• 현대적 느낌

제가 Kgateway 문서에 기여하면서 이 기능이 사용자 경험을 눈에 띄게 향상시켰습니다. Hugo든 다른 정적 사이트 생성기든, 재사용 가능한 툴팁 시스템을 도입하는 것을 강력히 권장합니다.

읽어 주셔서 감사합니다! 재사용 가능한 템플릿이나 모듈 버전이 필요하시면 언제든지 문의 주세요. 해당 작업에 대한 병합된 Pull Request는 여기에서 확인할 수 있습니다: Tooltip Hover feature