| 1 | # Directives |
| 2 | |
| 3 | ### This is a stub page! |
| 4 | |
| 5 | Marp has an extended syntax called **"Directives"** to control theme, page number, header, footer, and other slide elements. |
| 6 | |
| 7 | > The syntax of directives is inherited from [Marpit framework](https://marpit.marp.app/directives). Please note that different directives are used by each Marp tool. |
| 8 | |
| 9 | ## Usage |
| 10 | |
| 11 | Marp parses directives as [YAML](https://yaml.org/). |
| 12 | |
| 13 | ### HTML comment |
| 14 | |
| 15 | ```markdown |
| 16 | <!-- |
| 17 | theme: default |
| 18 | paginate: true |
| 19 | --> |
| 20 | ``` |
| 21 | |
| 22 | ### Front matter |
| 23 | |
| 24 | Like many tools (e.g. [Jekyll site generator](https://jekyllrb.com/docs/front-matter/)), Marp uses **YAML front matter**. Directives can be defined in front matter. |
| 25 | |
| 26 | YAML front matter must be at the beginning of a Markdown document and enclosed by dashed rulers. |
| 27 | |
| 28 | ```markdown |
| 29 | --- |
| 30 | theme: default |
| 31 | paginate: true |
| 32 | --- |
| 33 | ``` |
| 34 | |
| 35 | Note that the dashed ruler is also used to indicate where Marp should [ split slides](/docs/guide/how-to-write-slides#slides). Marp uses the first two dashed rulers to indicate YAML front matter. Subsequent dashed rulers indicate slide breaks. |
| 36 | |
| 37 | > TIP: Defining directives in the front matter is equivalent to setting the directives using an HTML comment on the first page. Suppose your favorite Markdown editor does not support the front matter syntax. In that case, you can safely define the directive in an HTML comment instead. |
| 38 | |
| 39 | ## Type of directives |
| 40 | |
| 41 | There are two types of Marp directives: |
| 42 | |
| 43 | - **[Global directives](#global-directives)** - Controlling settings for the all slides (e.g. `theme`, `size`) |
| 44 | - **[Local directives](#local-directives)** - Controlling setting values for one slide (e.g. `paginate`, `header`, `footer`) |
| 45 | |
| 46 | You can define both directives in the same way. You can mix definitions too. The only difference is that some settings apply to all slides, and some apply to only one slide. |
| 47 | |
| 48 | ### Global directives |
| 49 | |
| 50 | **Global directives** are settings for the entire slide deck. |
| 51 | |
| 52 | | Name | Description | |
| 53 | | ---------------- | ------------------------------------------------------------------------------ | |
| 54 | | `theme` | [Set a theme name for the slide deck ▶️](/docs/guide/theme) | |
| 55 | | `style` | Specify CSS for tweaking theme | |
| 56 | | `headingDivider` | [Specify heading divider option ▶️](/docs/guide/heading-divider) | |
| 57 | | `size` | Choose the slide size preset provided by theme | |
| 58 | | `math` | [Choose a library to render math typesetting ▶️](/docs/guide/math-typesetting) | |
| 59 | | `title` | Set a title of the slide deck | |
| 60 | | `author` | Set an author of the slide deck | |
| 61 | | `description` | Set a description of the slide deck | |
| 62 | | `keywords` | Set comma-separated keywords for the slide deck | |
| 63 | | `url` | Set canonical URL for the slide deck (for HTML export) | |
| 64 | | `image` | Set Open Graph image URL (for HTML export) | |
| 65 | | `marp` | Set whether or not enable Marp feature in VS Code | |
| 66 | |
| 67 | If you set the same global directive multiple times, Marp will use the last defined value. |
| 68 | |
| 69 | ### Local directives |
| 70 | |
| 71 | **Local directives** are settings for a specific slide. |
| 72 | |
| 73 | | Name | Description | |
| 74 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | |
| 75 | | `paginate` | [Show page number on the slide if set to `true` ▶️](#page-number) | |
| 76 | | `header` | [Specify the content of the slide header ▶️](#header-and-footer) | |
| 77 | | `footer` | [Specify the content of the slide footer ▶️](#header-and-footer) | |
| 78 | | `class` | Set [HTML `class` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) for the slide element `<section>` | |
| 79 | | `backgroundColor` | Set [`background-color` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) of the slide | |
| 80 | | `backgroundImage` | Set [`background-image` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-image) of the slide | |
| 81 | | `backgroundPosition` | Set [`background-position` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) of the slide | |
| 82 | | `backgroundRepeat` | Set [`background-repeat` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat) of the slide | |
| 83 | | `backgroundSize` | Set [`background-size` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) of the slide | |
| 84 | | `color` | Set [`color` style](https://developer.mozilla.org/en-US/docs/Web/CSS/color) of the slide | |
| 85 | |
| 86 | #### Inheritance |
| 87 | |
| 88 | Slides will inherit setting values of local directives from the immediately previous slide **unless** a local directive is explicitly set for the current slide. In other words, defined local directives will apply to both the defined page and subsequent pages. |
| 89 | |
| 90 | For example, the Markdown for this set of slides defines the `backgroundColor` directive on the second page. Because subsequent pages inherit local directives, the third page will also have the same color. |
| 91 | |
| 92 | ```markdown |
| 93 | # Page 1 |
| 94 | |
| 95 | Go to next page :arrow_right: |
| 96 | |
| 97 | --- |
| 98 | |
| 99 | <!-- backgroundColor: lightblue --> |
| 100 | |
| 101 | # Page 2 |
| 102 | |
| 103 | ## This page has a light blue background. |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | # Page 3 |
| 108 | |
| 109 | ## This page also has the same light blue background. |
| 110 | ``` |
| 111 | |
| 112 | ```markdown:marp |
| 113 | # Page 1 |
| 114 | |
| 115 | Go to next page :arrow_right: |
| 116 | |
| 117 | --- |
| 118 | |
| 119 | <!-- backgroundColor: lightblue --> |
| 120 | |
| 121 | # Page 2 |
| 122 | |
| 123 | ## This page has a light blue background. |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | # Page 3 |
| 128 | |
| 129 | ## This page also has the same light blue background. |
| 130 | ``` |
| 131 | |
| 132 | #### Scoped local directives |
| 133 | |
| 134 | If you want a local directive to apply only to the current page, add the underscore prefix `_` to the name of directives. |
| 135 | |
| 136 | The value of a scoped directive will be given priority over an inherited value, and subsequent pages will not inherit the value of the scoped directive. |
| 137 | |
| 138 | ```markdown |
| 139 | <!-- color: red --> |
| 140 | |
| 141 | # Page 1 |
| 142 | |
| 143 | This page has red text. |
| 144 | |
| 145 | --- |
| 146 | |
| 147 | <!-- _color: blue --> |
| 148 | |
| 149 | # Page 2 |
| 150 | |
| 151 | This page has blue text, specified by a scoped local directive. |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | # Page 3 |
| 156 | |
| 157 | Go back to red text. |
| 158 | ``` |
| 159 | |
| 160 | ```markdown:marp |
| 161 | <!-- color: red --> |
| 162 | |
| 163 | # Page 1 |
| 164 | |
| 165 | This page has red text. |
| 166 | |
| 167 | --- |
| 168 | |
| 169 | <!-- _color: blue --> |
| 170 | |
| 171 | # Page 2 |
| 172 | |
| 173 | This page has blue text, specified by a scoped local directive. |
| 174 | |
| 175 | --- |
| 176 | |
| 177 | # Page 3 |
| 178 | |
| 179 | Go back to red text. |
| 180 | ``` |
| 181 | |
| 182 | The underscore prefix can be added to any local directives. |
| 183 | |
| 184 | #### Diagram |
| 185 | |
| 186 |  |
| 187 | |
| 188 | ## Theme |
| 189 | |
| 190 | <!-- TODO: Link to "Theme" section --> |
| 191 | |
| 192 | ## Page number |
| 193 | |
| 194 | To add page number to the slide, set the **`paginate`** local directive to `true`. |
| 195 | |
| 196 | ```markdown |
| 197 | <!-- paginate: true --> |
| 198 | |
| 199 | You can see the slide number in the lower right. |
| 200 | ``` |
| 201 | |
| 202 | ```markdown:marp |
| 203 | <!-- paginate: true --> |
| 204 | |
| 205 | You can see the slide number in the lower right. |
| 206 | |
| 207 | <style> |
| 208 | @keyframes point { |
| 209 | from { background-position: bottom 55px right 55px; } |
| 210 | to { background-position: bottom 40px right 40px; } |
| 211 | } |
| 212 | section { |
| 213 | animation: 0.5s ease-in-out alternate infinite point; |
| 214 | background: #fff url('https://icongr.am/feather/arrow-down-right.svg?color=0288d1') no-repeat bottom 40px right 40px / 100px; |
| 215 | } |
| 216 | @media (prefers-reduced-motion) { |
| 217 | section { |
| 218 | animation: none; |
| 219 | } |
| 220 | } |
| 221 | </style> |
| 222 | ``` |
| 223 | |
| 224 | Refer to [theme guide](/docs/guide/theme) for details on how to style a slide number. |
| 225 | |
| 226 | ### Skip pagination in the title slide |
| 227 | |
| 228 | Just move the definition of the `paginate` directive to the second slide. |
| 229 | |
| 230 | ```markdown |
| 231 | # Title slide |
| 232 | |
| 233 | --- |
| 234 | |
| 235 | <!-- paginate: true ---> |
| 236 | |
| 237 | ## Start pagination from this slide. |
| 238 | ``` |
| 239 | |
| 240 | ```markdown:marp |
| 241 | # Title slide |
| 242 | |
| 243 | --- |
| 244 | |
| 245 | <!-- paginate: true ---> |
| 246 | |
| 247 | ## Start pagination from this slide. |
| 248 | |
| 249 | <style scoped> |
| 250 | @keyframes point { |
| 251 | from { background-position: bottom 55px right 55px; } |
| 252 | to { background-position: bottom 40px right 40px; } |
| 253 | } |
| 254 | section { |
| 255 | animation: 0.5s ease-in-out alternate infinite point; |
| 256 | background: #fff url('https://icongr.am/feather/arrow-down-right.svg?color=0288d1') no-repeat bottom 40px right 40px / 100px; |
| 257 | } |
| 258 | @media (prefers-reduced-motion) { |
| 259 | section { |
| 260 | animation: none; |
| 261 | } |
| 262 | } |
| 263 | </style> |
| 264 | ``` |
| 265 | |
| 266 | You can also use [scoped directive](#scoped-local-directives) to disable pagination in the title slide. |
| 267 | |
| 268 | ```markdown |
| 269 | --- |
| 270 | paginate: true |
| 271 | _paginate: false |
| 272 | --- |
| 273 | |
| 274 | # Title slide |
| 275 | |
| 276 | --- |
| 277 | |
| 278 | ## Start pagination from this slide. |
| 279 | ``` |
| 280 | |
| 281 | ## Header and footer |
| 282 | |
| 283 | Use **`header`** and **`footer`** local directives to add headers and footers to slides. |
| 284 | |
| 285 | ```markdown |
| 286 | <!-- |
| 287 | header: Header content |
| 288 | footer: Footer content |
| 289 | --> |
| 290 | |
| 291 | # Header and footer |
| 292 | ``` |
| 293 | |
| 294 | ```markdown:marp |
| 295 | <!-- |
| 296 | header: Header content |
| 297 | footer: Footer content |
| 298 | --> |
| 299 | |
| 300 | # Header and footer |
| 301 | <style> |
| 302 | @keyframes point-up { |
| 303 | from { background-position: 50px 50px; } |
| 304 | to { background-position: 50px 70px; } |
| 305 | } |
| 306 | @keyframes point-down { |
| 307 | from { background-position: left 50px bottom 50px; } |
| 308 | to { background-position: left 50px bottom 70px; } |
| 309 | } |
| 310 | section { |
| 311 | animation: 0.5s ease-in-out alternate infinite point-up; |
| 312 | background: #fff url('https://icongr.am/feather/arrow-up.svg?color=0288d1') no-repeat 50px 50px / 80px; |
| 313 | } |
| 314 | section::before { |
| 315 | content: ''; |
| 316 | display: block; |
| 317 | position: absolute; |
| 318 | top: 0; |
| 319 | left: 0; |
| 320 | right: 0; |
| 321 | bottom: 0; |
| 322 | pointer-events: none; |
| 323 | animation: 0.5s ease-in-out alternate infinite point-down; |
| 324 | background: transparent url('https://icongr.am/feather/arrow-down.svg?color=0288d1') no-repeat left 50px bottom 50px / 80px; |
| 325 | } |
| 326 | @media (prefers-reduced-motion) { |
| 327 | section, section::before { |
| 328 | animation: none; |
| 329 | } |
| 330 | } |
| 331 | </style> |
| 332 | ``` |
| 333 | |
| 334 | Refer to [theme guide](/docs/guide/theme) for details on how to style header and footer. |
| 335 | |
| 336 | ### Markdown formatting |
| 337 | |
| 338 | You can use inline Markdown formatting (italic, bold, inline image, etc) in header and footer like this: |
| 339 | |
| 340 | ```markdown |
| 341 | --- |
| 342 | header: '**bold** _italic_' |
| 343 | footer: '' |
| 344 | --- |
| 345 | ``` |
| 346 | |
| 347 | To make directives parsable as valid YAML, you can wrap content with (double-)quotes. |
| 348 | |
| 349 | ### Reset header and footer |
| 350 | |
| 351 | Set the value of a directive to an empty string value to reset the header and footer in the middle of the slide deck. |
| 352 | |
| 353 | ```markdown |
| 354 | --- |
| 355 | header: '**Header**' |
| 356 | footer: '_Footer_' |
| 357 | --- |
| 358 | |
| 359 | # Example |
| 360 | |
| 361 | --- |
| 362 | |
| 363 | <!-- |
| 364 | header: '' |
| 365 | footer: '' |
| 366 | --> |
| 367 | |
| 368 | ## Reset header and footer |
| 369 | ``` |
| 370 | |
| 371 | ```markdown:marp |
| 372 | --- |
| 373 | header: '**Header**' |
| 374 | footer: '_Footer_' |
| 375 | --- |
| 376 | |
| 377 | # Example |
| 378 | |
| 379 | --- |
| 380 | |
| 381 | <!-- |
| 382 | header: '' |
| 383 | footer: '' |
| 384 | --> |
| 385 | |
| 386 | ## Reset header and footer |
| 387 | ``` |
| 388 | |
| 389 | ## Styling slide |
| 390 | |
| 391 | ### Shorthand |
| 392 | |
| 393 | ## Editor integration |
| 394 | |
| 395 | <!-- By using **Marp for VS Code**, you can preview --> |
| 396 |