` can't take children, an unknown tag won't compile).\n\n### Why not just HTML?\n\nA reasonable alternative is to render the components to HTML (they're JSX after all) and convert that to markdown with rehype-remark or turndown. The problem is that HTML can express more than markdown can, so converting back is lossy - the converter has to guess how to represent things that have no markdown equivalent, and code blocks in particular come back as messy `` markup. It's also more steps (JSX -> HTML -> parse -> markdown -> stringify) and you lose type safety on the markdown you actually emit. Going straight to mdast avoids all of that: you stay in markdown the whole time and can only produce valid markdown.\n\n## Install\n\n```shell\nnpm i mdast-jsx\n```\n\n```shell\npnpm add mdast-jsx\n```\n\n## Usage\n\nAdd the following pragmas to the top of your `.tsx` file, then write components (functions) that return mdast nodes:\n\n```tsx\n/** @jsxRuntime automatic */\n/** @jsxImportSource mdast-jsx */\n\nexport const MyComponent = () => (\n <>\n Title \n Body text. \n \n);\n```\n\nThe pragmas are per-file comments the compiler reads (or set `jsxImportSource: \"mdast-jsx\"` in your tsconfig to apply it everywhere):\n\n- `@jsxRuntime automatic` compiles JSX into `jsx(...)` calls (the modern transform) instead of `React.createElement`.\n- `@jsxImportSource mdast-jsx` points those calls at this runtime, so `\n \n Name \n Count \n \n \n a \n 1 \n \n
,\n { extensions: [gfmToMarkdown()] },\n);\n```\n\nproduces:\n\n```md\n| Name | Count |\n| :--- | ----: |\n| a | 1 |\n```\n\n### Compiling\n\nThis is a standard automatic JSX runtime: if a tool can compile React's automatic runtime, it can compile this - the only difference is `jsxImportSource`. You opt in either with the per-file pragmas shown above, or once for the whole project with `jsxImportSource: \"mdast-jsx\"` (and `jsx: \"react-jsx\"`) in your tsconfig.\n\n> Note this doesn't use React - the JSX is just syntax the compiler turns into plain mdast objects. `react-jsx` is a legacy name for the `automatic` transform, not a React dependency.\n\nIn practice you will:\n\n- **Just run it** - `tsx file.tsx` or `bun file.tsx` execute `.tsx` directly with the transform included; the fastest way to try it.\n- **Compile in a project** - tsc (set `jsx: \"react-jsx\"` to emit runnable `jsx()` calls), esbuild, and Babel all support the automatic runtime and `jsxImportSource`, via their config or the pragmas. (With tsc's `jsx: \"preserve\"` the JSX is emitted untransformed for a downstream tool, so pair it with a runner or bundler.)\n- **Use Vite / Vitest** - needs no JSX-specific config: both read `jsx` and `jsxImportSource` from your tsconfig and honor the per-file pragmas, regardless of the underlying transformer (esbuild on Vite ≤7 / Vitest ≤3, Oxc on Vite 8 / Vitest 4).\n\n## How it maps to mdast\n\nThe JSX is almost a direct reflection of mdast. A lowercase tag becomes a node of that `type`, props become the node's fields, and children become its `children`:\n\n```tsx\nSetup \n// { type: 'heading', depth: 2, children: [{ type: 'text', value: 'Setup' }] }\n```\n\nBare strings become `text` nodes, and inline elements nest the way you'd expect:\n\n```tsx\n\n Run \n// {\n// type: 'paragraph',\n// children: [\n// { type: 'text', value: 'Run ' },\n// { type: 'inlineCode', value: 'npm i' },\n// { type: 'text', value: ' to install.' },\n// ],\n// }\n```\n\nIf you're ever unsure which tags are available or how to use them, check the [mdast schema](https://github.com/syntax-tree/mdast#nodes).\n\nA few rules cover the spots where mdast isn't perfectly uniform:\n\n- **Literal nodes** (`code`, `inlineCode`, `html`, `yaml`) hold their content in a `value` field, not children, so they're self-closing and take a `value` prop:\n\n ```tsx\n \n {label} \n \n );\n ```\n\n- **Fragments (`<>`) become a `root`** and flatten when nested, so `.map` drops in cleanly:\n\n ```tsx\n \n {items.map((i) => (\n {i} \n ))}\n \n ```\n\n- `null` / `false` / whitespace-only children are dropped, so `{cond && Show more
...\" />\n```\n\nThere are no native ``, ``, etc. tags, because those aren't mdast nodes - anything markdown can't express goes through `` as a string.\n\nIf you want to _nest markdown_ inside an HTML block (e.g. a collapsible ``), split the open and close tags into their own `html` nodes and place mdast nodes between them:\n\n```tsx\n<>\n Details
\" />\n \n Real markdown inside.\n \n \" />\n\n```\n\n```md\nDetails
\n\nReal **markdown** inside.\n\n\n```\n\nThe blank lines are what matter here - the serializer adds them between block siblings, and a blank line inside an HTML block is what tells the final renderer (GitHub, etc) to parse the content between the tags as markdown rather than literal text. (Note: `\\n` in a plain attribute string is literal; use `value={'...\\n...'}` if you need actual newlines.)\n\n## Maintenance\n\nmdast-jsx is just a thin wrapper around mdast. It has almost no knowledge of markdown itself - the core is essentially:\n\n```ts\nfunction jsx(type, props) {\n if (typeof type === 'function') return type(props); // a component\n const { children, ...fields } = props;\n return { type, ...fields, children: normalize(children) }; // an mdast node\n}\n```\n\nIt simply builds an object with the right node shape, and the type system ensures that the shape is correct.\n\n`normalize` is the only other moving part - it flattens arrays/fragments, drops falsy children, and wraps bare strings as `text` nodes. Notably there's no reconciliation, no state, no lifecycle. Those exist in React to keep a live UI in sync over time; here we build a tree once and serialize it, so none of it applies.\n\nThe element types aren't hand-maintained either - they're derived from `@types/mdast` with a mapped type, so the set of usable tags _is_ the mdast node set and stays in sync on its own.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}