@marp-team/marpit

Marpit: Markdown slide deck framework

---

Marpit /mɑːrpɪt/ is the skinny framework for creating slide deck from Markdown.

It could transform the Markdown and CSS theme(s) to slide deck composed by static HTML and CSS. (powered by markdown-it and PostCSS)

• Marpit Markdown - Based on CommonMark, and have extended Directives.
• Clear markup - Marpit theme CSS has no own class, so you can focus on your markup.
• Inline SVG slide (Experimental) - Support slide auto-scaling without extra JavaScript.

Marpit will become a core of the next version of Marp.

:warning: This framework is under development and not ready to use. In addition, we are not ready to accept your contributes because it is proof of concept about the next version of Marp.

Marpit Markdown

Marpit Markdown syntax focuses a compatibility with commonly Markdown documents. It means the result of rendering keeps looking nice even if you open the Marpit Markdown in a general Markdown editor.

Directives

Difference from pre-released Marp

• Removed directives about slide size. Use width / height declaration of theme CSS.
• Parse directives by YAML parser. (js-yaml + FAILSAFE_SCHEMA)
• Support Jekyll style front-matter.
• Global directives is no longer requires $ prefix. (but it still supports because of compatibility and clarity)
• Page directives is renamed to local directives.
• Spot directives, that is known as scoped page directive to current slide, has prefix _.

Pagination

We support a pagination by the paginate local directive. It is same as the page_number directive in pre-released Marp.

<!-- paginate: true -->

You would be able to see a page number of slide in the lower right.

Skip pagination on title slide

Simply you have to move a definition of paginate directive to an inside of a second page.

# Title slide

(This page will not paginate by lack of `paginate` local directive)

---

<!-- paginate: true -->

It will paginate slide from a this page.

Slide backgrounds

We provide a background image syntax to specify slide's background through Markdown. Include bg to the alternate text.

