heading-divider.md - marp

heading-divider.md

1	# Heading divider
2
3	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.
4
5	Heading dividers is similar to [Pandoc](https://pandoc.org/)'s [`--slide-level` option](https://pandoc.org/MANUAL.html#structuring-the-slide-show) and [Deckset 2](https://www.deckset.com/2/)'s "Slide Dividers" option.
6
7	> This feature is inherited from the [Marpit framework](https://marpit.marp.app/directives?id=heading-divider).
8
9	## Example
10
11	Let’s say you have a Markdown document like this:
12
13	```markdown
14	# Markdown document
15
16	The article of Markdown
17
18	## What is Markdown?
19
20	> Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
21	>
22	> _-- https://en.wikipedia.org/wiki/Markdown_
23
24	## History
25
26	### Origin
27
28	Markdown has created by John Gruber in 2004.
29
30	https://daringfireball.net/projects/markdown/
31
32	### Standardization
33
34	CommonMark is a project for a standardization of Markdown launched in 2012.
35	```
36
37	Add the [`headingDivider` global directive](/docs/guide/directives#global-directives).
38
39	```markdown
40	<!-- headingDivider: 2 -->
41	```
42
43	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.
44
45	```markdown:marp
46	<!-- headingDivider: 2 -->
47
48	# Markdown document
49
50	The article of Markdown
51
52	## What is Markdown?
53
54	> Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
55	>
56	> _-- https://en.wikipedia.org/wiki/Markdown_
57
58	## History
59
60	### Origin
61
62	Markdown was created by John Gruber in 2004.
63
64	https://daringfireball.net/projects/markdown/
65
66	### Standardization
67
68	CommonMark is a project for a standardization of Markdown launched in 2012.
69	```
70
71	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.
72
73	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:
74
75	```markdown:marp
76	<!-- headingDivider: 3 -->
77
78	# Markdown document
79
80	The article of Markdown
81
82	## What is Markdown?
83
84	> Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
85	>
86	> _-- https://en.wikipedia.org/wiki/Markdown_
87
88	## History
89
90	### Origin
91
92	Markdown was created by John Gruber in 2004.
93
94	https://daringfireball.net/projects/markdown/
95
96	### Standardization
97
98	CommonMark is a project for a standardization of Markdown launched in 2012.
99	```
100
101	> [Rulers to split pages](/docs/guide/how-to-write-slides#slides) still work normally even if enabled `headingDivider`.
102
103	## Advanced
104
105	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.
106
107	```markdown
108	<!-- headingDivider: [1, 3] -->
109	```
110
111	This setting will instruct Marp to split slides at heading levels 1 and 3.
112

112 lines MARKDOWN