Add better docs

dev/index.js

@@ -1,6 +1,6 @@
 /**
  * @typedef {import('./lib/html.js').Handle} Handle
- * @typedef {import('./lib/html.js').Options} Options
+ * @typedef {import('./lib/html.js').HtmlOptions} HtmlOptions
  */
 
 export {directive} from './lib/syntax.js'

dev/lib/html.js

@@ -18,7 +18,7 @@
  *
  * @typedef {(this: CompileContext, directive: Directive) => boolean|void} Handle
  *
- * @typedef {Record<string, Handle>} Options
+ * @typedef {Record<string, Handle>} HtmlOptions
  */
 
 import assert from 'assert'
@@ -27,7 +27,7 @@ import {decodeEntity} from 'parse-entities/decode-entity.js'
 const own = {}.hasOwnProperty
 
 /**
- * @param {Options} [options]
+ * @param {HtmlOptions} [options]
  * @returns {HtmlExtension}
  */
 export function directiveHtml(options = {}) {

readme.md

@@ -16,12 +16,12 @@ Generic directives solve the need for an infinite number of potential extensions
 to markdown in a single markdown-esque way.
 However, it’s just [a proposal][prop] and may never be specced.
 
-This package provides the low-level modules for integrating with the micromark
+## When to use this
-tokenizer and the micromark HTML compiler.
 
-You probably shouldn’t use the HTML parts of this package directly, but instead
+If you’re using [`micromark`][micromark] or
-use [`mdast-util-directive`][mdast-util-directive] with **[mdast][]** or
+[`mdast-util-from-markdown`][from-markdown], use this package.
-[`remark-directive`][remark-directive] with **[remark][]**
+Alternatively, if you’re using **[remark][]**, use
+[`remark-directive`][remark-directive].
 
 ## Install
 
@@ -45,19 +45,16 @@ A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
 And our script, `example.js`, looks as follows:
 
 ```js
-var fs = require('fs')
+import fs from 'node:fs'
-var micromark = require('micromark')
+import {micromark} from 'micromark'
-var syntax = require('micromark-extension-directive')
+import {directive, directiveHtml} from 'micromark-extension-directive'
-var html = require('micromark-extension-directive/html')
 
-var doc = fs.readFileSync('example.md')
+const output = micromark(fs.readFileSync('example.md'), {
-
+  extensions: [directive()],
-var result = micromark(doc, {
+  htmlExtensions: [directiveHtml({abbr})]
-  extensions: [syntax()],
-  htmlExtensions: [html({abbr: abbr})]
 })
 
-console.log(result)
+console.log(output)
 
 function abbr(d) {
   if (d.type !== 'textDirective') return false
@@ -85,17 +82,18 @@ Now, running `node example` yields (abbreviated):
 This package exports the following identifiers: `directive`, `directiveHtml`.
 There is no default export.
 
+The export map supports the endorsed
+[`development` condition](https://nodejs.org/api/packages.html#packages_resolving_user_conditions).
+Run `node --conditions development module.js` to get instrumented dev code.
+Without this condition, production code is loaded.
+
 ### `directive(syntaxOptions?)`
 
 ### `directiveHtml(htmlOptions?)`
 
-Support the [generic directives proposal][prop].
+Functions that can be called with options to get an extension for micromark to
-The export of `syntax` is a function that can be called with options and returns
+parse directives (can be passed in `extensions`) and one to compile them to HTML
-an extension for the micromark parser (to tokenize directives in text, flow,
+(can be passed in `htmlExtensions`).
-and as a container; can be passed in `extensions`).
-The export of `html` is a function that can be called with options and returns
-an extension for the default HTML compiler (to compile directives a certain way;
-can be passed in `htmlExtensions`).
 
 ###### `syntaxOptions`
 
@@ -113,8 +111,8 @@ How to handle a `directive` ([`Directive`][directive]).
 
 ##### Returns
 
-`boolean` — `false` can be used to signal that the directive could not be
+`boolean` or `void` — `false` can be used to signal that the directive could not
-handled, in which case the fallback is used (when given).
+be handled, in which case the fallback is used (when given).
 
 ### `Directive`
 
@@ -122,12 +120,11 @@ An object representing a directive.
 
 ###### Fields
 
-*   `type` (`enum`, either `'textDirective'`, `'leafDirective'`, or
+*   `type` (`'textDirective'|'leafDirective'|'containerDirective'`)
-    `'containerDirective'`)
 *   `name` (`string`) — name of directive
-*   `label` (`string?`) — compiled HTML content in brackets
+*   `label` (`string?`) — compiled HTML content that was in `[brackets]`
-*   `attributes` (`Object.<string>?`) — optional object w/ HTML attributes
+*   `attributes` (`Record<string, string>?`) — object w/ HTML attributes
-*   `content` (`string?`) — compiled HTML content when `container`
+*   `content` (`string?`) — compiled HTML content inside container directive
 
 ## Syntax
 
@@ -207,6 +204,8 @@ this implementation mimics CommonMark as closely as possible:
 
 *   [`remarkjs/remark`][remark]
     — markdown processor powered by plugins
+*   [`remarkjs/remark-directive`][remark-directive]
+    — remark plugin using this to support directive
 *   [`micromark/micromark`][micromark]
     — the smallest commonmark-compliant markdown parser that exists
 *   [`syntax-tree/mdast-util-directive`][mdast-util-directive]
@@ -278,8 +277,6 @@ abide by its terms.
 
 [remark]: https://github.com/remarkjs/remark
 
-[mdast]: https://github.com/syntax-tree/mdast
-
 [prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444
 
 [mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

test/index.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../dev/index.js').Options} Options
+ * @typedef {import('../dev/index.js').HtmlOptions} HtmlOptions
  * @typedef {import('../dev/index.js').Handle} Handle
  */
 
@@ -1453,7 +1453,7 @@ function h(d) {
 }
 
 /**
- * @param {Options} [options]
+ * @param {HtmlOptions} [options]
  */
 function options(options) {
   return {