Heading levels influencing revealjs behavior

[jhkuperus]

Yesterday I was tinkering with a series of slide decks that we convert to revealjs presentations using Asciidoctor-revealjs. We noticed some strange behaviour with include and source highlighting would not work at all. After some digging, I found the problem to be in how we structured headings in the document.

TL;DR: There seem to be assumptions about root-level headings (with just 1 =) that influence whether certain features are correctly turned on. The main question is: is this a bug or is it something that we should document as a caveat/troubleshooting thing?

I'll detail the exact cause and fix of the issue here.

Syntax Highlighting

Our document is structured with a single index.adoc, which includes a series of topics to combine into a single document. These documents looked like this:

index.adoc:

== Presentation Title
:doctype: book
:imagesdir: ../../../images/moduleX
:source-highlighter: highlight.js

include::01-intro.adoc[]

include::02-encapsulation.adoc[]

01-intro.adoc

= Intro

...

After some digging I found that the :source-highlighter: attribute was not picked up by Asciidoc-revealjs because the first heading was on the second level (== instead of =). By changing the heading to first level, the syntax highlighting suddenly worked.

I don't know enough of the Asciidoctor internal document format to decide if this is something that could be changed, or that it just is the way it is. That's why I'm looking for advice here.

Slide-breaks not working / Slides rendered inside a slide

The above series of documents shows another issue. Every included document started with a first-level heading (=):

01-intro.adoc

= Intro

...

This caused revealjs to generate a slide for the heading Intro and all subsequent headings in that file were rendered as slides (<section>) within the <section> for the Intro heading.

Again, the question is whether this is behavior that is inherent to Asciidocs internal document structure or not. If it is, then I would propose adding a little section in "Write your presentation" that would explain this situation and outline that the root document should only have first-level headings and any included documents should have deeper nested headings.

Dear maintainers, what say you? Are these "undocumented features" to be documented, or are they bugs?

[mojavelinux]

There seem to be assumptions about root-level headings (with just 1 =) that influence whether certain features are correctly turned on. The main question is: is this a bug or is it something that we should document as a caveat/troubleshooting thing?

This assumption isn't just specific to this converter. It is a fundamental part of the AsciiDoc language. The first level-0 section title (i.e., the doctitle) marks the beginning of the document header. Document-scoped attributes that impact the converter can only be set in the document header. See https://docs.asciidoctor.org/asciidoc/latest/document/header/

We've tried to be as clear as we can about this in the AsciiDoc docs. If you have a better way to phrase, please let us know.

[mojavelinux]

What you have shown here is incorrect:

== Presentation Title
:doctype: book
:imagesdir: ../../../images/moduleX
:source-highlighter: highlight.js

You are trying to make a level-1 heading act as the doctitle, and that's not how AsciiDoc works. It should be:

= Presentation Title
:imagesdir: ../../../images/moduleX
:source-highlighter: highlight.js

(Note that I removed doctype book because it's not relevant for reveal.js).

If you don't want to have a title slide, you would still need to define the document-scoped attributes before the first slide.

:source-highlighter: highlight.js

== First Slide

[,ruby]
----
puts "Hello, World!"
----

The doctitle (aka title slide) is not required. But the document header is.

However, to use this converter as designed, the structure should really be as described on this page: https://docs.asciidoctor.org/reveal.js-converter/latest/converter/features/#basic-presentation-with-speaker-notes. In other words:

= Title Slide
Author Name
:source-highlighter: highlight.js

== Slide One

* Foo
* Bar
* World

== Slide Two

A Great Story

To me, those instructions are pretty clear.

You need to take care that the heading levels follow this pattern. If your include has section titles that are not at the right level, you can adjust them using the leveloffset attribute on the include directive. See https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset

= Presentation Title
:imagesdir: ../../../images/moduleX
:source-highlighter: highlight.js

include::01-intro.adoc[leveloffset=+1]

However, it might be better just to fix the level in the include file so you don't need to rely on the leveloffset setting.

[jhkuperus]

Thanks for the clear demonstration. I figured out that the structure was the problem. The slides were the result of some collaborative work and that's why the headings were not uniform. It took me a lot of time to see that that was the actual problem. Reading the pages you are referencing definitely clears that up.

To be perfectly honest, AsciiDoc is relatively new to me and we jumped right into generating slides. Since the highlighting didn't work, I was looking for the source of my problem in de docs on the revealjs converter. I'm wondering how to prevent the next person from spending too much time on this.

Maybe the "Syntax Highlighting" section could have a paragraph "Troubleshooting":

If syntax highlighting does not appear to work, make sure the document follows the general structure of an AsciiDoc
document and that the :source-highlighter: attributes is defined in the Document Header (with URL to the header docs).

And perhaps include the example with a section title at the start instead of a document title.

Or maybe it is enough for the internet to index this issue? 😅

[mojavelinux]

I'm glad that information was helpful. It's very important for us to hear from users of all backgrounds so we understand how to write instructions that are universally understood.

Maybe the "Syntax Highlighting" section could have a paragraph "Troubleshooting":

I think we could go up a level. I think the documentation for the revealjs converter could emphasize the importance of the document header and link to the relevant page in the AsciiDoc docs. I'm thinking something like a link from https://docs.asciidoctor.org/reveal.js-converter/latest/converter/features/#basic-presentation-with-speaker-notes to https://docs.asciidoctor.org/reveal.js-converter/latest/converter/syntax/title/ then to https://docs.asciidoctor.org/asciidoc/latest/document/header/. There should be a clear statement that the document header is what configures the presentation. I think that would help users get off to the right start.

And perhaps include the example with a section title at the start instead of a document title.

I like that idea.

[jhkuperus]

Alright, I'll fork and work on a draft.