# Share Pandoc HTML Output — One Self-Contained File, One Link
Canonical: https://commareports.com/share-pandoc-html
Published: 2026-08-28
> `pandoc --standalone --embed-resources` gives you a document that works anywhere except in someone else's inbox. Publish it to Comma: a URL, anchored comments, and revisions when you re-render.
# Share Pandoc HTML output
Pandoc is the easiest way to get from markdown, LaTeX, DOCX or reST to a
respectable HTML document:
```bash
pandoc report.md \
--standalone \
--embed-resources \
--toc \
--metadata title="Q3 analysis" \
-o report.html
```
Two flags do most of the work:
- **`--standalone`** wraps the converted fragment in a full document.
Without it you get body content with no ``, which renders
unstyled and looks broken the moment it leaves your machine.
- **`--embed-resources`** inlines the CSS, images and fonts as data
URIs. This is the flag that makes the output genuinely one file — the
deprecated `--self-contained` did the same thing.
Skip the metadata title and Pandoc warns that the format requires a
nonempty ``. It still renders; you just end up with an
untitled tab and a poor link preview.
## Then the delivery problem
You now have one honest, portable file, and the ways to send it are all
bad:
- **Email**: HTML attachments are the shape of a phishing page, so mail
filters quarantine them — [emailing an HTML report](/email-html-report).
- **Chat**: it downloads instead of opening, and on a phone it doesn't
open at all.
- **A repo**: `raw.githubusercontent.com` serves it as `text/plain`, so
the reader sees your markup —
[rendering HTML from a Gist](/alternatives/github-gist-html-alternatives).
## Publish it
Drag `report.html` into [Comma](https://commareports.com/) and you get a
URL. Because `--embed-resources` already inlined everything, this is the
simple case: one file, nothing else to bring.
If you rendered _without_ `--embed-resources` — a shared `--css`
stylesheet, images on disk — drag the whole directory instead and the
relative references are rewritten to the uploaded copies.
- Renders faithfully, on a laptop or a phone, with no account for the
reader.
- Access per report: private, team, anyone signed in, or link holders
with view, comment or edit — [sharing & access control](/docs/sharing).
## Re-render without breaking the link
```bash
pandoc report.md --standalone --embed-resources -o report.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 report.html \
--arg title "Q3 analysis" '{title: $title, html: $html}')"
```
Same id, same URL, new revision. The link you already sent keeps
working, and the previous version stays available to diff. Wire it into
a `Makefile` target or a CI job — [publishing from CI](/docs/ci).
## Review on the document itself
Comment permission lets a reviewer select the sentence and reply there.
The thread stays anchored across re-renders, so the note survives the
next `pandoc` run instead of being an email that no longer quotes
anything — [commenting on HTML](/comment-on-html).
## Limits
Entry HTML 5 MB. `--embed-resources` with a few full-page screenshots
crosses that quickly — render without it and publish the directory
instead, which also keeps the images cacheable. Assets: 25 MB per file,
250 MB and 500 files per report.
## Try it
Comma is free — unlimited reports, unlimited commenters, unlimited
revision history.
**[Publish a Pandoc document →](https://commareports.com/)**
### Related
- [Share an R Markdown report](/share-rmarkdown-report) · [Share Sphinx docs](/share-sphinx-docs)
- [Share an MkDocs site](/share-mkdocs-site) · [Comma vs Google Docs](/vs/google-docs)
- [Upload an HTML file and get a link](/upload-html-file-get-link)