unist-util-mdx-define


A unist utility to define MDX exports.

Table of Contents

- Introduction
- Installation
- Usage
- API
- define
- Compatibility
- Related projects
- License

Introduction

This package provides a utility to define exports in an MDX AST, so you don’t
have to worry about the details. It supports mdast
(remark), hast
(rehype), and estree /
esast (recma). This
package supports various options to export the variables you define and to handle name conflicts.

Installation

``sh
npm install unist-util-mdx-define
`

Usage

Typically this is used with an MDX plugin.

`ts
import { compile } from '@mdx-js/mdx'
import type * as estree from 'estree'
import type * as hast from 'hast'
import type * as mdast from 'mdast'
import { type Plugin } from 'unified'
import { define } from 'unist-util-mdx-define'

const yourRemarkMdxPlugin: Plugin<[], mdast.Root> = () => (ast, file) => {
define(ast, file, { remarkVariable: { type: 'Literal', value: 'Hello remark plugin!' } })
}

const yourRehypeMdxPlugin: Plugin<[], hast.Root> = () => (ast, file) => {
define(ast, file, { rehypeVariable: { type: 'Literal', value: 'Hello rehype plugin!' } })
}

const yourRecmaMdxPlugin: Plugin<[], estree.Program> = () => (ast, file) => {
define(ast, file, { recmaVariable: { type: 'Literal', value: 'Hello recma plugin!' } })
}

const { value } = await compile('{remarkVariable} {rehypeVariable} {recmaVariable}', {
remarkPlugins: [yourRemarkMdxPlugin],
rehypePlugins: [yourRehypeMdxPlugin],
recmaPlugins: [yourRecmaMdxPlugin]
})

console.log(value)
`

MDX remark, rehype, and recma plugins are similar, but not the same. The type of plugin you should
create depends on your goal.

If your goal is to handle something specific to the markdown content, you should write a remark
plugin. A practical example is
remark-mdx-frontmatter. This plugin
handles frontmatter data, which no longer exists after the mdast is compiled to hast.

If your goal is to transform or access content, you typically want a rehype plugin. A good example
is rehype-mdx-title, which accesses the title
of the document.

For most other purposes, use a recma plugin. For example,
recma-export-filepath exposes file
information. This doesn’t need access to the content.

unist-util-mdx-define can define variables in any of these AST types. For mdast and hast, it
prepends the variable declarations to the root. This way they’ll end up at the start of the module,
and their value can be used by user defined expressions. This does mean the generated
expressions are not able to use other variables. For ESTree, unist-util-mdx-define attempts to do
the same.

API

$3

Define variables in an MDX related AST.

#### Parameters

- ast (mdast.Root |
hast.Root |
estree.Program) — The AST in which to define an export.
- file (VFile) — The file to emit warnings to.
- variables (Record) — A mapping of variables to define. They keys
are the names. The values are the ESTree expression to represent them.
- options (Options) — Additional options to configure behaviour.

#### Options

- export — If and how to export the variable. (Default: 'module')
- 'module': Export the value using an ESM const export declaration.
- 'namespace': Attach the value as a property on MDXContent.
- false: Define the variable locally, but don’t export it.
- conflict — What to do if there’s a name conflict. (Default: 'throw')
- 'skip': Don’t insert the variable if there’s a name conflict.
- 'throw': Throw if there’s a name conflict.
- 'warn': Emit a vfile warning, but don’t throw.

Compatibility

This project is compatible with Node.js 16 or greater.

Related projects

- estree-util-value-to-estree` —
Convert a JavaScript value to an estree expression

License

MIT © Remco Haszing