make jekyll search and feedback accessible to all
Why Accessibility and Inclusion Matter for Static Sites
When building a knowledge base with Jekyll, it's easy to focus on content and design while overlooking users with disabilities or diverse technology needs. Accessibility (a11y) ensures that all users — including those with visual impairments, motor disabilities, or cognitive challenges — can navigate, search, and give feedback effectively.
Key Accessibility Challenges in Static Jekyll Setups
Common accessibility issues in Jekyll-based knowledge bases include:
- Search interfaces that aren’t keyboard navigable
- Feedback buttons without screen reader labels
- Poor color contrast in custom themes
- No ARIA (Accessible Rich Internet Applications) support
Step 1: Make Search Inputs Keyboard-Friendly
Your client-side search should be operable without a mouse. Make sure search inputs are properly labeled and focusable:
<label for="search-box">Search Articles</label>
<input type="text" id="search-box" aria-label="Search Articles" />
Ensure results can be navigated using the arrow keys and selected using the Enter key. Use tabindex="0" where needed.
Step 2: Use ARIA Roles for Dynamic Elements
ARIA roles help screen readers understand the context of dynamically loaded content like search results:
<div id="search-results" role="region" aria-live="polite"></div>
This tells assistive technology to announce updates in this region automatically.
Step 3: Ensure All Interactive Elements Are Focusable
Use proper <button> elements instead of <div> or <span> for clicks:
<button onclick="submitFeedback(true)" aria-label="Mark article as helpful">đ</button>
<button onclick="submitFeedback(false)" aria-label="Mark article as not helpful">đ</button>
Screen readers will skip non-interactive elements unless they are properly marked up.
Step 4: Improve Color Contrast and Font Readability
Follow WCAG guidelines for contrast ratios (minimum 4.5:1 for normal text). Tools like Lighthouse or the WAVE extension can help.
Also, avoid very small fonts or thin styles. Stick with readable font sizes and avoid decorative typefaces for body content.
Step 5: Provide Feedback via Visual and Auditory Cues
After a user submits feedback, don’t just hide the button — provide a clear message. Use both text and ARIA alerts:
document.querySelector('.feedback-box').innerHTML =
'<p role="alert">Thank you for your feedback!</p>';
This ensures users who rely on screen readers are also notified.
Step 6: Use Semantic HTML for Structure
Always use proper tags like <section>, <article>, <nav>, and <main> to indicate layout regions. Avoid div-heavy layouts that lack meaning.
<main>
<section aria-labelledby="main-heading">
<h2 id="main-heading">Knowledge Base Articles</h2>
...
</section>
</main>
Step 7: Include a Skip to Content Link
Keyboard users appreciate the ability to skip navbars or headers. Add a hidden but focusable link:
<a href="#main" class="skip-link">Skip to content</a>
Style it with CSS to appear only when focused:
.skip-link {
position: absolute;
top: -40px;
left: 0;
background: #000;
color: #fff;
padding: 8px;
}
.skip-link:focus {
top: 0;
}
Step 8: Localize for Multilingual Support
Support non-English speakers by:
- Setting
lang="en"or other locale on<html> - Making your feedback and search UI translatable using Liquid variables
- Avoiding hardcoded text in JS — store labels in a JSON or data file
Step 9: Test with Assistive Technologies
Use VoiceOver (Mac), NVDA (Windows), or ChromeVox (Chrome extension) to test your site. Also try navigating entirely with a keyboard — no mouse.
Step 10: Add an Accessibility Statement
Being transparent helps build trust. Create an accessibility.md page outlining your efforts and contact options for issues:
We’re committed to ensuring our knowledge base is accessible. If you encounter any issues, please open an issue on our GitHub repo or contact us at [email protected].
Conclusion
Improving accessibility and inclusion doesn’t require a complex backend or redesign — just attention to HTML, keyboard interaction, and ARIA roles. When you make your Jekyll-based knowledge base more inclusive, you expand your reach and serve all users better, regardless of ability.
In the next article, we’ll explore how to build a documentation changelog using Jekyll collections so users can track what’s new and what’s changed over time.
