init

node_modules/unist-util-mdx-define/README.md

@@ -0,0 +1,129 @@
+# unist-util-mdx-define
+
+[![github actions](https://github.com/remcohaszing/unist-util-mdx-define/actions/workflows/ci.yaml/badge.svg)](https://github.com/remcohaszing/unist-util-mdx-define/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/remcohaszing/unist-util-mdx-define/branch/main/graph/badge.svg)](https://codecov.io/gh/remcohaszing/unist-util-mdx-define)
+[![npm version](https://img.shields.io/npm/v/unist-util-mdx-define)](https://www.npmjs.com/package/unist-util-mdx-define)
+[![npm downloads](https://img.shields.io/npm/dm/unist-util-mdx-define)](https://www.npmjs.com/package/unist-util-mdx-define)
+
+A [unist](https://github.com/syntax-tree/unist) utility to define [MDX](https://mdxjs.com) exports.
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+  - [`define`](#define)
+- [Compatibility](#compatibility)
+- [Related projects](#related-projects)
+- [License](#license)
+
+## Introduction
+
+This package provides a utility to define exports in an [MDX](https://mdxjs.com) AST, so you don’t
+have to worry about the details. It supports [mdast](https://github.com/syntax-tree/mdast)
+([remark](https://github.com/remarkjs)), [hast](https://github.com/syntax-tree/hast)
+([rehype](https://github.com/rehypejs)), and [estree](https://github.com/estree/estree) /
+[esast](https://github.com/syntax-tree/esast) ([recma](https://github.com/mdx-js/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`](https://github.com/remcohaszing/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`](https://github.com/remcohaszing/rehype-mdx-title), which accesses the title
+of the document.
+
+For most other purposes, use a recma plugin. For example,
+[`recma-export-filepath`](https://github.com/remcohaszing/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](https://github.com/syntax-tree/mdast#root) |
+  [hast.Root](https://github.com/syntax-tree/hast#root) |
+  [estree.Program](https://github.com/estree/estree)) — The AST in which to define an export.
+- `file` ([VFile](https://github.com/vfile/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](#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`](https://github.com/remcohaszing/estree-util-value-to-estree) —
+  Convert a JavaScript value to an estree expression
+
+## License
+
+[MIT](LICENSE.md) © [Remco Haszing](https://github.com/remcohaszing)