This guide covers Markdown features available to authors writing slides with Marp Core.

• 📦 Built-in features
  • Marp Markdown
  • Themes
  • Emoji
  • Slide size
  • Auto-scaling

• 🧩 Optional features by core plugins
  • Syntax highlighting
  • Mermaid diagrams
  • Math typesetting

Built-in features

Marp Markdown

Marp Markdown is based on Marpit Markdown and CommonMark. Marp Core changes the defaults as follows:

• Changes from Marpit Markdown
  • Enabled inline SVG slide, CSS container query support and loose YAML parsing by default.

• Changes from CommonMark
  • Supports GitHub Flavored Markdown tables and strikethrough.
  • Line breaks in paragraph will convert to <br> tag.
  • Generates GitHub-like IDs for headings (slugifications).
  • Allows only known-safe HTML elements and attributes by default.

Applications can change these defaults through constructor options.

Themes

Marp Core includes 3 built-in themes:

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

See themes documentation for details.

Emoji

Emoji shortcodes such as :smile: and Unicode emoji such as 😄 are converted to SVG images provided by Twemoji. This keeps emoji rendering sharp and consistent across output formats.

Applications can change shortcode, Unicode, and Twemoji behavior through the emoji constructor option.

Slide size

Use the size global directive to select a size preset defined by the current theme:

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

# A traditional 4:3 slide

Every built-in theme provides 16:9$** (1280 \times 720: \text{default}) \text{and} **$4:3 (960×720) presets.

Theme authors can define custom presets.

Auto-scaling

The auto-scaling feature helps block content fit seamlessly into your slides.

While this feature depends on theme support, it is natively supported by all built-in themes. Theme authors should see how to enable auto scaling by setting @auto-scaling metadata.

Fitting header

Add <!-- fit --> inside a heading (# ~ ######) to scale it to the slide width:

# <!-- fit --> Fitting header

Auto-shrink blocks

Some wide blocks are automatically shrunk when the theme enables their corresponding auto scaling features.

• Code block
• KaTeX math block (when the KaTeX plugin is registered)

Optional features by core plugins

Syntax highlighting

Requirements: @marp-team/marp-core/plugins/shiki plugin and shiki dependency (npm install --save shiki)

A code fence is highlighted when its info string contains a supported language identifier.

```js
import { Marp } from '@marp-team/marp-core'
import shiki from '@marp-team/marp-core/plugins/shiki'

const marp = new Marp().use(shiki())
const { html, css } = marp.render('# Hello, Marp!')
```

Refer to Shiki's language list for supported identifiers.

Colors for syntax highlighting can be customized with CSS variables.

Line highlighting

Add a space-separated {} attribute after the language.

```js {2,4-5}
import { Marp } from '@marp-team/marp-core'
import shiki from '@marp-team/marp-core/plugins/shiki'

const marp = new Marp().use(shiki())
const { html, css } = marp.render('# Hello, Marp!')
```

Mermaid diagrams

Requirements: @marp-team/marp-core/plugins/mermaid plugin and beautiful-mermaid dependency (npm install --save beautiful-mermaid)

Use a mermaid code fence to render mermaid diagrams.

```mermaid
graph LR
  M[Marpit framework] --> C{Marp Core}
  C --> CLI[Marp CLI]
  C --> VS[Marp for VS Code]
  C --> O[[Your own app]]
```

Marp Core uses beautiful-mermaid for deterministic server-side output. It supports the following diagram types:

```mermaid
graph LR
  M[Marpit framework] --> C{Marp Core}
  C --> CLI[Marp CLI]
  C --> VS[Marp for VS Code]
  C --> O[[Your own app]]
```

```mermaid
sequenceDiagram
  actor U as User
  participant M as Marp
  participant P as Markdown parser
  U->>+M: Request render
  M->>P: Parse Markdown
  P-->>M: Parsed result
  M-->>-U: Output
```

```mermaid
stateDiagram
  direction LR
  [*]-->Draft
  Draft-->FeedbackLoop
  state FeedbackLoop {
    Edit-->Preview
    Preview-->Edit
  }
  FeedbackLoop-->Export
  Export-->[*]: Present
```

```mermaid
classDiagram
  class Marp {
    +constructor(options: MarpOptions)
  }
  class Marpit {
    +constructor(options: Marpit.Options)
    +render(markdown: string, env?: object) RenderResult
  }
  Marp <|-- Marpit
```

```mermaid
erDiagram
  User ||--o{ MarpDocument : owns
  User ||--o{ Theme : owns
  User ||--o{ Asset : owns
  MarpDocument o{--o| Theme : uses
  MarpDocument o{..o{ Asset : uses
  User {
    int id
    string name
  }
  MarpDocument {
    int id
    string markdown
  }
  Theme {
    int id
    string css
  }
  Asset {
    int id
    string url
  }
```

```mermaid
xychart
  title "npm Downloads (2025-08 to 2026-07)"
  x-axis [Aug, Sep, Oct, Nov, Dec, Jan, Feb, Mar, Apr, May, Jun, Jul]
  y-axis "Downloads" 0 --> 500000
  bar [30958, 40546, 46111, 52399, 59409, 67686, 120845, 270062, 390907, 477828, 298524, 298974]
```

```mermaid
xychart
  title "npm Downloads (2025-08 to 2026-07)"
  x-axis [Aug, Sep, Oct, Nov, Dec, Jan, Feb, Mar, Apr, May, Jun, Jul]
  y-axis "Downloads" 0 --> 500000
  line [30958, 40546, 46111, 52399, 59409, 67686, 120845, 270062, 390907, 477828, 298524, 298974]
```

Interactive diagrams

Add interactive after the info string to enable beautiful-mermaid's interactive mode. For example, charts show a tooltip when hovering over a bar or line.

```mermaid interactive
xychart
  x-axis [Jan, Feb, Mar]
  bar [10, 15, 12]
```

Math typesetting

Requirements (At least one):

• @marp-team/marp-core/plugins/katex plugin and katex dependency (npm install --save katex)
• @marp-team/marp-core/plugins/mathjax plugin and MathJax dependencies (npm install --save @mathjax/src @mathjax/mathjax-bbm-font-extension @mathjax/mathjax-bboldx-font-extension @mathjax/mathjax-dsfont-font-extension @mathjax/mathjax-mhchem-font-extension)

Marp Core supports Pandoc-style math typesetting, powered by MathJax and KaTeX:

Render inline math such as $ax^2+bx+c$.

$$
f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi
$$

Choose a math library

Use the math global directive to select the library for the current Markdown document:

---
math: katex
---

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

For deterministic rendering, we recommend to declare math: mathjax or math: katex whenever a document uses math.