https://github.com/syntax-tree/mdast-util-to-markdown

mdast utility to serialize markdown
https://github.com/syntax-tree/mdast-util-to-markdown

compile markdown mdast mdast-util serialize stringify unist

Last synced: 9 days ago
JSON representation

mdast utility to serialize markdown

• Host: GitHub
• URL: https://github.com/syntax-tree/mdast-util-to-markdown
• Owner: syntax-tree
• License: mit
• Created: 2020-09-09T18:13:52.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2024-10-28T11:49:28.000Z (13 days ago)
• Last Synced: 2024-10-29T13:04:49.241Z (12 days ago)
• Topics: compile, markdown, mdast, mdast-util, serialize, stringify, unist
• Language: JavaScript
• Homepage: http://unifiedjs.com
• Size: 508 KB
• Stars: 95
• Watchers: 9
• Forks: 19
• Open Issues: 3
• Metadata Files:
  • Readme: readme.md
  • License: license

Awesome Lists containing this project

README

        
# mdast-util-to-markdown

[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![Downloads][downloads-badge]][downloads]

[![Size][size-badge]][size]

[![Sponsors][sponsors-badge]][collective]

[![Backers][backers-badge]][collective]

[![Chat][chat-badge]][chat]

**[mdast][]** utility that turns a syntax tree into markdown.

## Contents

