Add improved docs

index.d.ts

@@ -1,11 +1,12 @@
 import type {Literal} from 'hast'
 
 // Expose types.
-export type {Options, Handler, Handlers, H} from './lib/index.js'
+export type {H, Handler, Handlers, Options} from './lib/index.js'
 
 // Expose JS API.
 export {one, all} from './lib/traverse.js'
-export {defaultHandlers, toHast} from './lib/index.js'
+export {handlers as defaultHandlers} from './lib/handlers/index.js'
+export {toHast} from './lib/index.js'
 
 // Expose node type.
 /**

index.js

@@ -1,3 +1,4 @@
 // Note: types exposed from `index.d.ts`.
 export {one, all} from './lib/traverse.js'
-export {defaultHandlers, toHast} from './lib/index.js'
+export {handlers as defaultHandlers} from './lib/handlers/index.js'
+export {toHast} from './lib/index.js'

lib/handlers/index.js

@@ -23,6 +23,9 @@ import {tableCell} from './table-cell.js'
 import {text} from './text.js'
 import {thematicBreak} from './thematic-break.js'
 
+/**
+ * Default handlers for nodes.
+ */
 export const handlers = {
   blockquote,
   break: hardBreak,

lib/index.js

@@ -96,7 +96,7 @@
  * @property {HastProperties} footnoteLabelProperties
  *   Properties on the HTML tag used for the footnote label.
  * @property {string} footnoteBackLabel
- *   Label to use to go back to a footnote call from the footnote section.
+ *   Label to use from backreferences back to their footnote call.
  * @property {(identifier: string) => MdastDefinition | null} definition
  *   Definition cache.
  * @property {Record<string, MdastFootnoteDefinition>} footnoteById
@@ -121,38 +121,26 @@
  * @typedef Options
  *   Configuration (optional).
  * @property {boolean | null | undefined} [allowDangerousHtml=false]
- *   Whether to allow `html` nodes and inject them as `raw` HTML.
+ *   Whether to persist raw HTML in markdown in the hast tree.
  * @property {string | null | undefined} [clobberPrefix='user-content-']
- *   Prefix to use before the `id` attribute to prevent it from *clobbering*.
- *   attributes.
- *   DOM clobbering is this:
- *
- *   ```html
- *   <p id=x></p>
- *   <script>alert(x)</script>
- *   ```
- *
- *   Elements by their ID are made available in browsers on the `window` object.
- *   Using a prefix prevents this from being a problem.
+ *   Prefix to use before the `id` attribute on footnotes to prevent it from
+ *   *clobbering*.
+ * @property {string | null | undefined} [footnoteBackLabel='Back to content']
+ *   Label to use from backreferences back to their footnote call (affects
+ *   screen readers).
  * @property {string | null | undefined} [footnoteLabel='Footnotes']
- *   Label to use for the footnotes section.
- *   Affects screen reader users.
- *   Change it if you’re authoring in a different language.
- * @property {string | null | undefined} [footnoteLabelTagName='h2']
- *   HTML tag to use for the footnote label.
- *   Can be changed to match your document structure and play well with your choice of css.
+ *   Label to use for the footnotes section (affects screen readers).
  * @property {HastProperties | null | undefined} [footnoteLabelProperties={className: ['sr-only']}]
- *   Properties to use on the footnote label.
- *   A 'sr-only' class is added by default to hide this from sighted users.
- *   Change it to make the label visible, or add classes for other purposes.
- * @property {string | null | undefined} [footnoteBackLabel='Back to content']
- *   Label to use from backreferences back to their footnote call.
- *   Affects screen reader users.
- *   Change it if you’re authoring in a different language.
+ *   Properties to use on the footnote label (note that `id: 'footnote-label'`
+ *   is always added as footnote calls use it with `aria-describedby` to
+ *   provide an accessible label).
+ * @property {string | null | undefined} [footnoteLabelTagName='h2']
+ *   Tag name to use for the footnote label.
  * @property {Handlers | null | undefined} [handlers]
- *   Object mapping mdast nodes to functions handling them
+ *   Extra handlers for nodes.
  * @property {Array<string> | null | undefined} [passThrough]
- *   List of custom mdast node types to pass through (keep) in hast
+ *   List of custom mdast node types to pass through (keep) in hast (note that
+ *   the node itself is passed, but eventual children are transformed).
  * @property {Handler | null | undefined} [unknownHandler]
  *   Handler for all unknown nodes.
  *
@@ -385,7 +373,74 @@ function applyData(origin, node) {
 }
 
 /**
- * Turn an mdast tree into a hast node.
+ * 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.

lib/traverse.js

@@ -42,6 +42,7 @@ export function one(h, node, parent) {
   }
 
   if (h.passThrough && h.passThrough.includes(type)) {
+    // To do: next major: deep clone.
     // @ts-expect-error: types of passed through nodes are expected to be added manually.
     return 'children' in node ? {...node, children: all(h, node)} : node
   }