Enhancement: improved the accessibility of codeblocks #3178

McZenith · 2020-07-31T14:47:42Z

As highlighted at #3119 Changing code block from initial span to code HTML tag improves accessibility for screen readers most especially.

docusaurus-bot · 2020-07-31T14:52:40Z

Deploy preview for docusaurus-2 ready!

Built with commit 03c47eb

https://deploy-preview-3178--docusaurus-2.netlify.app

slorber

Unfortunately, this change seems to totally break Docusaurus 2 website code blocks.

https://deploy-preview-3178--docusaurus-2.netlify.app/build/docs/next/markdown-features#code-title

McZenith · 2020-07-31T18:56:59Z

Wow! I'm going to look into this thanks!

McZenith · 2020-08-01T14:48:25Z

It has been resolved! Since the goal is to ensure screen readers do not read codeblocks I have added aria-hidden="true" attribute to the span tag and It worked!

slorber · 2020-08-01T17:13:29Z

Thanks I'm not very familiar with accessibility, do you have an authority link that claims this aria attribute on code blocks is a good practice? Le sam. 1 août 2020 à 16:48, Isaiah Awotide <[email protected]> a écrit :

…

It has been resolved! Since the goal is to ensure screen readers do not read codeblocks I have added aria-hidden="true" attribute to the span tag and It worked! — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3178 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PREX54MFLZRMKVGNWTR6QTMNANCNFSM4PQMAHLQ> .

McZenith · 2020-08-01T20:27:20Z

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute

I feel removing codeblocks from accessibility tree could help solve the problem as written in the guide above.

I'm also relatively new to accessibility API but if you have a better way to go about it, I'd be glad to implement it.

Thank you.

slorber · 2020-08-03T10:24:13Z

I'm not either an accessibility expert.
Unfortunately not sure I want to merge such PR if we are unable to find an authoritative source that says it's a good practice.

If you know a dev website that care a lot about accessibility, maybe we can check how they handle the code blocks and ask them for feedback.

slorber · 2020-08-03T14:05:26Z

@McZenith it looks to me we should just use

{code}

, as it's something I see in many places including sites like W3 (https://www.w3.org/WAI/tutorials/forms/instructions/) etc...

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.tsx

slorber · 2020-08-03T14:07:02Z

packages/docusaurus-theme-bootstrap/src/theme/CodeBlock/index.js

@@ -21,9 +21,13 @@ export default ({children, className}) => {
      {({style, tokens, getLineProps, getTokenProps}) => (
        <pre className={className} style={{...style, padding: '20px'}}>


here we have pre, but we should add code too I think

Thank you @slorber, I will look into it and make necessary changes... I really appreciate your help and I just learnt something new...

McZenith · 2020-08-04T21:44:48Z

@slorber Thanks for your guide this far. I really enjoyed the ride... I know it's not easy dealing with a newcomer but you helped me out and here it is, done... Thank you...

slorber · 2020-08-05T14:10:04Z

np, happy to help you :)

slorber

Unfortunately I can't merge this yet.

You should use real CSS, not inline styles.

+, this is an accessibility only PR, and the design should not be modified.

Before:

After:

I'm only willing to merge this PR if you make it so that the design is exactly the same as it was before

slorber · 2020-08-05T14:11:09Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.tsx

+                        padding: '0px',
+                        whiteSpace: 'pre-wrap',
+                        wordBreak: 'break-word',
+                      }}>


We should use the css module styles instead of inline styles

Oh, okay! Copy that! Next commit in a jiffy. Thank you.

NikitaIT · 2020-08-07T15:11:56Z

I looked at the code, it doesn't look bad.
But as far as I know, any changes should be justified in tests. From the solutions that I saw: a11y (for the storybook) and axe, but if this is not in the project, then this issue should be considered separately. Unfortunately, I do not have sufficient expertise in writing accessibility tests, neither with the provided libraries nor without them.
I think it would be possible to bring in someone who is really well versed in this matter. If there is no such person, then the current solution is obviously better than the previous one.

