{"id":13483636,"url":"https://github.com/syntax-tree/mdast-util-mdx","last_synced_at":"2025-04-10T01:24:12.985Z","repository":{"id":57293490,"uuid":"319756735","full_name":"syntax-tree/mdast-util-mdx","owner":"syntax-tree","description":"mdast extension to parse and serialize MDX (or MDX.js)","archived":false,"fork":false,"pushed_at":"2024-02-10T09:25:36.000Z","size":111,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-24T03:11:21.334Z","etag":null,"topics":["esm","expression","jsx","markdown","md","mdast","mdast-util","mdx","mdxjs"],"latest_commit_sha":null,"homepage":"https://unifiedjs.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syntax-tree.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2020-12-08T20:45:34.000Z","updated_at":"2025-03-07T16:57:40.000Z","dependencies_parsed_at":"2024-02-10T10:28:20.824Z","dependency_job_id":"7a1678e0-4980-478b-b380-795134e225ed","html_url":"https://github.com/syntax-tree/mdast-util-mdx","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"bdd0226fb82853e928b139fe1a9c0423aa35e727"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-mdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-mdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-mdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntax-tree%2Fmdast-util-mdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntax-tree","download_url":"https://codeload.github.com/syntax-tree/mdast-util-mdx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248138835,"owners_count":21053966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esm","expression","jsx","markdown","md","mdast","mdast-util","mdx","mdxjs"],"created_at":"2024-07-31T17:01:13.567Z","updated_at":"2025-04-10T01:24:12.955Z","avatar_url":"https://github.com/syntax-tree.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":["JavaScript"],"sub_categories":[],"readme":"# mdast-util-mdx\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n[![Sponsors][sponsors-badge]][collective]\n[![Backers][backers-badge]][collective]\n[![Chat][chat-badge]][chat]\n\n[mdast][] extensions to parse and serialize [MDX][]: ESM, JSX, and expressions.\n\n## Contents\n\n*   [What is this?](#what-is-this)\n*   [When to use this](#when-to-use-this)\n*   [Install](#install)\n*   [Use](#use)\n*   [API](#api)\n    *   [`mdxFromMarkdown()`](#mdxfrommarkdown)\n    *   [`mdxToMarkdown(options?)`](#mdxtomarkdownoptions)\n    *   [`ToMarkdownOptions`](#tomarkdownoptions)\n*   [HTML](#html)\n*   [Syntax](#syntax)\n*   [Syntax tree](#syntax-tree)\n*   [Types](#types)\n*   [Compatibility](#compatibility)\n*   [Related](#related)\n*   [Contribute](#contribute)\n*   [License](#license)\n\n## What is this?\n\nThis package contains two extensions that add support for MDX syntax in\nmarkdown to [mdast][]: ESM (`import x from 'y'`), JSX (`\u003ca /\u003e`), and\nexpressions (`{Math.PI}`).\nThese extensions plug into\n[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing\nMDX in markdown into a syntax tree) and\n[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing\nMDX in syntax trees to markdown).\n\n## When to use this\n\nYou can use these extensions when you are working with\n`mdast-util-from-markdown` and `mdast-util-to-markdown` already.\n\nWhen working with `mdast-util-from-markdown`, you must combine this package\nwith [`micromark-extension-mdx`][mdx] or [`micromark-extension-mdxjs`][mdxjs].\n\nInstead of this package, you can also use the extensions separately:\n\n*   [`mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)\n    — support MDX expressions\n*   [`mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)\n    — support MDX JSX\n*   [`mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)\n    — support MDX ESM\n\nAll these packages are used in [`remark-mdx`][remark-mdx], which\nfocusses on making it easier to transform content by abstracting these\ninternals away.\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install mdast-util-mdx\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {mdxFromMarkdown, mdxToMarkdown} from 'https://esm.sh/mdast-util-mdx@3'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {mdxFromMarkdown, mdxToMarkdown} from 'https://esm.sh/mdast-util-mdx@3?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay our document `example.mdx` contains:\n\n```mdx\nimport Box from \"place\"\n\nHere’s an expression:\n\n{\n  1 + 1 /* } */\n}\n\nWhich you can also put inline: {1+1}.\n\n\u003cBox\u003e\n  \u003cSmallerBox\u003e\n    - Lists, which can be indented.\n  \u003c/SmallerBox\u003e\n\u003c/Box\u003e\n```\n\n…and our module `example.js` looks as follows:\n\n```js\nimport fs from 'node:fs/promises'\nimport {mdxjs} from 'micromark-extension-mdxjs'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\nimport {mdxFromMarkdown, mdxToMarkdown} from 'mdast-util-mdx'\nimport {toMarkdown} from 'mdast-util-to-markdown'\n\nconst doc = await fs.readFile('example.mdx')\n\nconst tree = fromMarkdown(doc, {\n  extensions: [mdxjs()],\n  mdastExtensions: [mdxFromMarkdown()]\n})\n\nconsole.log(tree)\n\nconst out = toMarkdown(tree, {extensions: [mdxToMarkdown()]})\n\nconsole.log(out)\n```\n\n…now running `node example.js` yields (positional info removed for brevity):\n\n```js\n{\n  type: 'root',\n  children: [\n    {\n      type: 'mdxjsEsm',\n      value: 'import Box from \"place\"',\n      data: {\n        estree: {\n          type: 'Program',\n          body: [\n            {\n              type: 'ImportDeclaration',\n              specifiers: [\n                {\n                  type: 'ImportDefaultSpecifier',\n                  local: {type: 'Identifier', name: 'Box'}\n                }\n              ],\n              source: {type: 'Literal', value: 'place', raw: '\"place\"'}\n            }\n          ],\n          sourceType: 'module'\n        }\n      }\n    },\n    {\n      type: 'paragraph',\n      children: [{type: 'text', value: 'Here’s an expression:'}]\n    },\n    {\n      type: 'mdxFlowExpression',\n      value: '\\n1 + 1 /* } */\\n',\n      data: {\n        estree: {\n          type: 'Program',\n          body: [\n            {\n              type: 'ExpressionStatement',\n              expression: {\n                type: 'BinaryExpression',\n                left: {type: 'Literal', value: 1, raw: '1'},\n                operator: '+',\n                right: {type: 'Literal', value: 1, raw: '1'}\n              }\n            }\n          ],\n          sourceType: 'module'\n        }\n      }\n    },\n    {\n      type: 'paragraph',\n      children: [\n        {type: 'text', value: 'Which you can also put inline: '},\n        {\n          type: 'mdxTextExpression',\n          value: '1+1',\n          data: {\n            estree: {\n              type: 'Program',\n              body: [\n                {\n                  type: 'ExpressionStatement',\n                  expression: {\n                    type: 'BinaryExpression',\n                    left: {type: 'Literal', value: 1, raw: '1'},\n                    operator: '+',\n                    right: {type: 'Literal', value: 1, raw: '1'}\n                  }\n                }\n              ],\n              sourceType: 'module'\n            }\n          }\n        },\n        {type: 'text', value: '.'}\n      ]\n    },\n    {\n      type: 'mdxJsxFlowElement',\n      name: 'Box',\n      attributes: [],\n      children: [\n        {\n          type: 'mdxJsxFlowElement',\n          name: 'SmallerBox',\n          attributes: [],\n          children: [\n            {\n              type: 'list',\n              ordered: false,\n              start: null,\n              spread: false,\n              children: [\n                {\n                  type: 'listItem',\n                  spread: false,\n                  checked: null,\n                  children: [\n                    {\n                      type: 'paragraph',\n                      children: [\n                        {type: 'text', value: 'Lists, which can be indented.'}\n                      ]\n                    }\n                  ]\n                }\n              ]\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n```mdx\nimport Box from \"place\"\n\nHere’s an expression:\n\n{\n  1 + 1 /* } */\n}\n\nWhich you can also put inline: {1+1}.\n\n\u003cBox\u003e\n  \u003cSmallerBox\u003e\n    *   Lists, which can be indented.\n  \u003c/SmallerBox\u003e\n\u003c/Box\u003e\n```\n\n## API\n\nThis package exports the identifiers [`mdxFromMarkdown`][api-mdx-from-markdown]\nand [`mdxToMarkdown`][api-mdx-to-markdown].\nThere is no default export.\n\n### `mdxFromMarkdown()`\n\nCreate an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]\nto enable MDX (ESM, JSX, expressions).\n\n###### Returns\n\nExtension for `mdast-util-from-markdown` to enable MDX\n([`FromMarkdownExtension`][from-markdown-extension]).\n\nWhen using the [syntax extensions with `addResult`][mdxjs], ESM and expression\nnodes will have `data.estree` fields set to ESTree [`Program`][program] node.\n\n### `mdxToMarkdown(options?)`\n\nCreate an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]\nto enable MDX (ESM, JSX, expressions).\n\nExtension for [`mdast-util-to-markdown`][mdast-util-to-markdown].\n\n###### Parameters\n\n*   `options` ([`ToMarkdownOptions`][api-to-markdown-options])\n    — configuration\n\n###### Returns\n\nExtension for `mdast-util-to-markdown` to enable MDX\n([`FromMarkdownExtension`][to-markdown-extension]).\n\n### `ToMarkdownOptions`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n*   `quote` (`'\"'` or `\"'\"`, default: `'\"'`)\n    — preferred quote to use around attribute values\n*   `quoteSmart` (`boolean`, default: `false`)\n    — use the other quote if that results in less bytes\n*   `tightSelfClosing` (`boolean`, default: `false`)\n    — do not use an extra space when closing self-closing elements: `\u003cimg/\u003e`\n    instead of `\u003cimg /\u003e`\n*   `printWidth` (`number`, default: `Infinity`)\n    — try and wrap syntax at this width.\n    When set to a finite number (say, `80`), the formatter will print\n    attributes on separate lines when a tag doesn’t fit on one line.\n    The normal behavior is to print attributes with spaces between them instead\n    of line endings\n\n## HTML\n\nMDX has no representation in HTML.\nThough, when you are dealing with MDX, you will likely go *through* hast.\nYou can enable passing MDX through to hast by configuring\n[`mdast-util-to-hast`][mdast-util-to-hast] with `passThrough: ['mdxjsEsm',\n'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression']`.\n\n## Syntax\n\nSee [Syntax in `micromark-extension-mdxjs`][mdxjs].\n\n## Syntax tree\n\nThis utility combines several mdast utilities.\nSee their readmes for the node types supported in the tree:\n\n*   [`mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression#syntax-tree)\n    — support MDX expressions\n*   [`mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx#syntax-tree)\n    — support MDX JSX\n*   [`mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm#syntax-tree)\n    — support MDX ESM\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the additional types\n`MdxFlowExpression` and `MdxTextExpression`\nfrom `mdast-util-mdx-expression`;\n`MdxJsxAttribute`,\n`MdxJsxAttributeValueExpression`,\n`MdxJsxExpressionAttribute`,\n`MdxJsxFlowElement`,\n`MdxJsxTextElement`,\nand [`ToMarkdownOptions`][api-to-markdown-options]\nfrom `mdast-util-mdx-jsx`;\nand `MdxjsEsm` from `mdast-util-mdxjs-esm`.\n\nIt also registers the node types with `@types/mdast` and `@types/hast`.\nIf you’re working with the syntax tree, make sure to import this utility\nsomewhere in your types, as that registers the new node types in the tree.\n\n```js\n/**\n * @typedef {import('mdast-util-mdx')}\n */\n\nimport {visit} from 'unist-util-visit'\n\n/** @type {import('mdast').Root} */\nconst tree = getMdastNodeSomeHow()\n\nvisit(tree, function (node) {\n  // `node` can now be an expression, JSX, or ESM node.\n})\n```\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release, we drop support for unmaintained versions of\nNode.\nThis means we try to keep the current release line, `mdast-util-mdx@^3`,\ncompatible with Node.js 16.\n\nThis utility works with `mdast-util-from-markdown` version 2+ and\n`mdast-util-to-markdown` version 2+.\n\n## Related\n\n*   [`remark-mdx`][remark-mdx]\n    — remark plugin to support MDX\n*   [`micromark-extension-mdx`][mdx]\n    — micromark extension to parse MDX\n*   [`micromark-extension-mdxjs`][mdxjs]\n    — micromark extension to parse JavaScript-aware MDX\n\n## Contribute\n\nSee [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for\nways to get started.\nSee [`support.md`][support] for ways to get help.\n\nThis project has a [code of conduct][coc].\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.\n\n## License\n\n[MIT][license] © [Titus Wormer][author]\n\n\u003c!-- Definitions --\u003e\n\n[build-badge]: https://github.com/syntax-tree/mdast-util-mdx/workflows/main/badge.svg\n\n[build]: https://github.com/syntax-tree/mdast-util-mdx/actions\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx.svg\n\n[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx\n\n[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx.svg\n\n[downloads]: https://www.npmjs.com/package/mdast-util-mdx\n\n[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size\u0026query=$.size.compressedSize\u0026url=https://deno.bundlejs.com/?q=mdast-util-mdx\n\n[size]: https://bundlejs.com/?q=mdast-util-mdx\n\n[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg\n\n[backers-badge]: https://opencollective.com/unified/backers/badge.svg\n\n[collective]: https://opencollective.com/unified\n\n[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg\n\n[chat]: https://github.com/syntax-tree/unist/discussions\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[typescript]: https://www.typescriptlang.org\n\n[license]: license\n\n[author]: https://wooorm.com\n\n[health]: https://github.com/syntax-tree/.github\n\n[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md\n\n[support]: https://github.com/syntax-tree/.github/blob/main/support.md\n\n[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md\n\n[mdast]: https://github.com/syntax-tree/mdast\n\n[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown\n\n[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension\n\n[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown\n\n[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options\n\n[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast\n\n[mdx]: https://github.com/micromark/micromark-extension-mdx\n\n[mdxjs]: https://github.com/micromark/micromark-extension-mdxjs\n\n[remark-mdx]: https://github.com/mdx-js/mdx/tree/next/packages/remark-mdx\n\n[program]: https://github.com/estree/estree/blob/master/es2015.md#programs\n\n[api-mdx-from-markdown]: #mdxfrommarkdown\n\n[api-mdx-to-markdown]: #mdxtomarkdownoptions\n\n[api-to-markdown-options]: #tomarkdownoptions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-mdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntax-tree%2Fmdast-util-mdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntax-tree%2Fmdast-util-mdx/lists"}