1- // Include `data` fields in mdast and `raw` nodes in hast.
2- /// <reference types="mdast-util-to-hast" />
3-
41/**
52 * @import {Root as HastRoot} from 'hast'
63 * @import {Root as MdastRoot} from 'mdast'
@@ -45,49 +42,56 @@ import {toHast} from 'mdast-util-to-hast'
4542 *
4643 * ###### Signature
4744 *
48- * * if a processor is given, runs the (rehype) plugins used on it with a
49- * hast tree, then discards the result (*bridge mode*)
50- * * otherwise, returns a hast tree, the plugins used after `remarkRehype`
51- * are rehype plugins (*mutate mode*)
45+ * * if a processor is given,
46+ * runs the (rehype) plugins used on it with a hast tree,
47+ * then discards the result (*bridge mode*)
48+ * * otherwise,
49+ * returns a hast tree,
50+ * the plugins used after `remarkRehype` are rehype plugins (*mutate mode*)
5251 *
53- * > 👉 **Note**: It’s highly unlikely that you want to pass a `processor`.
52+ * > 👉 **Note**:
53+ * > It’s highly unlikely that you want to pass a `processor`.
5454 *
5555 * ###### HTML
5656 *
5757 * Raw HTML is available in mdast as `html` nodes and can be embedded in hast
5858 * as semistandard `raw` nodes.
5959 * Most plugins ignore `raw` nodes but two notable ones don’t:
6060 *
61- * * `rehype-stringify` also has an option `allowDangerousHtml` which will
62- * output the raw HTML.
63- * This is typically discouraged as noted by the option name but is useful if
64- * you completely trust authors
65- * * `rehype-raw` can handle the raw embedded HTML strings by parsing them
66- * into standard hast nodes (`element`, `text`, etc).
67- * This is a heavy task as it needs a full HTML parser, but it is the only way
68- * to support untrusted content
61+ * * `rehype-stringify` also has an option `allowDangerousHtml` which will
62+ * output the raw HTML.
63+ * This is typically discouraged as noted by the option name but is useful if
64+ * you completely trust authors
65+ * * `rehype-raw` can handle the raw embedded HTML strings by parsing them
66+ * into standard hast nodes (`element`, `text`, etc);
67+ * this is a heavy task as it needs a full HTML parser,
68+ * but it is the only way to support untrusted content
6969 *
7070 * ###### Footnotes
7171 *
7272 * Many options supported here relate to footnotes.
73- * Footnotes are not specified by CommonMark, which we follow by default.
74- * They are supported by GitHub, so footnotes can be enabled in markdown with
75- * `remark-gfm`.
73+ * Footnotes are not specified by CommonMark,
74+ * which we follow by default.
75+ * They are supported by GitHub,
76+ * so footnotes can be enabled in markdown with `remark-gfm`.
7677 *
7778 * The options `footnoteBackLabel` and `footnoteLabel` define natural language
78- * that explains footnotes, which is hidden for sighted users but shown to
79- * assistive technology.
80- * When your page is not in English, you must define translated values.
79+ * that explains footnotes,
80+ * which is hidden for sighted users but shown to assistive technology.
81+ * When your page is not in English,
82+ * you must define translated values.
8183 *
82- * Back references use ARIA attributes, but the section label itself uses a
83- * heading that is hidden with an `sr-only` class.
84- * To show it to sighted users, define different attributes in
85- * `footnoteLabelProperties`.
84+ * Back references use ARIA attributes,
85+ * but the section label itself uses a heading that is hidden with an
86+ * `sr-only` class.
87+ * To show it to sighted users,
88+ * define different attributes in `footnoteLabelProperties`.
8689 *
8790 * ###### Clobbering
8891 *
89- * Footnotes introduces a problem, as it links footnote calls to footnote
90- * definitions on the page through `id` attributes generated from user content,
92+ * Footnotes introduces a problem,
93+ * as it links footnote calls to footnote definitions on the page through `id`
94+ * attributes generated from user content,
9195 * which results in DOM clobbering.
9296 *
9397 * DOM clobbering is this:
@@ -109,11 +113,13 @@ import {toHast} from 'mdast-util-to-hast'
109113 * Unknown nodes are nodes with a type that isn’t in `handlers` or `passThrough`.
110114 * The default behavior for unknown nodes is:
111115 *
112- * * when the node has a `value` (and doesn’t have `data.hName`,
113- * `data.hProperties`, or `data.hChildren`, see later), create a hast `text`
114- * node
115- * * otherwise, create a `<div>` element (which could be changed with
116- * `data.hName`), with its children mapped from mdast to hast as well
116+ * * when the node has a `value`
117+ * (and doesn’t have `data.hName`, `data.hProperties`, or `data.hChildren`,
118+ * see later),
119+ * create a hast `text` node
120+ * * otherwise,
121+ * create a `<div>` element (which could be changed with `data.hName`),
122+ * with its children mapped from mdast to hast as well
117123 *
118124 * This behavior can be changed by passing an `unknownHandler`.
119125 *
@@ -129,7 +135,8 @@ import {toHast} from 'mdast-util-to-hast'
129135 * @param {Readonly<Options> | Processor | null | undefined } [destination]
130136 * Processor or configuration (optional).
131137 * @param {Readonly<Options> | null | undefined } [options]
132- * When a processor was given, configuration (optional).
138+ * When a processor was given,
139+ * configuration (optional).
133140 * @returns {TransformBridge | TransformMutate }
134141 * Transform.
135142 */
0 commit comments