unified

Project: syntax-tree/mdast-util-to-markdown

Package: mdast-util-to-markdown@1.3.0

  1. Dependents: 0
  2. mdast utility to serialize markdown
  1. markdown 151
  2. util 147
  3. utility 143
  4. unist 133
  5. mdast 88
  6. tree 44
  7. ast 36
  8. mdast-util 31
  9. syntax 28
  10. markup 19
  11. stringify 19
  12. compile 14
  13. serialize 12

mdast-util-to-markdown

Build Coverage Downloads Size Sponsors Backers Chat

mdast utility that turns a syntax tree into markdown.

Contents

What is this?

This package is a utility that takes an mdast syntax tree as input and turns it into serialized markdown.

This utility is a low level project. It’s used in remark-stringify, which focusses on making it easier to transform content by abstracting these internals away.

When should I use this?

If you want to handle syntax trees manually, use this. For an easier time processing content, use the remark ecosystem instead.

You can combine this utility with other utilities to add syntax extensions. Notable examples that deeply integrate with it are mdast-util-gfm, mdast-util-mdx, mdast-util-frontmatter, mdast-util-math, and mdast-util-directive.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install mdast-util-to-markdown

In Deno with esm.sh:

import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@1'

In browsers with esm.sh:

<script type="module">
  import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@1?bundle'
</script>

Use

Say our module example.js looks as follows:

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

/** @type {import('mdast').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))

…now running node example.js yields:

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

👉 Note: observe the properly escaped characters which would otherwise turn into a list and image respectively.

API

This package exports the identifier toMarkdown. There is no default export.

toMarkdown(tree[, options])

Turn an mdast syntax tree into markdown.

Formatting options
options.bullet

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

options.bulletOther

Marker to use in certain cases where the primary bullet doesn’t work ('*', '+', or '-', default: depends).

There are three cases where the primary bullet can’t be used:

options.bulletOrdered

Marker to use for bullets of items in ordered lists ('.' or ')', default: '.').

options.bulletOrderedOther

Marker to use in certain cases where the primary bullet for ordered items doesn’t work ('.' or ')', default: none).

There is one case where the primary bullet for ordered items can’t be used:

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 for emphasis ('*' or '_', default: '*').

options.fence

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

options.fences

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

options.incrementListMarker

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

options.listItemIndent

How to indent the content of list items ('one', 'tab', or 'mixed', default: 'tab'). Either with the size of the bullet plus one space (when 'one'), 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).

options.quote

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

Whether to always use resource links (boolean, default: false). The default is to use autolinks (<https://example.com>) when possible and resource links ([text](url)) otherwise.

options.rule

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

options.ruleRepetition

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). The default is to always use ATX headings (# heading) instead of setext headings (heading\n=======). Setext headings can’t be used for empty headings or headings with a rank of three or more.

options.strong

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

options.tightDefinitions

Whether to join definitions without a blank line (boolean, default: false). The default is to add blank lines between any flow (“block”) construct. Turning this option on is a shortcut for a join function like so:

function joinTightDefinitions(left, right) {
  if (left.type === 'definition' && right.type === 'definition') {
    return 0
  }
}
options.handlers

Object mapping node types to custom handlers (Record<string, Handle>, default: {}). Useful for syntax extensions.

This option is a bit advanced. It’s recommended to look at the code in lib/handle/ for examples.

options.join

List of functions used to determine what to place between two flow nodes (Array<Join>, default: []).

“Blocks” are typically joined by one blank line. Sometimes it’s nicer to have them flush next to each other, yet other times they can’t occur together at all. Join functions receive two adjacent siblings and their parent and can return number or boolean, to signal how many blank lines to use between them. A return value of true is as passing 1. A return value of false means the nodes cannot be joined by a blank line, such as two adjacent block quotes or indented code after a list, in which case a comment will be injected to break them up:

> Quote 1

<!---->

> Quote 2
options.unsafe

List of patterns to escape (Array<Unsafe>). Useful for syntax extensions.

This option is quite advanced. It’s recommended to look at the code in lib/unsafe.js for examples.

Extension options
options.extensions

List of extensions (Array<ToMarkdownExtension>, default: []). Each ToMarkdownExtension is an object with the same interface as options here.

Returns

Serialized markdown (string).

List of extensions

Syntax

Markdown is serialized according to CommonMark but care is taken to format in such a way that the resulting markdown should work with most markdown parsers. Extensions can add support for custom syntax.

Syntax tree

The syntax tree is mdast.

Types

This package is fully typed with TypeScript. It exports the additional types Options, Map, Unsafe, Join, Handlers, Handle, Context, SafeOptions, which model the interfaces used by options and extensions.

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.

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