*   [What is this?](#what-is-this)

*   [When should I use this?](#when-should-i-use-this)

*   [Install](#install)

*   [Use](#use)

*   [API](#api)

    *   [`toMarkdown(tree[, options])`](#tomarkdowntree-options)

    *   [`defaultHandlers`](#defaulthandlers)

    *   [`ConstructName`](#constructname)

    *   [`ConstructNameMap`](#constructnamemap)

    *   [`Handle`](#handle)

    *   [`Handlers`](#handlers)

    *   [`Info`](#info)

    *   [`Join`](#join)

    *   [`Map`](#map)

    *   [`Options`](#options)

    *   [`SafeConfig`](#safeconfig)

    *   [`State`](#state)

    *   [`Tracker`](#tracker)

    *   [`Unsafe`](#unsafe)

*   [List of extensions](#list-of-extensions)

*   [Syntax](#syntax)

*   [Syntax tree](#syntax-tree)

*   [Types](#types)

*   [Compatibility](#compatibility)

*   [Security](#security)

*   [Related](#related)

*   [Contribute](#contribute)

*   [License](#license)

## 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`][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-gfm],

[`mdast-util-mdx`][mdast-util-mdx],

[`mdast-util-frontmatter`][mdast-util-frontmatter],

[`mdast-util-math`][mdast-util-math], and

[`mdast-util-directive`][mdast-util-directive].

## Install

This package is [ESM only][esm].

In Node.js (version 16+), install with [npm][]:

```sh

npm install mdast-util-to-markdown

```

In Deno with [`esm.sh`][esmsh]:

```js

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

```

In browsers with [`esm.sh`][esmsh]:

```html

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

```

## Use

Say our module `example.js` looks as follows:

```js

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:

```markdown

> ***

>

> \- 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 identifiers [`defaultHandlers`][api-default-handlers]

and [`toMarkdown`][api-to-markdown].

There is no default export.

### `toMarkdown(tree[, options])`

Turn an **[mdast][]** syntax tree into markdown.

###### Parameters

*   `tree` ([`Node`][node])

    — tree to serialize

*   `options` ([`Options`][api-options], optional)

    — configuration

###### Returns

Serialized markdown representing `tree` (`string`).

### `defaultHandlers`

Default (CommonMark) handlers ([`Handlers`][api-handlers]).

### `ConstructName`

Construct names for things generated by `mdast-util-to-markdown` (TypeScript

type).

This is an enum of strings, each being a semantic label, useful to know when

serializing whether we’re for example in a double (`"`) or single (`'`) quoted

title.

###### Type

```ts

type ConstructName = ConstructNameMap[keyof ConstructNameMap]

```

### `ConstructNameMap`

Interface of registered constructs (TypeScript type).

###### Type

```ts

interface ConstructNameMap { /* see code */ }

```

When working on extensions that use new constructs, extend the corresponding

interface to register its name:

```ts

declare module 'mdast-util-to-markdown' {

  interface ConstructNameMap {

    // Register a new construct name (value is used, key should match it).

    gfmStrikethrough: 'gfmStrikethrough'

  }

}

```

### `Handle`

Handle a particular node (TypeScript type).

###### Parameters

*   `node` (`any`)

    — expected mdast node

*   `parent` ([`Node`][node], optional)

    — parent of `node`

*   `state` ([`State`][api-state])

    — info passed around about the current state

*   `info` ([`Info`][api-info])

    — info on the surrounding of the node that is serialized

###### Returns

Serialized markdown representing `node` (`string`).

### `Handlers`

Handle particular nodes (TypeScript type).

Each key is a node type (`Node['type']`), each value its corresponding handler

([`Handle`][api-handle]).

###### Type

```ts

type Handlers = Record

```

### `Info`

Info on the surrounding of the node that is serialized (TypeScript type).

###### Fields

*   `now` ([`Point`][point])

    — current point

*   `lineShift` (`number`)

    — number of columns each line will be shifted by wrapping nodes

*   `before` (`string`)

    — characters before this (guaranteed to be one, can be more)

*   `after` (`string`)

    — characters after this (guaranteed to be one, can be more)

### `Join`

How to join two blocks (TypeScript type).

“Blocks” are typically joined by one blank line.

Sometimes it’s nicer to have them flush next to each other, yet other times

they cannot occur together at all.

Join functions receive two adjacent siblings and their parent and what they

return defines how many blank lines to use between them.

###### Parameters

*   `left` ([`Node`][node])

    — first of two adjacent siblings

*   `right` ([`Node`][node])

    — second of two adjacent siblings

*   `parent` ([`Node`][node])

    — parent of the two siblings

*   `state` ([`State`][api-state])

    — info passed around about the current state

###### Returns

How many blank lines to use between the siblings (`boolean`, `number`,

optional).

Where `true` is as passing `1` and `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:

```markdown

> Quote 1

> Quote 2

```

> 👉 **Note**: abusing this feature will break markdown.

> One such example is when returning `0` for two paragraphs, which will result

> in the text running together, and in the future to be seen as one paragraph.

### `Map`

Map function to pad a single line (TypeScript type).

###### Parameters

*   `value` (`string`)

    — a single line of serialized markdown

*   `line` (`number`)

    — line number relative to the fragment

*   `blank` (`boolean`)

    — whether the line is considered blank in markdown

###### Returns

Padded line (`string`).

### `Options`

Configuration (TypeScript type).

##### Fields

The following fields influence how markdown is serialized.

###### `options.bullet`

Marker to use for bullets of items in unordered lists (`'*'`, `'+'`, or `'-'`,

default: `'*'`).

There are three cases where the primary bullet cannot be used:

*   when three or more list items are on their own, the last one is empty, and

    `bullet` is also a valid `rule`: `* - +`; this would turn into a thematic

    break if serialized with three primary bullets; `bulletOther` is used for

    the last item

*   when a thematic break is the first child of a list item and `bullet` is the

    same character as `rule`: `- ***`; this would turn into a single thematic

    break if serialized with primary bullets; `bulletOther` is used for the

    item

*   when two unordered lists appear next to each other: `* a\n- b`;

    `bulletOther` is used for such lists

###### `options.bulletOther`

Marker to use in certain cases where the primary bullet doesn’t work (`'*'`,

`'+'`, or `'-'`, default: `'-'` when `bullet` is `'*'`, `'*'` otherwise).

Cannot be equal to `bullet`.

###### `options.bulletOrdered`

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

`'.'`).

There is one case where the primary bullet for ordered items cannot be used:

*   when two ordered lists appear next to each other: `1. a\n2) b`; to solve

    that, `'.'` will be used when `bulletOrdered` is `')'`, and `'.'` otherwise

###### `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: `true`).

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 (`'mixed'`, `'one'`, or `'tab'`,

default: `'one'`).

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: `'"'`).

###### `options.resourceLink`

Whether to always use resource links (`boolean`, default: `false`).

The default is to use autolinks (``) 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 cannot 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`][api-join] function like so:

```js

function joinTightDefinitions(left, right) {

  if (left.type === 'definition' && right.type === 'definition') {

    return 0

  }

}

```

###### `options.handlers`

Handle particular nodes ([`Handlers`][api-handlers], optional).

###### `options.join`

How to join blocks ([`Array`][api-join], optional).

###### `options.unsafe`

Schemas that define when characters cannot occur

([`Array`][api-unsafe], optional).

###### `options.extensions`

List of extensions (`Array`, default: `[]`).

Each extension is an object with the same interface as `Options` itself.

### `SafeConfig`

Configuration passed to `state.safe` (TypeScript type).

###### Fields

*   `before` (`string`)

    — characters before this (guaranteed to be one, can be more)

*   `after` (`string`)

    — characters after this (guaranteed to be one, can be more)

*   `encode` (`Array`, optional)

    — extra characters that *must* be encoded (as character references) instead

    of escaped (character escapes).

    Only ASCII punctuation will use character escapes, so you never need to

    pass non-ASCII-punctuation here

### `State`

Info passed around about the current state (TypeScript type).

###### Fields

*   `stack` ([`Array`][api-construct-name])

    — stack of constructs we’re in

*   `indexStack` (`Array`)

    — positions of child nodes in their parents

*   `associationId` (`(node: Association) => string`)

    — get an identifier from an association to match it to others (see

    [`Association`][association])

*   `enter` (`(construct: ConstructName) => () => undefined`)

    — enter a construct (returns a corresponding exit function)

    (see [`ConstructName`][api-construct-name])

*   `indentLines` (`(value: string, map: Map) => string`)

    — pad serialized markdown (see [`Map`][api-map])

*   `compilePattern` (`(pattern: Unsafe) => RegExp`)

    — compile an unsafe pattern to a regex (see [`Unsafe`][api-unsafe])

*   `containerFlow` (`(parent: Node, info: Info) => string`)

    — serialize flow children (see [`Info`][api-info])

*   `containerPhrasing` (`(parent: Node, info: Info) => string`)

    — serialize phrasing children (see [`Info`][api-info])

*   `createTracker` (`(info: Info) => Tracker`)

    — track positional info in the output (see [`Info`][api-info],

    [`Tracker`][api-tracker])

*   `safe` (`(value: string, config: SafeConfig) => string`)

    — make a string safe for embedding (see [`SafeConfig`][api-safe-config])

*   `options` ([`Options`][api-options])

    — applied user configuration

*   `unsafe` ([`Array`][api-unsafe])

    — applied unsafe patterns

*   `join` ([`Array`][api-join])

    — applied join handlers

*   `handle` ([`Handle`][api-handle])

    — call the configured handler for the given node

*   `handlers` ([`Handlers`][api-handlers])

    — applied handlers

*   `bulletCurrent` (`string` or `undefined`)

    — list marker currently in use

*   `bulletLastUsed` (`string` or `undefined`)

    — list marker previously in use

### `Tracker`

Track positional info in the output (TypeScript type).

This info isn’t used yet but such functionality will allow line wrapping,

source maps, etc.

###### Fields

*   `current` (`() => Info`)

    — get current tracked info

*   `shift` (`(value: number) => undefined`)

    — define a relative increased line shift (the typical indent for lines)

*   `move` (`(value: string) => string`)

    — move past some generated markdown

### `Unsafe`

Schema that defines when a character cannot occur (TypeScript type).

###### Fields

*   `character` (`string`)

    — single unsafe character

*   `inConstruct` ([`Array`][api-construct-name],

    `ConstructName`, optional)

    — constructs where this is bad

*   `notInConstruct` ([`Array`][api-construct-name],

    `ConstructName`, optional)

    — constructs where this is fine again

*   `before` (`string`, optional)

    — `character` is bad when this is before it (cannot be used together with

    `atBreak`)

*   `after` (`string`, optional)

    — `character` is bad when this is after it

*   `atBreak` (`boolean`, optional)

    — `character` is bad at a break (cannot be used together with `before`)

## List of extensions

*   [`syntax-tree/mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive)

    — directives

*   [`syntax-tree/mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter)

    — frontmatter (YAML, TOML, more)

*   [`syntax-tree/mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm)

    — GFM

*   [`syntax-tree/mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)

    — GFM autolink literals

*   [`syntax-tree/mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)

    — GFM footnotes

*   [`syntax-tree/mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)

    — GFM strikethrough

*   [`syntax-tree/mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)

    — GFM tables

*   [`syntax-tree/mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)

    — GFM task list items

*   [`syntax-tree/mdast-util-math`](https://github.com/syntax-tree/mdast-util-math)

    — math

*   [`syntax-tree/mdast-util-mdx`](https://github.com/syntax-tree/mdast-util-mdx)

    — MDX

*   [`syntax-tree/mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)

    — MDX expressions

*   [`syntax-tree/mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)

    — MDX JSX

*   [`syntax-tree/mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)

    — MDX ESM

## 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

[`ConstructName`][api-construct-name],

[`ConstructNameMap`][api-construct-name-map],

[`Handle`][api-handle],

[`Handlers`][api-handlers],

[`Info`][api-info],

[`Join`][api-join],

[`Map`][api-map],

[`Options`][api-options],

[`SafeConfig`][api-safe-config],

[`State`][api-State], and

[`Unsafe`][api-Unsafe].

## Compatibility

Projects maintained by the unified collective are compatible with maintained

versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of

Node.

This means we try to keep the current release line, `mdast-util-to-markdown@^2`,

compatible with Node.js 16.

## 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)][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`][hast-util-sanitize] to make the tree safe.

## Related

*   [`syntax-tree/mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown)

    — parse markdown to mdast

*   [`micromark/micromark`](https://github.com/micromark/micromark)

    — parse markdown

*   [`remarkjs/remark`](https://github.com/remarkjs/remark)

    — process markdown

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for

ways to get started.

See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].

By interacting with this repository, organization, or community you agree to

abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

[build-badge]: https://github.com/syntax-tree/mdast-util-to-markdown/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-to-markdown/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-to-markdown.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-to-markdown

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-to-markdown.svg

[downloads]: https://www.npmjs.com/package/mdast-util-to-markdown

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-to-markdown

[size]: https://bundlejs.com/?q=mdast-util-to-markdown

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[point]: https://github.com/syntax-tree/unist#point

[mdast]: https://github.com/syntax-tree/mdast

[node]: https://github.com/syntax-tree/mdast#nodes

[association]: https://github.com/syntax-tree/mdast#association

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[mdast-util-math]: https://github.com/syntax-tree/mdast-util-math

[mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

[remark]: https://github.com/remarkjs/remark

[remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify

[api-construct-name]: #constructname

[api-construct-name-map]: #constructnamemap

[api-default-handlers]: #defaulthandlers

[api-handle]: #handle

[api-handlers]: #handlers

[api-info]: #info

[api-join]: #join

[api-map]: #map

[api-options]: #options

[api-safe-config]: #safeconfig

[api-state]: #state

[api-to-markdown]: #tomarkdowntree-options

[api-tracker]: #tracker

[api-unsafe]: #unsafe