An implicit paragraph.
hast utility to transform to mdast
npm install hast-util-to-mdast[![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]
[hast][] utility to transform to [mdast][].
* What is this?
* When should I use this?
* Install
* Use
* API
* [toMdast(tree[, options])](#tomdasttree-options)
* defaultHandlers
* defaultNodeHandlers
* Handle
* NodeHandle
* Options
* State
* Examples
* Example: ignoring things
* Example: keeping some HTML
* Algorithm
* Syntax
* Syntax tree
* Types
* Compatibility
* Security
* Related
* Contribute
* License
This package is a utility that takes a [hast][] (HTML) syntax tree as input and
turns it into an [mdast][] (markdown) syntax tree.
This project is useful when you want to turn HTML to markdown.
The mdast utility [mdast-util-to-hast][mdast-util-to-hast] does the inverse of
this utility.
It turns markdown into HTML.
The rehype plugin [rehype-remark][rehype-remark] wraps this utility to also
turn HTML to markdown at a higher-level (easier) abstraction.
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
``sh`
npm install hast-util-to-mdast
In Deno with [esm.sh][esmsh]:
`js`
import {toMdast} from 'https://esm.sh/hast-util-to-mdast@10'
In browsers with [esm.sh][esmsh]:
`html`
Say we have the following example.html:
`html`Hello world!
…and next to it a module example.js:
`js
import fs from 'node:fs/promises'
import {fromHtml} from 'hast-util-from-html'
import {toMdast} from 'hast-util-to-mdast'
import {toMarkdown} from 'mdast-util-to-markdown'
const html = String(await fs.readFile('example.html'))
const hast = fromHtml(html, {fragment: true})
const mdast = toMdast(hast)
const markdown = toMarkdown(mdast)
console.log(markdown)
`
…now running node example.js yields:
`markdown`Hello world!
This package exports the identifiers [defaultHandlers][api-default-handlers],defaultNodeHandlers
[][api-default-node-handlers], andtoMdast
[][api-to-mdast].
There is no default export.
Transform hast to mdast.
###### Parameters
* tree ([HastNode][hast-node])options
— hast tree to transform
* ([Options][api-options], optional)
— configuration
###### Returns
mdast tree ([MdastNode][mdast-node]).
Default handlers for elements (Record).
Each key is an element name, each value is a [Handle][api-handle].
Default handlers for nodes (Record).
Each key is a node type, each value is a [NodeHandle][api-node-handle].
Handle a particular element (TypeScript type).
###### Parameters
* state ([State][api-state])element
— info passed around about the current state
* ([Element][element])parent
— element to transform
* ([HastParent][hast-parent])element
— parent of
###### Returns
mdast node or nodes (Array).
Handle a particular node (TypeScript type).
###### Parameters
* state ([State][api-state])node
— info passed around about the current state
* (any)parent
— node to transform
* ([HastParent][hast-parent])node
— parent of
###### Returns
mdast node or nodes (Array).
Configuration (TypeScript type).
##### Fields
###### newlines
Keep line endings when collapsing whitespace (boolean, default: false).
The default collapses to a single space.
###### checked
Value to use for a checked checkbox or radio input (string, default: [x]).
###### unchecked
Value to use for an unchecked checkbox or radio input (string, default:[ ]).
###### quotes
List of quotes to use (Array, default: ['"']).
Each value can be one or two characters.
When two, the first character determines the opening quote and the second the
closing quote at that level.
When one, both the opening and closing quote are that character.
The order in which the preferred quotes appear determines which quotes to use at
which level of nesting.
So, to prefer ‘’ at the first level of nesting, and “” at the second, pass['‘’', '“”'].
If s are nested deeper than the given amount of quotes, the markers wrap['«»', '‹›']
around: a third level of nesting when using should have double
guillemets, a fourth single, a fifth double again, etc.
###### document
Whether the given tree represents a complete document (boolean, default:undefined).
Applies when the tree is a root node.
When the tree represents a complete document, then things are wrapped in
paragraphs when needed, and otherwise they’re left as-is.
The default checks for whether there’s mixed content: some [phrasing][] nodes
and some non-phrasing nodes.
###### handlers
Object mapping tag names to functions handling the corresponding elements
(Record).
Merged into the defaults.
See [Handle][api-handle].
###### nodeHandlers
Object mapping node types to functions handling the corresponding nodes
(Record).
Merged into the defaults.
See [NodeHandle][api-node-handle].
Info passed around about the current state (TypeScript type).
###### Fields
* patch ((from: HastNode, to: MdastNode) => undefined)one
— copy a node’s positional info
* ((node: HastNode, parent: HastParent | undefined) => Array)all
— transform a hast node to mdast
* ((parent: HastParent) => Array)toFlow
— transform the children of a hast parent to mdast
* ((nodes: Array)toSpecificContent
— transform a list of mdast nodes to flow
* ()resolve
— turn arbitrary content into a list of a particular node type
* ((url: string | null | undefined) => string)options
— resolve a URL relative to a base
* ([Options][api-options])elementById
— user configuration
* (Map)id
— elements by their
* (Record)Handle
— applied element handlers (see [][api-handle])nodeHandlers
* (Record)NodeHandle
— applied node handlers (see [][api-node-handle])baseFound
* (boolean)
— whether a element was seenfrozenBaseUrl
* (string | undefined)href
— of , if anyinTable
* (boolean)qNesting
— whether we’re in a table
* (number)
— how deep we’re in s
It’s possible to exclude something from within HTML when turning it into
markdown, by wrapping it in an element with a data-mdast attribute set to'ignore'.
For example:
` Strong and emphasis.html`
Yields:
`markdown`
Strong and .
It’s also possible to pass a handler to ignore nodes.
For example, to ignore em elements, pass handlers: {'em': function () {}}:
` Strong and emphasis.html`
Yields:
`markdown`
Strong and .
The goal of this project is to map HTML to plain and readable markdown.
That means that certain elements are ignored (such as
Say we have the following file example.html:
`html`
Some text with
a graphic… Wait is that a dead pixel?
This can be achieved with example.js like so:
`js
/**
* @import {Html} from 'mdast'
*/
import fs from 'node:fs/promises'
import {fromHtml} from 'hast-util-from-html'
import {toHtml} from 'hast-util-to-html'
import {toMdast} from 'hast-util-to-mdast'
import {toMarkdown} from 'mdast-util-to-markdown'
const html = String(await fs.readFile('example.html'))
const hast = fromHtml(html, {fragment: true})
const mdast = toMdast(hast, {
handlers: {
svg(state, node) {
/* @type {Html} /
const result = {type: 'html', value: toHtml(node, {space: 'svg'})}
state.patch(node, result)
return result
}
}
})
const markdown = toMarkdown(mdast)
console.log(markdown)
`
Yields:
`markdown`
Some text with a graphic… Wait is that a dead pixel?
The algorithm used in this project is very powerful.
It supports all HTML elements, including ancient elements (xmp) and obscurebase
ones ().
It’s particularly good at forms, media, and around implicit and explicit
paragraphs (see [HTML Standard, A. van Kesteren; et al. WHATWG § 3.2.5.4
Paragraphs][html-paragraphs]), such as:
`html`
An implicit paragraph.
An explicit paragraph.
Yields:
`markdown
An implicit paragraph.
Syntax
HTML is handled according to [WHATWG HTML][html] (the living standard), which is
also followed by browsers such as Chrome and Firefox.
This project creates markdown according to [GFM][], which is a standard that’s
based on [CommonMark][] but adds the strikethrough (
) and tables
(| Table header | …) amongst some alternative syntaxes.Syntax tree
The input syntax tree format is [hast][].
Any HTML that can be represented in hast is accepted as input.
The output syntax tree format is [mdast][].
When