Add an article about accessibility features

[cderv]

• Take write up from the next blog post https://github.com/rstudio/blog/pull/436 and make it an article for the website
• Add some links
• Plan is to add more content later in this post

Preview: https://deploy-preview-2108--rmarkdown-pkg.netlify.app/articles/articles/accessibility

Note: I used the visual editor to format the Rmd post.

Issue: I don't know why yet but the toc is off with pkgdown... 🤔

[yihui]

I feel this article should go to the R Markdown Cookbook---perhaps a section after this https://bookdown.org/yihui/rmarkdown-cookbook/html-accessibility.html (or add a subsection in it). I tend not to add more vignettes or articles into the package, but keep all documentation in the Definitive Guide or Cookbook. Same thing applies to bookdown and blogdown, since they all have companion books (unlike other packages). We can always link to a specific section in the books and promote it when necessary.

What do you think?

[cderv]

This is a good question. I asked myself the same thing because I was worried of duplication and several places for documentations. So I understand your comment.

I feel this article should go to the R Markdown Cookbook

The R Markdown Cookbook could certainly be a good place for this as there is already the chapters on accessibility.

I tend not to add more vignettes or articles into the package, but keep all documentation in the Definitive Guide or Cookbook. Same thing applies to bookdown and blogdown, since they all have companion books (unlike other packages).

However, I feel package websites are a great way to document some specific topics and could be easier for "discoverability" than in the middle of a book. Unfortunately, we don't have a lot of vignette and so documentation inside package is sparsed. Even if vignettes could be a constraint (bc CRAN), 'articles' feature from pkgdown is nice to avoid that and still share documentations on websites.

So we should really discuss that and decide where new topics should be added. Current other ideas are:

• Customization of HTML documents using CSS and SCSS/SASS
• Bootstrap 4 supports though bslib (somthing like flexdahsboard : https://flexdashboard-pkg.netlify.app/articles/theme.html#using-bootstrap-1)

All the other packages have useful documentations in their website - I feel we should have some too because it is expected by users and easily findable. Other packages don't have book though and we should also take advantage of that. Now that the books are promoted in front page, there is no way to miss it.

For this specific articles, I agree that a subsection in https://bookdown.org/yihui/rmarkdown-cookbook/html-accessibility.html maybe a better place for it. All the more because it shows how to use fig.alt which is in knitr really and this is not directly related to rmarkdown (except the fig_caption: FALSE)

I'll set this as a draft until we decide.

[yihui]

I need to go back to the pkgdown site discussion from a few months ago and think more about it. Basically, we have already got three resources for the documentation: the R help (Rd), the official website rmarkdown.rstudio.com, and the two 350-page books. I feel these were enough, and don't really want to invest too much into a fourth place for documentation (vignettes/articles). If there is anything new to add, I'd prefer adding to the existing resources. (BTW, the Lua filters vignette should perhaps go to Part IV of the Definitive Guide.)

[cderv]

Yes we need to think this through.

BTW, the Lua filters vignette should perhaps go to Part IV of the Definitive Guide.

Yes I think so too. We mention them in the R Markdown Cookbook already too now : https://bookdown.org/yihui/rmarkdown-cookbook/lua-filters.html
This was after the vignette creation - at first it was mainly as a technical documentation about Lua filters but it should now get part of the book as there is interesting feature tied to it.

I need to make an habit of updating the books as new feature goes in.

[apreshill]

Let's remove articles then? Distill does not have any either: https://pkgs.rstudio.com/distill/

[yihui]

That sounds good to me (after we move the Lua filters article into a book chapter or section).

[apreshill]

It may be worth transitioning those book websites over to bs4_book so that online search works better, if that is the sole source of documentation.