NikitaIT · 2020-08-07T15:32:52Z

packages/docusaurus-theme-bootstrap/src/theme/CodeBlock/index.js

+          }}>
+          <code style={{...style, padding: '20px', display: 'inline-flex'}}>
+            {tokens.map((line, i) => (
+              <div


The only thing I don't like is that in the code div tag. It doesn't seem to be valid. Try it on:
https://validator.w3.org/nu/#textarea

<!DOCTYPE html > <html lang="en"> <head><title>d</title></head> <body> <pre> <code> <div><span>werwer</span> </div> <div><span>werwer</span> </div> </code> </pre> </body> </html>

Output:

Error: Element div not allowed as child of element code in this context. (Suppressing further errors from this subtree.) From line 9, column 15; to line 9, column 19 <div><span> Contexts in which element div may be used: Where flow content is expected. As a child of a dl element. Content model for element code: Phrasing content.

Phrasing content: https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2

Ohw okay, I will look into it and see what I can do. I initially didn't include it but I noticed the code highlights were not functioning properly. So I added it and it worked as expected.

NikitaIT · 2020-08-07T15:45:22Z

Also, I'm not sure if the text is clearly visible here. This does not apply to this pr. But it's worth checking out as accessibility issue.
https://deploy-preview-3178--docusaurus-2.netlify.app/build/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus

slorber

bootstrap theme has inline styles

slorber · 2020-08-07T20:00:23Z

packages/docusaurus-theme-bootstrap/src/theme/CodeBlock/index.js

+            whiteSpace: 'pre-wrap',
+            wordBreak: 'break-word',
+          }}>
+          <code style={{...style, padding: '20px', display: 'inline-flex'}}>


still has inline styles here

done! All solved!

NikitaIT · 2020-08-16T13:53:00Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.tsx

-                    </div>
+                    <pre className={styles.preTag}>
+                      <code className={styles.codeTag}>
+                        <div key={i} {...lineProps}>


this is still not valid html

And I think a comment is needed on why exactly pre>code>span is done here in the code, in both places, since this is not covered by tests, this is the only way to guarantee validity in the future.

thanks, I'm not an expert but why is this not valid?

@slorber #3178 (comment)

@slorber I would still recommend setting up tests to check accessibility and validity. Any mistakes can be critical for those who care.
In addition, it is often useful for correct indexing, the search on the site is of course important, but when the developer does not know something, he usually uses google to search, and internal search is the second step.
It may be worth asking the community for help in this matter. And to do it so that it is really seen.

how can we setup accessibility and validity tests? how do we ask for such help to the community for you?

I don't know much about these topics but any help is definitively welcome

slorber

Thanks, but still not good 🤪

These 2 pages are still different:

https://deploy-preview-3178--docusaurus-2.netlify.app/build/docs/next/markdown-features
https://v2.docusaurus.io/docs/next/markdown-features

This PR is about accessibility, not design, so the expected result is to have improved accessibility, yet keeping the EXACT same design. Here the new design is different, and looks worst to me.

slorber · 2020-10-19T16:14:13Z

Closing due to inactivity

Changed codeblock to <code /> for accessibiity purpose

9dbe822

McZenith requested review from lex111 and yangshun as code owners July 31, 2020 14:47

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jul 31, 2020

changed code backround-color to transparent

8fa7a06

slorber requested changes Jul 31, 2020

View reviewed changes

Added aria-hidden attribute to codeblock's span

fd0f842

slorber reviewed Aug 3, 2020

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.tsx Outdated Show resolved Hide resolved

slorber reviewed Aug 3, 2020

View reviewed changes

slorber marked this pull request as draft August 3, 2020 14:09

Added pre+code tags where necessary

1c68c6b

McZenith changed the title ~~Changed codeblock to <code /> in Docusaurus theme for accessibiity purpose~~ Enhancement: improved the accessibility of codeblocks Aug 4, 2020

slorber requested changes Aug 5, 2020

View reviewed changes

converts inline css to modules system

d3ba61c

McZenith marked this pull request as ready for review August 7, 2020 09:12

McZenith requested a review from slorber August 7, 2020 14:01

NikitaIT reviewed Aug 7, 2020

View reviewed changes

slorber requested changes Aug 7, 2020

View reviewed changes

removed inline styles from boostrap theme

03c47eb

McZenith requested a review from slorber August 15, 2020 02:17

NikitaIT reviewed Aug 16, 2020

View reviewed changes

slorber requested changes Aug 17, 2020

View reviewed changes

slorber closed this Oct 19, 2020

slorber mentioned this pull request Nov 9, 2020

Accessibility: CodeBlock theme-classic #3119

Closed

This was referenced May 28, 2022

[Snyk] Security upgrade sharp from 0.29.3 to 0.30.5 Qdigital/docusaurus#12

Open

[Snyk] Security upgrade sharp from 0.29.3 to 0.30.5 Qdigital/docusaurus#13

Open

NikolayS mentioned this pull request May 28, 2022

[Snyk] Security upgrade sharp from 0.25.4 to 0.30.5 NikolayS/docusaurus#40

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhancement: improved the accessibility of codeblocks #3178

Enhancement: improved the accessibility of codeblocks #3178

McZenith commented Jul 31, 2020

docusaurus-bot commented Jul 31, 2020 •

edited

Loading

slorber left a comment

McZenith commented Jul 31, 2020 •

edited

Loading

McZenith commented Aug 1, 2020

slorber commented Aug 1, 2020 via email

McZenith commented Aug 1, 2020

slorber commented Aug 3, 2020

slorber commented Aug 3, 2020

slorber Aug 3, 2020

McZenith Aug 3, 2020

McZenith commented Aug 4, 2020

slorber commented Aug 5, 2020

slorber left a comment

slorber Aug 5, 2020

McZenith Aug 5, 2020

McZenith Aug 7, 2020

NikitaIT commented Aug 7, 2020

NikitaIT Aug 7, 2020 •

edited

Loading

McZenith Aug 7, 2020

NikitaIT commented Aug 7, 2020

slorber left a comment

slorber Aug 7, 2020

McZenith Aug 15, 2020

NikitaIT Aug 16, 2020

NikitaIT Aug 16, 2020

slorber Aug 17, 2020

NikitaIT Aug 19, 2020

NikitaIT Aug 19, 2020 •

edited

Loading

slorber Aug 21, 2020

slorber left a comment

slorber commented Oct 19, 2020

		@@ -21,9 +21,13 @@ export default ({children, className}) => {
		{({style, tokens, getLineProps, getTokenProps}) => (
		<pre className={className} style={{...style, padding: '20px'}}>

Enhancement: improved the accessibility of codeblocks #3178

Enhancement: improved the accessibility of codeblocks #3178

Conversation

McZenith commented Jul 31, 2020

docusaurus-bot commented Jul 31, 2020 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

McZenith commented Jul 31, 2020 • edited Loading

McZenith commented Aug 1, 2020

slorber commented Aug 1, 2020 via email

McZenith commented Aug 1, 2020

slorber commented Aug 3, 2020

slorber commented Aug 3, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

McZenith commented Aug 4, 2020

slorber commented Aug 5, 2020

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NikitaIT commented Aug 7, 2020

NikitaIT Aug 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NikitaIT commented Aug 7, 2020

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NikitaIT Aug 19, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

slorber commented Oct 19, 2020

docusaurus-bot commented Jul 31, 2020 •

edited

Loading

McZenith commented Jul 31, 2020 •

edited

Loading

NikitaIT Aug 7, 2020 •

edited

Loading

NikitaIT Aug 19, 2020 •

edited

Loading