Add improved docs

Closes GH-22.

Reviewed-by: with-heart <with.heart+git@pm.me>
Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>

index.js

@@ -1,63 +1,8 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('hast').Root} HastRoot
- * @typedef {import('mdast').Root} MdastRoot
- * @typedef {import('mdast-util-to-hast').Options} Options
- * @typedef {import('unified').Processor<any, any, any, any>} Processor
- *
- * @typedef {import('mdast-util-to-hast')} DoNotTouchAsThisImportIncludesRawInTree
+ * @typedef {import('./lib/index.js').Options} Options
+ * @typedef {import('./lib/index.js').Processor} Processor
  */
 
-import {toHast} from 'mdast-util-to-hast'
-
-// Note: the `<MdastRoot, HastRoot>` overload doesn’t seem to work :'(
-
-/**
- * Plugin to bridge or mutate to rehype.
- *
- * If a destination is given, runs the destination with the new hast tree
- * (bridge-mode).
- * Without destination, returns the hast tree: further plugins run on that tree
- * (mutate-mode).
- *
- * @param destination
- *   Optional unified processor.
- * @param options
- *   Options passed to `mdast-util-to-hast`.
- */
-const remarkRehype =
-  /** @type {(import('unified').Plugin<[Processor, Options?]|[null|undefined, Options?]|[Options]|[], MdastRoot>)} */
-  (
-    function (destination, options) {
-      return destination && 'run' in destination
-        ? bridge(destination, options)
-        : mutate(destination || options)
-    }
-  )
+import remarkRehype from './lib/index.js'
 
 export default remarkRehype
-
-/**
- * Bridge-mode.
- * Runs the destination with the new hast tree.
- *
- * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
- */
-function bridge(destination, options) {
-  return (node, file, next) => {
-    destination.run(toHast(node, options), file, (error) => {
-      next(error)
-    })
-  }
-}
-
-/**
- * Mutate-mode.
- * Further transformers run on the nlcst tree.
- *
- * @type {import('unified').Plugin<[Options?]|void[], MdastRoot, HastRoot>}
- */
-function mutate(options) {
-  // @ts-expect-error: assume a corresponding node is returned for `toHast`.
-  return (node) => toHast(node, options)
-}

lib/index.js

@@ -0,0 +1,71 @@
+/**
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('mdast').Root} MdastRoot
+ * @typedef {import('mdast-util-to-hast').Options} Options
+ * @typedef {import('unified').Processor<any, any, any, any>} Processor
+ *
+ * @typedef {import('mdast-util-to-hast')} DoNotTouchAsThisImportIncludesRawInTree
+ */
+
+import {toHast} from 'mdast-util-to-hast'
+
+// Note: the `<MdastRoot, HastRoot>` overload doesn’t seem to work :'(
+
+/**
+ * Plugin that turns markdown into HTML to support rehype.
+ *
+ * *   If a destination processor is given, that processor runs with a new HTML
+ *     (hast) tree (bridge-mode).
+ *     As the given processor runs with a hast tree, and rehype plugins support
+ *     hast, that means rehype plugins can be used with the given processor.
+ *     The hast tree is discarded in the end.
+ *     It’s highly unlikely that you want to do this.
+ * *   The common case is to not pass a destination processor, in which case the
+ *     current processor continues running with a new HTML (hast) tree
+ *     (mutate-mode).
+ *     As the current processor continues with a hast tree, and rehype plugins
+ *     support hast, that means rehype plugins can be used after
+ *     `remark-rehype`.
+ *     It’s likely that this is what you want to do.
+ *
+ * @param destination
+ *   Optional unified processor.
+ * @param options
+ *   Options passed to `mdast-util-to-hast`.
+ */
+const remarkRehype =
+  /** @type {(import('unified').Plugin<[Processor, Options?]|[null|undefined, Options?]|[Options]|[], MdastRoot>)} */
+  (
+    function (destination, options) {
+      return destination && 'run' in destination
+        ? bridge(destination, options)
+        : mutate(destination || options)
+    }
+  )
+
+export default remarkRehype
+
+/**
+ * Bridge-mode.
+ * Runs the destination with the new hast tree.
+ *
+ * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
+ */
+function bridge(destination, options) {
+  return (node, file, next) => {
+    destination.run(toHast(node, options), file, (error) => {
+      next(error)
+    })
+  }
+}
+
+/**
+ * Mutate-mode.
+ * Further plugins run on the hast tree.
+ *
+ * @type {import('unified').Plugin<[Options?]|void[], MdastRoot, HastRoot>}
+ */
+function mutate(options) {
+  // @ts-expect-error: assume a corresponding node is returned by `toHast`.
+  return (node) => toHast(node, options)
+}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "remark-rehype",
   "version": "10.0.0",
-  "description": "remark plugin to transform to rehype",
+  "description": "remark plugin that turns markdown into HTML to support rehype",
   "license": "MIT",
   "keywords": [
     "unified",
@@ -31,6 +31,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
+    "lib/",
     "index.d.ts",
     "index.js"
   ],
@@ -56,7 +57,7 @@
     "xo": "^0.46.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"lib/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api",
@@ -86,8 +87,9 @@
     "ignoreCatch": true,
     "#": "needed `any`s",
     "ignoreFiles": [
-      "index.d.ts",
-      "index.js"
+      "lib/index.d.ts",
+      "lib/index.js",
+      "index.d.ts"
     ]
   }
 }