{"id":13613769,"url":"https://github.com/marp-team/marp-core","last_synced_at":"2025-05-15T11:00:20.668Z","repository":{"id":37978655,"uuid":"136200010","full_name":"marp-team/marp-core","owner":"marp-team","description":"The core of Marp converter","archived":false,"fork":false,"pushed_at":"2024-12-26T20:41:31.000Z","size":3491,"stargazers_count":864,"open_issues_count":12,"forks_count":136,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-14T16:57:39.923Z","etag":null,"topics":["deck","markdown","marp","presentation","slides"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marp-team.png","metadata":{"funding":{"github":["yhatt"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-05T15:43:27.000Z","updated_at":"2025-04-13T22:09:13.000Z","dependencies_parsed_at":"2024-01-14T11:00:24.797Z","dependency_job_id":"17e89eec-2e3c-4737-b62d-d7630c45b060","html_url":"https://github.com/marp-team/marp-core","commit_stats":{"total_commits":876,"total_committers":5,"mean_commits":175.2,"dds":0.1187214611872146,"last_synced_commit":"93cd661c1682afe950b8481d16a57a3f674fea6a"},"previous_names":[],"tags_count":91,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marp-team%2Fmarp-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marp-team","download_url":"https://codeload.github.com/marp-team/marp-core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deck","markdown","marp","presentation","slides"],"created_at":"2024-08-01T20:00:53.439Z","updated_at":"2025-05-15T11:00:20.623Z","avatar_url":"https://github.com/marp-team.png","language":"TypeScript","funding_links":["https://github.com/sponsors/yhatt"],"categories":["TypeScript","markdown","Ecosystem"],"sub_categories":["Official"],"readme":"# @marp-team/marp-core\n\n[![CircleCI](https://img.shields.io/circleci/project/github/marp-team/marp-core/main.svg?style=flat-square\u0026logo=circleci)](https://circleci.com/gh/marp-team/marp-core/)\n[![Codecov](https://img.shields.io/codecov/c/github/marp-team/marp-core/main.svg?style=flat-square\u0026logo=codecov)](https://codecov.io/gh/marp-team/marp-core)\n[![npm](https://img.shields.io/npm/v/@marp-team/marp-core.svg?style=flat-square\u0026logo=npm)](https://www.npmjs.com/package/@marp-team/marp-core)\n[![LICENSE](https://img.shields.io/github/license/marp-team/marp-core.svg?style=flat-square)](./LICENSE)\n\n**The core of [Marp](https://github.com/marp-team/marp) converter.**\n\nIn order to use on Marp tools, we have extended from the slide deck framework **[Marpit](https://github.com/marp-team/marpit)**. You can use the practical Markdown syntax, advanced features, and official themes.\n\n## Install\n\n```bash\nnpm install --save @marp-team/marp-core\n```\n\n## Usage\n\nWe provide `Marp` class, that is inherited from [Marpit](https://github.com/marp-team/marpit).\n\n```javascript\nimport { Marp } from '@marp-team/marp-core'\n\n// Convert Markdown slide deck into HTML and CSS\nconst marp = new Marp()\nconst { html, css } = marp.render('# Hello, marp-core!')\n```\n\n## Features\n\n_We will only explain features extended in marp-core._ Please refer to [Marpit framework](https://marpit.marp.app) if you want to know the basic features.\n\n---\n\n### Marp Markdown\n\n**Marp Markdown** is a custom Markdown flavor based on [Marpit](https://marpit.marp.app) and [CommonMark](https://commonmark.org/). Following are principle differences from the original:\n\n- **Marpit**\n  - Enabled [inline SVG slide](https://marpit.marp.app/inline-svg), [CSS container query support and loose YAML parsing](https://marpit-api.marp.app/marpit#Marpit) by default.\n\n* **CommonMark**\n  - For making secure, using some insecure HTML elements and attributes are denied by default.\n  - Support [table](https://github.github.com/gfm/#tables-extension-) and [strikethrough](https://github.github.com/gfm/#strikethrough-extension-) syntax, based on [GitHub Flavored Markdown](https://github.github.com/gfm/).\n  - Line breaks in paragraph will convert to `\u003cbr\u003e` tag.\n  - Slugification for headings (assigning auto-generated `id` attribute for `\u003ch1\u003e` - `\u003ch6\u003e`) is enabled by default.\n\n---\n\n### [Built-in official themes][themes]\n\nWe provide bulit-in official themes for Marp. See more details in [themes].\n\n|                Default                |                 Gaia                  |                Uncover                |\n| :-----------------------------------: | :-----------------------------------: | :-----------------------------------: |\n| [![](https://bit.ly/2Op7Bp6)][themes] | [![](https://bit.ly/2QhDq4S)][themes] | [![](https://bit.ly/2DqZvvh)][themes] |\n|       `\u003c!-- theme: default --\u003e`       |        `\u003c!-- theme: gaia --\u003e`         |       `\u003c!-- theme: uncover --\u003e`       |\n\n[themes]: ./themes/\n\n---\n\n### `size` global directive\n\nDo you want a traditional 4:3 slide size? Marp Core adds the support of `size` global directive. The extended theming system can switch the slide size easier.\n\n```markdown\n---\ntheme: gaia\nsize: 4:3\n---\n\n# A traditional 4:3 slide\n```\n\n[Bulit-in themes for Marp][themes] have provided `16:9` (1280x720) and `4:3` (960x720) preset sizes.\n\n#### Define size presets in custom theme CSS\n\nIf 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][metadata].\n\nTheme 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.\n\n[metadata]: ./themes#metadata-for-additional-features\n\n---\n\n### Emoji support\n\nEmoji shortcode (like `:smile:`) and Unicode emoji 😄 will convert into the SVG vector image provided by [twemoji](https://github.com/jdecked/twemoji) \u003cimg src=\"https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/1f604.svg\" alt=\"😄\" width=\"16\" height=\"16\" /\u003e. It could render emoji with high resolution.\n\n---\n\n### Math typesetting\n\nWe have [Pandoc's Markdown style](https://pandoc.org/MANUAL.html#math) math typesetting support. Surround your formula by `$...$` to render math as inline, and `$$...$$` to render as block.\n\n\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth style=\"text-align:center;width:50%;\"\u003eMarkdown\u003c/th\u003e\n\u003cth style=\"text-align:center;width:50%;\"\u003eRendered slide\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```tex\nRender inline math such as $ax^2+bc+c$.\n\n$$ I_{xx}=\\int\\int_Ry^2f(x,y)\\cdot{}dydx $$\n\n$$\nf(x) = \\int_{-\\infty}^\\infty\n    \\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\n    \\,d\\xi\n$$\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n![Math typesetting support](https://user-images.githubusercontent.com/3993388/142782335-15bce585-68f1-4c89-8747-8d11533f3ca6.png)\n\n\u003c/td\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\nYou can choose using library for math from [MathJax](https://www.mathjax.org/) and [KaTeX](https://khan.github.io/KaTeX/) in [`math` global directive](#math-global-directive) (or [JS constructor option](#math-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.\n\n#### `math` global directive\n\nThrough `math` global directive, Marp Core is supporting to declare math library that will be used within current Markdown.\n\nSet **`mathjax`** or **`katex`** in the `math` global directive like this:\n\n```markdown\n---\n# Declare to use KaTeX in this Markdown\nmath: katex\n---\n\n$$\n\\begin{align}\nx \u0026= 1+1 \\tag{1} \\\\\n  \u0026= 2\n\\end{align}\n$$\n```\n\nIf not declared, Marp Core will use MathJax to render math. But we recommend to declare the library whenever to use math typesetting.\n\n\u003e [!WARNING]\n\u003e The declaration of math library is given priority over [`math` JS constructor option](#math-constructor-option), but you cannot turn on again via `math` global directive if disabled math typesetting by the constructor.\n\n---\n\n### Auto-scaling features\n\nMarp Core has some auto-scaling features:\n\n- [**Fitting header**](#fitting-header): Get bigger heading that fit onto the slide by `# \u003c!--fit--\u003e`.\n- [**Auto-shrink the code block and KaTeX block**](#auto-shrink-block): Prevent sticking out the block from the right of the slide.\n\nAuto-scaling is available if defined [`@auto-scaling` metadata][metadata] in an using theme CSS.\n\n```css\n/*\n * @theme foobar\n * @auto-scaling true\n */\n```\n\nAll of [Marp Core's built-in themes][themes] are ready to use full-featured auto scalings. If you're the theme author, you can control target elements which enable auto-scaling [by using metadata keyword(s).][metadata]\n\nThis feature depends to inline SVG, so note that it will not working if disabled [Marpit's `inlineSVG` mode](https://github.com/marp-team/marpit#inline-svg-slide-experimental) by setting `inlineSVG: false` in constructor option.\n\n\u003e [!WARNING]\n\u003e Auto-scaling is designed for horizontal scaling. In vertical, the scaled element still may stick out from bottom of slide if there are a lot of contents around it.\n\n#### Fitting header\n\nWhen the headings contains `\u003c!-- fit --\u003e` comment, the size of headings will resize to fit onto the slide size.\n\n```markdown\n# \u003c!-- fit --\u003e Fitting header\n```\n\nThis syntax is similar to [Deckset's `[fit]` keyword](https://docs.decksetapp.com/English.lproj/Formatting/01-headings.html), but we use HTML comment to hide a fit keyword on Markdown rendered as document.\n\n#### Auto-shrink the block\n\nSome of blocks will be shrunk to fit onto the slide. It is useful preventing stuck out the block from the right of the slide.\n\n|                      |              Traditional rendering               |              Auto-scaling               |\n| :------------------: | :----------------------------------------------: | :-------------------------------------: |\n|    **Code block**    | ![Traditional rendering](https://bit.ly/2LyEnmi) | ![Auto-scaling](https://bit.ly/2N4yWQZ) |\n| **KaTeX math block** | ![Traditional rendering](https://bit.ly/2NXoHuW) | ![Auto-scaling](https://bit.ly/2M6LyCk) |\n\n\u003e [!NOTE]\n\u003e MathJax math block will always be scaled without even setting `@auto-scaling` metadata.\n\n---\n\n## Constructor options\n\nYou can customize a behavior of Marp parser by passing an options object to the constructor. You can also pass together with [Marpit constructor options](https://marpit-api.marp.app/marpit#Marpit).\n\n\u003e [!NOTE]\n\u003e\n\u003e [Marpit's `markdown` option](https://marpit-api.marp.app/marpit#Marpit) is accepted only object options because of always using CommonMark.\n\n```javascript\nconst marp = new Marp({\n  // marp-core constructor options\n  html: true,\n  emoji: {\n    shortcode: true,\n    unicode: false,\n    twemoji: {\n      base: '/resources/twemoji/',\n    },\n  },\n  math: 'katex',\n  minifyCSS: true,\n  script: {\n    source: 'cdn',\n    nonce: 'xxxxxxxxxxxxxxx',\n  },\n  slug: false,\n\n  // It can be included Marpit constructor options\n  looseYAML: false,\n  markdown: {\n    breaks: false,\n  },\n})\n```\n\n### `html`: _`boolean`_ | _`object`_\n\nSetting whether to render raw HTML in Markdown. It's an alias to `markdown.html` ([markdown-it option](https://markdown-it.github.io/markdown-it/#MarkdownIt.new)) but has additional feature about HTML allowlist.\n\n- (default): Use Marp's default allowlist.\n- `true`: The all HTML will be allowed.\n- `false`: All HTML except supported in Marpit Markdown will be disallowed.\n\nBy passing `object`, you can set the allowlist to specify allowed tags and attributes.\n\n```javascript\n// Specify tag name as key, and attributes to allow as string array.\n{\n  a: ['href', 'target'],\n  br: [],\n}\n```\n\n```javascript\n// You may use custom attribute sanitizer by passing object.\n{\n  img: {\n    src: (value) =\u003e (value.startsWith('https://') ? value : '')\n  }\n}\n```\n\nBy default, Marp Core allows known HTML elements and attributes that are considered as safe. That is defined as a readonly `html` member in `Marp` class. [See the full default allowlist in the source code.](src/html/allowlist.ts)\n\n\u003e [!NOTE]\n\u003e Whatever any option is selected, `\u003c!-- HTML comment --\u003e` and `\u003cstyle\u003e` tags are always parsed by Marpit for directives / tweaking style.\n\n### `emoji`: _`object`_\n\nSetting about emoji conversions.\n\n- **`shortcode`**: _`boolean` | `\"twemoji\"`_\n  - By setting `false`, it does not convert any emoji shortcodes.\n  - By setting `true`, it converts emoji shortcodes into Unicode emoji. `:dog:` → 🐶\n  - By setting `\"twemoji\"` string, it converts into twemoji vector image. `:dog:` → \u003cimg src=\"https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/1f436.svg\" alt=\"🐶\" width=\"16\" height=\"16\" valign=\"middle\" /\u003e _(default)_\n\n* **`unicode`**: _`boolean` | `\"twemoji\"`_\n  - It can convert Unicode emoji into twemoji when setting `\"twemoji\"`. 🐶 → \u003cimg src=\"https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/1f436.svg\" alt=\"🐶\" width=\"16\" height=\"16\" valign=\"middle\" /\u003e _(default)_\n  - If you not want this aggressive conversion, please set `false`.\n\n- **`twemoji`**: _`object`_\n  - **`base`**: _`string`_ - Corresponds to [twemoji's `base` option](https://github.com/twitter/twemoji#object-as-parameter). If not specified, Marp Core will use [online emoji images through jsDelivr CDN](https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/).\n  - **`ext`**: _`\"svg\"` | `\"png\"`_ - Setting the file type of twemoji images. _(`svg` by default)_\n\n\u003e **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`.\n\n### `math`: _`boolean` | `\"mathjax\"` | `\"katex\"` | `object`_ \u003ca name=\"math-constructor-option\" id=\"math-constructor-option\"\u003e\u003c/a\u003e\n\nEnable or disable [math typesetting](#math-typesetting) syntax and [`math` global directive](#math-global-directive).\n\nYou can choose the default library for math by passing **`\"mathjax\"`** (default) or **`\"katex\"`**, and modify more settings by passing an object of sub-options.\n\n- **`lib`**: _`\"mathjax\"` | `\"katex\"`_\n  - Choose the default library for math typesetting. _(`mathjax` by default)_\n\n* **`katexOption`**: _`object`_\n  - Options that will be passed to KaTeX. Please refer to [KaTeX document](https://khan.github.io/KaTeX/docs/options.html).\n\n- **`katexFontPath`**: _`string` | `false`_\n  - By default, Marp Core will use [online web-font resources through jsDelivr CDN](https://cdn.jsdelivr.net/npm/katex@latest/dist/fonts/). 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`).\n\n### `minifyCSS`: _`boolean`_\n\nEnable or disable minification for rendered CSS. `true` by default.\n\n### `script`: _`boolean` | `object`_\n\nSetting about an injected helper script for the browser context. This script is necessary for applying [WebKit polyfill](https://github.com/marp-team/marpit-svg-polyfill) and rendering [auto-scaled elements](#auto-scaling-features) correctly.\n\n- **`true` (default)**: Inject the inline helper script into after the last of slides.\n- **`false`**: Don't inject helper script. Developer must execute a helper script manually, exported in [`@marp-team/marp-core/browser`](src/browser.ts). Requires bundler such as [webpack](https://webpack.js.org/). It's suitable to the fully-controlled tool such as [Marp Web](https://github.com/marp-team/marp-web).\n\nYou can control details of behavior by passing `object`.\n\n- **`source`**: _`string`_ - Choose the kind of script.\n  - **`inline`**: Inject the inline script. It would work correctly also in the environment that there is not network. (default)\n  - **`cdn`**: Inject script referred through [jsDelivr CDN](https://www.jsdelivr.com/). It's better choice on the restricted environment by [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).\n\n* **`nonce`**: _`string`_ - Set [`nonce` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-nonce) of `\u003cscript\u003e`.\n\n### `slug`: _`boolean` | `function` | `object`_\n\nConfigure slugification for headings. By default, Marp Core tries to make the slug by the similar way to GitHub. It should be compatible with [Markdown Language Server](https://code.visualstudio.com/blogs/2022/08/16/markdown-language-server).\n\n- **`true` (default)**: Assign auto-generated `id` attribute from the contents of `\u003ch1\u003e`-`\u003ch6\u003e` headings.\n- **`false`**: Disable auto-assigning slug to headings.\n- _`function`_: Set the custom slugifier function, that takes one argument: the content of the heading. It must return a generated slug string.\n\nYou can control details of behavior by passing `object`.\n\n- **`slugifier`**: _`function`_ - Set the custom slugifier function.\n- **`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 to `id` attribute of the heading.\n\n  By default, Marp Core applies the post-process to avoid assigning duplicated `id`s in the document: ``(slug, index) =\u003e (index \u003e 0 ? `${slug}-${index}` : slug)``\n\n  Assigning the custom post-process function is also helpful to append the custom prefix and suffix to the generated slug: `` (slug, i) =\u003e `prefix:${slug}:${i}` ``\n\n\u003e [!NOTE]\n\u003e Take care not to confuse Marp Core's `slug` option and [Marpit's `anchor` option](https://marpit-api.marp.app/marpit#:~:text=Description-,anchor,-boolean%20%7C%20Marpit). `slug` is for the Markdown headings, and `anchor` is for the slide elements.\n\u003e\n\u003e `Marp` class is extended from `Marpit` class so you can customize both options in the constructor. To fully disable auto-generated `id` attribute, set both options as `false`. (This is important to avoid breaking your Web application by user's Markdown contents)\n\n## Contributing\n\nAre you interested in contributing? Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) and [the common contributing guideline for Marp team](https://github.com/marp-team/.github/blob/master/CONTRIBUTING.md).\n\n## Author\n\nManaged by [@marp-team](https://github.com/marp-team).\n\n- \u003cimg src=\"https://github.com/yhatt.png\" width=\"16\" height=\"16\"/\u003e Yuki Hattori ([@yhatt](https://github.com/yhatt))\n\n## License\n\nThis package releases under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarp-team%2Fmarp-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarp-team%2Fmarp-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarp-team%2Fmarp-core/lists"}