Add Glossary Page

[Mike-4-prog]

Summary
I’d like to propose two documentation enhancements:

Glossary Page – a dedicated page explaining key terms (API Gateway, Envoy Proxy, Kubernetes Gateway API, microgateway, control plane, etc.) to improve onboarding and keep terminology consistent.

Algolia DocSearch – integrate Algolia’s free DocSearch for fast, typo-tolerant search and analytics, making it easier for users to discover content across the docs.

Why

Glossary: helps new users quickly understand domain-specific concepts without leaving the docs.

Algolia: improves discoverability, provides search analytics for maintainers, and offers a polished user experience.

Implementation Sketch

Glossary: create docs/glossary.md with definitions; update the sidebar navigation to include it.

DocSearch: apply for Algolia’s free DocSearch, add sitemap.xml or crawler config, and embed the DocSearch UI snippet.

Benefits
These enhancements can significantly improve onboarding for new users and reduce support overhead for maintainers.

[Mike-4-prog]

I’d be happy to implement this once it’s approved. Please let me know if you’d like me to start a PR after feedback.

[artberger]

@Mike-4-prog hello, thanks for your proposals. These seem like 2 different issues, so I would propose to tackle them separately.

For the Glossary, perhaps a plan of action similar to the following would be helpful?

1. Put together a list of terms to define. These could be taken from the most frequently used terms already in the docs, terms we see people using or asking about in Slack, and similar glossaries in gateway doc sets.
2. Get the list reviewed.
3. Draft definitions. Check how we currently define these in the docs.

Then, it would be good to have some sort of shortcode tooltip implementation so that when we use the term, it is automatically explained when people hover over.

• Example blog that explains one person's approach to implementing tooltips: https://deborahwrites.com/blog/hugo-tooltip-shortcode/
• Example gloss shortcode in Istio docs: https://github.com/istio/istio.io/blob/master/layouts/shortcodes/gloss.html / their glossary page: https://istio.io/latest/docs/reference/glossary/#sidecar

For the Search proposal, I think that would be a much larger chunk of work. We have had issues getting the current search to work due to the theme styling and custom versioning that is implemented. Additionally, I am not sure if the Hextra theme has support out-of-the-box for Algolia.

[Mike-4-prog]

Hello Art, Thank you for your directives. I think it's best for me to start with the Glossary task. I'll follow your proposal and steps to get this done...I'm working on it this week alongside all the tips and snippets to make it better...I'll send a review for when I'm done...After that We can see what to do about the search..I think there is a way, but let us finish one task first. Thank you for your feedback. Mike

…

On Fri, 26 Sep 2025, 15:37 Art, ***@***.***> wrote: *artberger* left a comment (kgateway-dev/kgateway.dev#398) <#398 (comment)> @Mike-4-prog <https://github.com/Mike-4-prog> hello, thanks for your proposals. These seem like 2 different issues, so I would propose to tackle them separately. For the Glossary, perhaps a plan of action similar to the following would be helpful? 1. Put together a list of terms to define. These could be taken from the most frequently used terms already in the docs, terms we see people using or asking about in Slack, and similar glossaries in gateway doc sets. 2. Get the list reviewed. 3. Draft definitions. Check how we currently define these in the docs. Also, a nice-to-have would be some sort of shortcode tooltip implementation (example blog <https://deborahwrites.com/blog/hugo-tooltip-shortcode/>) so that when we use the term, it is automatically explained when people hover over. For the Search proposal, I think that would be a much larger chunk of work. We have had issues getting the current search to work due to the theme styling and custom versioning that is implemented. Additionally, I am not sure if the Hextra theme <https://imfing.github.io/hextra/docs/guide/configuration/#flexsearch-index> has support out-of-the-box for Algolia. — Reply to this email directly, view it on GitHub <#398 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BJGLVR2UVRCPI6AGB33WH7L3UVFUFAVCNFSM6AAAAACGZU74M6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGMZZGAYDAMZUGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[artberger]

First draft of glossary terms from @Mike-4-prog : https://docs.google.com/document/d/1qe4MkhQK67VR3L1q5yhgu1Sa5MrUPHlGMNGdsmQdFSw/edit?tab=t.0#heading=h.8ccwnu4jc8ga

[artberger]

Shared latest draft in community meeting today: https://docs.google.com/document/d/1qe4MkhQK67VR3L1q5yhgu1Sa5MrUPHlGMNGdsmQdFSw/edit?tab=t.m4c8b228wdtg#heading=h.k646ngk3rg8d