107 lines
3.5 KiB
JavaScript
107 lines
3.5 KiB
JavaScript
/**
|
||
* @typedef {import('hast').Nodes} HastNodes
|
||
* @typedef {import('mdast').Nodes} MdastNodes
|
||
* @typedef {import('./state.js').Options} Options
|
||
*/
|
||
|
||
import {ok as assert} from 'devlop'
|
||
import {footer} from './footer.js'
|
||
import {createState} from './state.js'
|
||
|
||
/**
|
||
* Transform mdast to hast.
|
||
*
|
||
* ##### Notes
|
||
*
|
||
* ###### HTML
|
||
*
|
||
* Raw HTML is available in mdast as `html` nodes and can be embedded in hast
|
||
* as semistandard `raw` nodes.
|
||
* Most utilities ignore `raw` nodes but two notable ones don’t:
|
||
*
|
||
* * `hast-util-to-html` also has an option `allowDangerousHtml` which will
|
||
* output the raw HTML.
|
||
* This is typically discouraged as noted by the option name but is useful
|
||
* if you completely trust authors
|
||
* * `hast-util-raw` can handle the raw embedded HTML strings by parsing them
|
||
* into standard hast nodes (`element`, `text`, etc).
|
||
* This is a heavy task as it needs a full HTML parser, but it is the only
|
||
* way to support untrusted content
|
||
*
|
||
* ###### Footnotes
|
||
*
|
||
* Many options supported here relate to footnotes.
|
||
* Footnotes are not specified by CommonMark, which we follow by default.
|
||
* They are supported by GitHub, so footnotes can be enabled in markdown with
|
||
* `mdast-util-gfm`.
|
||
*
|
||
* The options `footnoteBackLabel` and `footnoteLabel` define natural language
|
||
* that explains footnotes, which is hidden for sighted users but shown to
|
||
* assistive technology.
|
||
* When your page is not in English, you must define translated values.
|
||
*
|
||
* Back references use ARIA attributes, but the section label itself uses a
|
||
* heading that is hidden with an `sr-only` class.
|
||
* To show it to sighted users, define different attributes in
|
||
* `footnoteLabelProperties`.
|
||
*
|
||
* ###### Clobbering
|
||
*
|
||
* Footnotes introduces a problem, as it links footnote calls to footnote
|
||
* definitions on the page through `id` attributes generated from user content,
|
||
* which results in DOM clobbering.
|
||
*
|
||
* DOM clobbering is this:
|
||
*
|
||
* ```html
|
||
* <p id=x></p>
|
||
* <script>alert(x) // `x` now refers to the DOM `p#x` element</script>
|
||
* ```
|
||
*
|
||
* Elements by their ID are made available by browsers on the `window` object,
|
||
* which is a security risk.
|
||
* Using a prefix solves this problem.
|
||
*
|
||
* More information on how to handle clobbering and the prefix is explained in
|
||
* Example: headings (DOM clobbering) in `rehype-sanitize`.
|
||
*
|
||
* ###### Unknown nodes
|
||
*
|
||
* Unknown nodes are nodes with a type that isn’t in `handlers` or `passThrough`.
|
||
* The default behavior for unknown nodes is:
|
||
*
|
||
* * when the node has a `value` (and doesn’t have `data.hName`,
|
||
* `data.hProperties`, or `data.hChildren`, see later), create a hast `text`
|
||
* node
|
||
* * otherwise, create a `<div>` element (which could be changed with
|
||
* `data.hName`), with its children mapped from mdast to hast as well
|
||
*
|
||
* This behavior can be changed by passing an `unknownHandler`.
|
||
*
|
||
* @param {MdastNodes} tree
|
||
* mdast tree.
|
||
* @param {Options | null | undefined} [options]
|
||
* Configuration (optional).
|
||
* @returns {HastNodes}
|
||
* hast tree.
|
||
*/
|
||
export function toHast(tree, options) {
|
||
const state = createState(tree, options)
|
||
const node = state.one(tree, undefined)
|
||
const foot = footer(state)
|
||
/** @type {HastNodes} */
|
||
const result = Array.isArray(node)
|
||
? {type: 'root', children: node}
|
||
: node || {type: 'root', children: []}
|
||
|
||
if (foot) {
|
||
// If there’s a footer, there were definitions, meaning block
|
||
// content.
|
||
// So `result` is a parent node.
|
||
assert('children' in result)
|
||
result.children.push({type: 'text', value: '\n'}, foot)
|
||
}
|
||
|
||
return result
|
||
}
|