The core of Marp converter.
In order to use on Marp tools, we have extended from the slide deck framework Marpit. You can use the practical Markdown syntax, advanced features, and official themes.
We provide Marp class, that is inherited from Marpit.
import Marp from '@marp-team/marp-core'
// Convert Markdown slide deck into HTML and CSS
const marp = new Marp()
const { html, css } = marp.render('# Hello, marp-core!')Marp class has ready() static method to work several features correctly. It must run on the browser context by using Browserify or webpack.
import Marp from '@marp-team/marp-core'
document.addEventListener('DOMContentLoaded', () => {
Marp.ready()
})We also provide a separated bundle lib/browser.js for browser context. It is useful when you cannot use bundler.
Loading lib/browser.js will bring the almost same result as running Marp.ready(). Thus, you could use it through CDN as below:
<html>
<body>
<!-- Please insert here rendered HTML by `Marp.render().html`... -->
<script
defer
src="https://cdn.jsdelivr.net/npm/@marp-team/marp-core/lib/browser.js"
></script>
</body>
</html>CommonJS bundle is also provided in lib/browser.cjs.js. It have to call manually as same as Marp.ready().
We will only explain features extended in marp-core. Please refer to @marp-team/marpit repository if you want to know the basic feature of Marpit framework.
Marp Markdown is based on Marpit and CommonMark, and there are these additional features:
- Marpit
- Enable inline SVG mode and loose YAML parsing by default.
- CommonMark
- For security reason, HTML tag only allows whitelisted elements by default.
- Support table syntax based on GitHub Flavored Markdown.
- Line breaks in paragraph will convert to
<br>tag. - Auto convert URL like text into hyperlink.
We provide bulit-in official themes for Marp. See more details in themes.
| Default | Gaia | Uncover |
|---|---|---|
<!-- theme: default --> |
<!-- theme: gaia --> |
<!-- theme: uncover --> |
Emoji shortcode (like :smile:) and Unicode emoji 😄 will convert into the SVG vector image provided by twemoji 
We have Pandoc's Markdown style math typesetting support by KaTeX. Surround your formula by $...$ to render math as inline, and $$...$$ to render as block.
| Markdown | Rendered slide |
|---|---|
Render inline math such as $ax^2+bc+c$.
$$ I_{xx}=\int\int_Ry^2f(x,y)\cdot{}dydx $$
$$
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}
\,d\xi
$$ |
|
Auto-scaling is available only if enabled Marpit's inlineSVG mode and defined @auto-scaling meta data in an using theme CSS. In addition, you have to run Marp.ready() on browser context.
/*
* @theme enable-all-auto-scaling
* @auto-scaling true
*/Marp Core's scaling features will be realized by manipulating the original DOM to use inline SVG. So the theme author must take care of updated DOM in styling. Refer to the source code of offical themes.
@auto-scaling meta can also pick the favorite features to enable by using keyword(s).
/*
* @theme enable-auto-scaling-for-fitting-header-and-math
* @auto-scaling fittingHeader,math
*/
⚠️ In the math block and the code block, Marp Core won't detect whether they actually protrude from the slide. It might not work scaling correctly when there are many elements in a slide.
When the headings contains <!-- fit --> comment, the size of headings will resize to fit onto the slide size.
# <!-- fit --> Fitting headerThis syntax is similar to Deckset's [fit] keyword, but we use HTML comment to hide a fit keyword on Markdown rendered as document.
ℹ️
@auto-scaling fittingHeaderis a keyword of the@auto-scalingmeta to enable fitting header.
We can scale-down the viewing size of math block (surrounded by $$) to fit a slide automatically.
| Traditional rendering | Auto-scaling |
|---|---|
ℹ️
@auto-scaling mathis a keyword of the@auto-scalingmeta to enable math block scaling.
Several themes also can scale-down the viewing size of the code block to fit a slide.
| Traditional rendering | Auto-scaling |
|---|---|
These features means that the contents on a slide are not cropped, and not shown unnecessary scrollbars in code.
ℹ️
@auto-scaling codeis a keyword of the@auto-scalingmeta to enable code block scaling.uncovertheme has disabled code block scaling because we use elastic style that has not compatible with it.
You can customize a behavior of Marp parser by passing an options object to the constructor. You can also pass together with Marpit constructor options.
ℹ️ Marpit's
markdownoption is accepted only object options because of always using CommonMark.
const marp = new Marp({
// marp-core constructor options
html: true,
emoji: {
shortcode: true,
unicode: false,
twemoji: {
base: '/resources/twemoji/',
},
},
math: {
katexFontPath: '/resources/fonts/',
},
// It can be included Marpit constructor options
looseYAML: false,
markdown: {
breaks: false,
},
})Setting whether to render raw HTML in Markdown.
true: The all HTML will be allowed.false: All HTML except supported in Marpit Markdown will be disallowed.- By passing
object, you can set the whitelist to specify allowed tags and attributes.
// Specify tag name as key, and attributes to allow as string array.
{
a: ['href', 'target'],
br: [],
}// You may use custom attribute sanitizer by passing object.
{
img: {
src: value => (value.startsWith('https://') ? value : '')
}
}Marp core allows only <br> tag by default, that is defined in Marp.html.
Whatever any option is selected, <!-- HTML comment --> is always parsed by Marpit for directives. When you are not disabled Marpit's inlineStyle option by false, <style> tags are parsed too for tweaking theme style.
ℹ️
htmlflag inmarkdownoption cannot use because of overridden by this.
Setting about emoji conversions.
-
shortcode:boolean|"twemoji"- By setting
false, it does not convert any emoji shortcodes. - By setting
true, it converts emoji shortcodes into Unicode emoji.:dog:→ 🐶 - By setting
"twemoji"string, it converts into twemoji vector image.:dog:→(default)
- By setting
-
unicode:boolean|"twemoji"- It can convert Unicode emoji into twemoji when setting
"twemoji". 🐶 → - If you not want this aggressive conversion, please set
false.
- It can convert Unicode emoji into twemoji when setting
-
twemoji:objectbase:string- It is corresponded to twemoji'sbaseoption. By default, marp-core will use online emoji images through MaxCDN (twemoji's default).ext:"svg"|"png"- Setting the file type of twemoji images. (svgby default)
For developers: When you setting
unicodeoption astrue, Markdown parser will convert Unicode emoji into tokens internally. The rendering result is same as infalse.
Enable or disable math typesetting syntax. The default value is true.
You can modify KaTeX further settings by passing an object of sub-options.
-
katexOption:object- The options passing to KaTeX. Please refer to KaTeX document.
-
katexFontPath:string|false- By default, marp-core will use online web-font resources through jsDelivr CDN. You have to set path to fonts directory if you want to use local resources. If you set
false, we will not manipulate the path (Use KaTeX's original path:fonts/KaTeX_***-***.woff2).
- By default, marp-core will use online web-font resources through jsDelivr CDN. You have to set path to fonts directory if you want to use local resources. If you set
Are you interested in contributing? Please see CONTRIBUTING.md.
Managed by @marp-team.
Yuki Hattori (@yhatt)
This package releases under the MIT License.