Summary
The issue at hand is that Pandoc is converting Markdown documents to HTML with WCAG-uncompliant links in code blocks. These links are empty anchors with href attributes, aria-hidden set to true, and tabindex set to -1, which are causing accessibility checkers to flag them as errors.
Root Cause
The root cause of this issue is that Pandoc is automatically generating these links in code blocks to provide a way to reference specific lines of code. The links are intended to be ignored by assistive technology, but they are still being flagged as errors by accessibility checkers. Some possible causes include:
- Pandoc’s default behavior of generating links in code blocks
- Lack of configuration options to suppress these links
- Inadequate handling of accessibility attributes in the generated HTML
Why This Happens in Real Systems
This issue occurs in real systems because:
- Pandoc is widely used for converting Markdown documents to HTML
- Accessibility checkers are becoming more stringent in enforcing WCAG guidelines
- Developers may not be aware of the links being generated in code blocks or how to suppress them
Real-World Impact
The real-world impact of this issue includes:
- Failed accessibility audits due to non-compliant links in code blocks
- Increased development time spent trying to resolve the issue
- Frustration and confusion among developers who are not aware of the cause of the issue
Example or Code
This is an example of Markdown code that may generate non-compliant links:print("Hello, World!")When converted to HTML using Pandoc, this code may generate links like <a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>.
How Senior Engineers Fix It
Senior engineers can fix this issue by:
- Using a Pandoc filter to remove the non-compliant links
- Configuring Pandoc to suppress the generation of links in code blocks
- Manually editing the generated HTML to remove the links
Why Juniors Miss It
Junior engineers may miss this issue because:
- Lack of experience with Pandoc and Markdown conversion
- Limited knowledge of accessibility guidelines and WCAG compliance
- Insufficient testing of the generated HTML for accessibility issues