Marp Core

Marp Markdown is a custom flavor based on Marpit and CommonMark. Key differences include:

• Security: Some insecure HTML elements and attributes are denied by default to ensure security.
• GFM Support: Supports GitHub Flavored Markdown syntax like tables and strikethrough.
• Line Breaks: Line breaks within a paragraph are converted to <br> tags.
• Heading IDs: Slugification for headings is enabled by default (e.g., <h1> gets an auto-generated id).

The gaia theme is inspired by the azusa-colors keynote template. It includes specific features:

• lead class: By default, Gaia aligns content to the top-left. Use the lead class to center content (useful for title slides).
• gaia class: Enables an additional color scheme.
• Multiple classes: You can combine classes using a space-separated string or a YAML array.

To apply a class to only the current page, use the scoped local directive _class.

<!--
theme: gaia
class: lead
-->

---

<!-- _class: lead -->

# Lead on this page only

---

<!-- class: lead gaia -->

# Lead + gaia color scheme

Marp Core supports Pandoc-style math typesetting. Use $ ... $ for inline math and $$ ... $$ for block math.

By default, Marp Core uses MathJax for better rendering and syntax support. However, you can switch to KaTeX for faster rendering (especially useful for decks with many formulas) using the math global directive in the YAML frontmatter.

---
# Declare to use KaTeX in this Markdown
math: katex
---

$$
\begin{align}
x &= 1+1 \tag{1} \\
  &= 2
\end{align}
$$

Marp Core provides auto-scaling to prevent content from overflowing the slide boundaries. This feature is available if the active theme defines @auto-scaling: true in its CSS metadata.

Fitting Header

To make a heading resize to fit the slide width, add the <!-- fit --> HTML comment inside the heading:

# <!-- fit --> Fitting header

Auto-shrink Blocks

Code blocks and KaTeX math blocks are automatically shrunk to prevent them from sticking out of the right side of the slide. Note that MathJax math blocks are always scaled even if @auto-scaling is not explicitly set.

Note: Auto-scaling requires inlineSVG to be enabled in the Marp constructor (which is the default).

You can control the aspect ratio of your slides using the size global directive in the YAML frontmatter. Built-in themes support the following presets:

• 16:9 (1280x720)
• 4:3 (960x720)

To use a specific size, add it to your frontmatter:

---
theme: gaia
size: 4:3
---

# A traditional 4:3 slide

You can select a built-in theme by using the Marpit theme directive in your Markdown. Marp Core provides several themes including default, gaia, and uncover.

<!-- theme: default -->

<!-- theme: gaia -->

<!-- theme: uncover -->

Marp Core provides several official themes that can be activated using YAML frontmatter. To use a theme, add a comment directive at the top of your Markdown file:

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

The following features are available across all built-in themes:

• 4:3 slide size: Use the size directive to set a traditional 4:3 aspect ratio (960x720).
• invert class: Use the invert class to switch to an inverted color scheme.

<!-- size: 4:3 -->

<!-- class: invert -->

To use the Marp converter core in your project, install the package using npm:

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

The sandbox directory is a local development area not managed by Git. You can use it to place Markdown files and test Marp Core features freely during development. Use the following command to start the sandbox environment:

npm run sandbox

The html option controls whether raw HTML is rendered in Markdown. It is an alias to markdown.html but includes an HTML allowlist feature.

• true: All HTML is allowed.
• false: All HTML except what is supported in Marpit Markdown is disallowed.
• default: Uses Marp's default allowlist.
• object: Specify allowed tags and attributes.

Allowlist formats:

• Tag name as key, attributes as string array: { a: ['href', 'target'], br: [] }
• Custom attribute sanitizer: { img: { src: (value) => (value.startsWith('https://') ? value : '') } }

Note: <!-- HTML comment --> and <style> tags are always parsed by Marpit for directives/styling regardless of this setting.

// Example: Allow specific attributes for an anchor tag
const marp = new Marp({
  html: {
    a: ['href', 'target'],
    br: [],
  }
});