Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jan 14, 2022
1 parent deffd14 commit 407af18
Showing 1 changed file with 142 additions and 67 deletions.
209 changes: 142 additions & 67 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,70 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

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

## When to use this
## Contents

Use this if you have direct access to an AST and need to serialize it.
Use **[remark][]** instead, which includes this, but has a nice interface and
hundreds of plugins.
* [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)
* [List of extensions](#list-of-extensions)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

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

This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
If you want to handle syntax trees manually, use this.
For an easier time processing content, use the **[remark][]** ecosystem instead.

[npm][]:
## Install

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

```sh
npm install mdast-util-to-markdown
```

In Deno with [Skypack][]:

```js
import {toMarkdown} from 'https://cdn.skypack.dev/mdast-util-to-markdown@1?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
import {toMarkdown} from 'https://cdn.skypack.dev/mdast-util-to-markdown@1?min'
</script>
```

## Use

Say we have the following script, `example.js`:
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: [
Expand All @@ -60,8 +98,7 @@ const tree = {
console.log(toMarkdown(tree))
```

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

```markdown
> ***
Expand All @@ -70,14 +107,17 @@ would otherwise turn into a list and image respectively):
> 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 following identifier: `toMarkdown`.
There is no default export.

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

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

##### Formatting options

Expand Down Expand Up @@ -138,48 +178,48 @@ heading as the opening sequence (`boolean`, default: `false`).

###### `options.emphasis`

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

###### `options.fence`

Marker to use to serialize fenced code (``'`'`` or `'~'`, default: ``'`'``).
Marker to use for 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.
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 value of bullets of items in ordered lists (`boolean`,
default: `true`).
Whether to increment the counter of ordered lists items (`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'`).
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 to serialize titles (`'"'` or `"'"`, default: `'"'`).
Marker to use for titles (`'"'` or `"'"`, default: `'"'`).

###### `options.resourceLink`

Whether to use resource links (`[text](url)`) always (`boolean`, default:
`false`).
The default is to use autolinks (`<https://example.com>`) when possible.
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`).
Number of markers to use for thematic breaks (`number`, default: `3`, min: `3`).

###### `options.ruleSpaces`

Expand All @@ -189,20 +229,23 @@ Whether to add spaces between markers in thematic breaks (`boolean`, default:
###### `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.
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 to serialize strong (`'*'` or `'_'`, default: `'*'`).
Marker to use for strong (`'*'` or `'_'`, default: `'*'`).

###### `options.tightDefinitions`

Whether to join definitions w/o a blank line (`boolean`, default: `false`).
Shortcut for a join function like so:
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:

```js
function (left, right) {
function joinTightDefinitions(left, right) {
if (left.type === 'definition' && right.type === 'definition') {
return 0
}
Expand All @@ -211,18 +254,23 @@ function (left, right) {

###### `options.handlers`

Object mapping node types to custom handlers.
Object mapping node types to custom handlers (`Record<string, Handle>`, default:
`{}`).
Useful for syntax extensions.
Take a look at [`lib/handle`][handlers] for examples.

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

###### `options.join`

List of functions used to determine what to place between two flow nodes.
Often, they are joined by one blank line.
In certain cases, it’s nicer to have them next to each other.
Or, they can’t occur together.
These functions receive two adjacent nodes and their parent and can return
`number` or `boolean`, referring to how many blank lines to use between them.
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
Expand All @@ -238,50 +286,69 @@ comment will be injected to break them up:

###### `options.unsafe`

List of patterns to escape.
List of patterns to escape (`Array<Unsafe>`).
Useful for syntax extensions.
Take a look at [`lib/unsafe.js`][unsafe] for examples.

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

##### Extension options

###### `options.extensions`

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

##### Returns

`string` — Serialized markdown.
Serialized markdown (`string`).

## List of extensions

* [`syntax-tree/mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive)
— serialize directives
— directives
* [`syntax-tree/mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter)
— serialize frontmatter (YAML, TOML, more)
— frontmatter (YAML, TOML, more)
* [`syntax-tree/mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm)
— serialize GFM
— GFM
* [`syntax-tree/mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)
— serialize GFM autolink literals
— GFM autolink literals
* [`syntax-tree/mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)
— serialize GFM footnotes
— GFM footnotes
* [`syntax-tree/mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)
— serialize GFM strikethrough
— GFM strikethrough
* [`syntax-tree/mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)
— serialize GFM tables
— GFM tables
* [`syntax-tree/mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)
— serialize GFM task list items
— GFM task list items
* [`syntax-tree/mdast-util-math`](https://github.com/syntax-tree/mdast-util-math)
— serialize math
— math
* [`syntax-tree/mdast-util-mdx`](https://github.com/syntax-tree/mdast-util-mdx)
— serialize MDX or MDX.js
— MDX
* [`syntax-tree/mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)
— serialize MDX or MDX.js expressions
— MDX expressions
* [`syntax-tree/mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)
— serialize MDX or MDX.js JSX
— MDX JSX
* [`syntax-tree/mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)
— serialize MDX.js 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 types `Options`, `Map`, `Unsafe`, `Join`, `Handlers`, `Handle`,
`Context`, `SafeOptions`, which model the interfaces used by options and
extensions.

## Security

Expand All @@ -290,20 +357,20 @@ 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
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`][sanitize] to make the tree safe.
[`hast-util-sanitize`][hast-util-sanitize] to make the tree safe.

## Related

* [`micromark/micromark`](https://github.com/micromark/micromark)
— the smallest commonmark-compliant markdown parser that exists
* [`remarkjs/remark`](https://github.com/remarkjs/remark)
— markdown processor powered by plugins
* [`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

Expand Down Expand Up @@ -349,6 +416,8 @@ abide by its terms.

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

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com
Expand All @@ -359,14 +428,20 @@ abide by its terms.

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

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

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

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

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

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

[handlers]: lib/handle

[unsafe]: lib/unsafe.js

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

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

0 comments on commit 407af18

Please sign in to comment.