Hugo Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance
Last updated: 2026-03-22
Hugo is one of the fastest static site generators available, building entire sites in milliseconds using Go templates. Because Hugo generates plain HTML files with no server-side processing or JavaScript framework overhead, it has a natural advantage for accessibility: pages load quickly, there is no client-side rendering that could block assistive technology, and the HTML output is predictable and consistent. However, this advantage only holds if the templates generate proper semantic HTML. Hugo's extensive theme ecosystem includes hundreds of community themes, many of which lack basic accessibility features like skip links, ARIA landmarks, proper heading hierarchy, and sufficient color contrast. Since Hugo sites are static, there are no server-side plugins or modules to bolt on accessibility fixes. Everything must be handled in the theme templates, content Markdown, and build configuration. Content authors writing in Markdown must also be mindful of accessibility, as Markdown's simplicity can lead to missing alt text on images, improper heading structures, and inaccessible table markup. This checklist identifies the most common accessibility issues in Hugo sites and provides specific template-level and content-level fixes that Hugo developers and content authors can implement to meet WCAG 2.1 AA standards and European Accessibility Act requirements.
Common Accessibility Issues
Hugo content is typically written in Markdown, where images use the syntax . Authors frequently leave the alt text brackets empty () or use filenames instead of descriptive text. Hugo's default Markdown renderer will output an img tag with an empty or meaningless alt attribute, leaving screen reader users without any context for the image.
Establish a content guideline requiring meaningful alt text in all Markdown image syntax. Create a custom render hook template at layouts/_default/_markup/render-image.html that validates the presence of alt text and can add additional attributes. Consider using Hugo's image processing to automatically generate appropriate alt text placeholders that remind authors to update them.
Many Hugo themes use div-based layouts without semantic HTML5 elements. The header, navigation, main content, sidebar, and footer regions are wrapped in generic div elements with CSS classes, providing no structural meaning for assistive technology users. Screen reader users cannot navigate by landmarks and must traverse the entire page linearly.
Update your Hugo theme's baseof.html and other layout templates to use semantic HTML5 elements. Replace div-based wrappers with header, nav, main, aside, and footer elements. Add appropriate ARIA labels to distinguish multiple navigation regions.
<div class="wrapper">
<div class="site-header">
{{ partial "nav.html" . }}
</div>
<div class="content">
{{ block "main" . }}{{ end }}
</div>
<div class="site-footer">
{{ partial "footer.html" . }}
</div>
</div><a href="#main-content" class="skip-link">Skip to content</a>
<header role="banner">
<nav aria-label="Primary navigation">
{{ partial "nav.html" . }}
</nav>
</header>
<main id="main-content">
{{ block "main" . }}{{ end }}
</main>
<footer role="contentinfo">
{{ partial "footer.html" . }}
</footer>Hugo's built-in .TableOfContents generates a nested list of heading links, but many themes wrap this in a generic div without identifying it as a navigation region. Screen reader users cannot quickly find or skip the table of contents, and the links may not clearly communicate that they navigate within the current page.
Wrap Hugo's TableOfContents output in a nav element with an aria-label of 'Table of contents'. This allows screen reader users to locate it by landmark navigation and understand its purpose. Ensure the generated anchor links have meaningful text derived from the actual heading content.
Some Hugo themes hardcode the lang attribute or omit it entirely from the html element in the baseof.html template. For multilingual Hugo sites, the language may not update correctly for non-default languages, causing screen readers to use incorrect pronunciation rules for the entire page content.
In your baseof.html template, use Hugo's built-in language variable to set the lang attribute dynamically: <html lang="{{ .Site.Language.Lang }}">. For multilingual sites, verify that each language configuration in config.toml includes the correct languageCode. For content with inline foreign language passages, wrap them in span elements with the appropriate lang attribute.
Hugo sites frequently contain code blocks using the built-in syntax highlighter (Chroma). These code blocks are rendered as pre/code elements with syntax highlighting spans, but they lack any accessible labeling that tells screen reader users what language the code is in or what the code demonstrates. Long code blocks can be tedious for screen reader users to navigate through.
Create a custom render hook for code blocks at layouts/_default/_markup/render-codeblock.html that wraps the code in a figure element with a figcaption describing the code's purpose. Add the language as an accessible label. Consider adding a 'skip code block' link before long code examples.
Many Hugo themes include dark mode toggle buttons implemented as div or span elements with JavaScript click handlers. These toggles lack proper button semantics, do not communicate their current state to assistive technology, and cannot be activated via keyboard. Screen reader users cannot determine whether dark mode is active or inactive.
Replace custom toggle elements with proper button elements. Add aria-pressed to indicate the toggle state, and update it via JavaScript when the state changes. Ensure the button has a descriptive accessible name that includes its purpose.
<div class="theme-toggle" onclick="toggleDark()">
<span class="icon-moon"></span>
</div><button type="button"
class="theme-toggle"
aria-pressed="false"
aria-label="Dark mode">
<span class="icon-moon" aria-hidden="true"></span>
</button>Hugo-Specific Tips
- Use Hugo's render hook templates (layouts/_default/_markup/) to enforce accessibility at the Markdown rendering level. Create render-image.html to ensure all images have alt text, render-link.html to add appropriate attributes to external links, and render-heading.html to add anchor IDs for in-page navigation.
- When selecting a Hugo theme, examine the baseof.html template for semantic HTML5 elements (header, nav, main, footer), skip-to-content links, and proper lang attribute usage before committing to it. The effort to retrofit accessibility into a poorly structured theme often exceeds building from scratch.
- Leverage Hugo's built-in image processing (resources.Get and .Resize) to generate responsive images with proper srcset attributes and automatically include width and height attributes that prevent layout shift, which benefits users with vestibular disorders.
- Run Pa11y or Lighthouse against Hugo's local development server output during development. Since Hugo generates static HTML, you can also integrate accessibility testing into your CI/CD pipeline by running automated tests against the built output before deployment.
Recommended Tools
Pa11y
A command-line accessibility testing tool that can be pointed at Hugo's local development server or the built static output, testing pages against WCAG 2.1 AA standards and generating detailed reports.
hugo-accessibility
A Hugo module that adds accessibility features to your site including skip links, ARIA attributes, and accessible navigation patterns that can be integrated into any Hugo theme.
Lighthouse CI
An automated tool that integrates Lighthouse audits (including accessibility scoring) into your CI/CD pipeline, ensuring every build of your Hugo site meets accessibility thresholds before deployment.
Further Reading
Other CMS Checklists
Get our free accessibility toolkit
We're building a simple accessibility checker for non-developers. Join the waitlist for early access and a free EAA compliance checklist.
No spam. Unsubscribe anytime.