# @wix/htmdx
Render editable MDX-like source inside a plain HTML file. `@wix/htmdx` v4 uses one component definition model for Built-ins, shadcn, and host extensions. HTMDX is built for artifacts that should be easy for people to view and easy for agents to edit.
**Live examples:** [examples index](https://wix-incubator.github.io/htmdx/) · [decision brief](https://wix-incubator.github.io/htmdx/decision-brief.html) · [blank canvas](https://wix-incubator.github.io/htmdx/blank-layout.html) · [component tour](https://wix-incubator.github.io/htmdx/component-tour.html) · [Storybook](https://wix-incubator.github.io/htmdx/storybook/) — every page is itself an htmdx artifact; view source to see what an agent edits.
Start with one HTML file:
```html
```
The runtime auto-mounts each bare source block: it wraps the script in a generated `` host in place and renders there. Write `` yourself only when you need explicit output placement or `src`; disable scanning with `register({ automount: false })`.
Source block notes:
- `` inside the source ends the block early; keep such examples in an external `src` file instead.
CDN caveats:
- Generated artifacts can load the browser bundle from [jsDelivr](https://www.jsdelivr.com/) after the package is published to npm.
- Pin the package major in generated artifacts. Do not use floating aliases like `@latest`, because saved HTML artifacts must keep rendering a compatible runtime over time.
## Component manifest
Every release includes its machine-readable component contract at:
```text
https://cdn.jsdelivr.net/npm/@wix/htmdx@4/dist/components.json
```
Use the same major as the artifact's runtime URL. The `htmdx@2`
manifest lists the full runtime catalog — Built-ins plus the shadcn/ui pack,
each entry tagged with its `source`, body mode, prop schema, and canonical
example. It projects this data from the same definitions used by the runtime;
the executable `Component` field does not appear in JSON.
Each manifest entry declares `body: "markdown" | "htmdx" | "none"`.
`markdown` passes raw Markdown to the component and rejects nested tags;
Built-ins use this mode. `htmdx` accepts Markdown, HTML, and nested registered
component tags; shadcn and external definitions use it when they support
composition. `none` accepts only an empty or self-closing tag. A Built-in's
`purpose` and `example`
describe any stricter list or table grammar it checks; `npx @wix/htmdx skill
components` prints the same grammar per family in prose, with a worked example
per family. Invalid bodies fail the
whole compile, and browser hosts show the error with the raw source. Imports,
exports, brace expressions, event handlers, and function-valued props cannot
be expressed — the source is data, not code.
## Raw HTML
Ordinary HTML renders alongside Markdown, from an allowlist:
```mdx
Watch the announcement or play it here.
## Still Markdown in here
Shipped
```
Structural, text-level, table, and media elements are allowed — `p`, `div`,
`section`, `figure`, `details`, `table`, `a`, `span`, `br`, `video`, `audio`,
`iframe`, and friends. Anything outside the list (`form`, `input`, `object`,
`svg`, unknown tags) is not markup at the top level, so it stays literal text
the way it always has.
Inside a component body, a tag outside the list still renders the way it did
before the allowlist existed — it is passed through with its attributes — so
documents written against the old behavior keep compiling. The exception is the
handful of elements that turn source into code (`script`, `style`, `link`,
`meta`, `base`, `embed`, `object`, `template`), which fail the compile.
A registered component still wins on name collision, as before: with the shadcn
pack registered, `