Repository files navigation

The core ofMarp converter.

In order to use on Marp tools, we have extended from the slide deck frameworkMarpit. You can use the practical Markdown syntax, advanced features, and official themes.

npm install --save @marp-team/marp-core

We provideMarp class, that is inherited fromMarpit.

import{Marp}from'@marp-team/marp-core'// Convert Markdown slide deck into HTML and CSSconstmarp=newMarp()const{ html, css}=marp.render('# Hello, marp-core!')

We will only explain features extended in marp-core. Please refer toMarpit framework if you want to know the basic features.

Marp Markdown is a custom Markdown flavor based onMarpit andCommonMark. Following are principle differences from the original:

• Marpit
  • Enabledinline SVG slide,CSS container query support and loose YAML parsing by default.

• CommonMark
  • For making secure, using some insecure HTML elements and attributes are denied by default.
  • Supporttable andstrikethrough syntax, based onGitHub Flavored Markdown.
  • Line breaks in paragraph will convert to<br> tag.
  • Slugification for headings (assigning auto-generatedid attribute for<h1> -<h6>) is enabled by default.

We provide built-in official themes for Marp. See more details inthemes.

Default	Gaia	Uncover
<!-- theme: default -->	<!-- theme: gaia -->	<!-- theme: uncover -->

Do you want a traditional 4:3 slide size? Marp Core adds the support ofsize global directive. The extended theming system can switch the slide size easier.

---theme:gaiasize:4:3---#A traditional 4:3 slide

Built-in themes for Marp have provided16:9 (1280x720) and4:3 (960x720) preset sizes.

If you want to use more size presets in your own theme, you have to define@size metadata(s) in theme CSS.Learn in the document of theme metadata for Marp Core.

Theme author does not have to worry an unintended design being used with unexpected slide size because user only can use pre-defined presets by author.

Emoji shortcode (like:smile:) and Unicode emoji 😄 will convert into the SVG vector image provided bytwemoji. It could render emoji with high resolution.

We havePandoc's Markdown style math typesetting support. Surround your formula by$...$ to render math as inline, and$$...$$ to render as block.

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$$

You can choose using library for math fromMathJax andKaTeX inmath global directive (orJS constructor option). By default, we prefer MathJax for better rendering and syntax support, but KaTeX is faster rendering if you had a lot of formulas.

Throughmath global directive, Marp Core is supporting to declare math library that will be used within current Markdown.

Setmathjax orkatex in themath global directive like this:

---# Declare to use KaTeX in this Markdownmath:katex---$$\begin{align}x &= 1+1 \tag{1} \\  &= 2\end{align}$$

If not declared, Marp Core will use MathJax to render math. But we recommend to declare the library whenever to use math typesetting.

Marp Core has some auto-scaling features:

• Fitting header: Get bigger heading that fit onto the slide by# <!--fit-->.
• Auto-shrink the code block and KaTeX block: Prevent sticking out the block from the right of the slide.

Auto-scaling is available if defined@auto-scaling metadata in an using theme CSS.

/* * @theme foobar * @auto-scaling true */

All ofMarp Core's built-in themes are ready to use full-featured auto scalings. If you're the theme author, you can control target elements which enable auto-scalingby using metadata keyword(s).

This feature depends to inline SVG, so note that it will not working if disabledMarpit'sinlineSVG mode by settinginlineSVG: false in constructor option.

When the headings contains<!-- fit --> comment, the size of headings will resize to fit onto the slide size.

#<!-- fit--> Fitting header

This syntax is similar toDeckset's[fit] keyword, but we use HTML comment to hide a fit keyword on Markdown rendered as document.

Some of blocks will be shrunk to fit onto the slide. It is useful preventing stuck out the block from the right of the slide.

	Traditional rendering	Auto-scaling
Code block
KaTeX math block

You can customize a behavior of Marp parser by passing an options object to the constructor. You can also pass together withMarpit constructor options.

