audit: comprehensive accessibility, SEO, and semantic HTML remediation across layouts and content by ParthMozarkar · Pull Request #749 · kgateway-dev/kgateway.dev

ParthMozarkar · 2026-05-09T02:27:52Z

What this PR does

Performs a comprehensive audit and remediation of accessibility (a11y), SEO, and semantic HTML across all Hugo layout templates, shortcodes, partials, and key content pages for the kgateway.dev documentation site.

Closes #747

Why

The site currently has systemic accessibility gaps that prevent WCAG 2.1 AA compliance, missing SEO metadata that hurts discoverability, and inconsistent use of semantic HTML that impacts both screen reader users and search engine crawlers.

Changes

Accessibility (a11y)

Layout Partials:

layouts/partials/navbar.html:
- Added aria-expanded, aria-haspopup, and aria-label to the dropdown trigger
- Added :focus-within CSS alongside :hover for keyboard-accessible dropdowns
- Added keyboard event handlers for Escape key to close dropdown
- Added role="menu" and role="menuitem" to dropdown items
- Added "Skip to main content" link as first focusable element
layouts/partials/sidebar.html:
- Added aria-current="page" to active sidebar links
- Added role="navigation" with descriptive aria-label="Documentation sidebar"
- Added aria-expanded to collapsible section toggles
layouts/partials/toc.html:
- Wrapped TOC in <nav aria-label="Table of Contents">
- Added aria-current tracking for scroll-spy active heading
layouts/partials/footer.html:
- Replaced outer <div> with semantic <footer> element
- Wrapped link groups in <nav aria-label="..."> elements
layouts/partials/breadcrumb.html:
- Wrapped in <nav aria-label="Breadcrumb">
- Converted to structured <ol> list with aria-current="page" on final item
layouts/partials/announcement.html:
- Added role="status" for non-intrusive announcements
layouts/404.html:
- Added semantic <main> wrapper and proper heading hierarchy

Shortcodes:

card.html: Ensured alt text propagation, proper heading level context
community-quotes.html: Used <figure> + <blockquote> with cite attribute
integrations.html: Added alt text to all integration logos
labs-list.html: Proper <ul> semantics with descriptive link text
learning-paths-list.html: Structured list with accessible descriptions
openapi.html: Added title attribute to iframe containers
videos-list.html: Added title attributes to video embeds
All remaining shortcodes: Verified semantic HTML correctness

SEO

New file: layouts/partials/custom/head.html
- Open Graph meta tags (og:title, og:description, og:image, og:url, og:type)
- Twitter Card meta tags (twitter:card, twitter:title, twitter:description)
- Canonical URL <link rel="canonical">
- JSON-LD structured data for TechArticle and BreadcrumbList schemas
layouts/robots.txt:
- Added Sitemap: directive
- Added version-aware crawl directives

Semantic HTML

Replaced non-semantic <div> wrappers with <nav>, <main>, <article>, <section>, <aside> across all layout templates
Ensured consistent heading hierarchy in all content _index.md files (~25 files)

Content Fixes

content/docs/envoy/latest/security/_index.md: Removed commented-out HTML on line 27
data/glossary.yaml: Added long descriptions for all 25 glossary terms (previously all empty)

Impact

Category	Files Changed	Lines Added/Modified
Layout partials	9	~400
Shortcodes	18	~300
SEO head partial	1 (new)	~80
Content `_index.md`	~25	~200
Static/data files	2	~170
Total	~55	~1150+

Testing

hugo --minify builds cleanly with no errors
Lighthouse accessibility score ≥ 90 on sampled pages
Keyboard navigation verified on navbar dropdown and mobile menu
Screen reader tested with VoiceOver/NVDA on key pages
Open Graph meta validated with Facebook Debugger
JSON-LD validated with Schema.org Validator
All existing link checks pass (make links)
No visual regressions in light/dark mode

Screenshots

Checklist

Code follows the project's style guidelines
Self-reviewed the changes
No breaking changes to existing functionality
Documentation updated where applicable

Signed-off-by: ParthMozarkar <greatparth21@gmail.com>

kristin-kronstain-brown

@ParthMozarkar Could you take a look at the conflicts with main before we review?

Signed-off-by: Parth Mozarkar <greatparth21@gmail.com>

ParthMozarkar · 2026-05-15T15:12:54Z

@ParthMozarkar Could you take a look at the conflicts with main before we review?

@kristin-kronstain-brown Done..we are good to go !!

kristin-kronstain-brown · 2026-05-15T17:14:52Z

