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

npm install unist-util-mdx-define

Usage

Typically this is used with an MDX plugin.

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

define

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<string, estree.Expression>) — 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