micromark-extension-directive - npm Package Compare versions

Comparing version 2.1.2 to 2.2.0

dev/index.d.ts

 export {directive} from './lib/syntax.js'
 export {directiveHtml} from './lib/html.js'
+export type Directive = import('./lib/html.js').Directive
 export type Handle = import('./lib/html.js').Handle
 export type HtmlOptions = import('./lib/html.js').HtmlOptions

dev/index.js

 /**
+ * @typedef {import('./lib/html.js').Directive} Directive
  * @typedef {import('./lib/html.js').Handle} Handle
@@ -3,0 +4,0 @@ * @typedef {import('./lib/html.js').HtmlOptions} HtmlOptions

dev/lib/directive-container.d.ts

 /** @type {Construct} */
 export const directiveContainer: Construct
 export type Construct = import('micromark-util-types').Construct
-export type Tokenizer = import('micromark-util-types').Tokenizer
 export type State = import('micromark-util-types').State
 export type Token = import('micromark-util-types').Token
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer

dev/lib/directive-container.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  * @typedef {import('micromark-util-types').State} State
  * @typedef {import('micromark-util-types').Token} Token
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
@@ -28,3 +29,6 @@
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveContainer(effects, ok, nok) {
@@ -197,3 +201,6 @@ const self = this
 
-  /** @type {Tokenizer} */
+  /**
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
   function tokenizeClosingFence(effects, ok, nok) {
@@ -241,3 +248,6 @@ let size = 0
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -256,3 +266,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -279,3 +292,6 @@ // Always a `{`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeNonLazyLine(effects, ok, nok) {
@@ -282,0 +298,0 @@ const self = this

dev/lib/directive-leaf.d.ts

 /** @type {Construct} */
 export const directiveLeaf: Construct
 export type Construct = import('micromark-util-types').Construct
+export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
 export type Tokenizer = import('micromark-util-types').Tokenizer
-export type State = import('micromark-util-types').State

dev/lib/directive-leaf.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
+ * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
- * @typedef {import('micromark-util-types').State} State
  */
@@ -22,3 +23,6 @@
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveLeaf(effects, ok, nok) {
@@ -85,3 +89,6 @@ const self = this
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -100,3 +107,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -103,0 +113,0 @@ // Always a `{`

dev/lib/directive-text.d.ts

 /** @type {Construct} */
 export const directiveText: Construct
 export type Construct = import('micromark-util-types').Construct
-export type Tokenizer = import('micromark-util-types').Tokenizer
 export type Previous = import('micromark-util-types').Previous
 export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer

dev/lib/directive-text.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  * @typedef {import('micromark-util-types').Previous} Previous
  * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
@@ -24,3 +25,6 @@
 
-/** @type {Previous} */
+/**
+ * @this {TokenizeContext}
+ * @type {Previous}
+ */
 function previous(code) {
@@ -34,3 +38,6 @@ // If there is a previous code, there will always be a tail.
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveText(effects, ok, nok) {
@@ -75,3 +82,6 @@ const self = this
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -89,3 +99,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -92,0 +105,0 @@ // Always a `{`

dev/lib/factory-attributes.d.ts

@@ -37,4 +37,4 @@ /**
 ) => void | import('micromark-util-types').State
+export type Code = import('micromark-util-types').Code
 export type Effects = import('micromark-util-types').Effects
 export type State = import('micromark-util-types').State
-export type Code = import('micromark-util-types').Code

dev/lib/factory-attributes.js

 /**
+ * @typedef {import('micromark-util-types').Code} Code
  * @typedef {import('micromark-util-types').Effects} Effects
  * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').Code} Code
  */
@@ -6,0 +6,0 @@

dev/lib/factory-name.d.ts

@@ -17,4 +17,4 @@ /**
 ) => void | import('micromark-util-types').State
-export type TokenizeContext = import('micromark-util-types').TokenizeContext
 export type Effects = import('micromark-util-types').Effects
 export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext

dev/lib/factory-name.js

 /**
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  * @typedef {import('micromark-util-types').Effects} Effects
  * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  */
@@ -6,0 +6,0 @@

dev/lib/html.d.ts

 /**
- * @param {HtmlOptions} [options]
+ * Create an extension for `micromark` to support directives when serializing
+ * to HTML.
+ *
+ * @param {HtmlOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support directives when serializing to HTML.
  */
-export function directiveHtml(options?: HtmlOptions | undefined): HtmlExtension
+export function directiveHtml(
+  options?: HtmlOptions | null | undefined
+): HtmlExtension
+export type CompileContext = import('micromark-util-types').CompileContext
+export type _Handle = import('micromark-util-types').Handle
 export type HtmlExtension = import('micromark-util-types').HtmlExtension
-export type _Handle = import('micromark-util-types').Handle
-export type CompileContext = import('micromark-util-types').CompileContext
+/**
+ * Internal tuple representing an attribute.
+ */
 export type Attribute = [string, string]
-export type DirectiveType =
-  | 'containerDirective'
-  | 'leafDirective'
-  | 'textDirective'
+/**
+ * Configuration.
+ *
+ * > 👉 **Note**: the special field `'*'` can be used to specify a fallback
+ * > handle to handle all otherwise unhandled directives.
+ */
+export type HtmlOptions = Record<string, Handle>
+/**
+ * Handle a directive.
+ */
+export type Handle = (
+  this: CompileContext,
+  directive: Directive
+) => boolean | void
+/**
+ * Structure representing a directive.
+ */
 export type Directive = {
+  /**
+   *   Kind.
+   */
   type: DirectiveType
+  /**
+   *   Name of directive.
+   */
   name: string
+  /**
+   * Compiled HTML content that was in `[brackets]`.
+   */
   label?: string | undefined
+  /**
+   * Object w/ HTML attributes.
+   */
   attributes?: Record<string, string> | undefined
+  /**
+   * Compiled HTML content inside container directive.
+   */
   content?: string | undefined
+  /**
+   * Private :)
+   */
   _fenceCount?: number | undefined
 }
-export type Handle = (
-  this: CompileContext,
-  directive: Directive
-) => boolean | void
-export type HtmlOptions = Record<string, Handle>
+/**
+ * Kind.
+ */
+export type DirectiveType =
+  | 'containerDirective'
+  | 'leafDirective'
+  | 'textDirective'

dev/lib/html.js

 /**
+ * @typedef {import('micromark-util-types').CompileContext} CompileContext
+ * @typedef {import('micromark-util-types').Handle} _Handle
  * @typedef {import('micromark-util-types').HtmlExtension} HtmlExtension
- * @typedef {import('micromark-util-types').Handle} _Handle
- * @typedef {import('micromark-util-types').CompileContext} CompileContext
  */
@@ -9,15 +9,39 @@
  * @typedef {[string, string]} Attribute
- * @typedef {'containerDirective'|'leafDirective'|'textDirective'} DirectiveType
+ *   Internal tuple representing an attribute.
+ */
+
+/**
+ * @typedef {Record<string, Handle>} HtmlOptions
+ *   Configuration.
  *
+ *   > 👉 **Note**: the special field `'*'` can be used to specify a fallback
+ *   > handle to handle all otherwise unhandled directives.
+ *
+ * @callback Handle
+ *   Handle a directive.
+ * @param {CompileContext} this
+ *   Current context.
+ * @param {Directive} directive
+ *   Directive.
+ * @returns {boolean | void}
+ *   Signal whether the directive was handled.
+ *   Yield `false` to let the fallback (a special handle for `'*'`) handle it.
+ *
  * @typedef Directive
+ *   Structure representing a directive.
  * @property {DirectiveType} type
+ *   Kind.
  * @property {string} name
- * @property {string} [label]
- * @property {Record<string, string>} [attributes]
- * @property {string} [content]
- * @property {number} [_fenceCount]
+ *   Name of directive.
+ * @property {string | undefined} [label]
+ *   Compiled HTML content that was in `[brackets]`.
+ * @property {Record<string, string> | undefined} [attributes]
+ *   Object w/ HTML attributes.
+ * @property {string | undefined} [content]
+ *   Compiled HTML content inside container directive.
+ * @property {number | undefined} [_fenceCount]
+ *   Private :)
  *
- * @typedef {(this: CompileContext, directive: Directive) => boolean|void} Handle
- *
- * @typedef {Record<string, Handle>} HtmlOptions
+ * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType
+ *   Kind.
  */
@@ -31,6 +55,13 @@
 /**
- * @param {HtmlOptions} [options]
+ * Create an extension for `micromark` to support directives when serializing
+ * to HTML.
+ *
+ * @param {HtmlOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support directives when serializing to HTML.
  */
-export function directiveHtml(options = {}) {
+export function directiveHtml(options) {
+  const options_ = options || {}
   return {
@@ -103,3 +134,6 @@ enter: {
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitName(token) {
@@ -112,3 +146,6 @@ /** @type {Directive[]} */
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function enterLabel() {
@@ -118,3 +155,6 @@ this.buffer()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitLabel() {
@@ -128,3 +168,6 @@ const data = this.resume()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function enterAttributes() {
@@ -135,5 +178,8 @@ this.buffer()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeIdValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -149,5 +195,8 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeClassValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -164,7 +213,10 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeName(token) {
     // Attribute names in CommonMark are significantly limited, so character
     // references can’t exist.
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -176,5 +228,8 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -188,3 +243,6 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributes() {
@@ -194,3 +252,3 @@ /** @type {Directive[]} */
     const stack = this.getData('directiveStack')
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -219,3 +277,6 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitContainerContent() {
@@ -229,3 +290,6 @@ const data = this.resume()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitContainerFence() {
@@ -241,3 +305,6 @@ /** @type {Directive[]} */
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exit() {
@@ -254,9 +321,9 @@ /** @type {Directive} */
 
-    if (own.call(options, directive.name)) {
-      result = options[directive.name].call(this, directive)
+    if (own.call(options_, directive.name)) {
+      result = options_[directive.name].call(this, directive)
       found = result !== false
     }
 
-    if (!found && own.call(options, '*')) {
-      result = options['*'].call(this, directive)
+    if (!found && own.call(options_, '*')) {
+      result = options_['*'].call(this, directive)
       found = result !== false
@@ -263,0 +330,0 @@ }

dev/lib/syntax.d.ts

 /**
+ * Create an extension for `micromark` to enable directive syntax.
+ *
  * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable directive syntax.
  */
 export function directive(): Extension
 export type Extension = import('micromark-util-types').Extension

dev/lib/syntax.js

@@ -11,3 +11,7 @@ /**
 /**
+ * Create an extension for `micromark` to enable directive syntax.
+ *
  * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable directive syntax.
  */
@@ -14,0 +18,0 @@ export function directive() {

index.d.ts

 export {directive} from './lib/syntax.js'
 export {directiveHtml} from './lib/html.js'
+export type Directive = import('./lib/html.js').Directive
 export type Handle = import('./lib/html.js').Handle
 export type HtmlOptions = import('./lib/html.js').HtmlOptions

index.js

 /**
+ * @typedef {import('./lib/html.js').Directive} Directive
  * @typedef {import('./lib/html.js').Handle} Handle
@@ -3,0 +4,0 @@ * @typedef {import('./lib/html.js').HtmlOptions} HtmlOptions

lib/directive-container.d.ts

 /** @type {Construct} */
 export const directiveContainer: Construct
 export type Construct = import('micromark-util-types').Construct
-export type Tokenizer = import('micromark-util-types').Tokenizer
 export type State = import('micromark-util-types').State
 export type Token = import('micromark-util-types').Token
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer

lib/directive-container.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  * @typedef {import('micromark-util-types').State} State
  * @typedef {import('micromark-util-types').Token} Token
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
@@ -32,3 +33,6 @@
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveContainer(effects, ok, nok) {
@@ -191,3 +195,6 @@ const self = this
 
-  /** @type {Tokenizer} */
+  /**
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
   function tokenizeClosingFence(effects, ok, nok) {
@@ -227,3 +234,6 @@ let size = 0
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -242,3 +252,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -265,3 +278,6 @@ // Always a `{`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeNonLazyLine(effects, ok, nok) {
@@ -268,0 +284,0 @@ const self = this

lib/directive-leaf.d.ts

 /** @type {Construct} */
 export const directiveLeaf: Construct
 export type Construct = import('micromark-util-types').Construct
+export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
 export type Tokenizer = import('micromark-util-types').Tokenizer
-export type State = import('micromark-util-types').State

lib/directive-leaf.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
+ * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
- * @typedef {import('micromark-util-types').State} State
  */
@@ -26,3 +27,6 @@
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveLeaf(effects, ok, nok) {
@@ -85,3 +89,6 @@ const self = this
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -100,3 +107,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -103,0 +113,0 @@ // Always a `{`

lib/directive-text.d.ts

 /** @type {Construct} */
 export const directiveText: Construct
 export type Construct = import('micromark-util-types').Construct
-export type Tokenizer = import('micromark-util-types').Tokenizer
 export type Previous = import('micromark-util-types').Previous
 export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer

lib/directive-text.js

 /**
  * @typedef {import('micromark-util-types').Construct} Construct
- * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  * @typedef {import('micromark-util-types').Previous} Previous
  * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
  */
@@ -26,3 +27,6 @@
 
-/** @type {Previous} */
+/**
+ * @this {TokenizeContext}
+ * @type {Previous}
+ */
 function previous(code) {
@@ -36,3 +40,6 @@ // If there is a previous code, there will always be a tail.
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeDirectiveText(effects, ok, nok) {
@@ -74,3 +81,6 @@ const self = this
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeLabel(effects, ok, nok) {
@@ -88,3 +98,6 @@ // Always a `[`
 
-/** @type {Tokenizer} */
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
 function tokenizeAttributes(effects, ok, nok) {
@@ -91,0 +104,0 @@ // Always a `{`

lib/factory-attributes.d.ts

@@ -37,4 +37,4 @@ /**
 ) => void | import('micromark-util-types').State
+export type Code = import('micromark-util-types').Code
 export type Effects = import('micromark-util-types').Effects
 export type State = import('micromark-util-types').State
-export type Code = import('micromark-util-types').Code

lib/factory-attributes.js

 /**
+ * @typedef {import('micromark-util-types').Code} Code
  * @typedef {import('micromark-util-types').Effects} Effects
  * @typedef {import('micromark-util-types').State} State
- * @typedef {import('micromark-util-types').Code} Code
  */
@@ -6,0 +6,0 @@

lib/factory-name.d.ts

@@ -17,4 +17,4 @@ /**
 ) => void | import('micromark-util-types').State
-export type TokenizeContext = import('micromark-util-types').TokenizeContext
 export type Effects = import('micromark-util-types').Effects
 export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext

lib/factory-name.js

 /**
- * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  * @typedef {import('micromark-util-types').Effects} Effects
  * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
  */
@@ -6,0 +6,0 @@

lib/html.d.ts

 /**
- * @param {HtmlOptions} [options]
+ * Create an extension for `micromark` to support directives when serializing
+ * to HTML.
+ *
+ * @param {HtmlOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support directives when serializing to HTML.
  */
-export function directiveHtml(options?: HtmlOptions | undefined): HtmlExtension
+export function directiveHtml(
+  options?: HtmlOptions | null | undefined
+): HtmlExtension
+export type CompileContext = import('micromark-util-types').CompileContext
+export type _Handle = import('micromark-util-types').Handle
 export type HtmlExtension = import('micromark-util-types').HtmlExtension
-export type _Handle = import('micromark-util-types').Handle
-export type CompileContext = import('micromark-util-types').CompileContext
+/**
+ * Internal tuple representing an attribute.
+ */
 export type Attribute = [string, string]
-export type DirectiveType =
-  | 'containerDirective'
-  | 'leafDirective'
-  | 'textDirective'
+/**
+ * Configuration.
+ *
+ * > 👉 **Note**: the special field `'*'` can be used to specify a fallback
+ * > handle to handle all otherwise unhandled directives.
+ */
+export type HtmlOptions = Record<string, Handle>
+/**
+ * Handle a directive.
+ */
+export type Handle = (
+  this: CompileContext,
+  directive: Directive
+) => boolean | void
+/**
+ * Structure representing a directive.
+ */
 export type Directive = {
+  /**
+   *   Kind.
+   */
   type: DirectiveType
+  /**
+   *   Name of directive.
+   */
   name: string
+  /**
+   * Compiled HTML content that was in `[brackets]`.
+   */
   label?: string | undefined
+  /**
+   * Object w/ HTML attributes.
+   */
   attributes?: Record<string, string> | undefined
+  /**
+   * Compiled HTML content inside container directive.
+   */
   content?: string | undefined
+  /**
+   * Private :)
+   */
   _fenceCount?: number | undefined
 }
-export type Handle = (
-  this: CompileContext,
-  directive: Directive
-) => boolean | void
-export type HtmlOptions = Record<string, Handle>
+/**
+ * Kind.
+ */
+export type DirectiveType =
+  | 'containerDirective'
+  | 'leafDirective'
+  | 'textDirective'

lib/html.js

 /**
+ * @typedef {import('micromark-util-types').CompileContext} CompileContext
+ * @typedef {import('micromark-util-types').Handle} _Handle
  * @typedef {import('micromark-util-types').HtmlExtension} HtmlExtension
- * @typedef {import('micromark-util-types').Handle} _Handle
- * @typedef {import('micromark-util-types').CompileContext} CompileContext
  */
@@ -9,15 +9,39 @@
  * @typedef {[string, string]} Attribute
- * @typedef {'containerDirective'|'leafDirective'|'textDirective'} DirectiveType
+ *   Internal tuple representing an attribute.
+ */
+
+/**
+ * @typedef {Record<string, Handle>} HtmlOptions
+ *   Configuration.
  *
+ *   > 👉 **Note**: the special field `'*'` can be used to specify a fallback
+ *   > handle to handle all otherwise unhandled directives.
+ *
+ * @callback Handle
+ *   Handle a directive.
+ * @param {CompileContext} this
+ *   Current context.
+ * @param {Directive} directive
+ *   Directive.
+ * @returns {boolean | void}
+ *   Signal whether the directive was handled.
+ *   Yield `false` to let the fallback (a special handle for `'*'`) handle it.
+ *
  * @typedef Directive
+ *   Structure representing a directive.
  * @property {DirectiveType} type
+ *   Kind.
  * @property {string} name
- * @property {string} [label]
- * @property {Record<string, string>} [attributes]
- * @property {string} [content]
- * @property {number} [_fenceCount]
+ *   Name of directive.
+ * @property {string | undefined} [label]
+ *   Compiled HTML content that was in `[brackets]`.
+ * @property {Record<string, string> | undefined} [attributes]
+ *   Object w/ HTML attributes.
+ * @property {string | undefined} [content]
+ *   Compiled HTML content inside container directive.
+ * @property {number | undefined} [_fenceCount]
+ *   Private :)
  *
- * @typedef {(this: CompileContext, directive: Directive) => boolean|void} Handle
- *
- * @typedef {Record<string, Handle>} HtmlOptions
+ * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType
+ *   Kind.
  */
@@ -29,6 +53,13 @@
 /**
- * @param {HtmlOptions} [options]
+ * Create an extension for `micromark` to support directives when serializing
+ * to HTML.
+ *
+ * @param {HtmlOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support directives when serializing to HTML.
  */
-export function directiveHtml(options = {}) {
+export function directiveHtml(options) {
+  const options_ = options || {}
   return {
@@ -100,3 +131,6 @@ enter: {
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitName(token) {
@@ -109,3 +143,6 @@ /** @type {Directive[]} */
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function enterLabel() {
@@ -115,3 +152,6 @@ this.buffer()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitLabel() {
@@ -125,3 +165,6 @@ const data = this.resume()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function enterAttributes() {
@@ -132,5 +175,8 @@ this.buffer()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeIdValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -146,5 +192,8 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeClassValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -160,7 +209,10 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeName(token) {
     // Attribute names in CommonMark are significantly limited, so character
     // references can’t exist.
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -171,5 +223,8 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributeValue(token) {
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -185,3 +240,6 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitAttributes() {
@@ -191,3 +249,3 @@ /** @type {Directive[]} */
     const stack = this.getData('directiveStack')
-    /** @type {Attribute[]} */
+    /** @type {Array<Attribute>} */
     // @ts-expect-error
@@ -213,3 +271,6 @@ const attributes = this.getData('directiveAttributes')
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitContainerContent() {
@@ -223,3 +284,6 @@ const data = this.resume()
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exitContainerFence() {
@@ -235,3 +299,6 @@ /** @type {Directive[]} */
 
-  /** @type {_Handle} */
+  /**
+   * @this {CompileContext}
+   * @type {_Handle}
+   */
   function exit() {
@@ -245,8 +312,8 @@ /** @type {Directive} */
     let result
-    if (own.call(options, directive.name)) {
-      result = options[directive.name].call(this, directive)
+    if (own.call(options_, directive.name)) {
+      result = options_[directive.name].call(this, directive)
       found = result !== false
     }
-    if (!found && own.call(options, '*')) {
-      result = options['*'].call(this, directive)
+    if (!found && own.call(options_, '*')) {
+      result = options_['*'].call(this, directive)
       found = result !== false
@@ -253,0 +320,0 @@ }

lib/syntax.d.ts

 /**
+ * Create an extension for `micromark` to enable directive syntax.
+ *
  * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable directive syntax.
  */
 export function directive(): Extension
 export type Extension = import('micromark-util-types').Extension

lib/syntax.js

@@ -10,3 +10,7 @@ /**
 /**
+ * Create an extension for `micromark` to enable directive syntax.
+ *
  * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable directive syntax.
  */
@@ -13,0 +17,0 @@ export function directive() {

package.json

 {
   "name": "micromark-extension-directive",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "micromark extension to support generic directives (`:cite[smith04]`)",
@@ -37,2 +37,3 @@ "license": "MIT",
   "exports": {
+    "types": "./index.d.ts",
     "development": "./dev/index.js",
@@ -51,3 +52,3 @@ "default": "./index.js"
   "devDependencies": {
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
@@ -60,13 +61,15 @@ "html-void-elements": "^2.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
-    "typescript": "^4.0.0",
-    "xo": "^0.52.0"
+    "typescript": "^5.0.0",
+    "xo": "^0.53.0"
   },
   "scripts": {
-    "build": "rimraf \"dev/**/*.d.ts\" \"test/**/*.d.ts\" && tsc && type-coverage && micromark-build",
+    "prepack": "npm run build && npm run format",
+    "build": "tsc --build --clean && tsc --build && type-coverage && micromark-build",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node --conditions development test/index.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test/index.js",
+    "test-api-prod": "node --conditions production test/index.js",
+    "test-api-dev": "node --conditions development test/index.js",
+    "test-api": "npm run test-api-dev && npm run test-api-prod",
+    "test-coverage": "c8 --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
@@ -73,0 +76,0 @@ },

readme.md

@@ -11,21 +11,52 @@ # micromark-extension-directive
 
-**[micromark][]** extension to support the [generic directives proposal][prop]
-(`:cite[smith04]`, `::youtube[Video of a cat in a box]{v=01ab2cd3efg}`, and
+[micromark][] extensions to support [directives][prop] (`:cite[smith04]` and
 such).
 
-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.
+## Contents
 
+*   [What is this?](#what-is-this)
+*   [When to use this](#when-to-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`directive()`](#directive)
+    *   [`directiveHtml(options?)`](#directivehtmloptions)
+    *   [`Directive`](#directive-1)
+    *   [`Handle`](#handle)
+    *   [`HtmlOptions`](#htmloptions)
+*   [Authoring](#authoring)
+*   [HTML](#html)
+*   [CSS](#css)
+*   [Syntax](#syntax)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package contains two extensions that add support for directive syntax in
+markdown to [`micromark`][micromark].
+
 ## When to use this
 
-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].
+This project is useful when you want to solve the need for an infinite number
+of potential extensions to markdown in a single markdown-esque way.
 
+You can use these extensions when you are working with [`micromark`][micromark]
+already.
+
+When you need a syntax tree, you can combine this package with
+[`mdast-util-directive`][mdast-util-directive].
+
+All these packages are used [`remark-directive`][remark-directive], which
+focusses on making it easier to transform content by abstracting these
+internals away.
+
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 14.14+), install with [npm][]:
 
@@ -38,5 +69,19 @@ [npm][]:
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@2?bundle'
+</script>
+```
+
 ## Use
 
-Say we have the following file, `example.md`:
+Say our document `example.md` contains:
 
@@ -47,10 +92,10 @@ ```markdown
 
-And our script, `example.js`, looks as follows:
+…and our module `example.js` looks as follows:
 
 ```js
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 import {micromark} from 'micromark'
 import {directive, directiveHtml} from 'micromark-extension-directive'
 
-const output = micromark(fs.readFileSync('example.md'), {
+const output = micromark(await fs.readFile('example.md'), {
   extensions: [directive()],
@@ -62,2 +107,6 @@ htmlExtensions: [directiveHtml({abbr})]
 
+/**
+ * @this {import('micromark-util-types').CompileContext}
+ * @type {import('micromark-extension-directive').Handle}
+ */
 function abbr(d) {
@@ -78,3 +127,3 @@ if (d.type !== 'textDirective') return false
 
-Now, running `node example` yields (abbreviated):
+…now running `node example.js` yields:
 
@@ -87,49 +136,89 @@ ```html
 
-This package exports the following identifiers: `directive`, `directiveHtml`.
+This package exports the identifiers [`directive`][api-directive] and
+[`directiveHtml`][api-directive-html].
 There is no default export.
 
-The export map supports the endorsed
-[`development` condition](https://nodejs.org/api/packages.html#packages_resolving_user_conditions).
+The export map supports the [`development` condition][development].
 Run `node --conditions development module.js` to get instrumented dev code.
 Without this condition, production code is loaded.
 
-### `directive(syntaxOptions?)`
+### `directive()`
 
-### `directiveHtml(htmlOptions?)`
+Create an extension for `micromark` to enable directive syntax.
 
-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`).
+###### Returns
 
-###### `syntaxOptions`
+Extension for `micromark` that can be passed in `extensions`, to enable
+directive syntax ([`Extension`][micromark-extension]).
 
-None yet, but might be added in the future.
+### `directiveHtml(options?)`
 
-###### `htmlOptions`
+Create an extension for `micromark` to support directives when serializing to
+HTML.
 
-An object mapping names of directives to handlers
-([`Record<string, Handle>`][handle]).
-The special name `'*'` is the fallback to handle all unhandled directives.
+> 👉 **Note**: this uses KaTeX to render math.
 
-### `function handle(directive)`
+###### Parameters
 
-How to handle a `directive` ([`Directive`][directive]).
+*   `options` ([`HtmlOptions`][api-html-options], optional)
+    — configuration
 
-##### Returns
+###### Returns
 
-`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).
+Extension for `micromark` that can be passed in `htmlExtensions`, to
+support directives when serializing to HTML
+([`HtmlExtension`][micromark-html-extension]).
 
 ### `Directive`
 
-An object representing a directive.
+Structure representing a directive (TypeScript type).
 
 ###### Fields
 
-*   `type` (`'textDirective'|'leafDirective'|'containerDirective'`)
-*   `name` (`string`) — name of directive
-*   `label` (`string?`) — compiled HTML content that was in `[brackets]`
-*   `attributes` (`Record<string, string>?`) — object w/ HTML attributes
-*   `content` (`string?`) — compiled HTML content inside container directive
+*   `type` (`'textDirective'`, `'leafDirective'`, or `'containerDirective'`)
+    — kind
+*   `name` (`string`)
+    — name of directive
+*   `label` (`string`, optional)
+    — compiled HTML content that was in `[brackets]`
+*   `attributes` (`Record<string, string>`, optional)
+    — object w/ HTML attributes
+*   `content` (`string`, optional)
+    — compiled HTML content inside container directive
 
+### `Handle`
+
+Handle a directive (TypeScript type).
+
+###### Parameters
+
+*   `this` ([`CompileContext`][micromark-compile-context])
+    — current context
+*   `directive` ([`Directive`][api-directive-type])
+    — directive
+
+###### Returns
+
+Signal whether the directive was handled (`boolean`, default: `true`).
+Yield `false` to let the fallback (a special handle for `'*'`) handle it.
+
+### `HtmlOptions`
+
+Configuration (TypeScript type).
+
+> 👉 **Note**: the special field `'*'` can be used to specify a fallback handle
+> to handle all otherwise unhandled directives.
+
+###### Type
+
+```ts
+type HtmlOptions = Record<string, Handle>
+```
+
+## Authoring
+
+## HTML
+
+## CSS
+
 ## Syntax
@@ -209,16 +298,29 @@
 
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional types [`Directive`][api-directive-type],
+[`Handle`][api-handle], and [`HtmlOptions`][api-html-options].
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 14.14+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+These extensions work with `micromark` version 3+.
+
+## Security
+
+This package is safe assuming that you write safe handlers.
+Any vulnerability in your code could open you to a
+[cross-site scripting (XSS)][xss] attack.
+
 ## Related
 
-*   [`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]
-    — mdast utility to support generic directives
-*   [`syntax-tree/mdast-util-from-markdown`][from-markdown]
-    — mdast parser using `micromark` to create mdast from markdown
-*   [`syntax-tree/mdast-util-to-markdown`][to-markdown]
-    — mdast serializer to create markdown from mdast
+*   [`remark-directive`][remark-directive]
+    — remark plugin to support directives
+*   [`mdast-util-directive`][mdast-util-directive]
+    — mdast utility to support directives
 
@@ -269,2 +371,4 @@ ## Contribute
 
+[esmsh]: https://esm.sh
+
 [license]: license
@@ -280,12 +384,16 @@
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[typescript]: https://www.typescriptlang.org
+
+[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions
+
 [micromark]: https://github.com/micromark/micromark
 
-[from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension
 
-[to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
+[micromark-extension]: https://github.com/micromark/micromark#syntaxextension
 
-[remark]: https://github.com/remarkjs/remark
+[micromark-compile-context]: https://github.com/micromark/micromark/blob/41e3c4c/packages/micromark-util-types/index.js#L457
 
-[prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444
-
 [mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive
@@ -295,4 +403,14 @@
 
-[handle]: #function-handledirective
+[prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444
 
-[directive]: #directive
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[api-directive]: #directive
+
+[api-directive-html]: #directivehtmloptions
+
+[api-directive-type]: #directive-1
+
+[api-handle]: #handle
+
+[api-html-options]: #htmloptions

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

96395

increased by11.2%

Dev dependency count

12

decreased by-7.69%

Lines of code

2877

increased by12.69%

Number of lines in readme file

407

increased by40.83%

No dependency changes