mdast-util-to-markdown

2.1.2 · active · verified Sun Apr 19

mdast-util-to-markdown is a low-level utility for serializing an mdast (Markdown Abstract Syntax Tree) syntax tree back into a Markdown string. It is currently at version 2.1.2. The package maintains an active release cadence, frequently publishing patch and minor versions for bug fixes and new features, with major versions reserved for significant breaking changes, such as Node.js version requirement updates or fundamental API shifts. This utility differentiates itself by providing direct, granular control over the Markdown serialization process, contrasting with higher-level solutions like `remark-stringify` which abstract away these internals. It is a core component within the unified `syntax-tree` ecosystem and is designed to be highly extensible through integration with other `mdast-util` packages, enabling support for various Markdown extensions like GFM, MDX, and frontmatter. Developers typically use this package when manual syntax tree manipulation is required, rather than relying on a full-fledged Markdown processor.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `mdast-util-to-markdown` in a CommonJS context.

fix Convert your module to ES Modules or use dynamic `import()` if you cannot switch entirely. For example, replace `const toMarkdown = require('mdast-util-to-markdown')` with `import { toMarkdown } from 'mdast-util-to-markdown'`.
```
TypeError: Cannot read properties of undefined (reading 'type')
```
cause The `tree` argument passed to `toMarkdown` is `undefined`, `null`, or an invalid object that lacks a `type` property.

fix Ensure that the `tree` variable you are passing to `toMarkdown` is a valid mdast node object, typically a `Root` or other compatible node, as documented by the mdast specification.
```
Error: Cannot find module 'mdast-util-to-markdown'
```
cause The package `mdast-util-to-markdown` has not been installed or the import path is incorrect.

fix Run `npm install mdast-util-to-markdown` to install the package. Verify that the import statement `import { toMarkdown } from 'mdast-util-to-markdown'` uses the correct package name.

Warnings

breaking Version 2.0.0 changed the minimum required Node.js version to 16. Older Node.js environments are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or newer. Use nvm or a similar tool to manage Node.js versions.
breaking Version 2.0.0 switched to using `exports` maps. Direct access to internal or private APIs via non-explicit import paths may break.
Fix: Ensure you are only importing publicly documented APIs from the package. Avoid deep imports (e.g., `mdast-util-to-markdown/lib/foo`).
breaking The `bulletOrderedOther` option was removed in v2.0.0 as its functionality became the default. Passing this option will have no effect or may cause errors if not handled gracefully by your code.
Fix: Remove the `bulletOrderedOther` option from your `toMarkdown` options object if you were previously setting it.
breaking The default value for the `fences` option changed to `true` in v2.0.0. If you relied on the previous default of `false` for fenced code blocks, your output may change.
Fix: If you require `fences: false`, explicitly set `fences: false` in the `options` object passed to `toMarkdown`.
gotcha Earlier versions (pre-2.1.1) had issues with round-tripping 'attention' (strong/emphasis) by incorrectly encoding surrounding characters, potentially leading to malformed Markdown output.
Fix: Update to `mdast-util-to-markdown@2.1.1` or newer to ensure correct encoding of attention. This fix prevents incorrect markdown generation around strong/emphasis characters.

Install

npm install mdast-util-to-markdown npm
yarn add mdast-util-to-markdown yarn
pnpm add mdast-util-to-markdown pnpm

Imports

toMarkdown
wrong:
```
const toMarkdown = require('mdast-util-to-markdown')
```
correct:
```
import { toMarkdown } from 'mdast-util-to-markdown'
```
This package is ESM-only in Node.js environments since v2.0.0, so `require()` is not supported.

defaultHandlers

wrong:

const { defaultHandlers } = require('mdast-util-to-markdown')

correct:

import { defaultHandlers } from 'mdast-util-to-markdown'

As an ESM-only package, `defaultHandlers` must be imported using `import` syntax.

Options
wrong:
```
import { Options } from 'mdast-util-to-markdown'
```
correct:
```
import type { Options } from 'mdast-util-to-markdown'
```
When using TypeScript, always import types with `import type` to avoid bundling issues or runtime errors if the symbol is not an actual value.

Quickstart

Demonstrates how to import and use `toMarkdown` to serialize an mdast syntax tree into a Markdown string, highlighting proper character escaping.

/**
 * @import {Root} from 'mdast'
 */

import {toMarkdown} from 'mdast-util-to-markdown'

/** @type {Root} */
const tree = {
  type: 'root',
  children: [
    {
      type: 'blockquote',
      children: [
        {type: 'thematicBreak'},
        {
          type: 'paragraph',
          children: [
            {type: 'text', value: '- a\nb !'},
            {
              type: 'link',
              url: 'example.com',
              children: [{type: 'text', value: 'd'}]
            }
          ]
        }
      ]
    }
  ]
}

console.log(toMarkdown(tree))

view raw JSON →