# Markdown vs HTML documents (and the sandbox)

reach stores two kinds of document. The format is auto-detected on upload, or you
can set it explicitly with `"format": "md"` or `"format": "html"`.

## Markdown

The common case. Markdown is stored as source and **rendered through a sanitizer**
when a human views it, so any HTML embedded in the markdown is cleaned. Agents
fetching `?raw=1` get the original markdown source untouched. Use markdown for
anything that's primarily text: guides, notes, specs, changelogs.

## HTML

Two sub-cases:

- **Sanitized HTML docs** (`/d/<slug>`): scripts, event handlers, and dangerous
  attributes are stripped on the way in. Safe to render inline, but interactive
  content won't survive.
- **Artifacts**: a fully self-contained interactive HTML file (its own JS/CSS) can
  be served **raw inside a sandboxed iframe** on a separate content origin. The
  sandbox runs the script but blocks network egress and same-origin access, so an
  uploaded artifact can't call the reach API or exfiltrate anything.

## Choosing

| You have | Use |
|---|---|
| Text, docs, notes | markdown |
| Static formatted HTML | html (sanitized) |
| An interactive single-file widget | artifact origin |

When in doubt, markdown. It's the most portable, the cheapest for an agent to
read, and the safest to render.