Skip to main content
MDX is a third Page format alongside Markdown and HTML. It combines readable prose with JSX, diagrams, built-in Plasma components, and page-local TypeScript modules.

​
When to use MDX

Ask for MDX when a document needs interactive sections without turning the whole result into a custom HTML application.
Create an MDX project review with a written summary, a Mermaid dependency diagram, and an interactive estimate calculator. Keep calculator inputs local unless I explicitly save them.
Use Markdown for simpler documents and standard components. Use HTML for a fully custom interface. Your request can describe the outcome without specifying code.

​
What an MDX Page can contain

  • Markdown headings, lists, tables, and prose.
  • Mermaid diagram fences and supported Plasma component fences.
  • Retained Page images and resource references.
  • React components with logic declared in page-local TypeScript modules.
  • Supported data bindings and resource-tool actions.
HTML and MDX Pages receive shared light/dark styling defaults. The Page follows the viewer’s theme without requiring a custom external stylesheet.

​
Authoring boundaries

Agents publish MDX using the Page format mdx. TypeScript belongs in top-level module fences such as tsx module=components/Calculator.tsx; it is not supported as arbitrary TypeScript syntax in the document prose. Modules can import other declared page-local modules, react, and @plasma/page. Arbitrary npm packages, Node built-ins, and URL imports are not supported. There is no package-install step inside the Page. The @plasma/page SDK provides read hooks, event-driven tool calls, data bindings, and Plasma components. Use read hooks for reads; writes belong behind explicit actions. Host-opening components such as resource cards should be declared in Plasma fences so their host actions can be trusted. Publication validates and links declared modules, reporting syntax, import, and missing-export errors. It strips TypeScript types but does not perform full type checking. Some document-rendering errors only appear when the Page opens, so the author should inspect the rendered result after publishing.

​
Data, permissions, and sharing

MDX runs in the same isolated Page environment as HTML. Tool calls require the current viewer’s and original authoring agent’s permissions. A shared Page does not share private credentials or grant resource access. Current agent-authored MDX Pages can use the supported tool runtime. Historical revisions and human-authored Pages cannot call those tools. Direct browser networking remains blocked; supported external requests use the backend-mediated runtime. Public share links show sanitized Markdown prose, not the live MDX application. Check the visitor view before sharing a Page whose meaning depends on interactive components.

​
Saved source and revisions

The source can be uploaded or imported from a repository’s .mdx file. Git imports capture the selected commit rather than continuously following the branch. Updating the Page creates a document revision. Shared records, comments, and external writes keep their own state; restoring a document revision does not undo them. See Interactive Pages, Evidence and sources, and Tables and data.