Editoria11y Accessibility Checker
A user-friendly, automatic accessibility checker that runs on every page load to help content authors identify and fix accessibility issues.
editoria11y
Install
composer require 'drupal/editoria11y:^2.2'
Overview
Editoria11y (editorial accessibility ally) is a comprehensive accessibility checker designed specifically for content authors. Unlike traditional accessibility tools that require manual execution, Editoria11y runs automatically on every page load, similar to how modern spellcheck works.
The module focuses exclusively on straightforward issues that content authors can easily understand and fix, avoiding overwhelming them with technical code-level problems. It checks content in context, meaning it can see issues across Views, Layout Builder, Paragraphs, and other assembled page components that tools running inside CKEditor alone would miss.
Key capabilities include checking for image alt text issues, heading structure problems, link accessibility, table headers, embedded content accessibility, and text formatting issues. Results are synced to a site-wide dashboard for administrators to track issues across all content, and users can dismiss or mark issues as OK to manage false positives.
Features
- Automatic accessibility checking on every page load without requiring manual activation
- Real-time checking within CKEditor5 and Gutenberg edit boxes during content editing
- Visual toggle button in the bottom right corner showing issue count with expandable details panel
- Document outline visualizer showing heading hierarchy across the page
- Image alt text visualizer displaying all image alternative text attributes
- Site-wide dashboard tracking accessibility issues across all content with sorting and filtering
- CSV export of issues, pages summary, and dismissals for reporting
- Ability to mark issues as OK (globally) or hide them (per-user) to manage false positives
- Over 25 configurable accessibility tests covering images, links, headings, tables, embeds, and text
- Customizable selectors for content containers, ignored elements, and hidden content handlers
- Multi-language support with translatable interface strings via Drupal's translation system
- CKEditor5 integration to automatically add table headers to new tables
- JavaScript events for theme developers to reveal hidden content with errors (accordions, tabs)
- Web component shadow DOM scanning support for modern frontend frameworks
- Smart alerting modes: always show, show on first detection, or never auto-show
- Three visual themes: Sleek, Classic, and Dark
Use Cases
Content editor daily workflow
When a content editor creates or edits a page, Editoria11y automatically checks the content on save and preview. The toggle in the bottom right shows an issue count, and clicking it reveals details about each issue with explanations of why it matters and how to fix it. Editors can mark false positives as OK or hide manual check reminders they've already addressed.
Site-wide accessibility audit
Administrators can use the dashboard at /admin/reports/editoria11y to see all accessibility issues across the site. The dashboard shows top issues by type, pages with the most problems, and recent findings. CSV exports allow teams to create remediation plans and track progress over time.
Training content editors
The descriptive tooltips help educate content editors about accessibility as they work. Each issue includes an explanation of the problem and guidance on fixing it, turning accessibility checking into a learning opportunity.
Quality assurance before launch
Before launching new sections or redesigns, teams can review all flagged issues on affected pages. The ability to filter by content type and export reports makes it easy to ensure accessibility compliance before go-live.
Managing false positives
For legitimate content that triggers warnings (e.g., a blockquote that is intentionally short, or an image that is deliberately decorative), authorized users can mark issues as OK to suppress them for all users, while regular editors can hide alerts for themselves only.
Custom theme integration
Theme developers can use JavaScript events to integrate Editoria11y with accordion, tab, and carousel components. When users try to jump to an issue hidden inside such components, the theme JS can automatically reveal the content before Editoria11y focuses on it.
Tips
- Start with the default settings and adjust only as needed based on your theme and content structure
- Use 'main' or '#main-content' as the content root instead of 'body' for more focused scanning
- Add edit links to your theme's local tasks to enable convenient Edit/Layout links in tooltips
- Set up custom heading levels for CKEditor fields so body content starts at H2 level
- Use the 'On first detection' alerting mode for less intrusive notifications after initial corrections
- Export CSV reports monthly to track accessibility improvement trends over time
- Train content editors that 'Mark as OK' is for permanent exceptions while 'Hide' is for personal preference
- Add shadow DOM component selectors if your theme uses web components with shadow roots
- Use the ed11yHiddenHandler event in your theme JS to auto-open accordions containing errors
- The ed1ref query parameter triggers immediate panel opening, useful for linking from dashboards to specific pages
Technical Details
Admin Pages 5
/admin/config/content/editoria11y
Configure all aspects of the accessibility checker including which page elements to scan, tests to run, display options, and synchronization settings.
/admin/reports/editoria11y
Site-wide dashboard showing accessibility issues detected across all content. Displays top issues by type, pages with the most issues, recent issues, and recent dismissals. Provides CSV export functionality for all data.
/admin/reports/editoria11y/page
View all accessibility issues on a specific page with ability to navigate to the page or purge its results
/admin/reports/editoria11y/issue
View all pages containing a specific accessibility issue type
/admin/reports/editoria11y/dismissals
View and manage all dismissed accessibility issues across the site with filtering by dismissal type and staleness
Permissions 5
Hooks 3
hook_page_attachments
Attaches the Editoria11y library and configuration to pages for users with the view permission. Handles route detection, dismissal loading, and sync configuration.
hook_entity_predelete
Cleans up Editoria11y results and dismissals when content entities are deleted
hook_ckeditor5_plugin_info_alter
Modifies CKEditor5 table plugin to set default header rows/columns when tables are inserted
Troubleshooting 6
Clear Drupal cache, verify the user role has 'View Editoria11y checker' permission, check that no CSS is hiding the ed11y-element-panel container (z-index or overflow:hidden issues), look for JavaScript errors in the browser console, and ensure the 'Disable the scanner if...' setting doesn't match elements on every page.
Verify the 'Check content in these containers' setting includes your content area. Many sites need 'main' instead of 'body'. Check that the 'Skip over these elements' setting isn't excluding your content. Homepages and Views often insert content outside the main element.
Results only sync when viewing the canonical entity route (e.g., /node/123). Edit pages, previews, and revisions do not sync new issues. Verify sync is not disabled in configuration. Check the browser console for API errors.
Add CSS selectors for problematic elements (social feeds, third-party widgets) to the 'Skip over these elements' setting. Optionally add them to 'Remind editor that content in these embeds needs manual review' to flag them for manual checking instead.
If your theme uses overflow:hidden on containers, add those selectors to 'Elements with overflow hidden'. If the panel is covered by other elements, adjust z-index via CSS for #ed11y-panel or use 'Don't cover these other widgets' setting.
Long selector lists in 'Skip over these elements' can slow performance as they're checked against every element. Attribute selectors ([aria-hidden]) are much slower than class/ID selectors. Simplify and shorten the selector list.
Security Notes 6
- The 'Administer Editoria11y checker' permission is marked as restricted access and should only be granted to trusted administrators
- The 'Manage Editoria11y results' permission allows viewing all site content paths and titles in the dashboard
- API endpoints are protected by CSRF tokens and require authentication
- The module validates all API input to prevent injection attacks
- CSV exports sanitize strings to prevent CSV injection attacks
- Path validation prevents reporting on non-existent URLs