$ npm install mdast-util-to-markdown
mdast utility that turns a syntax tree into markdown.
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.
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
.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-to-markdown
In Deno with esm.sh
:
import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@2'
In browsers with esm.sh
:
<script type="module">
import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@2?bundle'
</script>
Say our module example.js
looks as follows:
/**
* @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))
β¦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.
This package exports the identifiers defaultHandlers
and toMarkdown
.
There is no default export.
toMarkdown(tree[, options])
Turn an mdast syntax tree into markdown.
Serialized markdown representing tree
(string
).
defaultHandlers
Default (CommonMark) handlers (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 ConstructName = ConstructNameMap[keyof ConstructNameMap]
ConstructNameMap
Interface of registered constructs (TypeScript type).
interface ConstructNameMap { /* see code */ }
When working on extensions that use new constructs, extend the corresponding interface to register its name:
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).
node
(any
)
β expected mdast nodeparent
(Node
, optional)
β parent of node
state
(State
)
β info passed around about the current stateinfo
(Info
)
β info on the surrounding of the node that is serializedSerialized markdown representing node
(string
).
Handlers
Handle particular nodes (TypeScript type).
Each key is a node type (Node['type']
), each value its corresponding handler
(Handle
).
type Handlers = Record<Node['type'], Handle>
Info
Info on the surrounding of the node that is serialized (TypeScript type).
now
(Point
)
β current pointlineShift
(number
)
β number of columns each line will be shifted by wrapping nodesbefore
(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.
left
(Node
)
β first of two adjacent siblingsright
(Node
)
β second of two adjacent siblingsparent
(Node
)
β parent of the two siblingsstate
(State
)
β info passed around about the current stateHow 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:
> 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).
value
(string
)
β a single line of serialized markdownline
(number
)
β line number relative to the fragmentblank
(boolean
)
β whether the line is considered blank in markdownPadded line (string
).
Options
Configuration (TypeScript type).
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:
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 itembullet
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* a\n- b
;
bulletOther
is used for such listsoptions.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:
1. a\n2) b
; to solve
that, '.'
will be used when bulletOrdered
is ')'
, and '.'
otherwiseoptions.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 (<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 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
function like so:
function joinTightDefinitions(left, right) {
if (left.type === 'definition' && right.type === 'definition') {
return 0
}
}
options.handlers
Handle particular nodes (Handlers
, optional).
options.join
How to join blocks (Array<Join>
, optional).
options.unsafe
Schemas that define when characters cannot occur
(Array<Unsafe>
, optional).
options.extensions
List of extensions (Array<Options>
, default: []
).
Each extension is an object with the same interface as Options
itself.
SafeConfig
Configuration passed to state.safe
(TypeScript type).
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<string>
, 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 hereState
Info passed around about the current state (TypeScript type).
stack
(Array<ConstructName>
)
β stack of constructs weβre inindexStack
(Array<number>
)
β positions of child nodes in their parentsassociationId
((node: Association) => string
)
β get an identifier from an association to match it to others (see
Association
)enter
((construct: ConstructName) => () => undefined
)
β enter a construct (returns a corresponding exit function)
(see ConstructName
)indentLines
((value: string, map: Map) => string
)
β pad serialized markdown (see Map
)compilePattern
((pattern: Unsafe) => RegExp
)
β compile an unsafe pattern to a regex (see Unsafe
)containerFlow
((parent: Node, info: Info) => string
)
β serialize flow children (see Info
)containerPhrasing
((parent: Node, info: Info) => string
)
β serialize phrasing children (see Info
)createTracker
((info: Info) => Tracker
)
β track positional info in the output (see Info
,
Tracker
)safe
((value: string, config: SafeConfig) => string
)
β make a string safe for embedding (see SafeConfig
)options
(Options
)
β applied user configurationunsafe
(Array<Unsafe>
)
β applied unsafe patternsjoin
(Array<Join>
)
β applied join handlershandle
(Handle
)
β call the configured handler for the given nodehandlers
(Handlers
)
β applied handlersbulletCurrent
(string
or undefined
)
β list marker currently in usebulletLastUsed
(string
or undefined
)
β list marker previously in useTracker
Track positional info in the output (TypeScript type).
This info isnβt used yet but such functionality will allow line wrapping, source maps, etc.
current
(() => Info
)
β get current tracked infoshift
((value: number) => undefined
)
β define a relative increased line shift (the typical indent for lines)move
((value: string) => string
)
β move past some generated markdownUnsafe
Schema that defines when a character cannot occur (TypeScript type).
character
(string
)
β single unsafe characterinConstruct
(Array<ConstructName>
,
ConstructName
, optional)
β constructs where this is badnotInConstruct
(Array<ConstructName>
,
ConstructName
, optional)
β constructs where this is fine againbefore
(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 itatBreak
(boolean
, optional)
β character
is bad at a break (cannot be used together with before
)syntax-tree/mdast-util-directive
β directivessyntax-tree/mdast-util-frontmatter
β frontmatter (YAML, TOML, more)syntax-tree/mdast-util-gfm
β GFMsyntax-tree/mdast-util-gfm-autolink-literal
β GFM autolink literalssyntax-tree/mdast-util-gfm-footnote
β GFM footnotessyntax-tree/mdast-util-gfm-strikethrough
β GFM strikethroughsyntax-tree/mdast-util-gfm-table
β GFM tablessyntax-tree/mdast-util-gfm-task-list-item
β GFM task list itemssyntax-tree/mdast-util-math
β mathsyntax-tree/mdast-util-mdx
β MDXsyntax-tree/mdast-util-mdx-expression
β MDX expressionssyntax-tree/mdast-util-mdx-jsx
β MDX JSXsyntax-tree/mdast-util-mdxjs-esm
β MDX ESMMarkdown 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.
The syntax tree is mdast.
This package is fully typed with TypeScript.
It exports the additional types
ConstructName
,
ConstructNameMap
,
Handle
,
Handlers
,
Info
,
Join
,
Map
,
Options
,
SafeConfig
,
State
, and
Unsafe
.
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.
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.
syntax-tree/mdast-util-from-markdown
β parse markdown to mdastmicromark/micromark
β parse markdownremarkjs/remark
β process markdownSee 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.
MIT Β© Titus Wormer
© 2010 - cnpmjs.org x YWFE | Home | YWFE