How do I make Pandoc output a single shareable HTML file?

`pandoc doc.md -o doc.html --standalone --embed-resources`. `--standalone` wraps the fragment in a real document with a ` `; `--embed-resources` inlines the CSS, images and fonts as data URIs so there is no sibling folder to lose. (`--self-contained` is the deprecated spelling of the same idea.)

Why does Pandoc warn about a nonempty title element?

Because `--standalone` needs a title for the ` ` and the source didn't supply one. Add YAML metadata (`title: …`) at the top of the markdown, or pass `--metadata title="…"`. Without it you get a valid document with an empty ` `, which also makes for a bad link preview.

Do Pandoc's math and syntax highlighting survive sharing?

Syntax highlighting does — it's inline CSS generated by Pandoc's own highlighter. Math depends on the flag: `--mathjax` and `--katex` load a script from a CDN at view time, so the equations need network access to render. `--webtex` bakes images in instead.

Can I publish Pandoc output from a Makefile or CI job?

Yes. Render in the job, then POST the HTML to Comma's API — or PATCH an existing report id so the URL stays stable across rebuilds and each render is kept as a revision.

How is this different from committing the HTML to a repo?

A repo gives you the file back; it doesn't render it — GitHub serves raw HTML as plain text. It also has nowhere for a reviewer to say 'this paragraph is wrong'. A published report renders, and comments anchor to the paragraph.

Share Pandoc HTML output

Pandoc is the easiest way to get from markdown, LaTeX, DOCX or reST to a respectable HTML document:

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 <head>, 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 <title>. 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.
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.

Publish it

Drag report.html into Comma 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.

Re-render without breaking the link

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.

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.

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 →