![bg](https://example.com/background.jpg)

When you defined 2 or more background images in a slide, Marpit will show the last defined image only. If you want to show multiple images, try the advanced backgrounds by enabling inline SVG mode.

You can disable by backgroundSyntax: false in Marpit constructor option if you not want the bg syntax.

Resize images

You can resize the image by space-separated options. The basic option value follows background-size style (but except length).

`cover` will scale image to fill the slide (default):
![bg cover](https://example.com/background.jpg)

---

`contain` will scale image to fit the slide:
![bg contain](https://example.com/background.jpg)

You can also use the `fit` keyword like Deckset:
![bg fit](https://example.com/background.jpg)

---

`auto` will not scale image, and use the original size:
![bg auto](https://example.com/background.jpg)

---

The percentage value will specify the scaling factor of image.
![bg 150%](https://example.com/background.jpg)

Styling through directives

If you want to use the gradient as background, you can set style directly through local or spot directives.

This feature is available regardless of backgroundSyntax option in Marpit constructor.

<!-- _backgroundImage: "linear-gradient(to bottom, #67b8e3, #0288d1)" -->

Marpit uses YAML for parsing directives, so you should wrap by quote when the value includes space.

Directives

Spot directive	Description	Default
_backgroundImage	Specify background-image style.
_backgroundPosition	Specify background-position style.	center
_backgroundRepeat	Specify background-repeat style.	no-repeat
_backgroundSize	Specify background-size style.	cover

The beginning underbar of directive means "Apply only to current slide page". (Spot directive)

When you remove the underbar, the background would apply to current and the following pages (Local directive).

Advanced backgrounds with inline SVG mode

The advanced backgrounds will work only with inlineSVG: true. It supports multiple background images, image filters, and split backgrounds.

Multiple background images

![bg](https://example.com/backgroundA.jpg)
![bg](https://example.com/backgroundB.jpg)

These images will arrange in a row.

Split backgrounds

The left or right keyword with bg keyword make a space for the background to the specified side. It has a half of slide size, and the space of a slide content will shrink too.

![bg left](https://example.com/backgroundA.jpg)

# Slide contents

The space of a slide content will shrink to the right side.

---

<!-- Multiple background images will work well in the specified background side. -->

![bg right](https://example.com/backgroundB.jpg)
![bg](https://example.com/backgroundC.jpg)

# Slide contents

The space of a slide content will shrink to the left side.

This feature is similar to Deckset's Split Slides.

Marpit uses a last defined keyword in a slide when left and right keyword is mixed in the same slide by using multiple background images.

Image filters

You can apply CSS filters to image through markdown image syntax. Include <filter-name>(:<param>(,<params>...)) to the space-separated alternate text of image syntax.

Filters can use in the inline image and the advanced backgrounds. You can disable this feature with filters: false in Marpit constructor option.

Filters

We are following the function of the filter style.

Markdown	(with arguments)	filter style
![blur]()	![blur:10px]()	blur(10px)
![brightness]()	![brightness:1.5]()	brightness(1.5)
![contrast]()	![contrast:200%]()	contrast(200%)
![drop-shadow]()	![drop-shadow:0,5px,10px,rgba(0,0,0,.4)]()	drop-shadow(0 5px 10px rgba(0, 0, 0, .4))
![grayscale]()	![grayscale:1]()	grayscale(1)
![hue-rotate]()	![hue-rotate:180deg]()	hue-rotate(180deg)
![invert]()	![invert:100%]()	invert(100%)
![opacity]()	![opacity:.5]()	opacity(.5)
![saturate]()	![saturate:2.0]()	saturate(2.0)
![sepia]()	![sepia:1.0]()	sepia(1.0)

Marpit will use the default arguments shown in above when you omit arguments.

Naturally multiple filters can apply to a image.

![brightness:.8 sepia:50%](https://example.com/image.jpg)

ToDo

• Header and footer directive

Markup

HTML output

The basic idea is that <section> element is corresponding to each slide. It is same as reveal.js.

<section>
  <h1>First page</h1>
</section>
<section>
  <h1>Second page</h1>
</section>

By default, Marpit wraps whole slides by <div class="marpit"> for scoping CSS.

<div class="marpit">
  <section>
    ...
  </section>
</div>

This container element(s) can change in Marpit constructor option. Also container: false can disable wrapping.

Theme CSS

:information_source: Marpit provides only the minimum style for scaffolding presentation, and does not provide default theme. You can use the @marp-team/marp package if you want (UNDER CONSTRUCTION).

In theme CSS, you need not think about the hierarchy of Marpit. All that you have to know is just that a <section> element becomes a slide.

/**
 * @theme marpit-theme
 */

section {
  width: 1280px;
  height: 960px;
  font-size: 40px;
  padding: 40px;
}

h1 {
  font-size: 60px;
}

The root section selector

In Marpit theme CSS, the root section selector means like a viewport of each slide.

Slide size

width and height declaration in section selector can specify a slide size. (1280x720 pixels by default)

The specified size is not only used in the section element size but also used in the size of each page of printed PDF.

For example, try these declarations in your theme CSS if you want a classic 4:3 slide:

section {
  width: 960px;
  height: 720px;
}

Please notice these must define a length in an absolute unit. We support cm, in, mm, pc, pt, and px.

Styling paginations

You can style the page number through section::after pseudo-element. (It is shown by paginate local directive)

section::after {
  font-weight: bold;
  text-shadow: 1px 1px 0 #fff;
}

Please refer to the default style of section::after in a scaffold theme as well.

:information_source: The root section::after has preserved a content of page number from Marpit. At present, you cannot use the root section::after selector for other use.

Theme set

The Marpit instance has a themeSet member that manages usable themes in the theme directive of Marpit Markdown. You have to add theme CSS by using themeSet.add(string).

import Marpit from '@marp-team/marpit'
import fs from 'fs'

const marpit = new Marpit()
marpit.themeSet.add(fs.readFileSync('marpit-theme.css', 'utf-8'))

A specified theme will convert to static CSS in rendering by marpit.render(). It will make it printable to pdf, and add scope with the container element(s) to each selector.

Inline SVG slide (experimental)

:warning: This feature is experimental because of a Chromium issue. A workaround to style can enable by inlineSVG: 'workaround', but it will disable a few basic styling defined in theme CSS. It includes position, transform and overflow with scrolling (auto and scroll).

When you set inlineSVG: true in Marpit constructor option, the each <section> are wrapped by inline SVG.

<svg viewBox="0 0 1280 960">
  <foreignObject width="1280" height="960">
    <section>
      ...
    </section>
  </foreignObject>
</svg>

SVG elements can scale contents with keeping aspect ratio. If you are creating an app that integrated Marpit, it would become easy to handle the layout of slides by CSS.

If it combines with CSS Scroll Snap, we would not need to require any JavaScript logic for the simple HTML-based presentation.

In addition, the advanced backgrounds will support in the layer of this SVG. The injected elements to support advanced background will not affect the DOM structure of each slide.

API

Refer JSDoc: https://marpit.netlify.com/

Development

Under construction.

Contributing

We are sorry but currently we are not ready to accept your contribute because it is under developing for proof of concept.

Author

Managed by @marp-team.

• Yuki Hattori (@yhatt)

License

MIT License

Changelog

v0.0.5 - 2018-05-12

Added

• Add paginate local directive (#17)
• Make Unicode emoji printable (#18)

Security

• Prevent style injections (#19)