constmarp=newMarp({// marp-core constructor optionshtml:true,emoji:{shortcode:true,unicode:false,twemoji:{base:'/resources/twemoji/',},},math:'katex',minifyCSS:true,script:{source:'cdn',nonce:'xxxxxxxxxxxxxxx',},slug:false,// It can be included Marpit constructor optionslooseYAML:false,markdown:{breaks:false,},})

Setting whether to render raw HTML in Markdown. It's an alias tomarkdown.html (markdown-it option) but has additional feature about HTML allowlist.

• (default): Use Marp's default allowlist.
• true: The all HTML will be allowed.
• false: All HTML except supported in Marpit Markdown will be disallowed.

By passingobject, you can set the allowlist 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 :'')}}

By default, Marp Core allows known HTML elements and attributes that are considered as safe. That is defined as a readonlyhtml member inMarp class.See the full default allowlist in the source code.

Setting about emoji conversions.

• shortcode:boolean |"twemoji"
  • By settingfalse, it does not convert any emoji shortcodes.
  • By settingtrue, it converts emoji shortcodes into Unicode emoji.:dog: → 🐶
  • By setting"twemoji" string, it converts into twemoji vector image.:dog: →(default)

• unicode:boolean |"twemoji"
  • It can convert Unicode emoji into twemoji when setting"twemoji". 🐶 →(default)
  • If you not want this aggressive conversion, please setfalse.

• twemoji:object
  • base:string - Corresponds totwemoji'sbase option. If not specified, Marp Core will useonline emoji images through jsDelivr CDN.
  • ext:"svg" |"png" - Setting the file type of twemoji images.(svg by default)

For developers: When you settingunicode option astrue, Markdown parser will convert Unicode emoji into tokens internally. The rendering result is same as infalse.

Enable or disablemath typesetting syntax andmath global directive.

You can choose the default library for math by passing"mathjax" (default) or"katex", and modify more settings by passing an object of sub-options.

• lib:"mathjax" |"katex"
  • Choose the default library for math typesetting.(mathjax by default)

• katexOption:object
  • Options that will be passed to KaTeX. Please refer toKaTeX document.

• katexFontPath:string |false
  • By default, Marp Core will useonline web-font resources through jsDelivr CDN. You have to set path to fonts directory if you want to use local resources. If you setfalse, we will not manipulate the path (Use KaTeX's original path:fonts/KaTeX_***-***.woff2).

Enable or disable minification for rendered CSS.true by default.

Setting about an injected helper script for the browser context. This script is necessary for applyingWebKit polyfill and renderingauto-scaled elements correctly.

• true (default): Inject the inline helper script into after the last of slides.
• false: Don't inject helper script. Developer must execute a helper script manually, exported in@marp-team/marp-core/browser. Requires bundler such aswebpack. It's suitable to the fully-controlled tool such asMarp Web.

You can control details of behavior by passingobject.

• source:string - Choose the kind of script.
  • inline: Inject the inline script. It would work correctly also in the environment that there is not network. (default)
  • cdn: Inject script referred throughjsDelivr CDN. It's better choice on the restricted environment byCSP.

• nonce:string - Setnonce attribute of<script>.

Configure slugification for headings. By default, Marp Core tries to make the slug by the similar way to GitHub. It should be compatible withMarkdown Language Server.

• true (default): Assign auto-generatedid attribute from the contents of<h1>-<h6> headings.
• false: Disable auto-assigning slug to headings.
• function: Set the custom slugifier function, that takes one argument: the content of the heading. It must return a generated slug string.

You can control details of behavior by passingobject.

• slugifier:function - Set the custom slugifier function.

• postSlugify:function - Set the post-process function after generated a slug. The function takes 2 arguments, the string of generated slug and the index of the same slug, and must return a string for assigning toid attribute of the heading.

  By default, Marp Core applies the post-process to avoid assigning duplicatedids in the document:(slug, index) => (index > 0 ? `${slug}-${index}` : slug)

  Assigning the custom post-process function is also helpful to append the custom prefix and suffix to the generated slug:(slug, i) => `prefix:${slug}:${i}`

Are you interested in contributing? Please seeCONTRIBUTING.md andthe common contributing guideline for Marp team.

Managed by@marp-team.

• Yuki Hattori (@yhatt)

This package releases under theMIT License.