Marpit has only one feature: Convert Markdown and theme set into HTML/CSS. Thus the basic usage is completely simple.
At first you must create an instance of Marpit class.
const { Marpit } = require('@marp-team/marpit')
// Create Marpit instance
const marpit = new Marpit()By passing object of options, you can customize the behavior of Marpit instance when creating.
See all options at JSDoc to details. Here we will introduce useful recipes.
📝 markdown-it parser setting
You can customize the behavior of Markdown parser by markdown option. It will pass to markdown-it initializer as it is.
const marpit = new Marpit({
markdown: {
html: true, // Enable HTML tags
breaks: true, // Convert line breaks into `<br />`
},
})You can customize container HTML elements too. These settings are using to scope the converted CSS. Element class helps to specify container(s).
const { Marpit, Element } = require('@marp-team/marpit')
const marpit = new Marpit({
container: [
new Element('article', { id: 'presentation' }),
new Element('div', { class: 'slides' }),
],
slideContainer: new Element('div', { class: 'slide' }),
})It would render elements like this:
<!-- Container elements -->
<article id="presentation">
<div class="slides">
<!-- Slide container elements -->
<div class="slide"><section>Page 1</section></div>
<div class="slide"><section>Page 2</section></div>
</div>
</article>The default container is <div class="marpit">, and no slide containers (render only <section>). If you may not use any containers and CSS scoping, please set container option as false.
Turn on the (experimental) inline SVG slide.
const marpit = new Marpit({
inlineSVG: true,
})Now, let's render Markdown. Just only pass a string of Markdown to marpit.render(markdown).
// Output rendered HTML, CSS, and collected HTML comments (See "Advanced")
const { html, css, comments } = marpit.render('# Hello, Marpit!')The HTML output is like this. (Formatted)
<div class="marpit">
<section id="1"><h1>Hello, Marpit!</h1></section>
</div>If the outputted CSS applies into this HTML, it become to be able to print slide deck as PDF in Chrome.
render() method is an only key feature of Marpit instance.
We had not assigned any theme in previous example. The rendered CSS only includes minimum declarations to work as slide deck.
You may assign the set of theme CSS through Marpit instance's themeSet property.
Use themeSet.add(css) to add theme CSS. It returns created Theme instance.
const theme = marpit.themeSet.add(`
/* @theme my-first-theme */
section {
background-color: #123;
color: #fff;
font-size: 30px;
padding: 40px;
}
h1 {
color: #8cf;
}
`)We require @theme meta comment in CSS. You can use added theme if you are selected it through directive (<!-- theme: my-first-theme -->).
By assigning Theme instance to themeSet.default property, you can specify default theme. It allows using theme without directive.
marpit.themeSet.default = marpit.themeSet.add('...')marpit.render() has an optional second argument env, to pass data object into markdown-it.
When you passed htmlAsArray: true, the renderer will output HTML as array, that has consisted HTML per slide pages.
const markdown = `
# Page 1
---
# Page 2
`
const { html } = marpit.render(markdown, { htmlAsArray: true })
/*
[ '<section id="1">\n<h1>Page 1</h1>\n</section>\n',
'<section id="2">\n<h1>Page 2</h1>\n</section>\n' ]
*/!> Marpit initializer's container option is still enabled to scope CSS, so you have to render these HTMLs within <div class="marpit"> or customized element(s).
Marpit can collect HTML comments written in Markdown while rendering, except directives. The collected comments are returned in the result of marpit.render().
You may use it as the presenter notes in Marpit integrated apps.
const { comments } = marpit.render(`
<!-- theme: default -->
# First page
<!-- HTML comment recognizes as a presenter note per pages. -->
<!-- You may place multiple comments in a single page. -->
---
## Second page
<!--
Also supports multiline.
We bet these comments would help your presentation...
-->
`)The returned value is a two-dimensional array composed by comments per slide pages.
[
[
"HTML comment recognizes as a presenter note per pages.",
"You may place multiple comments in a single page."
],
[
"Also supports multiline.\nWe bet these comments would help your presentation..."
]
]You can extend Marpit Markdown parser by marpit.use() with markdown-it plugin.
Due to our policy, Marpit has not extended Markdown syntax such as to break CommonMark. But you may use plugins if you want the aggressive extended syntax.
For example, let's say you want to use the custom container by markdown-it-container to support multi-column block.
const { Marpit } = require('@marp-team/marpit')
const markdownItContainer = require('markdown-it-container')
// Create the extended Marpit instance
const marpit = new Marpit().use(markdownItContainer, 'columns')
// Setting default theme for styling multi-column
marpit.themeSet.default = marpit.themeSet.add(`
/* @theme custom-container */
section { padding: 50px; }
.columns { column-count: 2; }
`)
// Render HTML and CSS from Markdown that includes custom container
const { html, css } = marpit.render(`
::: columns
Lorem ipsum dolor sit amet consectetur, adipisicing elit. Perspiciatis
perferendis, dolorem amet adipisci quas rem iusto excepturi ipsam aperiam quo
expedita totam a laborum ut voluptatibus voluptate fugit voluptatem eum?
:::
`)You're ready to use multi-column through custom container! The rendered slide is as follows.
!> Marpit has already many extends to support converting Markdown into slide deck. So some markdown-it plugins that are not created for Marpit would not work as expected because of existing extends.
The documentation of Marpit API, created by JSDoc, is hosted on another site. Please refer to https://marpit-api.marp.app/.