Quarto TOC/sidebar scanner reads R code comments as chapter headings

[friendly]

Description

Here's something I found really weird: The sidebar/TOC for the HTML version of my book just added a spurious Chapter, "1 Make" and all subsequent chapter numbers were bumped by one.

What happened

My index.qmd starts with a hidden R setup chunk to load common functions and other settings (via source("R/common.R")), followed later by:

# Preface {.unnumbered}

I was testing the use of the LaTeX smartdiagram package, and added a comment in the initial setup chunk. My index.qmd file then looked like this:

```{r include=FALSE}
source("R/common.R")
clean_pkgs()
# Make \usepackage{smartdiagram} available for the {tikz} book-parts diagram below.
knitr::opts_chunk$set(...)
```

...

# Preface {.unnumbered}

I had to root around deeply in the rendered weeds to see what had happened. The page itself rendered correctly: <h1 class="unnumbered">Preface</h1> appeared on the page. Only the sidebar/TOC entry was wrong.

The full "title" that Quarto extracted (visible in the data-render-id base64 value in
the sidebar HTML) was:

Make \usepackage{smartdiagram} available for the {tikz} book-parts diagram below.

-- which is the complete text of the R comment, without the leading #.

What I think happens

Quarto pre-scans each .qmd source file to extract chapter titles and build the sidebar before (or independently of) running knitr. The scanner appears to search simply for any lines beginning with # without properly skipping the contents of fenced code blocks. So:

# Make \usepackage{smartdiagram}...   ← found first, treated as chapter heading

was found before:

# Preface {.unnumbered}               ← correct heading, found later

Because the comment line carried no {.unnumbered} attribute, the chapter was also treated as numbered, displacing all later chapters.

Minimal reproduction

In a Quarto book, create index.qmd with no YAML frontmatter:

```{r include=FALSE}
# My comment here
```

# Preface {.unnumbered}

Content.

Render the book. The sidebar will show "My comment here" as a numbered chapter instead of "Preface" as unnumbered.

Fix

The simplest was just to remove that # Make \usepackage{smartdiagram}. Is there anything that could be done in a YML header to avoid this so Quarto never needs to scan the body for the title?

---
title: Preface
---

Questions for Quarto Dev

1. Is this a known limitation of Quarto's chapter-title scanner? I also note that the Outline button in source editor window is confused by ## comments in a ::: div block.
2. Shouldn't fenced code block content be excluded when scanning for headings?
3. Is adding title: to the YAML frontmatter of every chapter file a recommended defence, or is there a book-level setting that prevents this?

[mcanouil]

Important

Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See Good Alt Text, Bad Alt Text — Making Your Content Perceivable.

[mcanouil]

This is a somehow recurring issue with documents not having explicit title in a YAML block.

Also, it's reported:

• Books: Table of Content picks up code-block comments as chapter titles #3390

[friendly]

What is not clear is how this relates to an unnumbered chapter, like my Preface in index.qmd, where I have:

```{r include=FALSE}
source("R/common.R")
clean_pkgs()
```

# Preface {.unnumbered}

Will a yaml title block pick up the .unnumbered from the first H1? Perhaps it is better just to move that # Preface before the code chunk.

This behavior should be noted in the Quarto documentation somewhere

[mcanouil]

Well, the issue is the R comment promoted to title. That's a bug.
Are you suggesting to document bugs?

[friendly]

Tested an initial yml title block -- it made the Preface a numbered chapter, so I had to move that # Preface line before the code chunk.
That altered the look I wanted for the page, but at least it worked.

I'm glad this is considered a bug-- or a limitation of Quarto design. If it is not/can not be fixed, then it should be documented, e.g., with a warning or callout somewhere.

[cscheid]

@mcanouil is correctly pointing out that this is plainly a bug. The bad news is that this is an annoyingly hard bug to fix properly in the constraints of Quarto 1. Quarto 2, in contrast, has a much stronger representation for the document's content inside its processing pipeline and there we'll have a chance to fix this issue for real.

We recently merged a (minimal!) version of Quarto 2 websites on that repo. We're nowhere near ready to tell you to switch, but the steps it will take for us to recommend a switch are:

• implement PDF formats
• implement book projects
• write the processing stage in Quarto 2's new pipeline to create a canonical representation for a title
• use that canonical representation exclusively to determine chapter headings

That's "all" it takes :) and this is say that we're truly working on it. Sometimes it's really that it takes a year of development to fix what looks to be a small bug.

[friendly]

Thanks @cscheid for this analysis. Quarto has long been evolving, and what you're suggesting for Quarto 2 seems a big step forward.

What has always perplexed me was the "Who, What, Where, How" of the Quarto pipeline from .qmd --> {HTML, PDF}, with actors pandoc, bibtex and even lua thrown into the mix.