# Share Marp Slides — Publish a Markdown Deck as a Link

Canonical: https://commareports.com/share-marp-slides
Published: 2026-08-29

> Marp turns markdown into an HTML deck. Publishing it is the missing step: one command from your build, a permanent URL per deck, and comments anchored to the slide someone is arguing with.

# Share Marp slides

Marp's premise is that a deck should be a markdown file in the repo, next
to the thing it describes. That works right up until someone has to look
at it, at which point you are back to exporting a PDF or telling people to
`npm i -g @marp-team/marp-cli` first.

The build already emits the right artifact. It just has nowhere to live.

## Build, then publish

```bash
npx @marp-team/marp-cli@latest deck.md -o deck.html

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html deck.html \
        --arg title "Design review — $(git rev-parse --short HEAD)" \
        '{title: $title, html: $html}')"
```

Marp CLI inlines its theme CSS, so the HTML output is one self-sufficient
file — which is the shape that publishes in a single call. Use a
[scoped token](/docs/api-tokens) (`reports:write`) from CI secrets, and
`PATCH` a saved id rather than `POST`ing, so the deck keeps one permanent
URL with a revision per build instead of a new orphan link every time.

For a one-off, drag `deck.html` into [the app](https://commareports.com/)
and skip all of that.

## Local images

Images referenced from your markdown are the one thing Marp doesn't inline
by default. Two ways through:

- Build with `--allow-local-files` so Marp embeds them, keeping the
  single-file shape.
- Or drop the whole output directory into the app — the images upload as
  [assets](/docs/api) and the relative references are rewritten to the
  uploaded copies.

## Why HTML and not PDF

Marp will happily emit a PDF, and it is the wrong artifact for review:

- Embedded video, iframes and any live chart flatten or vanish.
- The reader has a copy, so two readers have two copies.
- Feedback lands in a mail thread, detached from the slide it is about.

A published HTML deck keeps the first, has one address instead of copies,
and takes **anchored comments** — select the claim on the slide, leave a
thread, and it stays there across revisions. See
[commenting on HTML](/comment-on-html).

## The deck as a living document

Because the source is markdown in the repo, the deck regenerates. Wire the
publish step into the same job that builds it and the URL is always
current — which makes a Marp deck a reasonable format for the things that
usually rot as wiki pages: onboarding walkthroughs, architecture
overviews, a weekly status readout. Add a
[routine](/features/routines/scheduled-html-reports) if it should refresh
on a schedule rather than on a push.

## Who can see it

Per report: private, team, anyone signed in at your domain, or anyone with
the link, with view / comment / edit rights for link holders. See
[sharing & access control](/docs/sharing).

## Limits

- **Entry HTML: 5 MB** — generous for a deck, unless every slide is a
  full-bleed inlined photograph. Assets: 25 MB per file, 250 MB and 500
  files total.
- **Scripts run, sandboxed** (`allow-scripts`, no `allow-same-origin`).
- **60 requests/minute per token.**

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history.

**[Publish a Marp deck →](https://commareports.com/)**

### Related

- [Share a reveal.js presentation](/share-revealjs-presentation)
- [Share Pandoc HTML](/share-pandoc-html) — the other markdown-to-HTML route
- [Publish from CI](/docs/ci) · [Scheduled HTML reports](/features/routines/scheduled-html-reports)
- [Stop screenshotting reports](/stop-screenshotting-reports)