mdast-util-definitions

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` this package in a CommonJS environment, but it is ESM-only since v5.0.0.
  fix Convert your project or specific file to ESM and use `import { definitions } from 'mdast-util-definitions'`.

• TypeError: Cannot read properties of null (reading '...')

  cause Your code is expecting `definitions(tree)('identifier')` to return `null` when a definition is not found, but it now returns `undefined` since v6.0.0.
  fix Update your code to check for `undefined` instead of `null`.

• SyntaxError: The requested module 'mdast-util-definitions' does not provide an export named 'default'

  cause Attempting to use a default import, e.g., `import definitions from 'mdast-util-definitions'`, when there is no default export.
  fix Use a named import: `import { definitions } from 'mdast-util-definitions'`.

• TypeError: definitions is not a function

  cause This error can occur if you're trying to call `definitions()` directly without first passing the `tree` to it, or if there was a problem with the import.
  fix Remember to call `definitions(tree)` first, which returns another function (a getter). Then call the returned getter with your identifier: `const getDefinition = definitions(tree); getDefinition('my-id');`

Warnings

• breaking Version 6.0.0 changed to require Node.js 16 or newer. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 16 or later.
• breaking Since version 5.0.0, this package is ESM-only. CommonJS `require()` statements are no longer supported and will result in an `ERR_REQUIRE_ESM` error.
  Fix: Migrate your codebase to use ES Modules (ESM) with `import` statements. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
• breaking As of v6.0.0, `definitions(tree)('identifier')` now returns `undefined` when a definition is not found, instead of `null`.
  Fix: Update your code to check for `undefined` instead of `null` when expecting a potentially missing definition.
• breaking Version 6.0.0 changed to use `export` map, preventing direct imports of private APIs (e.g., `mdast-util-definitions/index.js`).
  Fix: Always use the public API through `import { definitions } from 'mdast-util-definitions'` and avoid internal paths.
• breaking Type definitions were added in v3.0.0, and updated in v5.1.0 to use `mdast` types, then again in v6.0.0 with `@types/mdast`. This might cause type conflicts if your project uses older or incompatible `@types/mdast` versions.
  Fix: Ensure your project's `@types/mdast` dependency is up-to-date and compatible with `mdast-util-definitions@6`.

Install

• npm install mdast-util-definitions npm
• yarn add mdast-util-definitions yarn
• pnpm add mdast-util-definitions pnpm

Imports

• definitions
  wrong:

  const definitions = require('mdast-util-definitions')

  correct:

  import { definitions } from 'mdast-util-definitions'

  This package is ESM-only since v5.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error. There is no default export.
• GetDefinition

  import type { GetDefinition } from 'mdast-util-definitions'

  This is a TypeScript type for the function returned by `definitions(tree)`.
• Default export
  wrong:

  import definitions from 'mdast-util-definitions'

  correct:

  /* No default export available */

  The package explicitly states there is no default export. Use named imports only.

Quickstart

Demonstrates how to use `mdast-util-definitions` to find definition nodes by identifier in an mdast tree generated from Markdown input.

import {definitions} from 'mdast-util-definitions'
import {fromMarkdown} from 'mdast-util-from-markdown'

const markdownInput = `
[example]: https://example.com "Example"
[another]: /path/to/another "Another Link"

This is some text with a reference to [example].
And another one to [another].

A non-existent [foo] reference.
`

const tree = fromMarkdown(markdownInput)

const getDefinition = definitions(tree)

console.log('Definition for "example":', getDefinition('example'))
// Expected: {type: 'definition', title: 'Example', url: 'https://example.com', identifier: 'example', label: 'example', ...}

console.log('Definition for "another":', getDefinition('another'))
// Expected: {type: 'definition', title: 'Another Link', url: '/path/to/another', identifier: 'another', label: 'another', ...}

console.log('Definition for "foo":', getDefinition('foo'))
// Expected: undefined

// To illustrate how one might access all definitions, though 'definitions' returns a getter function
const allDefinitions = {}
tree.children.forEach(node => {
  if (node.type === 'definition') {
    allDefinitions[node.identifier] = node
  }
})
console.log('All definitions found in tree:', allDefinitions)