mdast-util-to-markdown

What is mdast-util-to-markdown?

The mdast-util-to-markdown package is a utility to serialize Markdown Abstract Syntax Tree (MDAST) nodes to markdown text. It is part of the unified ecosystem and is typically used to convert MDAST, which is an abstract representation of markdown documents, back into markdown format.

What are mdast-util-to-markdown's main functionalities?

Serialize MDAST to Markdown

Converts an MDAST node into a markdown string. This is the core functionality of the package.

const toMarkdown = require('mdast-util-to-markdown');
const mdast = {
  type: 'paragraph',
  children: [{ type: 'text', value: 'Hello, world!' }]
};
const markdown = toMarkdown(mdast);
console.log(markdown); // Outputs: 'Hello, world!'

Customize Handlers

Allows the user to define custom handlers for different types of MDAST nodes, enabling serialization of custom or extended MDAST nodes.

const toMarkdown = require('mdast-util-to-markdown');
const mdast = {
  type: 'customNode',
  value: 'This is custom'
};
const handlers = {
  customNode(node) {
    return `Custom: ${node.value}`;
  }
};
const markdown = toMarkdown(mdast, { handlers });
console.log(markdown); // Outputs: 'Custom: This is custom'

Extensions

Supports extensions to handle syntax from GitHub Flavored Markdown (GFM) and other markdown variants.

const toMarkdown = require('mdast-util-to-markdown');
const gfm = require('mdast-util-gfm');
const mdast = {
  type: 'paragraph',
  children: [{ type: 'text', value: 'Hello, world!' }]
};
const markdown = toMarkdown(mdast, { extensions: [gfm.toMarkdown] });
console.log(markdown); // Outputs: 'Hello, world!' with GFM-specific serialization

Other packages similar to mdast-util-to-markdown

remark-stringify

Part of the remark processor that turns MDAST into markdown. It is similar to mdast-util-to-markdown but is typically used within the remark ecosystem.

rehype-stringify

Part of the rehype processor that turns HAST (Hypertext Abstract Syntax Tree) into HTML. While it operates on a different type of syntax tree, it provides a similar serialization functionality for HTML instead of markdown.

commonmark

A library that provides parsing and rendering of CommonMark Markdown. It offers similar markdown serialization capabilities but is based on the CommonMark specification.

README

mdast-util-to-markdown

mdast utility to parse markdown.

Install

npm:

npm install mdast-util-to-markdown

Use

Say we have the following script, example.js:

var toMarkdown = require('.')

var 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))

Now, running node example yields (note the properly escaped characters which would otherwise turn into a list and image respectively):

> ***
>
> \- a
> b \![d](example.com)

API

toMarkdown(doc[, options])

Serialize mdast to markdown.

Formatting options

options.bullet

Marker to use to for bullets of items in unordered lists ('*', '+', or '-', default: '*').

options.closeAtx

Whether to add the same number of number signs (#) at the end of an ATX heading as the opening sequence (boolean, default: false).

options.emphasis

Marker to use to serialize emphasis ('*' or '_', default: '*').

options.incrementListMarker

Whether to increment the value of bullets of items in ordered lists (boolean, default: true).

options.listItemIndent

Whether to indent the content of list items with the size of the bullet plus one space (when 'one') or a tab stop ('tab'), or depending on the item and its parent list ('mixed', uses 'one' if the item and list are tight and 'tab' otherwise) ('one', 'tab', or 'mixed', default: 'tab').

options.fence

Marker to use to serialize fenced code ('`' or '~', default: '`').

options.fences

Whether to use fenced code always (boolean, default: false). The default is to fenced code if there is a language defined, if the code is empty, or if it starts or ends in empty lines.

options.quote

Marker to use to serialize titles ('"' or "'", default: '"').

options.rule

Marker to use for thematic breaks ('*', '-', or '_', default: '*').

options.ruleRepeat

Number of markers to use for thematic breaks (number, default: 3, min: 3).

options.ruleSpaces

Whether to add spaces between markers in thematic breaks (boolean, default: false).

options.setext

Whether to use setext headings when possible (boolean, default: false). Setext headings are not possible for headings with a rank more than 2 or when they’re empty.

options.strong

Marker to use to serialize strong ('*' or '_', default: '*').

Escape options

options.unsafe

List of patterns to escape. Useful for syntax extensions. Take a look at lib/unsafe.js for examples.

Extensions or overwrites options

options.handlers

Object mapping node types to custom handlers. Useful for syntax extensions. Take a look at lib/handle for examples.

Returns

string — Serialized markdown.

Security

mdast-util-to-markdown will do its best to serialize markdown to match the syntax tree, but there are several cases where that is impossible. It’ll do its best, but complete roundtripping is impossible given that any value could be injected into the tree.

As Markdown is sometimes used for HTML, and improper use of HTML can open you up to a cross-site scripting (XSS) attack, use of mdast-util-to-markdown and parsing it again later could potentially be unsafe. When parsing markdown afterwards and then going to HTML, use something like hast-util-sanitize to make the tree safe.

Related

• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• remarkjs/remark — markdown processor powered by plugins
• syntax-tree/mdast-util-from-markdown — parse markdown to mdast

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer