diff --git a/CHANGELOG.md b/CHANGELOG.md index d5437720..2c09f7b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ - Add `env` argument to [`Marpit.render()`](https://marpit-api.marp.app/marpit#render) ([#118](https://github.com/marp-team/marpit/pull/118)) - Output HTML per slide page as array by passing `htmlAsArray` env ([#119](https://github.com/marp-team/marpit/pull/119)) - Update docs to explain SVG slide polyfill ([#117](https://github.com/marp-team/marpit/pull/117)) +- Update docs to explain usage of plugin ([#120](https://github.com/marp-team/marpit/pull/120)) ## v0.5.0 - 2018-12-28 diff --git a/docs/assets/plugin-custom-container.png b/docs/assets/plugin-custom-container.png new file mode 100644 index 00000000..12d9366b Binary files /dev/null and b/docs/assets/plugin-custom-container.png differ diff --git a/docs/usage.md b/docs/usage.md index b80af787..d897e14b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -199,6 +199,48 @@ The returned value is a two-dimensional array composed by comments per slide pag ] ``` +### Extend Marpit by plugins + +You can extend Marpit Markdown parser by [`marpit.use()`](https://marpit-api.marp.app/marpit#use) with [markdown-it plugin](https://www.npmjs.com/search?q=keywords: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](https://github.com/markdown-it/markdown-it-container) to support multi-column block. + +```javascript +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. + +

+ +[Rendered custom container](/assets/plugin-custom-container.png) + +

+ +!> 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. + ## Full API documentation The documentation of Marpit API, created by JSDoc, is hosted on another site. Please refer to **[https://marpit-api.marp.app/](https://marpit-api.marp.app/)**.