How do I share a Marp deck as a link?

Build it with `marp deck.md -o deck.html`, which writes one self-contained HTML file, then publish that file to Comma — drag it in, or POST it to https://commareports.com/api/v1/reports from CI. Reviewers open a URL; there is no export step and no attachment.

Does the Marp HTML output need its assets uploaded separately?

Usually not. Marp CLI inlines its theme CSS into the HTML output, so a plain deck is a single file. Local images referenced from your markdown are the exception — pass `--allow-local-files` when building, or upload the image folder alongside the deck as report assets.

Should I publish the HTML or the PDF?

The HTML. Marp can emit PDF, but that flattens any embedded video or iframe and leaves reviewers nowhere to write. A published HTML deck keeps the interactive parts and takes comments anchored to individual slides.

Can I regenerate the deck from CI and keep the same link?

Yes. Save the report id once and PATCH it on each build. Every run appends a revision at the same URL, so a deck kept in the repo alongside its markdown source always has one current address.

Does this work for Marp for VS Code exports too?

Yes — the extension's HTML export is the same shape as the CLI's. Export to HTML, drag the file in, send the link.

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

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 (reports:write) from CI secrets, and PATCH a saved id rather than POSTing, 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 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 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.

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 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.

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 →

Share a reveal.js presentation
Share Pandoc HTML — the other markdown-to-HTML route
Publish from CI · Scheduled HTML reports
Stop screenshotting reports