Docusaurus: Accessibility issues

[jaimeiniesta]

🐛 Bug Report

Related to https://github.com/facebook/docusaurus/issues/462

I've run an HTML and Accessibility check on 100 pages from https://v2.docusaurus.io/ - each page was checked using the latest version of W3C Validator for HTML issues, and Deque Axe-core 3.5.2 for Accessibility issues.

Here is the result report per page - the tabs allow to group the common issues on the site:

https://rocketvalidator.com/s/5f7336e6-2ab5-4bcf-bc42-c9627b32ebbe/p

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

Check the pages using the W3C HTML validator, axe-core for Accessibility or other checkers.

Expected behavior

Not finding incorrect HTML markup nor accessibility issues.

Actual Behavior

HTML and A11Y issues found.

Your Environment

n/a

Reproducible Demo

https://rocketvalidator.com/s/5f7336e6-2ab5-4bcf-bc42-c9627b32ebbe/p

[yangshun]

Thanks for the reports. Most of the violations are code-block/syntax highlighting related and unfortunately we can't really do anything about them. PRs welcome to fix the other issues.

[amimas]

I wonder if the code block or syntax highlight related issues need to be opened as separate issues elsewhere.

[jaimeiniesta]

I wonder if the code block or syntax highlight related issues need to be opened as separate issues elsewhere.

In case it helps, I finally chose another template for our documentation site - I run into similar issues for code blocks, fixing was easy: choosing a higher contrast theme, and making scrollable code blocks focusable by the keyboard (tabindex=0).

Also, I'll be happy to provide free accounts on our accessibility scanner for those interested in improving the accessibility of Docusaurus. Just ping me at [email protected] and I'll set yo up.

[yangshun]

@lex111 fixed a bunch of these issues. How many of them are left? @jaimeiniesta are you able to help us run the audit again?

[jaimeiniesta]

Sure, here's the current report:

https://rocketvalidator.com/s/e9a5f1cd-592a-4e7d-9cc8-2551b1506c0b/p

Great job! Almost all the HTML issues are gone now, and accessibility issues have been reduced to half, compared with the first report.

I'm glad to run the reports for you whenever you ask me but remember that I can provide free accounts for you - so you can work faster with the tool. Just ping me at [email protected] and I'll set you up.

[lex111]

I think I can close this issue, since the opening of this Issue we have done a lot of work to improve accessibility. There are also a11y issues, but a lot of them are related to the third party packages that we use. However, to prevent staled issues, I'll close this one now.

@jaimeiniesta thank you again for providing access to your awesome service Rocket Validator!

[jaimeiniesta]

Hey, thanks to you for improving the accessibility of Docusaurus!

I'll just leave a more up to date report, as this week axe-core released a new version with new rules.

https://rocketvalidator.com/s/f0ba95e1-c6a1-40c5-8e30-860e24a8fce6

If anyone wants a free account to work on fixing those issues just ping me.