rmarkdown
rmarkdown copied to clipboard
rstudio
Add a default lang attribute in HTML template ?
Our HTML template is missing a default lang attribute.
Pandoc verbosity informs about it:
[INFO] No value for 'lang' was specified in the metadata.
It is recommended that lang be specified for this format.
Pandoc doc: https://pandoc.org/MANUAL.html#language-variables
We have https://github.com/rstudio/rmarkdown/blob/c0b858496e2346acb82c28db85c0511a0e56dca1/inst/rmd/h/default.html#L3
I believe this is a requirement in Web Accessibility rule https://www.w3.org/WAI/standards-guidelines/act/rules/html-page-lang-b5c3f8/
We may need to come with a default, or at list warn about missing lang attribute. Also adding it in our template and documentation could help.
Related work on the shiny side: https://github.com/rstudio/shiny/pull/3087, https://github.com/rstudio/shiny/issues/2844 and https://github.com/rstudio/shiny/pull/3087
Default as been set to en empty string lang="", but it seems it should not be 🤔
https://www.w3.org/WAI/standards-guidelines/act/rules/html-page-lang-b5c3f8/#expectation
@jooyoungseo pinging you here for your expertise as I remember you worked on that for shiny if I am right.
Is defaulting to empty string (i.e lang="") something ok and better than not setting it on <html> tag ?
From this W3 guideline resource, I was unsure if it is better or not.
Choosing another default may be hard without side effect to user document.
The other improvement we could make is to be sure to include lang variable in all our Rmd examples to show this needs to be set and how user can change.
@yihui if you have a thought on this. I may ask around also in the other team to understand best practice.
lang attribute's value must be (carefully) determined by content language of the current block/document. The best practice is a manual setup by the content creator because there is no simple predictive solution. Leaving it blank (as default) won't cause serious accessibility violations. If we default it to "en", for example, it may cause some issues for non-English screen reader users because the markup would force their screen reader synthesizers to switch into a certain language (e.g., English in this case).
Lang attribute is one of the minimal accessibility requirements; however, its better to keep a gentle violation rather than to make a somewhat aggressive prediction which can lead to much worse accessibility barriers.
Thus, my suggestion is having lang: "" in our example templates, asking its content creators to manually fill out their values, and prompting warning against empty lang.
Thanks !
Regarding your suggestion, our example templates are written in English, so I would think they need to set lang: en, wouldn't they ? The user would then have to manually change this YAML field to the correct value as one need to do with other fields in the YAML.
and prompting warning against empty lang.
Maybe warning for this during render() is too strong. We could print a message if this is not set. However, this could also be something for the IDE as YAML validation / linting to show a warning icon in the source editor for missing lang attribute in Rmd files 🤔
I'll think more about this.
For anyone else that find these a priority, I've written a package that helps to avoid some of these 'gotchas' - accessrmd. 1.0.0 now on CRAN.
Thanks @r-leyshon ! Great package !
We really want to improve this in default format. Please do submit PR for some changes you found are needed. I'll use your work on examples to understand better what is missing. Happy to work with you on improving all this.
Regarding this issue with lang attribute, the remaining question is which value to use by default. Currently a user can set lang attribute in the YAML header, but I am not sure a lot of R Markdown user are doing it. Maybe tools like yours is the solution to increase awareness.
Thanks so much @cderv, the approach I've taken with accessrmd is to raise an error if valid lang attribute is not set when you create the doc. This has avoided making the assumption of lang="en".
There's a few issues that should be trivial to resolve that would make the docs much more accessible for those who use a screen reader. I would greatly appreciate working with you to help identify & resolve some of these issues within the rmarkdown codebase too.
the approach I've taken with accessrmd is to raise an error if valid lang attribute is not set when you create the doc
That is why I was thinking a warning. An error would be too much. But you're approach of an external function to help know what to do is a nice one. We could imagine a check function for that maybe in rmarkdown. Like the check functions in blogdown but for accessibility
I would greatly appreciate working with you to help identify & resolve some of these issues within the rmarkdown codebase too.
Great! Best way would be to open an issue per topic that needs fixing. We could then organize the work within a main issue linking this other as tasks list or a dedicated project board. I can setup this once the issues are created. Thanks!
Sounds like a plan. I'll collate the issues flagged by our accessibility audit & begin raising some issues. Just to flag some of the brilliant work that govdown have made in this regard too. They deactivate certain html tags like strikethrough & italic. It was a little too prescriptive for our purposes as the style applied was very specific to UK gov websites. If we're going to get a project going, seems like we could benefit from their input too. Govdown repo here.