From 914f83a1feb646fe3eda5b7868c81cfe07be527e Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Tue, 8 Jun 2021 17:27:58 +0200 Subject: [PATCH] Add better docs --- dev/index.js | 2 +- dev/lib/html.js | 4 ++-- readme.md | 59 +++++++++++++++++++++++-------------------------- test/index.js | 4 ++-- 4 files changed, 33 insertions(+), 36 deletions(-) diff --git a/dev/index.js b/dev/index.js index 4e4844b..5999f02 100644 --- a/dev/index.js +++ b/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' diff --git a/dev/lib/html.js b/dev/lib/html.js index b4fd231..a59e5cb 100644 --- a/dev/lib/html.js +++ b/dev/lib/html.js @@ -18,7 +18,7 @@ * * @typedef {(this: CompileContext, directive: Directive) => boolean|void} Handle * - * @typedef {Record} Options + * @typedef {Record} 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 = {}) { diff --git a/readme.md b/readme.md index d8797db..9f11599 100644 --- a/readme.md +++ b/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 -tokenizer and the micromark HTML compiler. +## When to use this -You probably shouldn’t use the HTML parts of this package directly, but instead -use [`mdast-util-directive`][mdast-util-directive] with **[mdast][]** or -[`remark-directive`][remark-directive] with **[remark][]** +If you’re using [`micromark`][micromark] or +[`mdast-util-from-markdown`][from-markdown], use this package. +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') -var micromark = require('micromark') -var syntax = require('micromark-extension-directive') -var html = require('micromark-extension-directive/html') +import fs from 'node:fs' +import {micromark} from 'micromark' +import {directive, directiveHtml} from 'micromark-extension-directive' -var doc = fs.readFileSync('example.md') - -var result = micromark(doc, { - extensions: [syntax()], - htmlExtensions: [html({abbr: abbr})] +const output = micromark(fs.readFileSync('example.md'), { + extensions: [directive()], + htmlExtensions: [directiveHtml({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]. -The export of `syntax` is a function that can be called with options and returns -an extension for the micromark parser (to tokenize directives in text, flow, -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`). +Functions that can be called with options to get an extension for micromark to +parse directives (can be passed in `extensions`) and one to compile them to HTML +(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 -handled, in which case the fallback is used (when given). +`boolean` or `void` — `false` can be used to signal that the directive could not +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 - `'containerDirective'`) +* `type` (`'textDirective'|'leafDirective'|'containerDirective'`) * `name` (`string`) — name of directive -* `label` (`string?`) — compiled HTML content in brackets -* `attributes` (`Object.?`) — optional object w/ HTML attributes -* `content` (`string?`) — compiled HTML content when `container` +* `label` (`string?`) — compiled HTML content that was in `[brackets]` +* `attributes` (`Record?`) — object w/ HTML attributes +* `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 diff --git a/test/index.js b/test/index.js index 120cfd7..bc5a6f4 100644 --- a/test/index.js +++ b/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 {