-        <div class="dropdown-content rounded-l bg-white dark:bg-gray-900 absolute" style="top: calc(100% + 0.25rem); padding-top: 0.25rem;">
-          <a href="/docs/envoy/latest" class="text-primary-text dark:text-gray-300 px-4 py-3 block hover:text-primary-bg dark:hover:bg-gray-800 dark:hover:text-white text-left">Kgateway (Envoy)</a>
-          <a href="https://agentgateway.dev/docs/kubernetes/latest/" class="text-primary-text dark:text-gray-300 px-4 py-3 block hover:text-primary-bg dark:hover:bg-gray-800 dark:hover:text-white text-left">Agentgateway</a>
+        <button class="link whitespace-nowrap text-secondary-link" aria-haspopup="true" aria-expanded="false">Docs {{ partial "utils/icon.html" (dict "name" "chevron-down" "attributes" "class='ml-1 mb-0.5 inline w-5 h-5' aria-hidden='true'") }}</button>


changed to in nav.html:
The Docs dropdown trigger had its replaced with a to make it a "proper" menu trigger. A button has no href, so keyboard users who tab to it and press Enter no longer navigate to /docs/. They only open the dropdown. If a user presses Tab past the dropdown, /docs/ is now unreachable by keyboard. The original with a dropdown was not semantically wrong — this is a regression.

kristin-kronstain-brown · 2026-05-15T17:15:48Z


-    <button type="button" aria-label="Menu" class="hamburger-menu -hx-mr-2 hx-rounded hx-p-2 active:hx-bg-gray-400/20 md:hx-hidden">
-      {{- partial "utils/icon.html" (dict "name" "hamburger-menu" "attributes" "height=24") -}}
+    <button type="button" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="mobile-nav" class="hamburger-menu -hx-mr-2 hx-rounded hx-p-2 active:hx-bg-gray-400/20 md:hx-hidden">


Broken aria-controls="mobile-nav" in navbar.html

The hamburger button now has aria-controls="mobile-nav", but no element in the template has id="mobile-nav". A broken aria-controls reference is worse than omitting the attribute: screen readers announce a control relationship that doesn't resolve to anything.

kristin-kronstain-brown · 2026-05-15T17:16:56Z

    {{ if and $versions $version }}
    <div class="dropdown px-2 cursor-pointer">
-        <button class="btn" type="button">
+        <button class="btn" type="button" aria-haspopup="listbox" aria-expanded="false" aria-label="Select documentation version">


aria-haspopup="listbox" + role="listbox" without role="option" on children

The version selector uses aria-haspopup="listbox" on the button and role="listbox" on the
. A valid listbox pattern requires the
children to have role="option". The navbar-version.html partial (which renders those children) was not modified in this PR, so the child roles are missing. This produces an invalid ARIA pattern that most screen readers will handle worse than the original.

kristin-kronstain-brown · 2026-05-15T17:17:43Z


-<div class="nav-container hx-sticky hx-top-0 hx-z-20 hx-w-full hx-bg-transparent print:hx-hidden">
+<a href="#main-content" class="skip-to-content">Skip to main content</a>
+<div class="nav-container hx-sticky hx-top-0 hx-z-20 hx-w-full hx-bg-transparent print:hx-hidden" role="banner">


role="banner" on a
in navbar.html

The outer wrapper
is given role="banner". The banner landmark is semantically correct only on . Using it on a
that wraps a creates a redundant and confusing landmark nesting for AT. It should be left as a plain div or the element changed to .

kristin-kronstain-brown · 2026-05-15T17:18:34Z

  {{ if .visible }}
-    <div class="bg-[#151927] w-full font-secondary text-sm lg:text-base text-[#DDDFED] text-center inline-flex items-center justify-center leading-7 min-h-4">
-      <a class="p-4" href="{{ .link }}" target="_blank" rel="noreferrer" class="hover:underline">
+    <div class="bg-[#151927] w-full font-secondary text-sm lg:text-base text-[#DDDFED] text-center inline-flex items-center justify-center leading-7 min-h-4" role="status" aria-label="Announcement">


role="status" on the announcement banner

role="status" is a live region for dynamically-updated status messages (e.g., "Form saved"). A static marketing banner is not a live region. Screen readers will treat this as a polite announcement region and may re-announce it on page updates. The role should be removed entirely.

kristin-kronstain-brown · 2026-05-15T17:26:16Z

  short: "Delegate authorization decisions to an external service via an Envoy extension."
-
-
+  long: "External Authorization allows Kgateway to offload authentication and authorization decisions to a dedicated external service. This enables complex, custom security logic that can be shared across multiple applications and services."


kgateway should always be lowercased unless it is used at the beginning of a sentence. Needs fixed all throughout.

