Overloading markdown # and ## as section and slide breaks

[DOSull]

This is a very general question about possible future directions, not something likely to get fixed overnight.

In short, I find the decision to overload markdown heading levels 1 and 2 by causing them to introduce section and slide breaks in revealjs decks a very strange one! In a standard reveal html page you can do this

<section data-markdown>
  # This will be H1
  ## and this will be H2
</section>

The slideshow structure is based on HTML <section> tag (nested to create vertical sections).

Overloading markdown # and ## as has been done in quarto forces the use of raw HTML <h1> and <h2> tags to get those formats in slides.

It seems an odd decision to me. Is there any chance of it being changed or of a setting being made available that would allow access to heading levels 1 and 2 formats without recourse to raw HTML? I've been using reveal for several years and this is an obstacle to me transitioning to generating my slides using quarto!

[cderv]

Thank you for your feedback.

I'll try to answer with a bit of Context first.

In a standard reveal html page you can do this (...) <section data-markdown>

The format revealjs used in Quarto leverages the Pandoc support for revealjs, and it does not use data-markdown feature. All the markdown is converted to HTML by Pandoc to generate a HTML version for revealjs, without any Markdown in the HTML. They do not use revealjs Markdown parsing feature.

Just wanted to share this as this decision should be discussed upstream in Pandoc rather than in Quarto probably.

Overloading markdown # and ## as has been done in quarto forces the use of raw HTML <h1> and <h2> tags to get those formats in slides.

This behavior comes directly from Pandoc. You can find documentation about this in their Manual: https://pandoc.org/MANUAL.html#structuring-the-slide-show It is not directly a Quarto decision.

It can be controlled using the --slide-level configuration. This is what determines which headers is used to create slides. Ultimately, setting --slide-level 0 will means "Do not create slides with Markdown header syntax". Only --- will create some slides.

This is again Pandoc behavior. Example using only Pandoc :

> quarto pandoc --slide-level 0 --to revealjs
# Slide 1
## Header 2

---

# Slide 2
## Header 2
^Z
<section class="slide level0">

<h1 id="slide-1">Slide 1</h1>
<h2 id="header-2">Header 2</h2>
</section>
<section class="slide level0">

<h1 id="slide-2">Slide 2</h1>
<h2 id="header-2-1">Header 2</h2>
</section>

This approach has some limitation though, because --- syntax does not support slides attributes, as they rely on the Pandoc's feature for attributes on headers. Still not possible on other elements: jgm/pandoc#684

Another approach would be to only use # to create headers for example, this would lead to <h1> headers on all slides, and then other headers would be in-slide. This can be done with --slide-level 1

> quarto pandoc --slide-level 1 --to revealjs
# Slide 1
## Slide 1.1
# Slide 2
## Slide 2.1
^Z
<section id="slide-1" class="slide level1">
<h1>Slide 1</h1>
<h2 id="slide-1.1">Slide 1.1</h2>
</section>
<section id="slide-2" class="slide level1">
<h1>Slide 2</h1>
<h2 id="slide-2.1">Slide 2.1</h2>
</section>

Though here, no vertical slide can be created I believe. This is another limitation on Pandoc design for revealjs.

I shared above context about how pandoc behaves. This can be reproduced using Quarto configuration syntax

format: 
  revealjs:
    slide-level: 0

Hopefully this helps understand the behavior and possible configuration. Does setting slide-level helps you ?

I am not sure Pandoc will allow all the flexibility you have from using Revealjs directly with its Markdown feature. Probably some improvement could be made upstream in Pandoc, or in Quarto otherwise to help using Revealjs better. Please, do share you ideas!

[DOSull]

Thank you for the comprehensive answer. I'll have to think about it for a bit to understand if it helps or not. And I certainly need to take a look at the decisions made in pandoc to really understand what's going on.