[FR] Skipping heading hierarchy

[r-leyshon]

WCAG2.1 expects the use of headings to follow as h1, h2, h3. Skipping from h1 to h3 would not be permitted. Likewise, headings should always contain content. These issues are present within the rmarkdown header, where the YAML title (h1) can be followed by author (not h2) etc. This is very confusing for screen reader users who rely on the heading hierarchy to efficiently navigate web pages to their desired content.

This gets a bit more complex as you consider table of contents, variable document YAML metadata (subtitle or no, author, date and so on). The approach in access_rmd::return_heading() is to return styled p tags for author / date etc. This is what we were advised was more 'semantically correct' during our accessibility audit.

If toc is specified, the most direct solution for us was to ensure toc_float was TRUE. The floating toc passed our accessibility checks, while the standard toc had additional accessibility issues (though I can't seem to find the reference in our docs, it would be best to check that within WAVE to help resolve).

WCAG guidance

1.3.1 Info and Relationships (Level A)

Semantic markup is used to designate headings (<h1>), regions/landmarks, lists (<ul>, <ol>, and <dl>), emphasized or special text (<strong>, <code>, <abbr>, <blockquote>, for example), etc. Semantic markup is used appropriately.

2.4.1 Bypass Blocks (Level A)

2.4.6 Headings and Labels (Level AA)

Page headings and labels for form and interactive controls are informative. Avoid duplicating heading (e.g., "More Details") or label text (e.g., "First Name") unless the structure provides adequate differentiation between them.