toc-location: left/right leads to a HTML document with a top-level h2 tag (a11y issue)

Open
#12,568 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
42/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
html, javascript

Research direction

Start by rendering the provided minimal .qmd example with toc-location: left and inspect the generated HTML in devtools, comparing it with the body TOC. Done means the floating TOC output no longer triggers the level-1-heading accessibility warning while preserving the left/right layout.

Written by the indexing model from the issue text.

Description

accessibility bug
Bug description

Hi folks,

Our internal digital team is keen that we align ourselves with web accessibility guidelines. They've pointed us towards 'siteimprove' to monitor accessibility of our Quarto documents, but I imagine other tools work similarly.

On any Quarto doc we create with floating TOC, we get the following flag:

Page does not start with a level 1 heading

A level 1 heading h1 tells the user what the page is about before they decide to navigate through the content.

Headings are used to structure content into a hierarchy of importance. If a page starts with a different heading level, it can cause confusion for the user.

This can be observed in the dev tools:

Image

Steps to reproduce
---
title: "TOC WAA"
author: "JD"
format: 
  html:
    toc: true
    toc-location: left
---

## Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

## Running Code

When you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this:
Actual behavior

Image

Expected behavior

(though naturally with the toc floating left - but proof the flag isn't there when the TOC is in the body)

Image

Your environment
  • IDE: RStudio 2024.12.0+467
  • Operating System: Windows 11
Quarto check output
Quarto 1.7.13
[>] Checking environment information...
      Quarto cache location: C:\Users\JD38\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.7.13
      Path: C:\Users\JD38\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (external install)
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\JD38\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2024

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files\Google\Chrome\Application\chrome.exe
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking R installation...........OK
      Version: 4.5.0
      Path: C:/Users/JD38/AppData/Local/Programs/R/R-4.5.0
      LibPaths:
        - C:/Users/JD38/AppData/Local/Programs/R/R-4.5.0/library
      knitr: 1.50
      rmarkdown: 2.29

[>] Checking Knitr engine render......OK
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/quarto-cli

All issues in quarto-dev/quarto-cli

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.