AK-21/Graphite-Industrial-Intelligence

1# mdast-util-mdx-expression2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7[![Sponsors][sponsors-badge]][collective]8[![Backers][backers-badge]][collective]9[![Chat][chat-badge]][chat]10 11[mdast][] extensions to parse and serialize [MDX][] expressions (`{Math.PI}`).12 13## Contents14 15* [What is this?](#what-is-this)16* [When to use this](#when-to-use-this)17* [Install](#install)18* [Use](#use)19* [API](#api)20  * [`mdxExpressionFromMarkdown()`](#mdxexpressionfrommarkdown)21  * [`mdxExpressionToMarkdown()`](#mdxexpressiontomarkdown)22  * [`MdxFlowExpression`](#mdxflowexpression)23  * [`MdxTextExpression`](#mdxtextexpression)24  * [`MdxFlowExpressionHast`](#mdxflowexpressionhast)25  * [`MdxTextExpressionHast`](#mdxtextexpressionhast)26* [HTML](#html)27* [Syntax](#syntax)28* [Syntax tree](#syntax-tree)29  * [Nodes](#nodes)30  * [Content model](#content-model)31* [Types](#types)32* [Compatibility](#compatibility)33* [Related](#related)34* [Contribute](#contribute)35* [License](#license)36 37## What is this?38 39This package contains two extensions that add support for MDX expression syntax40in markdown to [mdast][].41These extensions plug into42[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing43expressions in markdown into a syntax tree) and44[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing45expressions in syntax trees to markdown).46 47## When to use this48 49You can use these extensions when you are working with50`mdast-util-from-markdown` and `mdast-util-to-markdown` already.51 52When working with `mdast-util-from-markdown`, you must combine this package53with [`micromark-extension-mdx-expression`][extension].54 55When you are working with syntax trees and want all of MDX, use56[`mdast-util-mdx`][mdast-util-mdx] instead.57 58All these packages are used in [`remark-mdx`][remark-mdx], which59focusses on making it easier to transform content by abstracting these60internals away.61 62## Install63 64This package is [ESM only][esm].65In Node.js (version 16+), install with [npm][]:66 67```sh68npm install mdast-util-mdx-expression69```70 71In Deno with [`esm.sh`][esmsh]:72 73```js74import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2'75```76 77In browsers with [`esm.sh`][esmsh]:78 79```html80<script type="module">81  import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2?bundle'82</script>83```84 85## Use86 87Say our document `example.mdx` contains:88 89```mdx90{91  a + 192}93 94b {true}.95```96 97…and our module `example.js` looks as follows:98 99```js100import fs from 'node:fs/promises'101import * as acorn from 'acorn'102import {mdxExpression} from 'micromark-extension-mdx-expression'103import {fromMarkdown} from 'mdast-util-from-markdown'104import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'mdast-util-mdx-expression'105import {toMarkdown} from 'mdast-util-to-markdown'106 107const doc = await fs.readFile('example.mdx')108 109const tree = fromMarkdown(doc, {110  extensions: [mdxExpression({acorn, addResult: true})],111  mdastExtensions: [mdxExpressionFromMarkdown()]112})113 114console.log(tree)115 116const out = toMarkdown(tree, {extensions: [mdxExpressionToMarkdown()]})117 118console.log(out)119```120 121…now running `node example.js` yields (positional info removed for brevity):122 123```js124{125  type: 'root',126  children: [127    {128      type: 'mdxFlowExpression',129      value: '\na + 1\n',130      data: {131        estree: {132          type: 'Program',133          body: [134            {135              type: 'ExpressionStatement',136              expression: {137                type: 'BinaryExpression',138                left: {type: 'Identifier', name: 'a'},139                operator: '+',140                right: {type: 'Literal', value: 1, raw: '1'}141              }142            }143          ],144          sourceType: 'module'145        }146      }147    },148    {149      type: 'paragraph',150      children: [151        {type: 'text', value: 'b '},152        {153          type: 'mdxTextExpression',154          value: 'true',155          data: {156            estree: {157              type: 'Program',158              body: [159                {160                  type: 'ExpressionStatement',161                  expression: {type: 'Literal', value: true, raw: 'true'}162                }163              ],164              sourceType: 'module'165            }166          }167        },168        {type: 'text', value: '.'}169      ]170    }171  ]172}173```174 175```markdown176{177  a + 1178}179 180b {true}.181```182 183## API184 185This package exports the identifiers186[`mdxExpressionFromMarkdown`][api-mdx-expression-from-markdown] and187[`mdxExpressionToMarkdown`][api-mdx-expression-to-markdown].188There is no default export.189 190### `mdxExpressionFromMarkdown()`191 192Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]193to enable MDX expressions in markdown.194 195When using the [micromark syntax extension][extension] with `addResult`, nodes196will have a `data.estree` field set to an ESTree [`Program`][program] node.197 198###### Returns199 200Extension for `mdast-util-from-markdown` to enable MDX expressions201([`FromMarkdownExtension`][from-markdown-extension]).202 203### `mdxExpressionToMarkdown()`204 205Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]206to enable MDX expressions in markdown.207 208###### Returns209 210Extension for `mdast-util-to-markdown` to enable MDX expressions211([`ToMarkdownExtension`][to-markdown-extension]).212 213### `MdxFlowExpression`214 215MDX expression node, occurring in flow (block) (TypeScript type).216 217###### Type218 219```ts220import type {Program} from 'estree-jsx'221import type {Data, Literal} from 'mdast'222 223interface MdxFlowExpression extends Literal {224  type: 'mdxFlowExpression'225  data?: MdxFlowExpressionData | undefined226}227 228interface MdxFlowExpressionData extends Data {229  estree?: Program | null | undefined230}231```232 233### `MdxTextExpression`234 235MDX expression node, occurring in text (block) (TypeScript type).236 237###### Type238 239```ts240import type {Program} from 'estree-jsx'241import type {Data, Literal} from 'mdast'242 243interface MdxTextExpression extends Literal {244  type: 'mdxTextExpression'245  data?: MdxTextExpressionData | undefined246}247 248interface MdxTextExpressionData extends Data {249  estree?: Program | null | undefined250}251```252 253### `MdxFlowExpressionHast`254 255Same as [`MdxFlowExpression`][api-mdx-flow-expression], but registered with256`@types/hast` (TypeScript type).257 258###### Type259 260```ts261import type {Program} from 'estree-jsx'262import type {Data, Literal} from 'hast'263 264interface MdxFlowExpressionHast extends Literal {265  type: 'mdxFlowExpression'266  data?: MdxFlowExpressionData | undefined267}268 269interface MdxFlowExpressionData extends Data {270  estree?: Program | null | undefined271}272```273 274### `MdxTextExpressionHast`275 276Same as [`MdxTextExpression`][api-mdx-text-expression], but registered with277`@types/hast` (TypeScript type).278 279###### Type280 281```ts282import type {Program} from 'estree-jsx'283import type {Data, Literal} from 'hast'284 285interface MdxTextExpressionHast extends Literal {286  type: 'mdxTextExpression'287  data?: MdxTextExpressionData | undefined288}289 290interface MdxTextExpressionData extends Data {291  estree?: Program | null | undefined292}293```294 295## HTML296 297MDX expressions have no representation in HTML.298Though, when you are dealing with MDX, you will likely go *through* hast.299You can enable passing MDX expressions through to hast by configuring300[`mdast-util-to-hast`][mdast-util-to-hast] with301`passThrough: ['mdxFlowExpression', 'mdxTextExpression']`.302 303## Syntax304 305See [Syntax in `micromark-extension-mdx-expression`][syntax].306 307## Syntax tree308 309The following interfaces are added to **[mdast][]** by this utility.310 311### Nodes312 313#### `MdxFlowExpression`314 315```idl316interface MdxFlowExpression <: Literal {317  type: 'mdxFlowExpression'318}319```320 321**MdxFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript322expression embedded in flow (block).323It can be used where **[flow][dfn-flow-content]** content is expected.324Its content is represented by its `value` field.325 326For example, the following markdown:327 328```markdown329{330  1 + 1331}332```333 334Yields:335 336```js337{type: 'mdxFlowExpression', value: '\n1 + 1\n'}338```339 340#### `MdxTextExpression`341 342```idl343interface MdxTextExpression <: Literal {344  type: 'mdxTextExpression"345}346```347 348**MdxTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript349expression embedded in text (span, inline).350It can be used where **[phrasing][dfn-phrasing-content]** content is expected.351Its content is represented by its `value` field.352 353For example, the following markdown:354 355```markdown356a {1 + 1} b.357```358 359Yields:360 361```js362{type: 'mdxTextExpression', value: '1 + 1'}363```364 365### Content model366 367#### `FlowContent` (MDX expression)368 369```idl370type FlowContentMdxExpression = MdxFlowExpression | FlowContent371```372 373#### `PhrasingContent` (MDX expression)374 375```idl376type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent377```378 379## Types380 381This package is fully typed with [TypeScript][].382It exports the additional types [`MdxFlowExpression`][api-mdx-flow-expression],383[`MdxFlowExpressionHast`][api-mdx-flow-expression-hast],384[`MdxTextExpression`][api-mdx-text-expression], and385[`MdxTextExpressionHast`][api-mdx-text-expression-hast].386 387It also registers the node types with `@types/mdast` and `@types/hast`.388If you’re working with the syntax tree, make sure to import this utility389somewhere in your types, as that registers the new node types in the tree.390 391```js392/**393 * @import {} from 'mdast-util-mdx-expression'394 * @import {Root} from 'mdast'395 */396 397import {visit} from 'unist-util-visit'398 399/** @type {Root} */400const tree = getMdastNodeSomeHow()401 402visit(tree, function (node) {403  // `node` can now be an expression node.404})405```406 407## Compatibility408 409Projects maintained by the unified collective are compatible with maintained410versions of Node.js.411 412When we cut a new major release, we drop support for unmaintained versions of413Node.414This means we try to keep the current release line,415`mdast-util-mdx-expression@^2`, compatible with Node.js 16.416 417This utility works with `mdast-util-from-markdown` version 2+ and418`mdast-util-to-markdown` version 2+.419 420## Related421 422* [`remarkjs/remark-mdx`][remark-mdx]423  — remark plugin to support MDX424* [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]425  — mdast utility to support MDX426* [`micromark/micromark-extension-mdx-expression`][extension]427  — micromark extension to parse MDX expressions428 429## Contribute430 431See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for432ways to get started.433See [`support.md`][support] for ways to get help.434 435This project has a [code of conduct][coc].436By interacting with this repository, organization, or community you agree to437abide by its terms.438 439## License440 441[MIT][license] © [Titus Wormer][author]442 443<!-- Definitions -->444 445[build-badge]: https://github.com/syntax-tree/mdast-util-mdx-expression/workflows/main/badge.svg446 447[build]: https://github.com/syntax-tree/mdast-util-mdx-expression/actions448 449[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx-expression.svg450 451[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx-expression452 453[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx-expression.svg454 455[downloads]: https://www.npmjs.com/package/mdast-util-mdx-expression456 457[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdx-expression458 459[size]: https://bundlejs.com/?q=mdast-util-mdx-expression460 461[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg462 463[backers-badge]: https://opencollective.com/unified/backers/badge.svg464 465[collective]: https://opencollective.com/unified466 467[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg468 469[chat]: https://github.com/syntax-tree/unist/discussions470 471[npm]: https://docs.npmjs.com/cli/install472 473[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c474 475[esmsh]: https://esm.sh476 477[typescript]: https://www.typescriptlang.org478 479[license]: license480 481[author]: https://wooorm.com482 483[health]: https://github.com/syntax-tree/.github484 485[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md486 487[support]: https://github.com/syntax-tree/.github/blob/main/support.md488 489[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md490 491[mdast]: https://github.com/syntax-tree/mdast492 493[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast494 495[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown496 497[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown498 499[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx500 501[extension]: https://github.com/micromark/micromark-extension-mdx-expression502 503[syntax]: https://github.com/micromark/micromark-extension-mdx-expression#syntax504 505[program]: https://github.com/estree/estree/blob/master/es2015.md#programs506 507[dfn-literal]: https://github.com/syntax-tree/mdast#literal508 509[remark-mdx]: https://mdxjs.com/packages/remark-mdx/510 511[mdx]: https://mdxjs.com512 513[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension514 515[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options516 517[api-mdx-expression-from-markdown]: #mdxexpressionfrommarkdown518 519[api-mdx-expression-to-markdown]: #mdxexpressiontomarkdown520 521[api-mdx-flow-expression]: #mdxflowexpression522 523[api-mdx-text-expression]: #mdxtextexpression524 525[api-mdx-flow-expression-hast]: #mdxflowexpressionhast526 527[api-mdx-text-expression-hast]: #mdxtextexpressionhast528 529[dfn-flow-content]: #flowcontent-mdx-expression530 531[dfn-phrasing-content]: #phrasingcontent-mdx-expression532