Marp

Heading divider

The heading divider directive tells Marp to automatically add a slide break before a heading of the specified level. This directive is particularly useful when converting an existing Markdown document to slides.

Heading dividers is similar to Pandoc's --slide-level option and Deckset 2's "Slide Dividers" option.

This feature is inherited from the Marpit framework.

Example

Let’s say you have a Markdown document like this:

  1. # Markdown document

  3. The article of Markdown

  5. ## What is Markdown?

  7. > Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
  8. >
  9. > _-- https://en.wikipedia.org/wiki/Markdown_

  11. ## History

  13. ### Origin

  15. Markdown has created by John Gruber in 2004.

  17. https://daringfireball.net/projects/markdown/

  19. ### Standardization

  21. CommonMark is a project for a standardization of Markdown launched in 2012.

Add the headingDivider global directive.

  1. <!-- headingDivider: 2 -->

Once you have specified the directive, Marp will automatically split the document into slides by starting a new slide whenever a section has a heading level of 2.

The headingDivider global directive accepts heading levels from 1 to 6. When the heading level is set as a number, Marp will split slides at headings that are at the specified level and at all parent levels. So, headingDivider: 2 will actually make new slides at headings of levels 1 and 2.

If a section has so much content that it overflows the slide, it might be better to split it by subsection. To do that, just change the base level for headingDivider to 3. Check out the difference from the previous example after the 3rd page:

Rulers to split pages still work normally even if enabled headingDivider.

Advanced

Auto split in parent heading levels is reasonable behavior in most cases, but sometimes you may require finer control of splitting levels. If you set the directive value to an array, you also instruct Marp to split at only the specified levels.

  1. <!-- headingDivider: [1, 3] -->

This setting will instruct Marp to split slides at heading levels 1 and 3.