Pandoc: Adding text directly below a level 1 header in Markdown screws up the resulting Reveal.JS slideshow

[AGresvig]

I noticed that if you have regular text directly following a level one (single #) header in the markdown input of a revealjs-slideshow, it completely screws up the section nesting.

Using the "habits.txt" example from the README it is simple to reproduce, simply insert text below the first header, like so:

% Habits
% John Doe
% March 22, 2005

# In the morning
Error

## Getting up

- Turn off alarm
- Get out of bed
...

Then compile a slideshow using the standard pandoc -t revealjs -s habits.txt -o habits.html and look at the resulting HTML, where the nesting of sections is screwed up.

Perhaps it is John's intention that top-level headings only be used to precede sub-headings (sub-slides), but it should probably either be fixed or documented in the README/man page, as I spent a small hour scratching my head over what was wrong with my markup.

Hope I haven't misunderstood anything here.

Thanks for a fantastic utility anyways!

[jgm]

One fix would be for pandoc to simply omit everything
under a header of level < slide-level that is not a header,
in revealjs.

+++ AGresvig [Apr 04 13 13:39 ]:

I noticed that if you have regular text directly following a level one
(single #) header in the markdown input of a revealjs-slideshow, it
completely screws up the section nesting.

Using the "habits.txt" example from the README it is simple to
reproduce, simply insert text below the first header, like so:
% Habits
% John Doe
% March 22, 2005

In the morning

Error

Getting up

• Turn off alarm

• Get out of bed
  ...

  Then compile a slideshow using the standard pandoc -t revealjs -s
  habits.txt -o habits.html and look at the resulting HTML, where the
  nesting of sections is screwed up.

  Perhaps it is John's intention that top-level headings only be used to
  precede sub-headings (sub-slides), but it should probably either be
  fixed or documented in the README/man page, as I spent a small hour
  scratching my head over what was wrong with my markup.

  Hope I haven't misunderstood anything here.

  Thanks for a fantastic utility anyways!

  —
  Reply to this email directly or [1]view it on GitHub.
  [xJAuenYDiIoVt3LF3y6849XcNRFyy1gKxtgWkyyahqMiuE32Pe23hEXIRRX0bJrv.gif]

References

1. https://github.com/jgm/pandoc/issues/816

[jgm]

Another alternative would be to introduce a slide-level header with empty contents.
But I think the alternative above is more consistent with how slides are treated in other formats -- e.g. in beamer, non-header content above the slide level is just ignored in the slides.

[AGresvig]

I agree - if the content was simply omitted I would have known that I wasn't complying with the recommended structure. The way it is now I have no way of knowing what it is that is causing trouble. If the trouble-causing text/element was removed in the output I'd know I had put it where it didn't belong.
That and a note in the man-page would do it I think.

[jgm]

Now that I look more closely at your report, I don't see any problem here. Pandoc's behavior here is exactly as documented. Quoth the README:

By default, the _slide level_ is the highest header level in the hierarchy that is followed immediately by content, and not another header, somewhere in the document.

In your example, this is level 1. So level 1 headers start slides, and level 2+ headers are treated as subheadings in slides. It works exactly the same way for slidy, beamer, s5, and the other slide formats pandoc supports.

Note: If you want slides to be triggered by level 2 headers in your example, you can override the default by using --slide-level=2 (as the README also notes).

Since I don't see anything amiss here, I'll close this bug report. But comment if you think I've missed something.

[certainlyakey]

So the situation is that we should choose now - we want the slides in our presentation that contain text or we want nested slides. There's really no way to combine these two features?

Using --slide-level=2 with various values and appropriate changes in markdown documents does not help, because text continues to disappear even though nested slides start to behave themselves.

[jgm]

I'm not sure what it is that you can't do with the present system.
Just make sure that all the text you want to appear on a slide
appears at slide level or below.

All headers above slide level are used only for hierarchical
organization.

[certainlyakey]

I think I may have a problem with understanding the concept of slide levels. How should we understand "above" slide level, does slide level equal 2 per default?

Here's a presentation which has the following markup:

#Heading n1

Paragraph text of section 1

#Heading n2

##Subheading n1

Paragraph text of subsection 1.1

##Subheading n2

Paragraph text of subsection 1.2

If I remove paragraph text of section 1, the section n2 gets subsections as nested slides. If I readd it, nested slides disappear and the content of the section becomes the content of one slide.

How should I rework the markup so we could retain both the contents of the section 1 and still have nested slides?

[jgm]

+++ certainlyakey [Oct 10 13 14:32 ]:

I think I may have a problem with understanding the concept of slide
levels. How should we understand "above" slide level, does slide level
equal 2 per default?

Unless you set slide level explicitly with the command-line option,
slide level is the highest header level that has text directly
under it (and not just other headers which might have text under them).

Here's a presentation which has the following markup:

Heading n1

Paragraph text of section 1

Heading n2

Subheading n1

Paragraph text of subsection 1.1

Subheading n2

Paragraph text of subsection 1.2

If I remove paragraph text of section 1, the section n2 gets
subsections as nested slides. If I readd it, nested slides disappear
and the content of the section becomes the content of one slide.

How should I rework the markup so we could retain both the contents of
the section 1 and still have nested slides?

Just put the text under a level-2 header, which if you like can have
the same text as the level-1 header (or you can use an empty one).

# Heading n1

## Heading n1

Paragraph text of section 1

# Heading n2

## Subheading n1

Paragraph text of subsection 1.1

## Subheading n2

Paragraph text of subsection 1.2

[certainlyakey]

OK, thanks for indicating the right way. I guess it's ok if we just duplicate the headings.

[ijlyttle]

Hi,

Sorry if I am rehashing an old conversation without bringing anything new to the discussion.

I would like to consider the use case where, within a reveal.js slideshow, the primary content is at the top level, allowing the presenter to proceed horizontally through the presentation. If there is a need to go into greater detail, the vertical dimension is available.

This seems to be the case in the reveal.js demonstration.

Within the framework of this issue discussion, one possible implementation would be to suppress the creation of a slide if there is no content.

Possible example, using --slide-level=2:

#
## Slide 1

Paragraph text for slide 1

#
## Slide 2

Paragraph text for slide 2

## Slide 2.1 (detail)

Paragraph text for slide 2.1

## Slide 2.2 (detail)

Paragraph text of slide 2.2

Could the suppression of the section slide be considered if the only thing separating the # from the ## is a newline?

The presentation could then render as:

Slide 1 -- Slide 2 ...
              |
           Slide 2.1 (detail)
              |
           Slide 2.2 (detail)   

I know it is important to keep the pan in pandoc, and I would understand if this is thought to be a bad idea for being too specific to a particular format, or, worse, if it would break other implementations.

Thanks,

Ian

[kenficara]

I don't know why this is so hard to explain, but the way Pandoc works obviates the entire point of a two-dimensional presentation. I'm working on one now that needs to have a 15-minute version and a 45-minute version. I would like the 15-minute version to consist of my level one slides, so that I could navigate through it horizontally, hitting the top-level points only. If questions come up about a particular point, I could navigate down to slides which have detailed examples of the points made on the first-level slide. For the full presentation I would navigate down through each subsection. This is pretty much the _point_ of a two-dimensional slide show.

The way Pandoc works, the top level slides are just headings, and the two-dimensional slideshow degrades to slides where the heading shows up first, followed by the content.

[jgm]

That was a good explanation indeed!

Ken Ficara [e-mail] writes:

I don't know why this is so hard to explain, but the way Pandoc works obviates the entire point of a two-dimensional presentation. I'm working on one now that needs to have a 15-minute version and a 45-minute version. I would like the 15-minute version to consist of my level one slides, so that I could navigate through it horizontally, hitting the top-level points only. If questions come up about a particular point, I could navigate down to slides which have detailed examples of the points made on the first-level slide. For the full presentation I would navigate down through each subsection. This is pretty much the _point_ of a two-dimensional slide show.

The way Pandoc works, the top level slides are just headings, and the two-dimensional slideshow degrades to slides where the heading shows up first, followed by the content.

[lafrech]

This was fixed in pandoc 2.7.

Related discussion : https://groups.google.com/forum/#!topic/pandoc-discuss/joqekZQRpq8