yaml titles vs first-level headers in quarto pdf books

[d-morrison]

Description

I'm building a quarto book (https://github.com/d-morrison/rme, https://d-morrison.github.io/rme/), and I'm having trouble with the header numbering in the pdf version (https://d-morrison.github.io/rme/Regression-Models-for-Epidemiology.pdf).

Currently, I've defined each chapter's title in the yaml header for the corresponding .qmd file, and I've used level-one headers (#) to define sections within the chapter. This works fine for the html version of the book (https://d-morrison.github.io/rme/) as long as I set shift-heading-level-by: 1 in the project-level .yml file (https://github.com/d-morrison/rme/blob/main/_quarto-book.yml).

However, the pdf version is not working correctly: it treats the chapter yaml title as a level-one header, and whether I set shift-heading-level-by: 1 or shift-heading-level-by: 0, I still get the chapter title and the level-one-headers treated as equivalent.

Am I configuring the pdf settings incorrectly, or is this a bug?

Thanks,
Ezra

[mcanouil]

FYI, I am going to look into this later this week (if someone else does not in the meantime).

[cderv]

Currently, I've defined each chapter's title in the yaml header for the corresponding .qmd file, and I've used level-one headers (#) to define sections within the chapter.

In our doc, we explain that title for chapters can be either level 1 heading using # or defined using title: YAML field. So it is highly possible that we treat both the same way, and that shift-heading-level-by applies on it. Though I understand that it works somehow for HTML and not for PDF.

So I am curious of why doing that, before we can see how shift-heading-level-by play with books. Why not use ## and ### and keep # for title ?

[d-morrison]

Thanks for looking into it! I think I could use ## and ### as you suggest instead of shift-heading-level-by; if I were starting from scratch I would probably just do that, but given how much I've already written, it's a bit tedious to demote all the existing sections by hand. I guess I could use a regex find-replace all, but just a standard find-replace of # with ## would turn ## into #### instead of ###. Using # for chapter titles also means typing an extra character for each heading going forward, which of course is no big deal, just slightly annoying and less minimalist.

[cscheid]

but just a standard find-replace of # with ##

If your text editor supports searching by regexp, ^# will only catch # starting at the beginning of the line. I've found that to be a useful trick in the past.

[mcanouil]

@d-morrison Did you manage to get the desired results?

[d-morrison]

Apologies for the very delayed reply! Switching chapter titles to first-level headers worked for the pdf book. However, I'm also using each chapter as a revealjs slide deck (using quarto profiles), and that doesn't work well with the chapter/deck title being a first-level header; even with slide-level: 3 in the yaml header, ## aren't being treated as sections. I built a reprex here: https://github.com/d-morrison/quarto.test.book

with chapter titles in the yaml header (branch intro-slides-work)

• Here's the outline view of intro.html with chapter titles in the yaml header, compiled with quarto render --profile=revealjs with slide-level: 2 in _quarto-book.yml (this is as expected):

• But here's the TOC for the pdf book, with chapter titles in the yaml header, compiled with quarto render --profile=book and shift-heading-level-by: 0 (this is not as expected: sections are being promoted to chapters):

• if we set shift-heading-level-by: 1 (branch intro-slides-work-pdf-shift-heading-1), it's still broken (this is not as expected: chapter titles are being demoted to sections):

with chapter titles as first-level headers (branch intro-slides-dont-work):

• Here's the outline view of intro.html with chapter titles as first-level headers, compiled with quarto render --profile=revealjs with slide-level: 3 in _quarto-book.yml (not as expected; compare with version above):

• here's the TOC for the pdf book, with chapter titles as first-level headers, compiled with quarto render --profile=book (this is as expected):

[mcanouil]

Level 1 header is equivalent to title so it's exactly as expected.

Starts your section from a level 2, and use shift-heading-level-by: -1 for revealjs.

PS: when sharing an example repository, please keep it simple: no need for code cells or any computations and no need for 10+ unrelated options, which only makes it harder to focus on what matters.

[d-morrison]

Thanks! That worked. Apologies for the messy reprex!

[d-morrison]

One more minor issue/question; some of my book chapters have sub-titles defined in their yaml headers; for example:

---
title: "Models for Count Outcomes"
subtitle: "Poisson regression and variations"
---

Is there any way to keep those sub-titles using the title = # format?

[mcanouil]

I don't follow, keep where?

The "title = first heading" thing is only in this context as a document needs to have a title.
There is no alternative to subtitle. only first heading is promoted to title when there is none. There are no other promotion for headings.

A not working workaround since metadata are gathered too early.

Note that you can use conditional contents to make particular conditioning: https://quarto.org/docs/authoring/conditional.html

::: {.content-visible when-format="html" when-format="pdf" unless-format="revealjs"}

---
title: "Models for Count Outcomes"
subtitle: "Poisson regression and variations"
---

:::

::: {.content-visible when-format="revealjs"}

# Models for Count Outcomes

:::

[cscheid]

@mcanouil No, that doesn't work; metadata is lifted out of content before conditional content is evaluated. This is a long-standing bug in Quarto+Pandoc that we can't easily fix.