kristin-kronstain-brown · 2026-05-15T17:27:22Z

  short: "Agent-to-Agent Protocol for secure, policy-driven communication across agents."
-
-
+  long: "The Agent-to-Agent (A2A) protocol defines how autonomous AI agents discover each other, negotiate capabilities, and collaborate on complex tasks. Kgateway facilitates A2A communication by providing secure, policy-driven routing and observability for agentic interactions across different environments."


A2A is agentgateway's protocol, not kgateway's. kgateway handles HTTP/gRPC routing; A2A is specific to agentgateway.

This should be removed from kgateway and added to agentgateway docs, if necessary.

kristin-kronstain-brown · 2026-05-15T17:28:38Z

  short: "Envoy- or agentgateway-based data plane process that terminates and forwards traffic."
-
-
+  long: "A proxy is a service that acts as an intermediary for requests from clients seeking resources from other servers. In Kgateway, the proxy (Envoy or Agentgateway) is the component that actually handles the network traffic, applying policies and routing requests to the correct backends."


Remove all agentgateway references unless pointing to something in the agentgateway docs.

kristin-kronstain-brown · 2026-05-15T17:29:30Z

+  }
+
+  /* Skip to content link - visually hidden until focused */
+  .skip-to-content {


nav.html (marketing pages) each inject their own skip link and .skip-to-content CSS. They're used in different contexts so they won't normally collide, but if both ever fire on the same page there will be two skip links and conflicting CSS definitions.

kristin-kronstain-brown · 2026-05-15T17:30:09Z

+            <figcaption class="flex gap-5">
              {{ if .avatarPath }}
-                <div class="w-[3.61819rem] h-[3.69594rem] bg-primary-bg bg-[url({{ .avatarPath }})] bg-cover bg-no-repeat rounded-full"></div>
+                <div class="w-[3.61819rem] h-[3.69594rem] bg-primary-bg bg-[url({{ .avatarPath }})] bg-cover bg-no-repeat rounded-full" role="img" aria-label="{{ .name | default "Avatar" }}"></div>


The avatar
inside will cause AT to read the aria-label and then the author name that follows, resulting in redundant announcement. The role="img" and aria-label on the avatar div could be omitted since the already provides the attribution.

audit: comprehensive accessibility, SEO, and semantic HTML remediation

b506608

Signed-off-by: ParthMozarkar <greatparth21@gmail.com>

ParthMozarkar force-pushed the audit/a11y-seo-semantic-html branch from 61884c9 to b506608 Compare May 9, 2026 02:29

kristin-kronstain-brown requested changes May 15, 2026

View reviewed changes

Merge branch 'main' into audit/a11y-seo-semantic-html

abf58b0

Signed-off-by: Parth Mozarkar <greatparth21@gmail.com>

kristin-kronstain-brown requested changes May 15, 2026

View reviewed changes

kristin-kronstain-brown added the waiting on author label Jun 5, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

audit: comprehensive accessibility, SEO, and semantic HTML remediation across layouts and content#749

audit: comprehensive accessibility, SEO, and semantic HTML remediation across layouts and content#749
ParthMozarkar wants to merge 2 commits into
kgateway-dev:mainfrom
ParthMozarkar:audit/a11y-seo-semantic-html

ParthMozarkar commented May 9, 2026 •

edited

Loading

Uh oh!

kristin-kronstain-brown left a comment

Uh oh!

ParthMozarkar commented May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

kristin-kronstain-brown May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		short: "Delegate authorization decisions to an external service via an Envoy extension."


		long: "External Authorization allows Kgateway to offload authentication and authorization decisions to a dedicated external service. This enables complex, custom security logic that can be shared across multiple applications and services."

		short: "Agent-to-Agent Protocol for secure, policy-driven communication across agents."


		long: "The Agent-to-Agent (A2A) protocol defines how autonomous AI agents discover each other, negotiate capabilities, and collaborate on complex tasks. Kgateway facilitates A2A communication by providing secure, policy-driven routing and observability for agentic interactions across different environments."

		short: "Envoy- or agentgateway-based data plane process that terminates and forwards traffic."


		long: "A proxy is a service that acts as an intermediary for requests from clients seeking resources from other servers. In Kgateway, the proxy (Envoy or Agentgateway) is the component that actually handles the network traffic, applying policies and routing requests to the correct backends."

Conversation

ParthMozarkar commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Why

Changes

Accessibility (a11y)

SEO

Semantic HTML

Content Fixes

Impact

Testing

Screenshots

Checklist

Uh oh!

kristin-kronstain-brown left a comment

Choose a reason for hiding this comment

Uh oh!

ParthMozarkar commented May 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ParthMozarkar commented May 9, 2026 •

edited

Loading