Jekyll Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance

The Minima theme that ships as Jekyll's default uses a brand-blue link colour (#828282 hover, #2a7ae2 base) that meets 4.5:1 only when the link sits next to its underline. When a Minima-based theme removes underlines for visual cleanliness (a common 'modernization' override) the colour-only differentiation fails 1.4.1 and the contrast often slips below 4.5:1 in the visited state, which Minima sets to #757575 on white (3.5:1).

// _sass/minima/_base.scss
$brand-color: #2a7ae2;
a { color: $brand-color; text-decoration: none; }
a:visited { color: #757575; }

// _sass/minima/_base.scss override in assets/main.scss
$brand-color: #1c5fc0;
a { color: $brand-color; text-decoration: underline; text-underline-offset: 2px; }
a:visited { color: #595959; }
a:hover, a:focus-visible { text-decoration-thickness: 2px; }

Many Jekyll themes include a 'Skip to main content' link in the header partial but position it with position: absolute; left: -9999px and never restore it on :focus. Keyboard users press Tab as their first action expecting to jump past the navigation, and instead they tab through every navigation link before reaching content, which fails WCAG 2.4.1 Bypass Blocks because the bypass mechanism exists in markup but is not operable.

/* _sass/minima/_layout.scss */
.skip-link { position: absolute; left: -9999px; }
/* No focus rule */

/* _sass/minima/_layout.scss */
.skip-link { position: absolute; top: -40px; left: 0; padding: 8px 16px; background: #fff; color: #1c5fc0; z-index: 100; }
.skip-link:focus-visible { top: 0; outline: 3px solid #1c5fc0; }

The default Rouge stylesheet generated by rougify style base16.light uses a comment colour of #998 on a #f8f8f8 background that measures roughly 3.1:1, well below 4.5:1. Code is content in technical blogs, and the comments inside code blocks frequently carry the explanatory load (the code shows the syntax, the comment explains the why). Unreadable comments break the value proposition of a developer blog.

/* assets/syntax.css generated by rougify style base16.light */
.highlight .c, .highlight .c1 { color: #998; font-style: italic; }

/* assets/syntax.css */
.highlight .c, .highlight .c1 { color: #57606a; font-style: italic; }
.highlight .cm, .highlight .cs { color: #57606a; }

Jekyll's jekyll-paginate plugin renders previous and next links using bare '<' and '>' characters or Unicode arrow glyphs in many community themes. Screen readers announce 'less-than link' or 'right-pointing-triangle link' which is not a meaningful link name. WCAG 2.4.4 requires every link to have a purpose that can be determined from the link text alone or together with its programmatically determined context.

<!-- _includes/paginator.html -->
<a href='{{ paginator.previous_page_path }}'>&laquo;</a>
<a href='{{ paginator.next_page_path }}'>&raquo;</a>

<!-- _includes/paginator.html -->
<a href='{{ paginator.previous_page_path }}'><span aria-hidden='true'>&laquo;</span><span class='visually-hidden'>Previous page</span></a>
<a href='{{ paginator.next_page_path }}'><span aria-hidden='true'>&raquo;</span><span class='visually-hidden'>Next page</span></a>

Minima's home.html layout renders the site title in the header as h1 on every page, then loops the post archive as h2 entries. On the archive page itself this means the page has no top-level heading describing what the page is. The pattern fails 1.3.1 Info and Relationships because the heading hierarchy does not reflect the document structure.

<!-- _includes/header.html -->
<header>
  <h1 class='site-title'><a href='{{ "/" | relative_url }}'>{{ site.title }}</a></h1>
  <nav>...</nav>
</header>

<!-- _includes/header.html -->
<header>
  <p class='site-title'><a href='{{ "/" | relative_url }}'>{{ site.title }}</a></p>
  <nav>...</nav>
</header>
<!-- _layouts/home.html -->
<main id='main-content'>
  <h1>{{ page.title | default: "All Posts" }}</h1>
  ...
</main>

The Disqus comments include that ships with many Jekyll themes embeds an iframe with no title attribute. Screen readers fall back to announcing the iframe URL or just 'frame', which gives no indication that the region contains user comments. WCAG 4.1.2 Name, Role, Value requires every iframe to have an accessible name.

<!-- _includes/disqus_comments.html -->
<div id='disqus_thread'></div>
<script>...</script>

<!-- _includes/disqus_comments.html -->
<section aria-labelledby='comments-heading'>
  <h2 id='comments-heading'>Comments</h2>
  <div id='disqus_thread'></div>
  <script>...</script>
</section>

Most Jekyll themes include an RSS feed link in the footer or social-icons section rendered as an SVG or icon font without surrounding text. The anchor has no aria-label and the SVG has no title element, so screen readers announce only 'link' or read out the SVG file name.

<a href='/feed.xml'>
  <svg viewBox='0 0 16 16'>...</svg>
</a>

<a href='/feed.xml' aria-label='Subscribe via RSS'>
  <svg role='img' aria-hidden='true' viewBox='0 0 16 16'>...</svg>
</a>

When a Jekyll theme is composed of a default layout that wraps content in <main>, plus an include partial (such as a series-navigation include) that also contains a <main>, the rendered page contains two main elements. Screen readers and landmark navigation tools (NVDA's D key, VoiceOver's rotor) become confused because there should be exactly one main per page.