The core of Marp converter
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.github
src
test
themes Prevent showing scrollbar in code on gaia theme Jan 13, 2019
.gitignore
.node-version
.prettierignore
.prettierrc Initial commit with TypeScript Jun 5, 2018
.stylelintrc
CHANGELOG.md Update CHANGELOG.md Jan 14, 2019
LICENSE
README.md
browser.js
jest.config.js
package.json
rollup.config.js Update rollup config to be silence warning of named export Dec 29, 2018
tsconfig.json
tslint.json
version.js
yarn.lock

README.md

@marp-team/marp-core

CircleCI Codecov npm LICENSE

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.

Basic usage

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.ready()

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()
})

Separated bundle

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().

Features

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

Marp Markdown is based on Marpit and CommonMark, and there are these additional features:

Built-in official themes

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

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

Emoji support

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

Math typesetting

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

Math typesetting support

Auto scaling features

Auto scaling is available only if enabled Marpit's inlineSVG mode. You have to run Marp.ready() on browser context.

Fitting header

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 to Deckset's [fit] keyword, but we use HTML comment to hide a fit keyword on Markdown rendered as document.

Math block

We can scale-down the viewing size of math block (surrounded by $$) to fit a slide automatically.

Traditional rendering Auto scaling
Traditional rendering Auto scaling

Code block (Only for default and gaia theme)

Several themes also can scale-down the viewing size of the code block to fit a slide.

Traditional rendering Auto scaling
Traditional rendering Auto scaling

These features means that the contents on a slide are not cropped, and not shown unnecessary scrollbars in code.

ℹ️ uncover theme has disabled scaling for code block because we use elastic style that has not compatible with it.

⚠️ We won't detect whether the math and code block actually protrudes from the slide. It might not work scaling correctly when there are many elements in a slide.

Constructor options

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 markdown option 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,
    twemojiBase: '/resources/twemoji/',
  },
  math: {
    katexFontPath: '/resources/fonts/',
  },

  // It can be included Marpit constructor options
  looseYAML: false,
  markdown: {
    breaks: false,
  },
})

html: boolean | object

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: [],
}

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.

ℹ️ html flag in markdown option cannot use because of overridden by this.

emoji: object

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)
  • unicode: boolean | "twemoji"

    • It can convert Unicode emoji into twemoji when setting "twemoji". 🐶🐶 (default)
    • If you not want this aggressive conversion, please set false.
  • twemojiBase: string

For developers: When you setting unicode option as true, Markdown parser will convert Unicode emoji into tokens internally. The rendering result is same as in false.

math: boolean | object

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

  • 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).

Contributing

Are you interested in contributing? Please see CONTRIBUTING.md.

Author

Managed by @marp-team.

License

This package releases under the MIT License.