Chapter numbering not affected by shift-heading-level-by

[retodomax]

Description

Problem: The shift-heading-level-by setting is ignored if the project is rendered by GitHub Action

Reprex:

1. RStudio > New Project > Quarto Book (with git and renv) => creates template
2. Make new GitHub repo and push everything to the repo
3. Set up Github action as described here
   • Set sourch branch to gh-pages
   • Ignore output (add output to .gitignore)
   • Add .github/workflows/publish.yml with example from here
4. Change _quarto.yml to include

format:
  html:
    shift-heading-level-by: 1

5. Add a few subchapters into the intro.qmd chapter

# Introduction

Test

# This is another Chapter

Hello

# And this also

World

According to the documentation, I am expecting the first chapter at the beginning of the document to replace the metadata title and the other titles to be shifted by 1 (i.e. level 2 instead of level 1)

6. Try out different options to render
   • quarto render => shift-heading-level-by is respected
   • quarto publish gh-pages => shift-heading-level-by is respected
   • Push change and rendering happens with GitHub Action => shift-heading-level-by is not respected

Is this behavior expected? Thanks for your help!

[cderv]

1. quarto render => shift-heading-level-by is respected
2. quarto publish gh-pages => shift-heading-level-by is respected
3. Push change and rendering happens with GitHub Action => shift-heading-level-by is not respected

If 1 and 2 are working, option 3 should be working too. Unless you are not using the same Quarto version in your workflow.

Can you share a repo which reproduce this ? The github action do exactly a quarto publish gh-pages, so it should work the same.

[cderv]

What is the purpose of using shift-heading-level-by in Quarto book exactly ? I am not sure why it was working ok in 1.4. I can reproduce not working in 1.5, but in general I would not expect this option to be used with Book without problem.

This is why I am interested to understand the use case before looking into it more.

Book structure is quite special, with expected content as documented and level 1 header are meaningful to set section.

[cderv]

As it triggered a vague memory of a Pandoc change, I dug into history.

Pandoc 3.1.2 change something about Numbering section. And latest Pandoc 1.4 uses 3.1.1, so it could be why you could see change Quarto 1.5.

Though from your example and your screenshot, the shift correctly happens because it is <h2> used.

So this is only the numbering that gets somehow wrong. There is something going on and probably Quarto does not well support shift-heading-level-by options

Knowing why you need it will help us how to tackle this.

[retodomax]

Thanks @cderv

Use case:
I paste many small articles together into a book. The headers in each article are h1. Now in the book they are a sub-chapter of a broader topic (broader topic = h1) and all former h1 headers should be come h2.
I could also manually change all # to ##, and all ## to ### and so on, but so far I used successfully the shift-heading-level-by option.

Maybe this was not the originally intended use case (described in pandoc manual).

[cderv]

I could also manually change all # to ##, and all ## to ### and so on, but so far I used successfully the shift-heading-level-by option.

For now, I think this would be safer to do, but I understand why you would need the shift-heading-level-by.

To investigate further, I think we need to test if Pandoc itself is handling this with numbering the way you expect.

AFAIK we don't do anything special for shift-heading-level-by and books, and maybe we should.

You should try a single document also (not a book and see if this work) - it may not

[retodomax]

You are right, the same behavior if it's a single document (i.e. not a book).
If shift-heading-level-by: 1 then h2 headers are numbered like h1 headers (which is good default behaviour).

---
title: Publication
number-sections: true
number-depth: 2
format:
  html:
    toc: true
    shift-heading-level-by: 1 # h1 titels become h2 titels
---

# Introduction

This is the introduction

# Methods

## in-vitro

Describe

## in-vivo

Experiment

# Results

Results of the experiment

However, in a book, this behavior will create a problem. The title (h1) of each section is numbered and if h2 is now numbered as if they were h1 then we have the same "number-level" for h1 and h2. The same number will even be allocated to different chapters (e.g. screenshot below, "2" is assigned to a h2 sub-chapter but also to a h1 chapter)

I think this was not the case in previous versions of Quarto.