Add improved docs

index.js

@@ -1,73 +1,7 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('mdast').Root} MdastRoot
- * @typedef {import('mdast-util-to-nlcst').ParserInstance} ParserInstance
- * @typedef {import('mdast-util-to-nlcst').ParserConstructor} ParserConstructor
- * @typedef {import('mdast-util-to-nlcst').Options} Options
- * @typedef {import('unified').Processor<any, any, any, any>} Processor
- * @typedef {import('unified').Parser<any>} Parser
+ * @typedef {import('./lib/index.js').Options} Options
  */
 
-import {toNlcst} from 'mdast-util-to-nlcst'
-
-/**
- * Plugin to bridge or mutate to retext.
- *
- * If a destination processor is given, runs the destination with the new nlcst
- * tree (bridge-mode).
- * If a parser is given, returns the nlcst tree: further plugins run on that
- * tree (mutate-mode).
- *
- * @param destination
- * Either a processor (`unified().use(retextEnglish)…`) or a parser.
- * @param options
- * Configuration passed to `mdast-util-to-nlcst`.
- */
-const remarkRetext =
- /**
- * @type {(import('unified').Plugin<[Processor, Options?]|[Processor], MdastRoot, MdastRoot> & import('unified').Plugin<[Parser, Options?]|[Parser], MdastRoot, Node>)}
- */
- (
- /**
- * @param {Processor|Parser} destination
- * @param {Options|undefined} options
- */
- function (destination, options) {
- return destination && 'run' in destination
- ? bridge(destination, options)
- : mutate(destination, options)
- }
- )
+import remarkRetext from './lib/index.js'
 
 export default remarkRetext
-
-/**
- * Mutate-mode.
- * Further transformers run on the nlcst tree.
- *
- * @type {import('unified').Plugin<[Parser, Options?], MdastRoot, Node>}
- */
-function mutate(parser, options) {
- // Assume the parser is a retext parser.
- const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
- return (node, file) => toNlcst(node, file, Parser, options)
-}
-
-/**
- * Bridge-mode.
- * Runs the destination with the new nlcst tree.
- *
- * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
- */
-function bridge(destination, options) {
- return (node, file, next) => {
- // Assume the parser is a retext parser.
- const Parser = /** @type {ParserConstructor|ParserInstance} */ (
- destination.freeze().Parser
- )
-
- destination.run(toNlcst(node, file, Parser, options), file, (error) => {
- next(error)
- })
- }
-}

lib/index.js

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('mdast').Root} MdastRoot
+ * @typedef {import('mdast-util-to-nlcst').ParserInstance} ParserInstance
+ * @typedef {import('mdast-util-to-nlcst').ParserConstructor} ParserConstructor
+ * @typedef {import('mdast-util-to-nlcst').Options} Options
+ * @typedef {import('unified').Processor<any, any, any, any>} Processor
+ * @typedef {import('unified').Parser<any>} Parser
+ */
+
+import {toNlcst} from 'mdast-util-to-nlcst'
+
+/**
+ * Plugin to support retext.
+ *
+ * * If a destination processor is given, runs the plugins attached to it with
+ * the new nlcst tree (bridge-mode).
+ * This given processor must have a parser attached (this can be done by
+ * using the plugin `retext-english` or similar) and should use other retext
+ * plugins.
+ * * If a parser is given, runs further plugins attached to the same processor
+ * with the new tree (mutate-mode).
+ * Such parsers are exported by packages like `retext-english` as `Parser`.
+ * You should use other retext plugins after `remark-retext`.
+ *
+ * @param destination
+ * Either a processor (`unified().use(retextEnglish)…`) or a parser.
+ * @param options
+ * Configuration passed to `mdast-util-to-nlcst`.
+ */
+const remarkRetext =
+ /**
+ * @type {(import('unified').Plugin<[Processor, Options?]|[Processor], MdastRoot, MdastRoot> & import('unified').Plugin<[Parser, Options?]|[Parser], MdastRoot, Node>)}
+ */
+ (
+ /**
+ * @param {Processor|Parser} destination
+ * @param {Options|undefined} options
+ */
+ function (destination, options) {
+ return destination && 'run' in destination
+ ? bridge(destination, options)
+ : mutate(destination, options)
+ }
+ )
+
+export default remarkRetext
+
+/**
+ * Mutate-mode.
+ * Further transformers run on the nlcst tree.
+ *
+ * @type {import('unified').Plugin<[Parser, Options?], MdastRoot, Node>}
+ */
+function mutate(parser, options) {
+ // Assume the parser is a retext parser.
+ const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
+ return (node, file) => toNlcst(node, file, Parser, options)
+}
+
+/**
+ * Bridge-mode.
+ * Runs the destination with the new nlcst tree.
+ *
+ * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
+ */
+function bridge(destination, options) {
+ return (node, file, next) => {
+ // Assume the parser is a retext parser.
+ const Parser = /** @type {ParserConstructor|ParserInstance} */ (
+ destination.freeze().Parser
+ )
+
+ destination.run(toNlcst(node, file, Parser, options), file, (error) => {
+ next(error)
+ })
+ }
+}

package.json

@@ -1,7 +1,7 @@
 {
  "name": "remark-retext",
  "version": "5.0.0",
- "description": "remark plugin to transform to retext",
+ "description": "remark plugin to support retext",
  "license": "MIT",
  "keywords": [
  "unified",
@@ -30,6 +30,7 @@
  "main": "index.js",
  "types": "index.d.ts",
  "files": [
+ "lib/",
  "index.d.ts",
  "index.js"
  ],
@@ -56,7 +57,7 @@
  "xo": "^0.45.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",
@@ -85,8 +86,8 @@
  "ignoreCatch": true,
  "#": "needed `any`s",
  "ignoreFiles": [
- "index.d.ts",
- "index.js"
+ "lib/index.d.ts",
+ "lib/index.js"
  ]
  }
 }